From e8d757d1202fcad55f8d78219686d8ec0af5e7a0 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Wed, 25 Feb 2026 19:59:17 +0900
Subject: [PATCH 01/28] docs: translate Chinese sections in README.md to
 English

---
 README.md | 44 ++++++++++++++++++++++----------------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 820e275..eb567a1 100644
--- a/README.md
+++ b/README.md
@@ -39,41 +39,41 @@ OpenMotion is a high-performance, open-source alternative to Remotion. It allows
 - 📹 **Offthread Video**: High-performance video decoding moved to background processes.
 - 📊 **Dynamic Metadata**: Calculate video dimensions, duration, and other properties dynamically based on input props.
 - 🎬 **GIF & Video Output**: Render to both MP4 video and GIF formats with automatic format detection.
-### 4. 渲染视频 (正式出片)
+### 4. Render Video (Production Output)
 
-推荐使用项目自带的 `render` 脚本进行渲染，它会自动完成 **构建 -> 启动静态服务 -> 渲染 -> 自动清理** 的全套流程，确保渲染过程极其稳健，不会因开发服务器缓冲区问题而卡死。
+It is recommended to use the project's built-in `render` script for rendering. It automatically handles the full pipeline of **build -> start static server -> render -> cleanup**, ensuring a robust rendering process that won't hang due to dev server buffer issues.
 
 ```bash
-# 执行一键渲染 (默认输出 ./out.mp4，开启 4 线程并行)
+# One-click render (default output: ./out.mp4, 4 parallel threads)
 npm run render
 
-# 修改输出文件名或指定合成 ID (通过 -- 透传参数)
+# Override the output filename or specify a composition ID (pass args via --)
 npm run render -- -o my-video.mp4 -c main
 ```
 
-## 💡 最佳实践
+## 💡 Best Practices
 
-### 稳健渲染方案
-生产环境建议始终优先使用 `npm run render`。该命令内部使用了静态服务模式，彻底告别渲染卡死。
+### Robust Rendering
+For production environments, always prefer `npm run render`. This command uses static server mode internally, completely eliminating the risk of rendering hangs.
 
-### 参数透传技巧
-你可以通过 `npm run render -- [更多参数]` 覆盖脚本中的默认值：
-- **修改并发数**: `npm run render -- -j 8`
-- **指定 Chromium 路径**: `npm run render -- --chromium-path "/path/to/chrome"`
+### Passing Additional Arguments
+You can override the script's defaults via `npm run render -- [additional args]`:
+- **Change concurrency**: `npm run render -- -j 8`
+- **Specify Chromium path**: `npm run render -- --chromium-path "/path/to/chrome"`
 
-### 资源存放
-所有本地图片/视频资源请放在 `public/` 目录下，在代码中通过 `/filename` 路径引用。
+### Asset Storage
+Place all local image/video assets in the `public/` directory and reference them in code using `/filename` paths.
 
-## 🎬 输出格式支持
-- **.mp4**: 标准视频，包含音频。
-- **.webm**: 支持透明背景的高质量视频。
-- **.gif**: 动态图片，不含音频。
-- **.webp**: 现代动图格式，体积更小，质量更好。
+## 🎬 Output Format Support
+- **.mp4**: Standard video with audio.
+- **.webm**: High-quality video with transparency support.
+- **.gif**: Animated images without audio.
+- **.webp**: Modern animated format — smaller file size, better quality than GIF.
 
-## 🛡️ 特色功能
-- 🛡️ **Pre-Flight Checks**: 内置浏览器安装检查与环境验证。
-- 🌍 **Custom Chromium Path**: 支持通过 `--chromium-path` 参数自定义浏览器路径。
-- 🚀 **Turbo Render**: 一键自动化构建与全自动渲染链条。
+## 🛡️ Notable Features
+- 🛡️ **Pre-Flight Checks**: Built-in browser installation checks and environment validation.
+- 🌍 **Custom Chromium Path**: Specify a custom browser path via the `--chromium-path` argument.
+- 🚀 **Turbo Render**: One-click automated build and full rendering pipeline.
 
 ## 📚 API Reference
 

From b49e7ad96937cb6f981402e4c98d1db99df87093 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Wed, 25 Feb 2026 20:01:44 +0900
Subject: [PATCH 02/28] docs: add Simplified Chinese translation (README.zh.md)

---
 README.zh.md | 319 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 319 insertions(+)
 create mode 100644 README.zh.md

diff --git a/README.zh.md b/README.zh.md
new file mode 100644
index 0000000..b7c0ffe
--- /dev/null
+++ b/README.zh.md
@@ -0,0 +1,319 @@
+# OpenMotion
+
+<p align="center">
+  <img src="assets/open-motion.jpg" width="120" height="120" alt="OpenMotion Logo" />
+</p>
+
+<p align="center">
+  <strong>专为 React 开发者打造的开源编程视频引擎。</strong>
+</p>
+
+<p align="center">
+  <a href="#-features">特性</a> •
+  <a href="#-installation">安装</a> •
+  <a href="#-quick-start">快速开始</a> •
+  <a href="#-packages">软件包</a>
+</p>
+
+---
+
+OpenMotion 是 Remotion 的高性能开源替代方案。它允许你使用熟悉的 React 组件、Hooks 和你喜欢的 CSS 库来创建帧准确（frame-perfect）的视频。
+
+### 🎬 展示
+
+| 功能展示 | 媒体展示 |
+| :---: | :---: |
+| ![Feature Showcase](assets/feature-showcase.gif) | ![Media Showcase](assets/media-showcase.gif) |
+| 品牌、仪表盘、缓动 | 视频、音频 |
+
+## ✨ 特性
+
+- ⚛️ **React 优先**: 充分利用 React 生态系统的全部力量。
+- ⏱️ **帧准确的确定性**: 先进的时间劫持技术确保每一帧都完全一致。
+- 🚀 **并行渲染**: 通过利用所有 CPU 核心来提升渲染速度。
+- 🎵 **多轨音频混合**: 支持多个 `<Audio />` 且具有独立音量控制。
+- 📈 **动画组件**: 内置循环（Loop）、过渡（Transitions）、缓动（Easing）等库。
+- 📦 **外部集成**: 原生支持 **Three.js** 和 **Lottie** 动画。
+- 💬 **字幕系统**: 自动化字幕渲染，支持 SRT 和 TikTok 风格动画。
+- 📊 **媒体分析**: 动态提取视频/音频元数据（时长、尺寸）。
+- 📹 **离线视频**: 高性能视频解码移至后台进程。
+- 📊 **动态元数据**: 根据输入 props 动态计算视频尺寸、时长等属性。
+- 🎬 **GIF & 视频输出**: 支持渲染为 MP4 视频和 GIF 格式，具有自动格式检测。
+
+### 4. 渲染视频 (正式出片)
+
+推荐使用项目自带的 `render` 脚本进行渲染。它会自动完成 **构建 -> 启动静态服务 -> 渲染 -> 自动清理** 的全套流程，确保渲染过程极其稳健，不会因开发服务器缓冲区问题而卡死。
+
+```bash
+# 一键渲染 (默认输出 ./out.mp4，开启 4 线程并行)
+npm run render
+
+# 修改输出文件名或指定合成 ID (通过 -- 透传参数)
+npm run render -- -o my-video.mp4 -c main
+```
+
+## 💡 最佳实践
+
+### 稳健渲染方案
+生产环境建议始终优先使用 `npm run render`。该命令内部使用了静态服务模式，彻底告别渲染卡死。
+
+### 参数透传技巧
+你可以通过 `npm run render -- [更多参数]` 覆盖脚本中的默认值：
+- **修改并发数**: `npm run render -- -j 8`
+- **指定 Chromium 路径**: `npm run render -- --chromium-path "/path/to/chrome"`
+
+### 资源存放
+所有本地图片/视频资源请放在 `public/` 目录下，在代码中通过 `/filename` 路径引用。
+
+## 🎬 输出格式支持
+- **.mp4**: 标准视频，包含音频。
+- **.webm**: 支持透明背景的高质量视频。
+- **.gif**: 动态图片，不含音频。
+- **.webp**: 现代动图格式，体积更小，质量更好。
+
+## 🛡️ 特色功能
+- 🛡️ **运行前检查**: 内置浏览器安装检查与环境验证。
+- 🌍 **自定义 Chromium 路径**: 支持通过 `--chromium-path` 参数自定义浏览器路径。
+- 🚀 **快速渲染**: 一键自动化构建与全自动渲染链条。
+
+## 📚 API 参考
+
+动态计算视频属性：
+
+```tsx
+<Composition
+  id="dynamic-video"
+  component={VideoComponent}
+  width={1280}
+  height={720}
+  fps={30}
+  durationInFrames={300}
+  calculateMetadata={async (props) => {
+    const meta = await getVideoMetadata(props.src);
+    return {
+      width: meta.width,
+      height: meta.height,
+      durationInFrames: Math.ceil(meta.durationInSeconds * 30)
+    };
+  }}
+/>
+```
+
+## 📦 软件包
+
+| 软件包 | 描述 |
+| :--- | :--- |
+| [`@open-motion/core`](./packages/core) | React 基元 (`Composition`, `Sequence`, `Loop`), Hooks, 以及媒体工具 (`getVideoMetadata`, `parseSrt`)。 |
+| [`@open-motion/components`](./packages/components) | 高级组件 (`Transition`, `ThreeCanvas`, `Lottie`, `Captions`, `TikTokCaption`)。 |
+| [`@open-motion/renderer`](./packages/renderer) | 基于 Playwright 的捕获引擎。 |
+| [`@open-motion/cli`](./packages/cli) | 命令行界面。 |
+
+## 🛠 安装
+
+```bash
+npm install @open-motion/core @open-motion/components
+```
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+# 全局安装 CLI 工具
+pnpm install -g @open-motion/cli @open-motion/renderer
+
+# 安装 Playwright 浏览器 (渲染必需)
+npx playwright install chromium
+```
+
+### 创建并运行你的第一个项目
+
+```bash
+# 创建新项目
+open-motion init fun-video
+cd fun-video && pnpm install
+
+# 启动开发服务器
+# 在一个终端运行 - 它会显示端口 (例如 5173)
+pnpm run dev
+```
+
+**注意**: 保持此终端开启。如果端口 5173 已被占用，Vite 会自动尝试 5174, 5175 等。请检查输出以获取实际端口号。
+
+### 渲染你的视频
+
+在另一个终端中，使用上面的端口渲染项目：
+
+```bash
+# 渲染为 MP4 (30fps 下 14 秒)
+open-motion render -u http://localhost:5173 -o out.mp4 --duration 420
+
+# 渲染为 GIF (30fps 下 14 秒)
+open-motion render -u http://localhost:5173 -o out.gif --duration 420
+
+# 渲染为 WebP (质量优于 GIF)
+open-motion render -u http://localhost:5173 -o out.webp --duration 420
+
+# 渲染为 WebM (支持透明视频)
+open-motion render -u http://localhost:5173 -o out.webm --duration 420
+```
+
+**时长解释**: `--duration 420` 表示 420 帧。在 30fps 下，即 420 ÷ 30 = **14 秒** 视频。
+
+### 创建一个 Composition
+
+```tsx
+import { Composition, useCurrentFrame, interpolate } from "@open-motion/core";
+import { Transition, TikTokCaption } from "@open-motion/components";
+
+const MyScene = () => {
+  const frame = useCurrentFrame();
+  return (
+    <Transition type="fade">
+      <div style={{ flex: 1, backgroundColor: 'black', color: 'white' }}>
+        <TikTokCaption text="Hello OpenMotion" active={true} />
+      </div>
+    </Transition>
+  );
+};
+```
+
+**关于端口的注意**: 如果端口 5173 已被占用，Vite 会自动尝试 5174, 5175 等。请查看开发服务器输出以获取实际端口号 (例如 "Local: http://localhost:5177/")。
+
+## 📚 API 参考
+
+所有 OpenMotion 特性和组件的完整参考。
+
+### 核心 Hooks
+
+**`useCurrentFrame()`**
+获取动画中的当前帧数。
+
+```tsx
+const frame = useCurrentFrame();
+const opacity = interpolate(frame, [0, 30], [0, 1]);
+```
+
+**`useVideoConfig()`**
+访问视频配置 (width, height, fps, durationInFrames)。
+
+```tsx
+const { width, height, fps } = useVideoConfig();
+```
+
+### 动画 & 过渡
+
+**`<Loop durationInFrames={30}>`**
+为子动画创建循环的时间上下文。
+
+```tsx
+<Loop durationInFrames={60}>
+  <SpinningLogo />
+</Loop>
+```
+
+**`<Transition type="wipe" direction="right">`**
+平滑的进入/退出过渡。类型：`fade`, `wipe`, `slide`, `zoom`。
+
+```tsx
+<Transition type="wipe" direction="right">
+  <Title text="Hello World" />
+</Transition>
+```
+
+**`Easing.inOutExpo`**
+完整的缓动函数库：
+- `Easing.linear`, `Easing.easeIn`, `Easing.easeOut`, `Easing.easeInOut`
+- `Easing.inOutCubic`, `Easing.outBack`, `Easing.inExpo` 等
+
+```tsx
+const value = interpolate(frame, [0, 30], [0, 100], {
+  easing: Easing.outCubic,
+});
+```
+
+### 3D & Lottie 集成
+
+**`<ThreeCanvas />`**
+渲染与视频帧同步的 Three.js 场景。详情见 `packages/components`。
+
+**`<Lottie url="..." />`**
+具有帧准确控制的声明式 Lottie 动画。
+
+```tsx
+<Lottie url="/animations/logo.json" />
+```
+
+### 媒体 & 字幕
+
+**`<Audio src="..." volume={0.8} />`**
+多轨音频支持，具有独立音量和定时。
+
+```tsx
+<Audio src="/music.mp3" volume={0.5} startFrom={30} startFrame={60} />
+```
+
+**`parseSrt(srtContent)`**
+将 SRT 字幕文件转换为数组。
+
+```tsx
+const subtitles = parseSrt(await fetch('/subtitles.srt').then(r => r.text()));
+```
+
+**`<Captions subtitles={subtitles} />`**
+具有样式选项的灵活字幕渲染器。
+
+```tsx
+<Captions subtitles={subtitles} color="white" fontSize={24} />
+```
+
+**`<TikTokCaption />`**
+预设样式的 TikTok 类动画字幕组件。
+
+**`getVideoMetadata(url)`**
+获取视频尺寸和时长。
+
+```tsx
+const { width, height, durationInSeconds } = await getVideoMetadata('/video.mp4');
+```
+
+**`<OffthreadVideo src="..." />`**
+后台进程中的高性能视频解码。
+
+### 输出 & 导出选项
+
+**CLI 命令**
+
+```bash
+# 基础渲染
+open-motion render -u http://localhost:5173 -o video.mp4
+
+# 使用自定义设置
+open-motion render -u http://localhost:5173 -o video.mp4 \
+  --duration 420 \
+  --width 1920 \
+  --height 1080 \
+  --fps 30
+
+# 渲染为 GIF
+open-motion render -u http://localhost:5173 -o animation.gif \
+  --duration 420 \
+  --public-dir ./public
+```
+
+**文件格式**
+- **MP4**: 包含音频支持的完整视频 (H.264)
+- **WebM**: 支持透明度的 Web 优化视频 (VP9)
+- **GIF**: 轻量级动画 (无音频)
+- **WebP**: 高质量动画图像 (优于 GIF，无音频)
+
+**质量参数**
+- `--width`: 输出宽度（像素）
+- `--height`: 输出高度（像素）
+- `--fps`: 每秒帧数 (默认: 30)
+- `--duration`: 总帧数 (例如: 420 = 30fps 下 14 秒)
+- `--format`: 显式格式 (mp4, webm, gif, webp, auto)
+
+## 📜 许可证
+
+MIT © [jsongo](https://github.com/jsongo)

From d00abae088263b762ef6a3962f3d31f71219f6ca Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Wed, 25 Feb 2026 20:03:27 +0900
Subject: [PATCH 03/28] docs: add Japanese translation (README.ja.md)

---
 README.ja.md | 319 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 319 insertions(+)
 create mode 100644 README.ja.md

diff --git a/README.ja.md b/README.ja.md
new file mode 100644
index 0000000..56f3cad
--- /dev/null
+++ b/README.ja.md
@@ -0,0 +1,319 @@
+# OpenMotion
+
+<p align="center">
+  <img src="assets/open-motion.jpg" width="120" height="120" alt="OpenMotion Logo" />
+</p>
+
+<p align="center">
+  <strong>React開発者のためのオープンソース・プログラマティック・ビデオエンジン。</strong>
+</p>
+
+<p align="center">
+  <a href="#-features">機能</a> •
+  <a href="#-installation">インストール</a> •
+  <a href="#-quick-start">クイックスタート</a> •
+  <a href="#-packages">パッケージ</a>
+</p>
+
+---
+
+OpenMotionは、Remotionに代わる高性能なオープンソースの選択肢です。使い慣れたReactコンポーネント、フック、お気に入りのCSSライブラリを使用して、フレーム単位で正確なビデオを作成できます。
+
+### 🎬 ショーケース
+
+| 機能ショーケース | メディアショーケース |
+| :---: | :---: |
+| ![Feature Showcase](assets/feature-showcase.gif) | ![Media Showcase](assets/media-showcase.gif) |
+| ブランド、ダッシュボード、イージング | ビデオ、オーディオ |
+
+## ✨ 機能
+
+- ⚛️ **Reactファースト**: Reactエコシステムのパワーを最大限に活用。
+- ⏱️ **フレーム精度の決定論**: 高度なタイムジャック技術により、すべてのフレームが同一であることを保証。
+- 🚀 **並列レンダリング**: すべてのCPUコアを利用してレンダリング速度をスケール。
+- 🎵 **マルチトラック・オーディオミキシング**: 独立した音量制御を持つ複数の `<Audio />` をサポート。
+- 📈 **アニメーションコンポーネント**: ループ、トランジション、イージングなどの組み込みライブラリ。
+- 📦 **外部連携**: **Three.js** や **Lottie** アニメーションをネイティブサポート。
+- 💬 **キャプションシステム**: SRTサポートとTikTokスタイルのアニメーションによる自動字幕レンダリング。
+- 📊 **メディア分析**: ビデオ/オーディオの動的なメタデータ抽出（長さ、解像度）。
+- 📹 **オフスレッドビデオ**: 高性能なビデオデコードをバックグラウンドプロセスに移行。
+- 📊 **動的メタデータ**: 入力プロップに基づいて、ビデオの解像度や長さなどのプロパティを動的に計算。
+- 🎬 **GIF & ビデオ出力**: 自動フォーマット検出により、MP4ビデオとGIFの両方の形式でレンダリング可能。
+
+### 4. ビデオのレンダリング (本番出力)
+
+レンダリングには、プロジェクトに組み込まれた `render` スクリプトの使用を推奨します。これは、**ビルド -> 静的サーバーの起動 -> レンダリング -> 自動クリーンアップ** という一連のプロセスを自動的に処理し、開発サーバーのバッファ問題によるフリーズを防ぎ、極めて堅牢なレンダリングを保証します。
+
+```bash
+# ワンクリックレンダリング (デフォルト出力: ./out.mp4、4スレッド並列)
+npm run render
+
+# 出力ファイル名の変更やコンポジションIDの指定 (引数を -- 経由で渡す)
+npm run render -- -o my-video.mp4 -c main
+```
+
+## 💡 ベストプラクティス
+
+### 堅牢なレンダリング
+本番環境では、常に `npm run render` を優先してください。このコマンドは内部で静的サーバーモードを使用しており、レンダリングのハングアップを完全に排除します。
+
+### 追加引数の受け渡し
+`npm run render -- [追加引数]` を使用してスクリプトのデフォルト値を上書きできます。
+- **並列数の変更**: `npm run render -- -j 8`
+- **Chromiumのパス指定**: `npm run render -- --chromium-path "/path/to/chrome"`
+
+### アセットの配置
+ローカルの画像やビデオアセットはすべて `public/` ディレクトリに配置し、コード内からは `/filename` パスで参照してください。
+
+## 🎬 出力形式のサポート
+- **.mp4**: 標準的なビデオ（オーディオ込み）。
+- **.webm**: 透過背景をサポートする高品質ビデオ。
+- **.gif**: アニメーション画像（オーディオなし）。
+- **.webp**: モダンなアニメーション形式。GIFより軽量で高品質。
+
+## 🛡️ 特徴的な機能
+- 🛡️ **実行前チェック**: ブラウザのインストール確認と環境検証機能を内蔵。
+- 🌍 **カスタムChromiumパス**: `--chromium-path` 引数によるブラウザパスのカスタマイズ。
+- 🚀 **Turbo Render**: ワンクリックの自動ビルドと自動レンダリングチェーン。
+
+## 📚 APIリファレンス
+
+ビデオプロパティを動的に計算する：
+
+```tsx
+<Composition
+  id="dynamic-video"
+  component={VideoComponent}
+  width={1280}
+  height={720}
+  fps={30}
+  durationInFrames={300}
+  calculateMetadata={async (props) => {
+    const meta = await getVideoMetadata(props.src);
+    return {
+      width: meta.width,
+      height: meta.height,
+      durationInFrames: Math.ceil(meta.durationInSeconds * 30)
+    };
+  }}
+/>
+```
+
+## 📦 パッケージ
+
+| パッケージ | 説明 |
+| :--- | :--- |
+| [`@open-motion/core`](./packages/core) | Reactプリミティブ (`Composition`, `Sequence`, `Loop`), フック, メディアユーティリティ (`getVideoMetadata`, `parseSrt`)。 |
+| [`@open-motion/components`](./packages/components) | 高度なコンポーネント (`Transition`, `ThreeCanvas`, `Lottie`, `Captions`, `TikTokCaption`)。 |
+| [`@open-motion/renderer`](./packages/renderer) | Playwrightベースのキャプチャエンジン。 |
+| [`@open-motion/cli`](./packages/cli) | コマンドラインインターフェース。 |
+
+## 🛠 インストール
+
+```bash
+npm install @open-motion/core @open-motion/components
+```
+
+## 🚀 クイックスタート
+
+### セットアップ
+
+```bash
+# CLIツールをグローバルにインストール
+pnpm install -g @open-motion/cli @open-motion/renderer
+
+# Playwrightブラウザをインストール (レンダリングに必要)
+npx playwright install chromium
+```
+
+### プロジェクトの作成と実行
+
+```bash
+# 新規プロジェクトの作成
+open-motion init fun-video
+cd fun-video && pnpm install
+
+# 開発サーバーの起動
+# ターミナルで実行 - ポート番号が表示されます (例: 5173)
+pnpm run dev
+```
+
+**注意**: このターミナルは開いたままにしてください。ポート5173が使用中の場合、Viteは自動的に5174, 5175などを試行します。実際のポート番号は出力を確認してください。
+
+### ビデオのレンダリング
+
+別のターミナルで、上記のポートを使用してプロジェクトをレンダリングします：
+
+```bash
+# MP4へのレンダリング (30fpsで14秒間)
+open-motion render -u http://localhost:5173 -o out.mp4 --duration 420
+
+# GIFへのレンダリング (30fpsで14秒間)
+open-motion render -u http://localhost:5173 -o out.gif --duration 420
+
+# WebPへのレンダリング (GIFより高品質)
+open-motion render -u http://localhost:5173 -o out.webp --duration 420
+
+# WebMへのレンダリング (透過ビデオをサポート)
+open-motion render -u http://localhost:5173 -o out.webm --duration 420
+```
+
+**長さの解説**: `--duration 420` は420フレームを意味します。30fpsの場合、420 ÷ 30 = **14秒** のビデオになります。
+
+### コンポジションの作成
+
+```tsx
+import { Composition, useCurrentFrame, interpolate } from "@open-motion/core";
+import { Transition, TikTokCaption } from "@open-motion/components";
+
+const MyScene = () => {
+  const frame = useCurrentFrame();
+  return (
+    <Transition type="fade">
+      <div style={{ flex: 1, backgroundColor: 'black', color: 'white' }}>
+        <TikTokCaption text="Hello OpenMotion" active={true} />
+      </div>
+    </Transition>
+  );
+};
+```
+
+**ポートに関する注意**: ポート5173が既に使用されている場合、Viteは自動的に5174, 5175などを試行します。実際のポート番号は開発サーバーの出力（例: "Local: http://localhost:5177/"）を確認してください。
+
+## 📚 APIリファレンス
+
+すべてのOpenMotion機能とコンポーネントの完全なリファレンス。
+
+### コアフック
+
+**`useCurrentFrame()`**
+アニメーションの現在のフレーム番号を取得します。
+
+```tsx
+const frame = useCurrentFrame();
+const opacity = interpolate(frame, [0, 30], [0, 1]);
+```
+
+**`useVideoConfig()`**
+ビデオ設定（width, height, fps, durationInFrames）にアクセスします。
+
+```tsx
+const { width, height, fps } = useVideoConfig();
+```
+
+### アニメーション & トランジション
+
+**`<Loop durationInFrames={30}>`**
+サブアニメーションのためのループする時間コンテキストを作成します。
+
+```tsx
+<Loop durationInFrames={60}>
+  <SpinningLogo />
+</Loop>
+```
+
+**`<Transition type="wipe" direction="right">`**
+スムーズな開始/終了トランジション。タイプ: `fade`, `wipe`, `slide`, `zoom`。
+
+```tsx
+<Transition type="wipe" direction="right">
+  <Title text="Hello World" />
+</Transition>
+```
+
+**`Easing.inOutExpo`**
+イージング機能の完全なライブラリ：
+- `Easing.linear`, `Easing.easeIn`, `Easing.easeOut`, `Easing.easeInOut`
+- `Easing.inOutCubic`, `Easing.outBack`, `Easing.inExpo` など
+
+```tsx
+const value = interpolate(frame, [0, 30], [0, 100], {
+  easing: Easing.outCubic,
+});
+```
+
+### 3D & Lottie 連携
+
+**`<ThreeCanvas />`**
+ビデオフレームと同期したThree.jsシーンをレンダリングします。詳細は `packages/components` を参照してください。
+
+**`<Lottie url="..." />`**
+フレーム精度の制御が可能な宣言的Lottieアニメーション。
+
+```tsx
+<Lottie url="/animations/logo.json" />
+```
+
+### メディア & キャプション
+
+**`<Audio src="..." volume={0.8} />`**
+独立した音量とタイミングを持つマルチトラック・オーディオサポート。
+
+```tsx
+<Audio src="/music.mp3" volume={0.5} startFrom={30} startFrame={60} />
+```
+
+**`parseSrt(srtContent)`**
+SRT字幕ファイルを配列に変換します。
+
+```tsx
+const subtitles = parseSrt(await fetch('/subtitles.srt').then(r => r.text()));
+```
+
+**`<Captions subtitles={subtitles} />`**
+スタイリングオプションを備えた柔軟な字幕レンダラー。
+
+```tsx
+<Captions subtitles={subtitles} color="white" fontSize={24} />
+```
+
+**`<TikTokCaption />`**
+TikTok風のアニメーション字幕のためのプリセット済みコンポーネント。
+
+**`getVideoMetadata(url)`**
+ビデオの解像度と長さを取得します。
+
+```tsx
+const { width, height, durationInSeconds } = await getVideoMetadata('/video.mp4');
+```
+
+**`<OffthreadVideo src="..." />`**
+バックグラウンドプロセスでの高性能ビデオデコード。
+
+### 出力 & エクスポートオプション
+
+**CLIコマンド**
+
+```bash
+# 基本的なレンダリング
+open-motion render -u http://localhost:5173 -o video.mp4
+
+# カスタム設定を使用
+open-motion render -u http://localhost:5173 -o video.mp4 \
+  --duration 420 \
+  --width 1920 \
+  --height 1080 \
+  --fps 30
+
+# GIFへのレンダリング
+open-motion render -u http://localhost:5173 -o animation.gif \
+  --duration 420 \
+  --public-dir ./public
+```
+
+**ファイル形式**
+- **MP4**: オーディオをサポートするフルビデオ (H.264)
+- **WebM**: 透過をサポートするWeb最適化ビデオ (VP9)
+- **GIF**: 軽量なアニメーション (オーディオなし)
+- **WebP**: 高品質なアニメーション画像 (GIFより優れ、オーディオなし)
+
+**品質パラメータ**
+- `--width`: 出力幅（ピクセル）
+- `--height`: 出力高さ（ピクセル）
+- `--fps`: フレーム数/秒 (デフォルト: 30)
+- `--duration`: 総フレーム数 (例: 420 = 30fpsで14秒)
+- `--format`: 明示的なフォーマット (mp4, webm, gif, webp, auto)
+
+## 📜 ライセンス
+
+MIT © [jsongo](https://github.com/jsongo)

From 02853c587e500d3c92bf2864b2b55e566e5854d6 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Wed, 25 Feb 2026 20:20:28 +0900
Subject: [PATCH 04/28] docs: restructure READMEs and add comprehensive CLI
 reference

---
 README.ja.md | 307 +++++++++++----------------------------------------
 README.md    | 300 ++++++++++---------------------------------------
 README.zh.md | 301 ++++++++++----------------------------------------
 3 files changed, 186 insertions(+), 722 deletions(-)

diff --git a/README.ja.md b/README.ja.md
index 56f3cad..c5efdae 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -10,9 +10,11 @@
 
 <p align="center">
   <a href="#-features">機能</a> •
+  <a href="#-packages">パッケージ</a> •
   <a href="#-installation">インストール</a> •
   <a href="#-quick-start">クイックスタート</a> •
-  <a href="#-packages">パッケージ</a>
+  <a href="#-cli-reference">CLI リファレンス</a> •
+  <a href="#-api-reference">API リファレンス</a>
 </p>
 
 ---
@@ -37,74 +39,15 @@ OpenMotionは、Remotionに代わる高性能なオープンソースの選択
 - 💬 **キャプションシステム**: SRTサポートとTikTokスタイルのアニメーションによる自動字幕レンダリング。
 - 📊 **メディア分析**: ビデオ/オーディオの動的なメタデータ抽出（長さ、解像度）。
 - 📹 **オフスレッドビデオ**: 高性能なビデオデコードをバックグラウンドプロセスに移行。
-- 📊 **動的メタデータ**: 入力プロップに基づいて、ビデオの解像度や長さなどのプロパティを動的に計算。
-- 🎬 **GIF & ビデオ出力**: 自動フォーマット検出により、MP4ビデオとGIFの両方の形式でレンダリング可能。
-
-### 4. ビデオのレンダリング (本番出力)
-
-レンダリングには、プロジェクトに組み込まれた `render` スクリプトの使用を推奨します。これは、**ビルド -> 静的サーバーの起動 -> レンダリング -> 自動クリーンアップ** という一連のプロセスを自動的に処理し、開発サーバーのバッファ問題によるフリーズを防ぎ、極めて堅牢なレンダリングを保証します。
-
-```bash
-# ワンクリックレンダリング (デフォルト出力: ./out.mp4、4スレッド並列)
-npm run render
-
-# 出力ファイル名の変更やコンポジションIDの指定 (引数を -- 経由で渡す)
-npm run render -- -o my-video.mp4 -c main
-```
-
-## 💡 ベストプラクティス
-
-### 堅牢なレンダリング
-本番環境では、常に `npm run render` を優先してください。このコマンドは内部で静的サーバーモードを使用しており、レンダリングのハングアップを完全に排除します。
-
-### 追加引数の受け渡し
-`npm run render -- [追加引数]` を使用してスクリプトのデフォルト値を上書きできます。
-- **並列数の変更**: `npm run render -- -j 8`
-- **Chromiumのパス指定**: `npm run render -- --chromium-path "/path/to/chrome"`
-
-### アセットの配置
-ローカルの画像やビデオアセットはすべて `public/` ディレクトリに配置し、コード内からは `/filename` パスで参照してください。
-
-## 🎬 出力形式のサポート
-- **.mp4**: 標準的なビデオ（オーディオ込み）。
-- **.webm**: 透過背景をサポートする高品質ビデオ。
-- **.gif**: アニメーション画像（オーディオなし）。
-- **.webp**: モダンなアニメーション形式。GIFより軽量で高品質。
-
-## 🛡️ 特徴的な機能
-- 🛡️ **実行前チェック**: ブラウザのインストール確認と環境検証機能を内蔵。
-- 🌍 **カスタムChromiumパス**: `--chromium-path` 引数によるブラウザパスのカスタマイズ。
-- 🚀 **Turbo Render**: ワンクリックの自動ビルドと自動レンダリングチェーン。
-
-## 📚 APIリファレンス
-
-ビデオプロパティを動的に計算する：
-
-```tsx
-<Composition
-  id="dynamic-video"
-  component={VideoComponent}
-  width={1280}
-  height={720}
-  fps={30}
-  durationInFrames={300}
-  calculateMetadata={async (props) => {
-    const meta = await getVideoMetadata(props.src);
-    return {
-      width: meta.width,
-      height: meta.height,
-      durationInFrames: Math.ceil(meta.durationInSeconds * 30)
-    };
-  }}
-/>
-```
+- 📊 **動的メタデータ**: ビデオの解像度や長さなどのプロパティを動的に計算。
+- 🎬 **GIF & ビデオ出力**: MP4, WebM, GIF, WebP形式でのレンダリングに対応。
 
 ## 📦 パッケージ
 
 | パッケージ | 説明 |
 | :--- | :--- |
-| [`@open-motion/core`](./packages/core) | Reactプリミティブ (`Composition`, `Sequence`, `Loop`), フック, メディアユーティリティ (`getVideoMetadata`, `parseSrt`)。 |
-| [`@open-motion/components`](./packages/components) | 高度なコンポーネント (`Transition`, `ThreeCanvas`, `Lottie`, `Captions`, `TikTokCaption`)。 |
+| [`@open-motion/core`](./packages/core) | Reactプリミティブ (`Composition`, `Sequence`, `Loop`), フック, メディアユーティリティ。 |
+| [`@open-motion/components`](./packages/components) | 高度なコンポーネント (`Transition`, `ThreeCanvas`, `Lottie`, `Captions`)。 |
 | [`@open-motion/renderer`](./packages/renderer) | Playwrightベースのキャプチャエンジン。 |
 | [`@open-motion/cli`](./packages/cli) | コマンドラインインターフェース。 |
 
@@ -116,203 +59,81 @@ npm install @open-motion/core @open-motion/components
 
 ## 🚀 クイックスタート
 
-### セットアップ
-
+### 1. セットアップ
+CLIツールと必要なブラウザをインストールします：
 ```bash
-# CLIツールをグローバルにインストール
 pnpm install -g @open-motion/cli @open-motion/renderer
-
-# Playwrightブラウザをインストール (レンダリングに必要)
 npx playwright install chromium
 ```
 
-### プロジェクトの作成と実行
-
+### 2. プロジェクトの作成
 ```bash
-# 新規プロジェクトの作成
-open-motion init fun-video
-cd fun-video && pnpm install
-
-# 開発サーバーの起動
-# ターミナルで実行 - ポート番号が表示されます (例: 5173)
-pnpm run dev
+open-motion init my-video
+cd my-video && pnpm install
 ```
 
-**注意**: このターミナルは開いたままにしてください。ポート5173が使用中の場合、Viteは自動的に5174, 5175などを試行します。実際のポート番号は出力を確認してください。
-
-### ビデオのレンダリング
-
-別のターミナルで、上記のポートを使用してプロジェクトをレンダリングします：
-
+### 3. 開発とレンダリング
+ターミナルで開発サーバーを起動します：
 ```bash
-# MP4へのレンダリング (30fpsで14秒間)
-open-motion render -u http://localhost:5173 -o out.mp4 --duration 420
-
-# GIFへのレンダリング (30fpsで14秒間)
-open-motion render -u http://localhost:5173 -o out.gif --duration 420
-
-# WebPへのレンダリング (GIFより高品質)
-open-motion render -u http://localhost:5173 -o out.webp --duration 420
-
-# WebMへのレンダリング (透過ビデオをサポート)
-open-motion render -u http://localhost:5173 -o out.webm --duration 420
-```
-
-**長さの解説**: `--duration 420` は420フレームを意味します。30fpsの場合、420 ÷ 30 = **14秒** のビデオになります。
-
-### コンポジションの作成
-
-```tsx
-import { Composition, useCurrentFrame, interpolate } from "@open-motion/core";
-import { Transition, TikTokCaption } from "@open-motion/components";
-
-const MyScene = () => {
-  const frame = useCurrentFrame();
-  return (
-    <Transition type="fade">
-      <div style={{ flex: 1, backgroundColor: 'black', color: 'white' }}>
-        <TikTokCaption text="Hello OpenMotion" active={true} />
-      </div>
-    </Transition>
-  );
-};
-```
-
-**ポートに関する注意**: ポート5173が既に使用されている場合、Viteは自動的に5174, 5175などを試行します。実際のポート番号は開発サーバーの出力（例: "Local: http://localhost:5177/"）を確認してください。
-
-## 📚 APIリファレンス
-
-すべてのOpenMotion機能とコンポーネントの完全なリファレンス。
-
-### コアフック
-
-**`useCurrentFrame()`**
-アニメーションの現在のフレーム番号を取得します。
-
-```tsx
-const frame = useCurrentFrame();
-const opacity = interpolate(frame, [0, 30], [0, 1]);
-```
-
-**`useVideoConfig()`**
-ビデオ設定（width, height, fps, durationInFrames）にアクセスします。
-
-```tsx
-const { width, height, fps } = useVideoConfig();
-```
-
-### アニメーション & トランジション
-
-**`<Loop durationInFrames={30}>`**
-サブアニメーションのためのループする時間コンテキストを作成します。
-
-```tsx
-<Loop durationInFrames={60}>
-  <SpinningLogo />
-</Loop>
-```
-
-**`<Transition type="wipe" direction="right">`**
-スムーズな開始/終了トランジション。タイプ: `fade`, `wipe`, `slide`, `zoom`。
-
-```tsx
-<Transition type="wipe" direction="right">
-  <Title text="Hello World" />
-</Transition>
-```
-
-**`Easing.inOutExpo`**
-イージング機能の完全なライブラリ：
-- `Easing.linear`, `Easing.easeIn`, `Easing.easeOut`, `Easing.easeInOut`
-- `Easing.inOutCubic`, `Easing.outBack`, `Easing.inExpo` など
-
-```tsx
-const value = interpolate(frame, [0, 30], [0, 100], {
-  easing: Easing.outCubic,
-});
-```
-
-### 3D & Lottie 連携
-
-**`<ThreeCanvas />`**
-ビデオフレームと同期したThree.jsシーンをレンダリングします。詳細は `packages/components` を参照してください。
-
-**`<Lottie url="..." />`**
-フレーム精度の制御が可能な宣言的Lottieアニメーション。
-
-```tsx
-<Lottie url="/animations/logo.json" />
-```
-
-### メディア & キャプション
-
-**`<Audio src="..." volume={0.8} />`**
-独立した音量とタイミングを持つマルチトラック・オーディオサポート。
-
-```tsx
-<Audio src="/music.mp3" volume={0.5} startFrom={30} startFrame={60} />
-```
-
-**`parseSrt(srtContent)`**
-SRT字幕ファイルを配列に変換します。
-
-```tsx
-const subtitles = parseSrt(await fetch('/subtitles.srt').then(r => r.text()));
-```
-
-**`<Captions subtitles={subtitles} />`**
-スタイリングオプションを備えた柔軟な字幕レンダラー。
-
-```tsx
-<Captions subtitles={subtitles} color="white" fontSize={24} />
+pnpm run dev
 ```
-
-**`<TikTokCaption />`**
-TikTok風のアニメーション字幕のためのプリセット済みコンポーネント。
-
-**`getVideoMetadata(url)`**
-ビデオの解像度と長さを取得します。
-
-```tsx
-const { width, height, durationInSeconds } = await getVideoMetadata('/video.mp4');
+別のターミナルで、サーバーのURLを使用してビデオをレンダリングします：
+```bash
+open-motion render -u http://localhost:5173 -o out.mp4
 ```
 
-**`<OffthreadVideo src="..." />`**
-バックグラウンドプロセスでの高性能ビデオデコード。
-
-### 出力 & エクスポートオプション
+## 💻 CLI リファレンス
 
-**CLIコマンド**
+### `open-motion init <name>`
+事前設定されたReactテンプレートを使用して、新しいOpenMotionプロジェクトを初期化します。
 
-```bash
-# 基本的なレンダリング
-open-motion render -u http://localhost:5173 -o video.mp4
+### `open-motion render`
+実行中のOpenMotionアプリケーションからビデオをレンダリングします。
 
-# カスタム設定を使用
-open-motion render -u http://localhost:5173 -o video.mp4 \
-  --duration 420 \
-  --width 1920 \
-  --height 1080 \
-  --fps 30
+| オプション | 説明 |
+| :--- | :--- |
+| `-u, --url <url>` | **必須。** OpenMotionアプリのURL (例: `http://localhost:5173`) |
+| `-o, --out <path>` | **必須。** 出力ファイルパス (例: `out.mp4`, `animation.gif`) |
+| `-c, --composition <id>` | レンダリングするコンポジションのID |
+| `-p, --props <json>` | コンポジションに渡すプロップのJSON文字列 |
+| `-j, --concurrency <n>` | 並列ブラウザインスタンスの数 (デフォルト: 1) |
+| `--format <format>` | 出力形式: `mp4`, `webm`, `gif`, `webp`, `auto` |
+| `--width <number>` | 出力幅を上書き |
+| `--height <number>` | 出力高さを上書き |
+| `--fps <number>` | フレームレート(FPS)を上書き |
+| `--duration <number>` | レンダリングする総フレーム数を上書き |
+| `--public-dir <path>` | 静的アセットの公開ディレクトリ (デフォルト: `./public`) |
+| `--chromium-path <path>`| カスタムChromium実行ファイルのパス |
+| `--timeout <number>` | ブラウザ操作のタイムアウト (ミリ秒) |
+
+## 📚 API リファレンス
+
+### コアフックと設定
+**`useCurrentFrame()`**: 現在のフレーム番号を取得します。
+**`useVideoConfig()`**: 幅、高さ、fps、長さにアクセスします。
+
+### コンポーネント
+- **`<Loop />`**: ループする時間コンテキストを作成します。
+- **`<Transition />`**: スムーズな開始/終了エフェクト (`fade`, `wipe`, `slide`, `zoom`)。
+- **`<ThreeCanvas />`**: 同期されたThree.jsシーンをレンダリングします。
+- **`<Lottie />`**: 宣言的なLottieアニメーション。
+- **`<Audio />`**: 音量制御可能なマルチトラックオーディオ。
+- **`<Captions />`** / **`<TikTokCaption />`**: 字幕レンダリング。
+- **`<OffthreadVideo />`**: 高性能なバックグラウンドビデオデコード。
+
+### ユーティリティ
+- **`interpolate()`**: イージングをサポートする範囲マッピング。
+- **`Easing`**: イージング関数の完全なライブラリ。
+- **`parseSrt()`**: SRTファイルをデータ構造に変換します。
+- **`getVideoMetadata()`**: ビデオファイルの解像度と長さを取得します。
 
-# GIFへのレンダリング
-open-motion render -u http://localhost:5173 -o animation.gif \
-  --duration 420 \
-  --public-dir ./public
-```
+## 💡 ベストプラクティス
 
-**ファイル形式**
-- **MP4**: オーディオをサポートするフルビデオ (H.264)
-- **WebM**: 透過をサポートするWeb最適化ビデオ (VP9)
-- **GIF**: 軽量なアニメーション (オーディオなし)
-- **WebP**: 高品質なアニメーション画像 (GIFより優れ、オーディオなし)
+### 堅牢なレンダリング
+本番環境では、プロジェクト組み込みの `npm run render` スクリプトを使用してください。これは **ビルド -> 静的サーバー -> レンダリング -> クリーンアップ** の全工程を処理し、バッファ問題を回避します。
 
-**品質パラメータ**
-- `--width`: 出力幅（ピクセル）
-- `--height`: 出力高さ（ピクセル）
-- `--fps`: フレーム数/秒 (デフォルト: 30)
-- `--duration`: 総フレーム数 (例: 420 = 30fpsで14秒)
-- `--format`: 明示的なフォーマット (mp4, webm, gif, webp, auto)
+### アセットの保存
+ローカルアセットはすべて `public/` に配置し、絶対パス（例: `/video.mp4`）で参照してください。
 
 ## 📜 ライセンス
 
diff --git a/README.md b/README.md
index eb567a1..8236c2b 100644
--- a/README.md
+++ b/README.md
@@ -10,9 +10,11 @@
 
 <p align="center">
   <a href="#-features">Features</a> •
+  <a href="#-packages">Packages</a> •
   <a href="#-installation">Installation</a> •
   <a href="#-quick-start">Quick Start</a> •
-  <a href="#-packages">Packages</a>
+  <a href="#-cli-reference">CLI Reference</a> •
+  <a href="#-api-reference">API Reference</a>
 </p>
 
 ---
@@ -37,73 +39,15 @@ OpenMotion is a high-performance, open-source alternative to Remotion. It allows
 - 💬 **Caption System**: Automated subtitle rendering with SRT support and TikTok-style animations.
 - 📊 **Media Analysis**: Dynamic metadata extraction for video/audio (duration, dimensions).
 - 📹 **Offthread Video**: High-performance video decoding moved to background processes.
-- 📊 **Dynamic Metadata**: Calculate video dimensions, duration, and other properties dynamically based on input props.
-- 🎬 **GIF & Video Output**: Render to both MP4 video and GIF formats with automatic format detection.
-### 4. Render Video (Production Output)
-
-It is recommended to use the project's built-in `render` script for rendering. It automatically handles the full pipeline of **build -> start static server -> render -> cleanup**, ensuring a robust rendering process that won't hang due to dev server buffer issues.
-
-```bash
-# One-click render (default output: ./out.mp4, 4 parallel threads)
-npm run render
-
-# Override the output filename or specify a composition ID (pass args via --)
-npm run render -- -o my-video.mp4 -c main
-```
-
-## 💡 Best Practices
-
-### Robust Rendering
-For production environments, always prefer `npm run render`. This command uses static server mode internally, completely eliminating the risk of rendering hangs.
-
-### Passing Additional Arguments
-You can override the script's defaults via `npm run render -- [additional args]`:
-- **Change concurrency**: `npm run render -- -j 8`
-- **Specify Chromium path**: `npm run render -- --chromium-path "/path/to/chrome"`
-
-### Asset Storage
-Place all local image/video assets in the `public/` directory and reference them in code using `/filename` paths.
-
-## 🎬 Output Format Support
-- **.mp4**: Standard video with audio.
-- **.webm**: High-quality video with transparency support.
-- **.gif**: Animated images without audio.
-- **.webp**: Modern animated format — smaller file size, better quality than GIF.
-
-## 🛡️ Notable Features
-- 🛡️ **Pre-Flight Checks**: Built-in browser installation checks and environment validation.
-- 🌍 **Custom Chromium Path**: Specify a custom browser path via the `--chromium-path` argument.
-- 🚀 **Turbo Render**: One-click automated build and full rendering pipeline.
-
-## 📚 API Reference
-
-Calculate video properties dynamically:
-
-```tsx
-<Composition
-  id="dynamic-video"
-  component={VideoComponent}
-  width={1280}
-  height={720}
-  fps={30}
-  durationInFrames={300}
-  calculateMetadata={async (props) => {
-    const meta = await getVideoMetadata(props.src);
-    return {
-      width: meta.width,
-      height: meta.height,
-      durationInFrames: Math.ceil(meta.durationInSeconds * 30)
-    };
-  }}
-/>
-```
+- 📊 **Dynamic Metadata**: Calculate video dimensions, duration, and other properties dynamically.
+- 🎬 **GIF & Video Output**: Render to MP4, WebM, GIF, and WebP formats.
 
 ## 📦 Packages
 
 | Package | Description |
 | :--- | :--- |
-| [`@open-motion/core`](./packages/core) | React primitives (`Composition`, `Sequence`, `Loop`), hooks, and media utils (`getVideoMetadata`, `parseSrt`). |
-| [`@open-motion/components`](./packages/components) | High-level components (`Transition`, `ThreeCanvas`, `Lottie`, `Captions`, `TikTokCaption`). |
+| [`@open-motion/core`](./packages/core) | React primitives (`Composition`, `Sequence`, `Loop`), hooks, and media utils. |
+| [`@open-motion/components`](./packages/components) | High-level components (`Transition`, `ThreeCanvas`, `Lottie`, `Captions`). |
 | [`@open-motion/renderer`](./packages/renderer) | Playwright-based capture engine. |
 | [`@open-motion/cli`](./packages/cli) | Command-line interface. |
 
@@ -115,203 +59,81 @@ npm install @open-motion/core @open-motion/components
 
 ## 🚀 Quick Start
 
-### Installation
-
+### 1. Setup
+Install CLI tools and required browsers:
 ```bash
-# Install CLI tools globally
 pnpm install -g @open-motion/cli @open-motion/renderer
-
-# Install Playwright browsers (required for rendering)
 npx playwright install chromium
 ```
 
-### Create & Run Your First Project
-
+### 2. Create Project
 ```bash
-# Create a new project
-open-motion init fun-video
-cd fun-video && pnpm install
+open-motion init my-video
+cd my-video && pnpm install
+```
 
-# Start development server
-# Run this in one terminal - it will show the port (e.g. 5173)
+### 3. Develop & Render
+Start the dev server in one terminal:
+```bash
 pnpm run dev
 ```
-
-**Note**: Keep this terminal open. If port 5173 is in use, Vite will automatically try 5174, 5175, etc. Check the output for the actual port number.
-
-### Render Your Video
-
-In another terminal, render your project using the port from above:
-
+In another terminal, render your video using the server URL:
 ```bash
-# Render to MP4 (14 seconds at 30fps)
-open-motion render -u http://localhost:5173 -o out.mp4 --duration 420
-
-# Render to GIF (14 seconds at 30fps)
-open-motion render -u http://localhost:5173 -o out.gif --duration 420
-
-# Render to WebP (better quality than GIF)
-open-motion render -u http://localhost:5173 -o out.webp --duration 420
-
-# Render to WebM (transparent video support)
-open-motion render -u http://localhost:5173 -o out.webm --duration 420
+open-motion render -u http://localhost:5173 -o out.mp4
 ```
 
-**Duration explained**: `--duration 420` means 420 frames. At 30fps, that's 420 ÷ 30 = **14 seconds** of video.
-
-### Create a Composition
+## 💻 CLI Reference
 
-```tsx
-import { Composition, useCurrentFrame, interpolate } from "@open-motion/core";
-import { Transition, TikTokCaption } from "@open-motion/components";
+### `open-motion init <name>`
+Initialize a new OpenMotion project with a pre-configured React template.
 
-const MyScene = () => {
-  const frame = useCurrentFrame();
-  return (
-    <Transition type="fade">
-      <div style={{ flex: 1, backgroundColor: 'black', color: 'white' }}>
-        <TikTokCaption text="Hello OpenMotion" active={true} />
-      </div>
-    </Transition>
-  );
-};
-```
+### `open-motion render`
+Render a video from a running OpenMotion application.
 
-**Note about ports**: If port 5173 is already in use, Vite will automatically try 5174, 5175, etc. Check the dev server output for the actual port number (e.g., "Local: http://localhost:5177/").
+| Option | Description |
+| :--- | :--- |
+| `-u, --url <url>` | **Required.** URL of the OpenMotion app (e.g., `http://localhost:5173`) |
+| `-o, --out <path>` | **Required.** Output file path (e.g., `out.mp4`, `animation.gif`) |
+| `-c, --composition <id>` | ID of the composition to render |
+| `-p, --props <json>` | JSON string of props to pass to the composition |
+| `-j, --concurrency <n>` | Number of parallel browser instances (default: 1) |
+| `--format <format>` | Output format: `mp4`, `webm`, `gif`, `webp`, `auto` |
+| `--width <number>` | Override output width |
+| `--height <number>` | Override output height |
+| `--fps <number>` | Override frames per second |
+| `--duration <number>` | Override total frames to render |
+| `--public-dir <path>` | Public directory for static assets (default: `./public`) |
+| `--chromium-path <path>`| Path to custom Chromium executable |
+| `--timeout <number>` | Timeout for browser operations in ms |
 
 ## 📚 API Reference
 
-Complete reference for all OpenMotion features and components.
-
-### Core Hooks
-
-**`useCurrentFrame()`**
-Get the current frame number in your animation.
-
-```tsx
-const frame = useCurrentFrame();
-const opacity = interpolate(frame, [0, 30], [0, 1]);
-```
-
-**`useVideoConfig()`**
-Access video configuration (width, height, fps, durationInFrames).
-
-```tsx
-const { width, height, fps } = useVideoConfig();
-```
-
-### Animation & Transitions
-
-**`<Loop durationInFrames={30}>`**
-Create looping time contexts for sub-animations.
-
-```tsx
-<Loop durationInFrames={60}>
-  <SpinningLogo />
-</Loop>
-```
-
-**`<Transition type="wipe" direction="right">`**
-Smooth enter/exit transitions. Types: `fade`, `wipe`, `slide`, `zoom`.
-
-```tsx
-<Transition type="wipe" direction="right">
-  <Title text="Hello World" />
-</Transition>
-```
-
-**`Easing.inOutExpo`**
-Complete library of easing functions:
-- `Easing.linear`, `Easing.easeIn`, `Easing.easeOut`, `Easing.easeInOut`
-- `Easing.inOutCubic`, `Easing.outBack`, `Easing.inExpo`, and more
-
-```tsx
-const value = interpolate(frame, [0, 30], [0, 100], {
-  easing: Easing.outCubic,
-});
-```
-
-### 3D & Lottie Integration
-
-**`<ThreeCanvas />`**
-Render Three.js scenes synced with video frames. See `packages/components` for details.
-
-**`<Lottie url="..." />`**
-Declarative Lottie animations with frame-accurate control.
-
-```tsx
-<Lottie url="/animations/logo.json" />
-```
-
-### Media & Captions
-
-**`<Audio src="..." volume={0.8} />`**
-Multi-track audio support with independent volume and timing.
-
-```tsx
-<Audio src="/music.mp3" volume={0.5} startFrom={30} startFrame={60} />
-```
+### Core Hooks & Configuration
+**`useCurrentFrame()`**: Get the current frame number.
+**`useVideoConfig()`**: Access width, height, fps, and duration.
+
+### Components
+- **`<Loop />`**: Create looping time contexts.
+- **`<Transition />`**: Smooth enter/exit effects (`fade`, `wipe`, `slide`, `zoom`).
+- **`<ThreeCanvas />`**: Render synced Three.js scenes.
+- **`<Lottie />`**: Declarative Lottie animations.
+- **`<Audio />`**: Multi-track audio with volume control.
+- **`<Captions />`** / **`<TikTokCaption />`**: Subtitle rendering.
+- **`<OffthreadVideo />`**: High-performance background video decoding.
+
+### Utilities
+- **`interpolate()`**: Map ranges with easing support.
+- **`Easing`**: Complete library of easing functions.
+- **`parseSrt()`**: Convert SRT files to data structures.
+- **`getVideoMetadata()`**: Fetch dimensions and duration of video files.
 
-**`parseSrt(srtContent)`**
-Convert SRT subtitle files to arrays.
-
-```tsx
-const subtitles = parseSrt(await fetch('/subtitles.srt').then(r => r.text()));
-```
-
-**`<Captions subtitles={subtitles} />`**
-Flexible subtitle renderer with styling options.
-
-```tsx
-<Captions subtitles={subtitles} color="white" fontSize={24} />
-```
-
-**`<TikTokCaption />`**
-Pre-styled component for TikTok-like animated captions.
-
-**`getVideoMetadata(url)`**
-Fetch video dimensions and duration.
-
-```tsx
-const { width, height, durationInSeconds } = await getVideoMetadata('/video.mp4');
-```
-
-**`<OffthreadVideo src="..." />`**
-High-performance video decoding in background processes.
-
-### Output & Export Options
-
-**CLI Commands**
-
-```bash
-# Basic rendering
-open-motion render -u http://localhost:5173 -o video.mp4
-
-# With custom settings
-open-motion render -u http://localhost:5173 -o video.mp4 \
-  --duration 420 \
-  --width 1920 \
-  --height 1080 \
-  --fps 30
-
-# Render to GIF
-open-motion render -u http://localhost:5173 -o animation.gif \
-  --duration 420 \
-  --public-dir ./public
-```
+## 💡 Best Practices
 
-**File Formats**
-- **MP4**: Full video with audio support (H.264)
-- **WebM**: Web-optimized video with transparency support (VP9)
-- **GIF**: Lightweight animations (no audio)
-- **WebP**: High-quality animated images (better than GIF, no audio)
+### Robust Rendering
+For production, use the project's built-in `npm run render` script. It handles the full **build -> static server -> render -> cleanup** pipeline, eliminating buffer issues.
 
-**Quality Parameters**
-- `--width`: Output width in pixels
-- `--height`: Output height in pixels
-- `--fps`: Frames per second (default: 30)
-- `--duration`: Total frames (e.g., 420 = 14 seconds at 30fps)
-- `--format`: Explicit format (mp4, webm, gif, webp, auto)
+### Asset Storage
+Place all local assets in `public/` and reference them via absolute paths (e.g., `/video.mp4`).
 
 ## 📜 License
 
diff --git a/README.zh.md b/README.zh.md
index b7c0ffe..50890d0 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -10,9 +10,11 @@
 
 <p align="center">
   <a href="#-features">特性</a> •
+  <a href="#-packages">软件包</a> •
   <a href="#-installation">安装</a> •
   <a href="#-quick-start">快速开始</a> •
-  <a href="#-packages">软件包</a>
+  <a href="#-cli-reference">CLI 参考</a> •
+  <a href="#-api-reference">API 参考</a>
 </p>
 
 ---
@@ -37,74 +39,15 @@ OpenMotion 是 Remotion 的高性能开源替代方案。它允许你使用熟
 - 💬 **字幕系统**: 自动化字幕渲染，支持 SRT 和 TikTok 风格动画。
 - 📊 **媒体分析**: 动态提取视频/音频元数据（时长、尺寸）。
 - 📹 **离线视频**: 高性能视频解码移至后台进程。
-- 📊 **动态元数据**: 根据输入 props 动态计算视频尺寸、时长等属性。
-- 🎬 **GIF & 视频输出**: 支持渲染为 MP4 视频和 GIF 格式，具有自动格式检测。
-
-### 4. 渲染视频 (正式出片)
-
-推荐使用项目自带的 `render` 脚本进行渲染。它会自动完成 **构建 -> 启动静态服务 -> 渲染 -> 自动清理** 的全套流程，确保渲染过程极其稳健，不会因开发服务器缓冲区问题而卡死。
-
-```bash
-# 一键渲染 (默认输出 ./out.mp4，开启 4 线程并行)
-npm run render
-
-# 修改输出文件名或指定合成 ID (通过 -- 透传参数)
-npm run render -- -o my-video.mp4 -c main
-```
-
-## 💡 最佳实践
-
-### 稳健渲染方案
-生产环境建议始终优先使用 `npm run render`。该命令内部使用了静态服务模式，彻底告别渲染卡死。
-
-### 参数透传技巧
-你可以通过 `npm run render -- [更多参数]` 覆盖脚本中的默认值：
-- **修改并发数**: `npm run render -- -j 8`
-- **指定 Chromium 路径**: `npm run render -- --chromium-path "/path/to/chrome"`
-
-### 资源存放
-所有本地图片/视频资源请放在 `public/` 目录下，在代码中通过 `/filename` 路径引用。
-
-## 🎬 输出格式支持
-- **.mp4**: 标准视频，包含音频。
-- **.webm**: 支持透明背景的高质量视频。
-- **.gif**: 动态图片，不含音频。
-- **.webp**: 现代动图格式，体积更小，质量更好。
-
-## 🛡️ 特色功能
-- 🛡️ **运行前检查**: 内置浏览器安装检查与环境验证。
-- 🌍 **自定义 Chromium 路径**: 支持通过 `--chromium-path` 参数自定义浏览器路径。
-- 🚀 **快速渲染**: 一键自动化构建与全自动渲染链条。
-
-## 📚 API 参考
-
-动态计算视频属性：
-
-```tsx
-<Composition
-  id="dynamic-video"
-  component={VideoComponent}
-  width={1280}
-  height={720}
-  fps={30}
-  durationInFrames={300}
-  calculateMetadata={async (props) => {
-    const meta = await getVideoMetadata(props.src);
-    return {
-      width: meta.width,
-      height: meta.height,
-      durationInFrames: Math.ceil(meta.durationInSeconds * 30)
-    };
-  }}
-/>
-```
+- 📊 **动态元数据**: 动态计算视频尺寸、时长等属性。
+- 🎬 **GIF & 视频输出**: 渲染为 MP4、WebM、GIF 和 WebP 格式。
 
 ## 📦 软件包
 
 | 软件包 | 描述 |
 | :--- | :--- |
-| [`@open-motion/core`](./packages/core) | React 基元 (`Composition`, `Sequence`, `Loop`), Hooks, 以及媒体工具 (`getVideoMetadata`, `parseSrt`)。 |
-| [`@open-motion/components`](./packages/components) | 高级组件 (`Transition`, `ThreeCanvas`, `Lottie`, `Captions`, `TikTokCaption`)。 |
+| [`@open-motion/core`](./packages/core) | React 基元 (`Composition`, `Sequence`, `Loop`), Hooks, 以及媒体工具。 |
+| [`@open-motion/components`](./packages/components) | 高级组件 (`Transition`, `ThreeCanvas`, `Lottie`, `Captions`)。 |
 | [`@open-motion/renderer`](./packages/renderer) | 基于 Playwright 的捕获引擎。 |
 | [`@open-motion/cli`](./packages/cli) | 命令行界面。 |
 
@@ -116,203 +59,81 @@ npm install @open-motion/core @open-motion/components
 
 ## 🚀 快速开始
 
-### 安装
-
+### 1. 设置
+安装 CLI 工具和必需的浏览器：
 ```bash
-# 全局安装 CLI 工具
 pnpm install -g @open-motion/cli @open-motion/renderer
-
-# 安装 Playwright 浏览器 (渲染必需)
 npx playwright install chromium
 ```
 
-### 创建并运行你的第一个项目
-
+### 2. 创建项目
 ```bash
-# 创建新项目
-open-motion init fun-video
-cd fun-video && pnpm install
+open-motion init my-video
+cd my-video && pnpm install
+```
 
-# 启动开发服务器
-# 在一个终端运行 - 它会显示端口 (例如 5173)
+### 3. 开发与渲染
+在一个终端中启动开发服务器：
+```bash
 pnpm run dev
 ```
-
-**注意**: 保持此终端开启。如果端口 5173 已被占用，Vite 会自动尝试 5174, 5175 等。请检查输出以获取实际端口号。
-
-### 渲染你的视频
-
-在另一个终端中，使用上面的端口渲染项目：
-
+在另一个终端中，使用服务器 URL 渲染视频：
 ```bash
-# 渲染为 MP4 (30fps 下 14 秒)
-open-motion render -u http://localhost:5173 -o out.mp4 --duration 420
-
-# 渲染为 GIF (30fps 下 14 秒)
-open-motion render -u http://localhost:5173 -o out.gif --duration 420
-
-# 渲染为 WebP (质量优于 GIF)
-open-motion render -u http://localhost:5173 -o out.webp --duration 420
-
-# 渲染为 WebM (支持透明视频)
-open-motion render -u http://localhost:5173 -o out.webm --duration 420
+open-motion render -u http://localhost:5173 -o out.mp4
 ```
 
-**时长解释**: `--duration 420` 表示 420 帧。在 30fps 下，即 420 ÷ 30 = **14 秒** 视频。
-
-### 创建一个 Composition
+## 💻 CLI 参考
 
-```tsx
-import { Composition, useCurrentFrame, interpolate } from "@open-motion/core";
-import { Transition, TikTokCaption } from "@open-motion/components";
+### `open-motion init <name>`
+使用预配置的 React 模板初始化一个新的 OpenMotion 项目。
 
-const MyScene = () => {
-  const frame = useCurrentFrame();
-  return (
-    <Transition type="fade">
-      <div style={{ flex: 1, backgroundColor: 'black', color: 'white' }}>
-        <TikTokCaption text="Hello OpenMotion" active={true} />
-      </div>
-    </Transition>
-  );
-};
-```
+### `open-motion render`
+从正在运行的 OpenMotion 应用程序渲染视频。
 
-**关于端口的注意**: 如果端口 5173 已被占用，Vite 会自动尝试 5174, 5175 等。请查看开发服务器输出以获取实际端口号 (例如 "Local: http://localhost:5177/")。
+| 选项 | 描述 |
+| :--- | :--- |
+| `-u, --url <url>` | **必需。** OpenMotion 应用的 URL (例如 `http://localhost:5173`) |
+| `-o, --out <path>` | **必需。** 输出文件路径 (例如 `out.mp4`, `animation.gif`) |
+| `-c, --composition <id>` | 要渲染的合成 ID |
+| `-p, --props <json>` | 传递给合成的 props JSON 字符串 |
+| `-j, --concurrency <n>` | 并行浏览器实例数量 (默认: 1) |
+| `--format <format>` | 输出格式: `mp4`, `webm`, `gif`, `webp`, `auto` |
+| `--width <number>` | 覆盖输出宽度 |
+| `--height <number>` | 覆盖输出高度 |
+| `--fps <number>` | 覆盖每秒帧数 |
+| `--duration <number>` | 覆盖要渲染的总帧数 |
+| `--public-dir <path>` | 静态资源的公共目录 (默认: `./public`) |
+| `--chromium-path <path>`| 自定义 Chromium 可执行文件路径 |
+| `--timeout <number>` | 浏览器操作超时时间 (毫秒) |
 
 ## 📚 API 参考
 
-所有 OpenMotion 特性和组件的完整参考。
-
-### 核心 Hooks
+### 核心 Hooks 与配置
+**`useCurrentFrame()`**: 获取当前帧数。
+**`useVideoConfig()`**: 访问宽度、高度、fps 和时长。
+
+### 组件
+- **`<Loop />`**: 创建循环的时间上下文。
+- **`<Transition />`**: 平滑的进入/退出效果 (`fade`, `wipe`, `slide`, `zoom`)。
+- **`<ThreeCanvas />`**: 渲染同步的 Three.js 场景。
+- **`<Lottie />`**: 声明式 Lottie 动画。
+- **`<Audio />`**: 具有音量控制的多轨音频。
+- **`<Captions />`** / **`<TikTokCaption />`**: 字幕渲染。
+- **`<OffthreadVideo />`**: 高性能后台视频解码。
+
+### 工具函数
+- **`interpolate()`**: 支持缓动的范围映射。
+- **`Easing`**: 完整的缓动函数库。
+- **`parseSrt()`**: 将 SRT 文件转换为数据结构。
+- **`getVideoMetadata()`**: 获取视频文件的尺寸和时长。
 
-**`useCurrentFrame()`**
-获取动画中的当前帧数。
-
-```tsx
-const frame = useCurrentFrame();
-const opacity = interpolate(frame, [0, 30], [0, 1]);
-```
-
-**`useVideoConfig()`**
-访问视频配置 (width, height, fps, durationInFrames)。
-
-```tsx
-const { width, height, fps } = useVideoConfig();
-```
-
-### 动画 & 过渡
-
-**`<Loop durationInFrames={30}>`**
-为子动画创建循环的时间上下文。
-
-```tsx
-<Loop durationInFrames={60}>
-  <SpinningLogo />
-</Loop>
-```
-
-**`<Transition type="wipe" direction="right">`**
-平滑的进入/退出过渡。类型：`fade`, `wipe`, `slide`, `zoom`。
-
-```tsx
-<Transition type="wipe" direction="right">
-  <Title text="Hello World" />
-</Transition>
-```
-
-**`Easing.inOutExpo`**
-完整的缓动函数库：
-- `Easing.linear`, `Easing.easeIn`, `Easing.easeOut`, `Easing.easeInOut`
-- `Easing.inOutCubic`, `Easing.outBack`, `Easing.inExpo` 等
-
-```tsx
-const value = interpolate(frame, [0, 30], [0, 100], {
-  easing: Easing.outCubic,
-});
-```
-
-### 3D & Lottie 集成
-
-**`<ThreeCanvas />`**
-渲染与视频帧同步的 Three.js 场景。详情见 `packages/components`。
-
-**`<Lottie url="..." />`**
-具有帧准确控制的声明式 Lottie 动画。
-
-```tsx
-<Lottie url="/animations/logo.json" />
-```
-
-### 媒体 & 字幕
-
-**`<Audio src="..." volume={0.8} />`**
-多轨音频支持，具有独立音量和定时。
-
-```tsx
-<Audio src="/music.mp3" volume={0.5} startFrom={30} startFrame={60} />
-```
-
-**`parseSrt(srtContent)`**
-将 SRT 字幕文件转换为数组。
-
-```tsx
-const subtitles = parseSrt(await fetch('/subtitles.srt').then(r => r.text()));
-```
-
-**`<Captions subtitles={subtitles} />`**
-具有样式选项的灵活字幕渲染器。
-
-```tsx
-<Captions subtitles={subtitles} color="white" fontSize={24} />
-```
-
-**`<TikTokCaption />`**
-预设样式的 TikTok 类动画字幕组件。
-
-**`getVideoMetadata(url)`**
-获取视频尺寸和时长。
-
-```tsx
-const { width, height, durationInSeconds } = await getVideoMetadata('/video.mp4');
-```
-
-**`<OffthreadVideo src="..." />`**
-后台进程中的高性能视频解码。
-
-### 输出 & 导出选项
-
-**CLI 命令**
-
-```bash
-# 基础渲染
-open-motion render -u http://localhost:5173 -o video.mp4
-
-# 使用自定义设置
-open-motion render -u http://localhost:5173 -o video.mp4 \
-  --duration 420 \
-  --width 1920 \
-  --height 1080 \
-  --fps 30
-
-# 渲染为 GIF
-open-motion render -u http://localhost:5173 -o animation.gif \
-  --duration 420 \
-  --public-dir ./public
-```
+## 💡 最佳实践
 
-**文件格式**
-- **MP4**: 包含音频支持的完整视频 (H.264)
-- **WebM**: 支持透明度的 Web 优化视频 (VP9)
-- **GIF**: 轻量级动画 (无音频)
-- **WebP**: 高质量动画图像 (优于 GIF，无音频)
+### 稳健渲染
+对于生产环境，请使用项目自带的 `npm run render` 脚本。它处理完整的 **构建 -> 静态服务 -> 渲染 -> 清理** 链条，消除缓冲区问题。
 
-**质量参数**
-- `--width`: 输出宽度（像素）
-- `--height`: 输出高度（像素）
-- `--fps`: 每秒帧数 (默认: 30)
-- `--duration`: 总帧数 (例如: 420 = 30fps 下 14 秒)
-- `--format`: 显式格式 (mp4, webm, gif, webp, auto)
+### 资源存放
+将所有本地资源放在 `public/` 中，并通过绝对路径引用 (例如 `/video.mp4`)。
 
 ## 📜 许可证
 

From da9f96506b974ae693eae45becc439e086cfbb5e Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Wed, 25 Feb 2026 22:11:05 +0900
Subject: [PATCH 05/28] feat(cli): add generate, edit, and config commands for
 AI-powered video creation

---
 README.md                             |  28 ++
 packages/cli/README.md                |  22 ++
 packages/cli/package.json             |  10 +-
 packages/cli/src/commands/config.ts   | 123 ++++++++
 packages/cli/src/commands/edit.ts     | 373 +++++++++++++++++++++++
 packages/cli/src/commands/generate.ts | 416 ++++++++++++++++++++++++++
 packages/cli/src/index.ts             | 164 +++++++++-
 packages/cli/src/llm/config.ts        | 196 ++++++++++++
 packages/cli/src/llm/factory.ts       |  54 ++++
 packages/cli/src/llm/types.ts         |  65 ++++
 packages/cli/src/prompts/edit.ts      |  49 +++
 packages/cli/src/prompts/generate.ts  | 194 ++++++++++++
 pnpm-lock.yaml                        | 310 ++++++++++++++++++-
 13 files changed, 1999 insertions(+), 5 deletions(-)
 create mode 100644 packages/cli/src/commands/config.ts
 create mode 100644 packages/cli/src/commands/edit.ts
 create mode 100644 packages/cli/src/commands/generate.ts
 create mode 100644 packages/cli/src/llm/config.ts
 create mode 100644 packages/cli/src/llm/factory.ts
 create mode 100644 packages/cli/src/llm/types.ts
 create mode 100644 packages/cli/src/prompts/edit.ts
 create mode 100644 packages/cli/src/prompts/generate.ts

diff --git a/README.md b/README.md
index 8236c2b..4bdd888 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,8 @@ OpenMotion is a high-performance, open-source alternative to Remotion. It allows
 ## ✨ Features
 
 - ⚛️ **React-First**: Use the full power of the React ecosystem.
+- 🤖 **AI-Powered Generation**: Create entire videos from text descriptions using LLMs.
+- ✍️ **AI-Assisted Editing**: Edit your TSX scenes using natural language.
 - ⏱️ **Frame-Perfect Determinism**: Advanced time-hijacking ensures every frame is identical.
 - 🚀 **Parallel Rendering**: Scale your rendering speed by utilizing all CPU cores.
 - 🎵 **Multi-track Audio Mixing**: Support for multiple `<Audio />` with independent volume.
@@ -87,6 +89,32 @@ open-motion render -u http://localhost:5173 -o out.mp4
 ### `open-motion init <name>`
 Initialize a new OpenMotion project with a pre-configured React template.
 
+### `open-motion generate <description>`
+Automatically generate video scenes and code from a text description using an LLM.
+
+| Option | Description |
+| :--- | :--- |
+| `--provider <name>` | LLM provider (`openai`, `anthropic`, `google`, `ollama`, `openai-compatible`) |
+| `--model <name>` | Model name (e.g., `gpt-4o`, `claude-3-5-sonnet`) |
+| `--scenes <number>` | Number of scenes to generate |
+| `--fps <number>` | Frames per second (default: 30) |
+| `--width <number>` | Video width (default: 1280) |
+| `--height <number>` | Video height (default: 720) |
+
+### `open-motion edit <file>`
+Edit a TSX scene file using natural language instructions.
+
+| Option | Description |
+| :--- | :--- |
+| `-m, --message <msg>` | Instruction for editing |
+| `-y, --yes` | Auto-apply changes (one-shot mode) |
+
+### `open-motion config`
+Manage LLM provider settings (API keys, models).
+
+- `open-motion config set <key> <value>`
+- `open-motion config list`
+
 ### `open-motion render`
 Render a video from a running OpenMotion application.
 
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 35e3bda..9407df1 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -5,6 +5,8 @@ The Command Line Interface for **OpenMotion** — the open-source programmatic v
 ## 🚀 Features
 
 - 🏗️ **Quick Init**: Scaffold new OpenMotion projects instantly.
+- 🤖 **AI Generation**: Generate scenes and code from text descriptions.
+- ✍️ **AI Editing**: Refine your TSX components using natural language.
 - 🎥 **High-Speed Rendering**: Capture and encode videos directly from your React code.
 - 🚀 **Parallel Execution**: Leverage multi-core CPUs for faster frame capturing.
 - 🎛️ **Dynamic Props**: Inject external data into your videos via JSON.
@@ -24,6 +26,26 @@ npx @open-motion/cli --help
 open-motion init my-video
 ```
 
+### Configure LLM (Optional for AI features)
+```bash
+open-motion config set provider openai
+open-motion config set openai.apiKey sk-...
+```
+
+### Generate a video from description
+```bash
+open-motion generate "Explain how React hooks work"
+```
+
+### Edit a scene file
+```bash
+# Interactive mode
+open-motion edit src/scenes/IntroScene.tsx
+
+# One-shot mode
+open-motion edit src/scenes/IntroScene.tsx -m "Make the text color blue" --yes
+```
+
 ### Render a video
 ```bash
 open-motion render --url http://localhost:5173 --out out.mp4 --concurrency 4
diff --git a/packages/cli/package.json b/packages/cli/package.json
index c2a5fff..32ac6b8 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -20,14 +20,22 @@
     "dist"
   ],
   "dependencies": {
+    "@ai-sdk/anthropic": "^1.2.0",
+    "@ai-sdk/google": "^1.2.0",
+    "@ai-sdk/openai": "^1.3.0",
     "@open-motion/core": "workspace:*",
     "@open-motion/encoder": "workspace:*",
     "@open-motion/renderer": "workspace:*",
+    "ai": "^4.3.0",
+    "chalk": "^4.1.2",
     "cli-progress": "^3.12.0",
     "commander": "^11.0.0",
+    "diff": "^5.2.0",
+    "ollama-ai-provider": "^1.2.0",
     "playwright": "^1.58.1"
   },
   "devDependencies": {
-    "@types/cli-progress": "^3.11.6"
+    "@types/cli-progress": "^3.11.6",
+    "@types/diff": "^5.2.1"
   }
 }
diff --git a/packages/cli/src/commands/config.ts b/packages/cli/src/commands/config.ts
new file mode 100644
index 0000000..d243269
--- /dev/null
+++ b/packages/cli/src/commands/config.ts
@@ -0,0 +1,123 @@
+import path from 'path';
+import os from 'os';
+import chalk from 'chalk';
+import {
+  readConfigFile,
+  setConfigKey,
+  getConfigKey,
+} from '../llm/config';
+
+const CONFIG_FILE = path.join(os.homedir(), '.open-motion', 'config.json');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const VALID_KEYS = [
+  'provider',
+  'model',
+  'openai.apiKey',
+  'openai.model',
+  'anthropic.apiKey',
+  'anthropic.model',
+  'google.apiKey',
+  'google.model',
+  'ollama.baseURL',
+  'ollama.model',
+  'openai-compatible.baseURL',
+  'openai-compatible.apiKey',
+  'openai-compatible.model',
+] as const;
+
+function maskSecret(key: string, value: string): string {
+  const lk = key.toLowerCase();
+  if (lk.endsWith('apikey') || lk.endsWith('api_key')) {
+    if (value.length <= 8) return '****';
+    return value.slice(0, 6) + '...' + value.slice(-4);
+  }
+  return value;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function flattenConfig(obj: any, prefix = ''): Array<[string, string]> {
+  const pairs: Array<[string, string]> = [];
+  for (const [k, v] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${k}` : k;
+    if (v !== null && typeof v === 'object') {
+      pairs.push(...flattenConfig(v, fullKey));
+    } else {
+      pairs.push([fullKey, String(v)]);
+    }
+  }
+  return pairs;
+}
+
+// ---------------------------------------------------------------------------
+// Sub-command handlers
+// ---------------------------------------------------------------------------
+
+export function runConfigSet(key: string, value: string): void {
+  setConfigKey(key, value);
+  const displayVal = maskSecret(key, value);
+  console.log(chalk.green(`✓ ${key} = ${displayVal}`));
+  console.log(chalk.dim(`  保存先: ${CONFIG_FILE}`));
+}
+
+export function runConfigGet(key: string): void {
+  const value = getConfigKey(key);
+  if (value === undefined) {
+    console.log(chalk.yellow(`  "${key}" は設定されていません`));
+  } else {
+    console.log(`${key} = ${maskSecret(key, value)}`);
+  }
+}
+
+export function runConfigList(): void {
+  const config = readConfigFile();
+  const pairs = flattenConfig(config);
+
+  if (pairs.length === 0) {
+    console.log(chalk.dim('設定がありません'));
+    console.log(chalk.dim(`設定ファイル: ${CONFIG_FILE}`));
+    console.log('');
+    console.log('例:');
+    console.log(chalk.cyan('  open-motion config set provider openai'));
+    console.log(chalk.cyan('  open-motion config set openai.apiKey sk-...'));
+    return;
+  }
+
+  console.log(chalk.bold(`設定ファイル: ${CONFIG_FILE}`));
+  console.log('');
+
+  for (const [key, value] of pairs) {
+    const displayVal = maskSecret(key, value);
+    console.log(`  ${chalk.dim(key.padEnd(36))} ${displayVal}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Usage hint
+// ---------------------------------------------------------------------------
+
+export function printConfigHelp(): void {
+  console.log(chalk.bold('open-motion config'));
+  console.log('');
+  console.log('使用可能なコマンド:');
+  console.log(
+    `  ${chalk.cyan('open-motion config set <key> <value>')}  設定値を保存`
+  );
+  console.log(
+    `  ${chalk.cyan('open-motion config get <key>')}          設定値を表示`
+  );
+  console.log(
+    `  ${chalk.cyan('open-motion config list')}               全設定を一覧表示`
+  );
+  console.log('');
+  console.log('設定可能なキー:');
+  VALID_KEYS.forEach((k) => console.log(`  ${chalk.dim(k)}`));
+  console.log('');
+  console.log('例:');
+  console.log(chalk.cyan('  open-motion config set provider anthropic'));
+  console.log(chalk.cyan('  open-motion config set anthropic.apiKey sk-ant-...'));
+  console.log(chalk.cyan('  open-motion config set openai-compatible.baseURL https://api.example.com/v1'));
+}
diff --git a/packages/cli/src/commands/edit.ts b/packages/cli/src/commands/edit.ts
new file mode 100644
index 0000000..971c1ca
--- /dev/null
+++ b/packages/cli/src/commands/edit.ts
@@ -0,0 +1,373 @@
+import fs from 'fs';
+import path from 'path';
+import readline from 'readline';
+import { generateText } from 'ai';
+import chalk from 'chalk';
+import * as diffLib from 'diff';
+import { resolveConfig, validateConfig, type CliConfigOverrides } from '../llm/config';
+import { createModel } from '../llm/factory';
+import { EDIT_SYSTEM_PROMPT, buildEditPrompt, parseEditResponse } from '../prompts/edit';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface EditOptions {
+  message?: string;
+  provider?: string;
+  model?: string;
+  apiKey?: string;
+  baseURL?: string;
+  yes?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Simple inline spinner */
+class Spinner {
+  private frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  private idx = 0;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private current = '';
+
+  start(text: string): void {
+    this.current = text;
+    process.stdout.write('\n');
+    this.timer = setInterval(() => {
+      process.stdout.write(
+        `\r${chalk.cyan(this.frames[this.idx % this.frames.length])} ${this.current}`
+      );
+      this.idx++;
+    }, 80);
+  }
+
+  succeed(text: string): void {
+    this.stop();
+    process.stdout.write(`\r${chalk.green('✓')} ${text}\n`);
+  }
+
+  fail(text: string): void {
+    this.stop();
+    process.stdout.write(`\r${chalk.red('✗')} ${text}\n`);
+  }
+
+  private stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+}
+
+/**
+ * Render a colored unified diff to the console.
+ */
+function printDiff(oldContent: string, newContent: string, filePath: string): void {
+  const hunks = diffLib.createPatch(
+    path.basename(filePath),
+    oldContent,
+    newContent,
+    'before',
+    'after'
+  );
+
+  if (oldContent === newContent) {
+    console.log(chalk.yellow('\n  (変更なし)'));
+    return;
+  }
+
+  console.log('\n' + chalk.bold('--- 変更内容 ---'));
+  hunks.split('\n').forEach((line) => {
+    if (line.startsWith('+++') || line.startsWith('---')) {
+      console.log(chalk.bold(line));
+    } else if (line.startsWith('+')) {
+      console.log(chalk.green(line));
+    } else if (line.startsWith('-')) {
+      console.log(chalk.red(line));
+    } else if (line.startsWith('@@')) {
+      console.log(chalk.cyan(line));
+    } else {
+      console.log(chalk.dim(line));
+    }
+  });
+  console.log(chalk.bold('----------------'));
+}
+
+/**
+ * Prompt the user for a yes/no/retry answer via readline.
+ */
+async function askConfirm(
+  rl: readline.Interface,
+  question: string
+): Promise<'yes' | 'no' | 'retry'> {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      const a = answer.trim().toLowerCase();
+      if (a === '' || a === 'y' || a === 'yes') {
+        resolve('yes');
+      } else if (a === 'r' || a === 'retry') {
+        resolve('retry');
+      } else {
+        resolve('no');
+      }
+    });
+  });
+}
+
+/**
+ * Ask for a text input.
+ */
+async function askInput(
+  rl: readline.Interface,
+  prompt: string
+): Promise<string> {
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      resolve(answer.trim());
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// LLM call
+// ---------------------------------------------------------------------------
+
+async function applyEdit(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  model: any,
+  fileContent: string,
+  instruction: string
+): Promise<string> {
+  const { text } = await generateText({
+    model,
+    system: EDIT_SYSTEM_PROMPT,
+    prompt: buildEditPrompt(fileContent, instruction),
+    maxTokens: 8192,
+  });
+  return parseEditResponse(text);
+}
+
+// ---------------------------------------------------------------------------
+// Main command
+// ---------------------------------------------------------------------------
+
+export async function runEdit(
+  filePath: string,
+  options: EditOptions
+): Promise<void> {
+  const absPath = path.resolve(process.cwd(), filePath);
+
+  // Validate file exists
+  if (!fs.existsSync(absPath)) {
+    console.error(chalk.red(`File not found: ${absPath}`));
+    process.exit(1);
+  }
+  if (!absPath.endsWith('.tsx') && !absPath.endsWith('.ts') && !absPath.endsWith('.jsx') && !absPath.endsWith('.js')) {
+    console.error(chalk.red('Only .tsx / .ts / .jsx / .js files are supported.'));
+    process.exit(1);
+  }
+
+  // ------------------------------------------------------------------
+  // Resolve LLM config
+  // ------------------------------------------------------------------
+  const configOverrides: CliConfigOverrides = {
+    provider: options.provider,
+    model: options.model,
+    apiKey: options.apiKey,
+    baseURL: options.baseURL,
+  };
+
+  let resolvedCfg;
+  try {
+    resolvedCfg = resolveConfig(configOverrides);
+    validateConfig(resolvedCfg);
+  } catch (err) {
+    console.error(chalk.red((err as Error).message));
+    process.exit(1);
+  }
+
+  let model;
+  try {
+    model = await createModel(resolvedCfg);
+  } catch (err) {
+    console.error(chalk.red(`Failed to initialize LLM provider: ${(err as Error).message}`));
+    process.exit(1);
+  }
+
+  const relPath = path.relative(process.cwd(), absPath);
+  const lineCount = fs.readFileSync(absPath, 'utf8').split('\n').length;
+
+  console.log(chalk.bold('\nopen-motion edit'));
+  console.log(chalk.dim(`ファイル : ${relPath} (${lineCount}行)`));
+  console.log(chalk.dim(`Provider : ${resolvedCfg.provider}  Model: ${resolvedCfg.model}`));
+  console.log('');
+
+  // ------------------------------------------------------------------
+  // One-shot mode (--message / -m)
+  // ------------------------------------------------------------------
+  if (options.message) {
+    await runOneShot(model, absPath, options.message, options.yes ?? false);
+    return;
+  }
+
+  // ------------------------------------------------------------------
+  // Interactive mode
+  // ------------------------------------------------------------------
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  });
+
+  console.log(chalk.dim("指示を入力してください ('exit' で終了)\n"));
+
+  // Keep previous instruction for retry
+  let lastInstruction = '';
+  let lastEditedContent: string | null = null;
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const instruction = await askInput(rl, chalk.cyan('> '));
+
+    if (instruction === '' && lastInstruction === '') {
+      continue;
+    }
+
+    if (instruction.toLowerCase() === 'exit' || instruction.toLowerCase() === 'quit') {
+      console.log(chalk.dim('終了しました。'));
+      rl.close();
+      return;
+    }
+
+    const effectiveInstruction = instruction !== '' ? instruction : lastInstruction;
+    if (!effectiveInstruction) {
+      console.log(chalk.yellow('指示を入力してください。'));
+      continue;
+    }
+
+    lastInstruction = effectiveInstruction;
+
+    // Read current file content (may have been updated in a previous iteration)
+    const currentContent = fs.readFileSync(absPath, 'utf8');
+
+    const spinner = new Spinner();
+    spinner.start('編集中...');
+
+    let edited: string;
+    try {
+      edited = await applyEdit(model, currentContent, effectiveInstruction);
+    } catch (err) {
+      spinner.fail('編集に失敗しました');
+      console.error(chalk.red((err as Error).message));
+      continue;
+    }
+
+    spinner.succeed('編集完了');
+    lastEditedContent = edited;
+
+    printDiff(currentContent, edited, absPath);
+
+    if (currentContent === edited) {
+      console.log(chalk.yellow('\n変更がありませんでした。指示を具体的にしてみてください。\n'));
+      continue;
+    }
+
+    const answer = await askConfirm(
+      rl,
+      chalk.bold('\n変更を適用しますか？') + chalk.dim(' (Y/n/retry) ')
+    );
+
+    if (answer === 'yes') {
+      fs.writeFileSync(absPath, edited, 'utf8');
+      console.log(chalk.green('\n保存しました!\n'));
+    } else if (answer === 'retry') {
+      console.log(chalk.dim('\n再生成します...\n'));
+      const spinner2 = new Spinner();
+      spinner2.start('再生成中...');
+      try {
+        edited = await applyEdit(model, currentContent, effectiveInstruction);
+        spinner2.succeed('再生成完了');
+        lastEditedContent = edited;
+        printDiff(currentContent, edited, absPath);
+
+        const ans2 = await askConfirm(
+          rl,
+          chalk.bold('\n変更を適用しますか？') + chalk.dim(' (Y/n) ')
+        );
+        if (ans2 === 'yes') {
+          fs.writeFileSync(absPath, edited, 'utf8');
+          console.log(chalk.green('\n保存しました!\n'));
+        } else {
+          console.log(chalk.dim('\nスキップしました。\n'));
+        }
+      } catch (err) {
+        spinner2.fail('再生成に失敗しました');
+        console.error(chalk.red((err as Error).message));
+      }
+    } else {
+      console.log(chalk.dim('\nスキップしました。\n'));
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// One-shot helper
+// ---------------------------------------------------------------------------
+
+async function runOneShot(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  model: any,
+  absPath: string,
+  instruction: string,
+  autoApply: boolean
+): Promise<void> {
+  const currentContent = fs.readFileSync(absPath, 'utf8');
+
+  const spinner = new Spinner();
+  spinner.start('編集中...');
+
+  let edited: string;
+  try {
+    edited = await applyEdit(model, currentContent, instruction);
+  } catch (err) {
+    spinner.fail('編集に失敗しました');
+    console.error(chalk.red((err as Error).message));
+    process.exit(1);
+  }
+
+  spinner.succeed('編集完了');
+  printDiff(currentContent, edited, absPath);
+
+  if (currentContent === edited) {
+    console.log(chalk.yellow('変更がありませんでした。'));
+    return;
+  }
+
+  if (autoApply) {
+    fs.writeFileSync(absPath, edited, 'utf8');
+    console.log(chalk.green('\n保存しました!'));
+    return;
+  }
+
+  // Ask for confirmation
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  });
+
+  const answer = await askConfirm(
+    rl,
+    chalk.bold('\n変更を適用しますか？') + chalk.dim(' (Y/n) ')
+  );
+  rl.close();
+
+  if (answer === 'yes') {
+    fs.writeFileSync(absPath, edited, 'utf8');
+    console.log(chalk.green('\n保存しました!'));
+  } else {
+    console.log(chalk.dim('\nキャンセルしました。'));
+  }
+}
diff --git a/packages/cli/src/commands/generate.ts b/packages/cli/src/commands/generate.ts
new file mode 100644
index 0000000..9bce8ec
--- /dev/null
+++ b/packages/cli/src/commands/generate.ts
@@ -0,0 +1,416 @@
+import fs from 'fs';
+import path from 'path';
+import { generateText } from 'ai';
+import chalk from 'chalk';
+import { resolveConfig, validateConfig, type CliConfigOverrides } from '../llm/config';
+import { createModel } from '../llm/factory';
+import {
+  GENERATE_SYSTEM_PROMPT,
+  buildPlanningPrompt,
+  buildSceneCodePrompt,
+  parsePlanResponse,
+  parseCodeResponse,
+  type ScenePlan,
+} from '../prompts/generate';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface GenerateOptions {
+  provider?: string;
+  model?: string;
+  apiKey?: string;
+  baseURL?: string;
+  scenes?: number;
+  fps?: number;
+  width?: number;
+  height?: number;
+  output?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Simple spinner using stdout */
+class Spinner {
+  private frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  private idx = 0;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private current = '';
+
+  start(text: string): void {
+    this.current = text;
+    process.stdout.write('\n');
+    this.timer = setInterval(() => {
+      process.stdout.write(
+        `\r${chalk.cyan(this.frames[this.idx % this.frames.length])} ${this.current}`
+      );
+      this.idx++;
+    }, 80);
+  }
+
+  update(text: string): void {
+    this.current = text;
+  }
+
+  succeed(text: string): void {
+    this.stop();
+    process.stdout.write(`\r${chalk.green('✓')} ${text}\n`);
+  }
+
+  fail(text: string): void {
+    this.stop();
+    process.stdout.write(`\r${chalk.red('✗')} ${text}\n`);
+  }
+
+  private stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+}
+
+/**
+ * Convert a video title (or scene title) to a valid PascalCase component name.
+ * E.g. "React Lifecycle" → "ReactLifecycle"
+ */
+function toPascalCase(str: string): string {
+  return str
+    .replace(/[^a-zA-Z0-9\u3040-\u30FF\u4E00-\u9FFF]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .map((word) =>
+      /^[a-zA-Z]/.test(word)
+        ? word.charAt(0).toUpperCase() + word.slice(1)
+        : word
+    )
+    .join('');
+}
+
+/**
+ * Build the main composition TSX that assembles all scenes in a Sequence.
+ */
+function buildCompositionFile(
+  videoTitle: string,
+  plan: ScenePlan,
+  fps: number,
+  width: number,
+  height: number
+): string {
+  const imports = plan.scenes
+    .map((s) => `import { ${s.componentName} } from './scenes/${s.componentName}';`)
+    .join('\n');
+
+  let offset = 0;
+  const sequences = plan.scenes
+    .map((s) => {
+      const durationInFrames = Math.round(s.durationInSeconds * fps);
+      const from = offset;
+      offset += durationInFrames;
+      return `  <Sequence from={${from}} durationInFrames={${durationInFrames}}>\n    <${s.componentName} />\n  </Sequence>`;
+    })
+    .join('\n');
+
+  const totalFrames = offset;
+  const componentName = toPascalCase(videoTitle) + 'Video';
+
+  return `import React from 'react';
+import { Sequence, useVideoConfig } from '@open-motion/core';
+${imports}
+
+/** Auto-generated composition: ${videoTitle} */
+export const ${componentName} = () => {
+  const { width, height } = useVideoConfig();
+  return (
+    <div style={{ width, height, overflow: 'hidden', backgroundColor: '#000' }}>
+${sequences}
+    </div>
+  );
+};
+
+/** Total duration in frames: ${totalFrames} (${(totalFrames / fps).toFixed(1)}s at ${fps}fps) */
+export const ${componentName}Config = {
+  id: '${componentName.replace(/([A-Z])/g, (m, l, i) => (i === 0 ? l.toLowerCase() : '-' + l.toLowerCase()))}',
+  component: ${componentName},
+  width: ${width},
+  height: ${height},
+  fps: ${fps},
+  durationInFrames: ${totalFrames},
+} as const;
+`;
+}
+
+/**
+ * Inject a new Composition into src/main.tsx.
+ * Finds the hidden-div block and appends the Composition before its closing tag.
+ */
+function updateMainTsx(
+  mainTsxPath: string,
+  compositionFile: string,
+  componentName: string,
+  config: { id: string; width: number; height: number; fps: number; durationInFrames: number }
+): void {
+  if (!fs.existsSync(mainTsxPath)) {
+    return; // No main.tsx to update — skip silently
+  }
+
+  let content = fs.readFileSync(mainTsxPath, 'utf8');
+
+  // Add import at the top (after the last existing import line)
+  const importStatement = `import { ${componentName}, ${componentName}Config } from './${compositionFile}';`;
+  if (content.includes(importStatement)) {
+    return; // Already imported
+  }
+
+  // Insert import after the last import block
+  const lastImportIndex = content.lastIndexOf('\nimport ');
+  if (lastImportIndex !== -1) {
+    const endOfLastImport = content.indexOf('\n', lastImportIndex + 1);
+    content =
+      content.slice(0, endOfLastImport + 1) +
+      importStatement +
+      '\n' +
+      content.slice(endOfLastImport + 1);
+  } else {
+    content = importStatement + '\n' + content;
+  }
+
+  // Insert Composition element before the closing </div> of the hidden block
+  const compositionElement =
+    `        <Composition\n` +
+    `          id="${config.id}"\n` +
+    `          component={${componentName}Config.component}\n` +
+    `          width={${config.width}}\n` +
+    `          height={${config.height}}\n` +
+    `          fps={${config.fps}}\n` +
+    `          durationInFrames={${config.durationInFrames}}\n` +
+    `        />`;
+
+  // Find the hidden div's closing </div>
+  const hiddenDivPattern = /display:\s*['"]none['"]/;
+  const match = hiddenDivPattern.exec(content);
+  if (match) {
+    // Find the closing </div> after this point
+    const searchFrom = match.index;
+    const closingTag = '</div>';
+    const closingIdx = content.indexOf(closingTag, searchFrom);
+    if (closingIdx !== -1) {
+      content =
+        content.slice(0, closingIdx) +
+        compositionElement +
+        '\n' +
+        content.slice(closingIdx);
+    }
+  }
+
+  fs.writeFileSync(mainTsxPath, content, 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Main command
+// ---------------------------------------------------------------------------
+
+export async function runGenerate(
+  description: string,
+  options: GenerateOptions
+): Promise<void> {
+  const fps = options.fps ?? 30;
+  const width = options.width ?? 1280;
+  const height = options.height ?? 720;
+
+  // Resolve output directory (default: src/scenes relative to cwd)
+  const outputDir = options.output
+    ? path.resolve(process.cwd(), options.output)
+    : path.join(process.cwd(), 'src', 'scenes');
+
+  console.log(chalk.bold('\nopen-motion generate'));
+  console.log(chalk.dim(`Description : ${description}`));
+  console.log(chalk.dim(`Output dir  : ${outputDir}`));
+  console.log('');
+
+  // ------------------------------------------------------------------
+  // 1. Resolve & validate LLM config
+  // ------------------------------------------------------------------
+  const configOverrides: CliConfigOverrides = {
+    provider: options.provider,
+    model: options.model,
+    apiKey: options.apiKey,
+    baseURL: options.baseURL,
+  };
+
+  let resolvedCfg;
+  try {
+    resolvedCfg = resolveConfig(configOverrides);
+    validateConfig(resolvedCfg);
+  } catch (err) {
+    console.error(chalk.red((err as Error).message));
+    process.exit(1);
+  }
+
+  console.log(
+    chalk.dim(`Provider: ${resolvedCfg.provider}  Model: ${resolvedCfg.model}`)
+  );
+
+  let model;
+  try {
+    model = await createModel(resolvedCfg);
+  } catch (err) {
+    console.error(chalk.red(`Failed to initialize LLM provider: ${(err as Error).message}`));
+    process.exit(1);
+  }
+
+  // ------------------------------------------------------------------
+  // 2. Plan scenes
+  // ------------------------------------------------------------------
+  const spinner = new Spinner();
+  spinner.start('[1/3] シーン構成を検討中...');
+
+  let plan: ScenePlan;
+  try {
+    const { text } = await generateText({
+      model,
+      system: GENERATE_SYSTEM_PROMPT,
+      prompt: buildPlanningPrompt(description),
+      maxTokens: 2048,
+    });
+    plan = parsePlanResponse(text);
+  } catch (err) {
+    spinner.fail('シーン構成の生成に失敗しました');
+    console.error(chalk.red((err as Error).message));
+    process.exit(1);
+  }
+
+  // Optionally override number of scenes
+  if (options.scenes && options.scenes > 0 && options.scenes !== plan.scenes.length) {
+    // Just warn — we respect what the LLM returned unless explicitly trimmed/expanded
+    console.log(
+      chalk.yellow(
+        `\n  Note: LLM generated ${plan.scenes.length} scenes ` +
+        `(you requested ${options.scenes}). Using LLM's plan.`
+      )
+    );
+  }
+
+  spinner.succeed(`[1/3] シーン構成: ${plan.scenes.length}シーン`);
+  plan.scenes.forEach((s, i) => {
+    console.log(
+      chalk.dim(`       Scene ${i + 1}: ${s.title} (${s.durationInSeconds}s)`)
+    );
+  });
+  console.log('');
+
+  // ------------------------------------------------------------------
+  // 3. Generate TSX for each scene
+  // ------------------------------------------------------------------
+  spinner.start(`[2/3] TSXを生成中... (0/${plan.scenes.length})`);
+
+  const scenesDir = path.join(outputDir);
+  fs.mkdirSync(scenesDir, { recursive: true });
+
+  const generatedFiles: string[] = [];
+
+  for (let i = 0; i < plan.scenes.length; i++) {
+    const scene = plan.scenes[i];
+    spinner.update(`[2/3] TSXを生成中... (${i + 1}/${plan.scenes.length}) — ${scene.title}`);
+
+    const durationInFrames = Math.round(scene.durationInSeconds * fps);
+
+    try {
+      const { text } = await generateText({
+        model,
+        system: GENERATE_SYSTEM_PROMPT,
+        prompt: buildSceneCodePrompt({
+          componentName: scene.componentName,
+          title: scene.title,
+          description: scene.description,
+          durationInSeconds: scene.durationInSeconds,
+          durationInFrames,
+          fps,
+          width,
+          height,
+          sceneIndex: i,
+          totalScenes: plan.scenes.length,
+        }),
+        maxTokens: 4096,
+      });
+
+      const code = parseCodeResponse(text);
+      const filePath = path.join(scenesDir, `${scene.componentName}.tsx`);
+      fs.writeFileSync(filePath, code + '\n', 'utf8');
+      generatedFiles.push(filePath);
+    } catch (err) {
+      spinner.fail(`Scene "${scene.title}" の生成に失敗しました`);
+      console.error(chalk.red((err as Error).message));
+      process.exit(1);
+    }
+  }
+
+  spinner.succeed(`[2/3] TSX生成完了 (${plan.scenes.length}シーン)`);
+  console.log('');
+
+  // ------------------------------------------------------------------
+  // 4. Generate composition wrapper
+  // ------------------------------------------------------------------
+  spinner.start('[3/3] コンポジションファイルを生成中...');
+
+  const compositionCode = buildCompositionFile(plan.videoTitle, plan, fps, width, height);
+  const compositionComponentName = toPascalCase(plan.videoTitle) + 'Video';
+
+  // Total duration for the composition
+  const totalFrames = plan.scenes.reduce(
+    (acc, s) => acc + Math.round(s.durationInSeconds * fps),
+    0
+  );
+
+  // Write composition to src/ (one level above scenes/)
+  const srcDir = path.dirname(outputDir);
+  const compositionFileName = `${compositionComponentName}`;
+  const compositionFilePath = path.join(srcDir, `${compositionFileName}.tsx`);
+  fs.writeFileSync(compositionFilePath, compositionCode + '\n', 'utf8');
+
+  // Try to update main.tsx
+  const mainTsxPath = path.join(srcDir, 'main.tsx');
+  updateMainTsx(mainTsxPath, compositionFileName, compositionComponentName, {
+    id: compositionComponentName
+      .replace(/([A-Z])/g, (m, l, i) => (i === 0 ? l.toLowerCase() : '-' + l.toLowerCase())),
+    width,
+    height,
+    fps,
+    durationInFrames: totalFrames,
+  });
+
+  const updatedMainTsx = fs.existsSync(mainTsxPath);
+  spinner.succeed('[3/3] コンポジション生成完了');
+  console.log('');
+
+  // ------------------------------------------------------------------
+  // 5. Summary
+  // ------------------------------------------------------------------
+  console.log(chalk.bold.green('完了!'));
+  console.log('');
+  console.log(chalk.bold('生成されたファイル:'));
+  generatedFiles.forEach((f) => {
+    const rel = path.relative(process.cwd(), f);
+    console.log(chalk.green('  ✓') + '  ' + rel);
+  });
+  const relComp = path.relative(process.cwd(), compositionFilePath);
+  console.log(chalk.green('  ✓') + '  ' + relComp + chalk.dim('  (コンポジション)'));
+  if (updatedMainTsx) {
+    const relMain = path.relative(process.cwd(), mainTsxPath);
+    console.log(chalk.green('  ✓') + '  ' + relMain + chalk.dim('  (Composition を追記)'));
+  }
+  console.log('');
+  console.log(
+    chalk.dim(
+      `合計: ${plan.scenes.length}シーン, ${totalFrames}フレーム ` +
+      `(${(totalFrames / fps).toFixed(1)}秒 @ ${fps}fps)`
+    )
+  );
+  console.log('');
+  console.log('次のステップ:');
+  console.log(chalk.cyan('  pnpm dev') + '  でプレビュー');
+  console.log(chalk.cyan('  pnpm render') + '  で動画をレンダリング');
+}
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index b6c966b..7b33532 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -6,6 +6,9 @@ import fs from 'fs';
 import { Command } from 'commander';
 import cliProgress from 'cli-progress';
 import { execSync } from 'child_process';
+import { runGenerate } from './commands/generate';
+import { runEdit } from './commands/edit';
+import { runConfigSet, runConfigGet, runConfigList, printConfigHelp } from './commands/config';
 
 const getPackageManager = () => {
   try {
@@ -370,11 +373,17 @@ Quick Start:
   1. Initialize project:  $ open-motion init my-video
   2. Enter directory:     $ cd my-video
   3. Install deps:        $ pnpm install
-  4. Start dev server:    $ pnpm dev
-  5. Render video:        $ pnpm render
+  4. Configure LLM:       $ open-motion config set provider openai
+                          $ open-motion config set openai.apiKey sk-...
+  5. Generate scenes:     $ open-motion generate "Reactのライフサイクルを説明する動画"
+  6. Edit a scene:        $ open-motion edit src/scenes/IntroScene.tsx
+  7. Start dev server:    $ pnpm dev
+  8. Render video:        $ pnpm render
 
 Example Usage:
   $ open-motion init my-project
+  $ open-motion generate "TypeScriptの型システム解説動画"
+  $ open-motion edit src/scenes/IntroScene.tsx --message "背景を青に変えて"
   $ open-motion render -u http://localhost:5173 -o output.mp4 --composition main
 `);
 
@@ -436,5 +445,156 @@ Examples:
   $ open-motion render -u http://localhost:3000 -o banner.gif --format gif --width 1200 --height 630
 `);
 
+  // ---------------------------------------------------------------------------
+  // generate command
+  // ---------------------------------------------------------------------------
+  const generateCommand = program
+    .command('generate <description>')
+    .description('LLMを使用して動画のシーンTSXを自動生成する')
+    .option('--provider <name>', 'LLMプロバイダ (openai/anthropic/google/ollama/openai-compatible)')
+    .option('--model <name>', '使用するモデル名')
+    .option('--api-key <key>', 'APIキー (設定ファイル・環境変数より優先)')
+    .option('--base-url <url>', 'ベースURL (openai-compatible / ollama)')
+    .option('--scenes <number>', '生成するシーン数 (省略時はLLMが決定)', parseInt)
+    .option('--fps <number>', 'フレームレート (デフォルト: 30)', parseInt)
+    .option('--width <number>', '動画の幅 (デフォルト: 1280)', parseInt)
+    .option('--height <number>', '動画の高さ (デフォルト: 720)', parseInt)
+    .option('--output <dir>', 'シーンファイルの出力ディレクトリ (デフォルト: src/scenes)')
+    .action(async (description: string, options) => {
+      try {
+        await runGenerate(description, {
+          provider: options.provider,
+          model: options.model,
+          apiKey: options.apiKey,
+          baseURL: options.baseUrl,
+          scenes: options.scenes,
+          fps: options.fps,
+          width: options.width,
+          height: options.height,
+          output: options.output,
+        });
+      } catch (err) {
+        console.error('Generate failed:', err);
+        process.exit(1);
+      }
+    });
+
+  generateCommand.addHelpText('after', `
+Examples:
+  $ open-motion generate "Reactのライフサイクルを説明する動画"
+  $ open-motion generate "TypeScriptの型システム解説" --scenes 4 --fps 30
+  $ open-motion generate "AWS S3の使い方" --provider anthropic --model claude-opus-4-5
+  $ open-motion generate "Dockerの仕組み" --provider ollama --model llama3
+  $ open-motion generate "CI/CDパイプライン解説" --width 1920 --height 1080
+
+Note:
+  - 事前に LLM の設定が必要です: open-motion config set provider openai
+  - 既存プロジェクト (open-motion init で作成したもの) のルートで実行してください
+`);
+
+  // ---------------------------------------------------------------------------
+  // edit command
+  // ---------------------------------------------------------------------------
+  const editCommand = program
+    .command('edit <file>')
+    .description('LLMを使用してTSXシーンファイルをインタラクティブに編集する')
+    .option('-m, --message <instruction>', 'ワンショットモード: 指示を文字列で渡す')
+    .option('--provider <name>', 'LLMプロバイダ (openai/anthropic/google/ollama/openai-compatible)')
+    .option('--model <name>', '使用するモデル名')
+    .option('--api-key <key>', 'APIキー (設定ファイル・環境変数より優先)')
+    .option('--base-url <url>', 'ベースURL (openai-compatible / ollama)')
+    .option('-y, --yes', '確認なしで変更を自動適用 (ワンショットモード時)')
+    .action(async (file: string, options) => {
+      try {
+        await runEdit(file, {
+          message: options.message,
+          provider: options.provider,
+          model: options.model,
+          apiKey: options.apiKey,
+          baseURL: options.baseUrl,
+          yes: options.yes,
+        });
+      } catch (err) {
+        console.error('Edit failed:', err);
+        process.exit(1);
+      }
+    });
+
+  editCommand.addHelpText('after', `
+Examples:
+  # インタラクティブモード (対話形式で繰り返し編集)
+  $ open-motion edit src/scenes/IntroScene.tsx
+
+  # ワンショットモード (1回だけ指示を渡す)
+  $ open-motion edit src/scenes/IntroScene.tsx --message "背景を青にして"
+  $ open-motion edit src/scenes/IntroScene.tsx -m "テキストを大きくして" --yes
+
+  # プロバイダを指定
+  $ open-motion edit src/scenes/IntroScene.tsx --provider anthropic -m "アニメーションを滑らかに"
+`);
+
+  // ---------------------------------------------------------------------------
+  // config command
+  // ---------------------------------------------------------------------------
+  const configCommand = program
+    .command('config')
+    .description('LLMプロバイダの設定を管理する (~/.open-motion/config.json)')
+    .action(() => {
+      printConfigHelp();
+    });
+
+  configCommand
+    .command('set <key> <value>')
+    .description('設定値を保存する')
+    .action((key: string, value: string) => {
+      runConfigSet(key, value);
+    });
+
+  configCommand
+    .command('get <key>')
+    .description('設定値を表示する')
+    .action((key: string) => {
+      runConfigGet(key);
+    });
+
+  configCommand
+    .command('list')
+    .description('全設定を一覧表示する')
+    .action(() => {
+      runConfigList();
+    });
+
+  configCommand.addHelpText('after', `
+設定可能なキー:
+  provider                      使用するプロバイダ (openai/anthropic/google/ollama/openai-compatible)
+  model                         グローバルモデル上書き
+  openai.apiKey                 OpenAI APIキー
+  openai.model                  OpenAIモデル (デフォルト: gpt-4o)
+  anthropic.apiKey              Anthropic APIキー
+  anthropic.model               Anthropicモデル (デフォルト: claude-3-5-sonnet-20241022)
+  google.apiKey                 Google AIキー
+  google.model                  Googleモデル (デフォルト: gemini-1.5-pro)
+  ollama.baseURL                OllamaサーバURL (デフォルト: http://localhost:11434)
+  ollama.model                  Ollamaモデル (デフォルト: llama3)
+  openai-compatible.baseURL     カスタムAPIのベースURL
+  openai-compatible.apiKey      カスタムAPIのAPIキー
+  openai-compatible.model       カスタムAPIのモデル名
+
+環境変数 (設定ファイルより優先):
+  OPEN_MOTION_PROVIDER          プロバイダ上書き
+  OPEN_MOTION_MODEL             モデル上書き
+  OPENAI_API_KEY                OpenAI APIキー
+  ANTHROPIC_API_KEY             Anthropic APIキー
+  GOOGLE_API_KEY / GEMINI_API_KEY  Google AIキー
+  OPEN_MOTION_BASE_URL          カスタムベースURL
+  OPEN_MOTION_API_KEY           カスタムAPIキー
+
+Examples:
+  $ open-motion config set provider openai
+  $ open-motion config set openai.apiKey sk-...
+  $ open-motion config set openai.model gpt-4o
+  $ open-motion config list
+`);
+
   program.parse(process.argv);
 };
diff --git a/packages/cli/src/llm/config.ts b/packages/cli/src/llm/config.ts
new file mode 100644
index 0000000..2834476
--- /dev/null
+++ b/packages/cli/src/llm/config.ts
@@ -0,0 +1,196 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import type { OpenMotionLLMConfig, ProviderName, ResolvedLLMConfig } from './types';
+import { DEFAULT_MODELS } from './types';
+
+const CONFIG_DIR = path.join(os.homedir(), '.open-motion');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+// ---------------------------------------------------------------------------
+// File I/O
+// ---------------------------------------------------------------------------
+
+export function readConfigFile(): OpenMotionLLMConfig {
+  if (!fs.existsSync(CONFIG_FILE)) {
+    return {};
+  }
+  try {
+    const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+    return JSON.parse(raw) as OpenMotionLLMConfig;
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfigFile(config: OpenMotionLLMConfig): void {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Set a nested key using dot notation.
+ * e.g. setConfigKey('openai.apiKey', 'sk-...') sets config.openai.apiKey
+ */
+export function setConfigKey(key: string, value: string): void {
+  const config = readConfigFile();
+  const parts = key.split('.');
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let obj: any = config;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (obj[parts[i]] === undefined || typeof obj[parts[i]] !== 'object') {
+      obj[parts[i]] = {};
+    }
+    obj = obj[parts[i]];
+  }
+  obj[parts[parts.length - 1]] = value;
+  writeConfigFile(config);
+}
+
+/**
+ * Get a nested key using dot notation.
+ */
+export function getConfigKey(key: string): string | undefined {
+  const config = readConfigFile();
+  const parts = key.split('.');
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let obj: any = config;
+  for (const part of parts) {
+    if (obj === undefined || obj === null) return undefined;
+    obj = obj[part];
+  }
+  return obj !== undefined && obj !== null ? String(obj) : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Environment variable helpers
+// ---------------------------------------------------------------------------
+
+function env(key: string): string | undefined {
+  const v = process.env[key];
+  return v && v.trim() !== '' ? v.trim() : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Config resolution
+// ---------------------------------------------------------------------------
+
+export interface CliConfigOverrides {
+  provider?: string;
+  model?: string;
+  apiKey?: string;
+  baseURL?: string;
+}
+
+/**
+ * Merge config file + environment variables + CLI overrides into a single
+ * ResolvedLLMConfig. Priority (high → low):
+ *   CLI flags > ENV vars > config file > built-in defaults
+ */
+export function resolveConfig(overrides: CliConfigOverrides = {}): ResolvedLLMConfig {
+  const file = readConfigFile();
+
+  // 1. Provider
+  const provider: ProviderName =
+    (overrides.provider as ProviderName | undefined) ||
+    (env('OPEN_MOTION_PROVIDER') as ProviderName | undefined) ||
+    file.provider ||
+    'openai';
+
+  // 2. Model — global override, then provider-specific, then default
+  const modelFromEnv = env('OPEN_MOTION_MODEL');
+  const modelFromFile =
+    file.model || (file[provider] as { model?: string } | undefined)?.model;
+  const model =
+    overrides.model || modelFromEnv || modelFromFile || DEFAULT_MODELS[provider];
+
+  // 3. API key / base URL (provider-specific)
+  let apiKey: string | undefined;
+  let baseURL: string | undefined;
+
+  switch (provider) {
+    case 'openai':
+      apiKey =
+        overrides.apiKey ||
+        env('OPENAI_API_KEY') ||
+        file.openai?.apiKey;
+      break;
+    case 'anthropic':
+      apiKey =
+        overrides.apiKey ||
+        env('ANTHROPIC_API_KEY') ||
+        file.anthropic?.apiKey;
+      break;
+    case 'google':
+      apiKey =
+        overrides.apiKey ||
+        env('GOOGLE_API_KEY') ||
+        env('GEMINI_API_KEY') ||
+        file.google?.apiKey;
+      break;
+    case 'ollama':
+      baseURL =
+        overrides.baseURL ||
+        env('OPEN_MOTION_BASE_URL') ||
+        file.ollama?.baseURL ||
+        'http://localhost:11434';
+      break;
+    case 'openai-compatible':
+      apiKey =
+        overrides.apiKey ||
+        env('OPEN_MOTION_API_KEY') ||
+        file['openai-compatible']?.apiKey;
+      baseURL =
+        overrides.baseURL ||
+        env('OPEN_MOTION_BASE_URL') ||
+        file['openai-compatible']?.baseURL;
+      break;
+  }
+
+  return { provider, model, apiKey, baseURL };
+}
+
+/**
+ * Validate config and throw a human-readable error if required fields are missing.
+ */
+export function validateConfig(cfg: ResolvedLLMConfig): void {
+  if (cfg.provider === 'ollama') {
+    // Ollama runs locally — no API key needed
+    return;
+  }
+  if (cfg.provider === 'openai-compatible') {
+    if (!cfg.baseURL) {
+      throw new Error(
+        'openai-compatible provider requires a base URL.\n' +
+        'Set it with: open-motion config set openai-compatible.baseURL <url>\n' +
+        'or set the OPEN_MOTION_BASE_URL environment variable.'
+      );
+    }
+    return;
+  }
+  if (!cfg.apiKey) {
+    const envVar: Record<ProviderName, string> = {
+      openai: 'OPENAI_API_KEY',
+      anthropic: 'ANTHROPIC_API_KEY',
+      google: 'GOOGLE_API_KEY',
+      ollama: '',
+      'openai-compatible': 'OPEN_MOTION_API_KEY',
+    };
+    const configKey: Record<ProviderName, string> = {
+      openai: 'openai.apiKey',
+      anthropic: 'anthropic.apiKey',
+      google: 'google.apiKey',
+      ollama: '',
+      'openai-compatible': 'openai-compatible.apiKey',
+    };
+    throw new Error(
+      `No API key found for provider "${cfg.provider}".\n` +
+      `Set it with one of:\n` +
+      `  open-motion config set ${configKey[cfg.provider]} <key>\n` +
+      `  export ${envVar[cfg.provider]}=<key>`
+    );
+  }
+}
diff --git a/packages/cli/src/llm/factory.ts b/packages/cli/src/llm/factory.ts
new file mode 100644
index 0000000..5810ff9
--- /dev/null
+++ b/packages/cli/src/llm/factory.ts
@@ -0,0 +1,54 @@
+import type { LanguageModelV1 } from 'ai';
+import type { ResolvedLLMConfig } from './types';
+
+/**
+ * Create a LanguageModelV1 instance from the resolved config.
+ * Each provider SDK is imported lazily so the CLI doesn't fail if a provider's
+ * package is somehow missing (peer-dep install issues, etc.).
+ */
+export async function createModel(cfg: ResolvedLLMConfig): Promise<LanguageModelV1> {
+  switch (cfg.provider) {
+    case 'openai': {
+      const { createOpenAI } = await import('@ai-sdk/openai');
+      const client = createOpenAI({ apiKey: cfg.apiKey });
+      return client(cfg.model) as LanguageModelV1;
+    }
+
+    case 'anthropic': {
+      const { createAnthropic } = await import('@ai-sdk/anthropic');
+      const client = createAnthropic({ apiKey: cfg.apiKey });
+      return client(cfg.model) as LanguageModelV1;
+    }
+
+    case 'google': {
+      const { createGoogleGenerativeAI } = await import('@ai-sdk/google');
+      const client = createGoogleGenerativeAI({ apiKey: cfg.apiKey });
+      return client(cfg.model) as LanguageModelV1;
+    }
+
+    case 'ollama': {
+      const { ollama: createOllama } = await import('ollama-ai-provider');
+      // ollama-ai-provider exports a pre-configured instance; to set a custom
+      // base URL we create a new one via createOllama (same module, named export).
+      if (cfg.baseURL && cfg.baseURL !== 'http://localhost:11434') {
+        const { createOllama: factory } = await import('ollama-ai-provider');
+        const client = factory({ baseURL: `${cfg.baseURL}/api` });
+        return client(cfg.model) as LanguageModelV1;
+      }
+      return createOllama(cfg.model) as LanguageModelV1;
+    }
+
+    case 'openai-compatible': {
+      const { createOpenAI } = await import('@ai-sdk/openai');
+      const client = createOpenAI({
+        baseURL: cfg.baseURL,
+        apiKey: cfg.apiKey || 'placeholder',
+      });
+      return client(cfg.model) as LanguageModelV1;
+    }
+
+    default: {
+      throw new Error(`Unknown provider: ${(cfg as ResolvedLLMConfig).provider}`);
+    }
+  }
+}
diff --git a/packages/cli/src/llm/types.ts b/packages/cli/src/llm/types.ts
new file mode 100644
index 0000000..ce0439c
--- /dev/null
+++ b/packages/cli/src/llm/types.ts
@@ -0,0 +1,65 @@
+export type ProviderName =
+  | 'openai'
+  | 'anthropic'
+  | 'google'
+  | 'ollama'
+  | 'openai-compatible';
+
+export interface OpenAIConfig {
+  apiKey?: string;
+  model?: string;
+}
+
+export interface AnthropicConfig {
+  apiKey?: string;
+  model?: string;
+}
+
+export interface GoogleConfig {
+  apiKey?: string;
+  model?: string;
+}
+
+export interface OllamaConfig {
+  baseURL?: string;
+  model?: string;
+}
+
+export interface OpenAICompatibleConfig {
+  baseURL?: string;
+  apiKey?: string;
+  model?: string;
+}
+
+/**
+ * Shape stored in ~/.open-motion/config.json
+ */
+export interface OpenMotionLLMConfig {
+  provider?: ProviderName;
+  /** Global model override (takes priority over provider-specific model) */
+  model?: string;
+  openai?: OpenAIConfig;
+  anthropic?: AnthropicConfig;
+  google?: GoogleConfig;
+  ollama?: OllamaConfig;
+  'openai-compatible'?: OpenAICompatibleConfig;
+}
+
+/**
+ * Fully resolved config after merging file + env vars + CLI flags
+ */
+export interface ResolvedLLMConfig {
+  provider: ProviderName;
+  model: string;
+  apiKey?: string;
+  baseURL?: string;
+}
+
+/** Default models for each provider */
+export const DEFAULT_MODELS: Record<ProviderName, string> = {
+  openai: 'gpt-4o',
+  anthropic: 'claude-3-5-sonnet-20241022',
+  google: 'gemini-1.5-pro',
+  ollama: 'llama3',
+  'openai-compatible': 'gpt-4o',
+};
diff --git a/packages/cli/src/prompts/edit.ts b/packages/cli/src/prompts/edit.ts
new file mode 100644
index 0000000..62b1d41
--- /dev/null
+++ b/packages/cli/src/prompts/edit.ts
@@ -0,0 +1,49 @@
+export const EDIT_SYSTEM_PROMPT = `You are an expert at editing React video animation components written with the open-motion library.
+
+## open-motion API Reference
+
+All animation is driven entirely by the current frame number. NEVER use useState, useEffect,
+setTimeout, setInterval, or any real-time mechanism for animation.
+
+### Core hooks (import from '@open-motion/core')
+- \`useCurrentFrame()\` — returns the current frame number (0-based integer)
+- \`useVideoConfig()\` — returns \`{ width, height, fps, durationInFrames }\`
+
+### Animation utilities (import from '@open-motion/core')
+- \`interpolate(value, inputRange, outputRange, options?)\`
+  - options: \`{ extrapolateLeft?: 'clamp'|'extend', extrapolateRight?: 'clamp'|'extend' }\`
+- \`spring({ frame, fps, config?, from?, to? })\`
+  - config: \`{ stiffness?: number, damping?: number, mass?: number }\`
+
+### Layout component
+- \`<Sequence from={n} durationInFrames={n}>\` — children visible only in a frame range
+
+## Editing rules
+1. Keep the same component name and named export
+2. Preserve all inline styles (no CSS files)
+3. Only modify what the user explicitly asks to change
+4. Keep the code compiling and functionally correct
+5. Do NOT add new imports unless they are from \`react\` or \`@open-motion/core\`
+`;
+
+export function buildEditPrompt(fileContent: string, instruction: string): string {
+  return `Here is the current TSX file:
+
+\`\`\`tsx
+${fileContent}
+\`\`\`
+
+Instruction: ${instruction}
+
+Return ONLY the complete updated TSX file content. No markdown code fences, no explanation.`;
+}
+
+/**
+ * Strip markdown code fences from a raw TSX edit response, if present.
+ */
+export function parseEditResponse(text: string): string {
+  return text
+    .replace(/^```(?:tsx?|jsx?|typescript|javascript)?\s*\n?/m, '')
+    .replace(/\n?```\s*$/m, '')
+    .trim();
+}
diff --git a/packages/cli/src/prompts/generate.ts b/packages/cli/src/prompts/generate.ts
new file mode 100644
index 0000000..28681ac
--- /dev/null
+++ b/packages/cli/src/prompts/generate.ts
@@ -0,0 +1,194 @@
+// ---------------------------------------------------------------------------
+// System prompt shared by all generation calls
+// ---------------------------------------------------------------------------
+export const GENERATE_SYSTEM_PROMPT = `You are an expert at creating React video animation components using the open-motion library.
+
+## open-motion API Reference
+
+All animation is driven entirely by the current frame number. NEVER use useState, useEffect,
+setTimeout, setInterval, or any real-time mechanism for animation.
+
+### Core hooks (import from '@open-motion/core')
+- \`useCurrentFrame()\` — returns the current frame number (0-based integer)
+- \`useVideoConfig()\` — returns \`{ width, height, fps, durationInFrames }\`
+
+### Animation utilities (import from '@open-motion/core')
+- \`interpolate(value, inputRange, outputRange, options?)\`
+  - Maps a value from one range to another (like CSS linear-gradient or Framer motion)
+  - options: \`{ extrapolateLeft?: 'clamp'|'extend', extrapolateRight?: 'clamp'|'extend' }\`
+  - Example: \`interpolate(frame, [0, 30], [0, 1], { extrapolateRight: 'clamp' })\`
+- \`spring({ frame, fps, config?, from?, to? })\`
+  - Returns a spring-animated value (0→1 by default)
+  - config: \`{ stiffness?: number, damping?: number, mass?: number }\`
+  - Example: \`spring({ frame, fps, config: { stiffness: 100, damping: 10 } })\`
+
+### Layout component (import from '@open-motion/core')
+- \`<Sequence from={n} durationInFrames={n}>\`
+  - Children are only rendered during frames [from, from+durationInFrames)
+  - Inside Sequence, \`useCurrentFrame()\` returns a frame relative to \`from\`
+
+## Coding rules
+1. Export the component as a **named export** (not default)
+2. All styles must be **inline React styles** (no CSS files, no styled-components)
+3. The root element MUST fill the full \`width\` and \`height\` from \`useVideoConfig()\`
+4. Never import anything outside of \`react\` and \`@open-motion/core\`
+5. Do NOT add \`<Composition>\` registration inside scene files — that belongs in main.tsx
+6. The component must be **completely self-contained** with no props required
+7. Use visually appealing designs: thoughtful colors, smooth animations, readable typography
+
+## Minimal valid example
+\`\`\`tsx
+import React from 'react';
+import { useCurrentFrame, useVideoConfig, interpolate, spring } from '@open-motion/core';
+
+export const ExampleScene = () => {
+  const frame = useCurrentFrame();
+  const { width, height, fps } = useVideoConfig();
+
+  const opacity = interpolate(frame, [0, 20], [0, 1], { extrapolateRight: 'clamp' });
+  const scale = spring({ frame, fps, config: { stiffness: 80, damping: 12 } });
+
+  return (
+    <div style={{
+      width,
+      height,
+      display: 'flex',
+      justifyContent: 'center',
+      alignItems: 'center',
+      backgroundColor: '#1a1a2e',
+    }}>
+      <h1 style={{
+        color: '#e0e0e0',
+        fontSize: 72,
+        fontFamily: 'sans-serif',
+        opacity,
+        transform: \`scale(\${scale})\`,
+      }}>
+        Hello open-motion
+      </h1>
+    </div>
+  );
+};
+\`\`\`
+`;
+
+// ---------------------------------------------------------------------------
+// Planning prompt: ask the LLM to break a description into scenes
+// ---------------------------------------------------------------------------
+export function buildPlanningPrompt(description: string): string {
+  return `Analyze the following video description and break it into logical scenes.
+
+Video description: "${description}"
+
+Respond with a JSON object (and nothing else) in this exact shape:
+{
+  "videoTitle": "A concise title for the entire video",
+  "scenes": [
+    {
+      "id": "kebab-case-unique-id",
+      "componentName": "PascalCaseComponentName",
+      "title": "Short scene title",
+      "description": "What this scene shows and how it animates",
+      "durationInSeconds": 5
+    }
+  ]
+}
+
+Guidelines:
+- Total video duration should feel natural for the content (typically 20-90 seconds)
+- Each scene should be self-contained and visually distinct
+- \`componentName\` must be a valid PascalCase React component name (e.g. "IntroScene", "DataFlowScene")
+- \`id\` must be unique kebab-case (e.g. "intro-scene", "data-flow-scene")
+- Aim for 3-6 scenes unless the content clearly needs more or fewer
+- Describe animations concretely (e.g. "text fades in from bottom, then a line draws across")
+
+Return ONLY the JSON object. No markdown fences, no explanation.`;
+}
+
+// ---------------------------------------------------------------------------
+// Code generation prompt: ask the LLM to write TSX for one scene
+// ---------------------------------------------------------------------------
+export interface SceneCodeContext {
+  componentName: string;
+  title: string;
+  description: string;
+  durationInSeconds: number;
+  durationInFrames: number;
+  fps: number;
+  width: number;
+  height: number;
+  sceneIndex: number;
+  totalScenes: number;
+}
+
+export function buildSceneCodePrompt(ctx: SceneCodeContext): string {
+  return `Generate a complete TSX file for the following open-motion scene:
+
+Component name : ${ctx.componentName}
+Scene title    : ${ctx.title}
+Scene index    : ${ctx.sceneIndex + 1} of ${ctx.totalScenes}
+Duration       : ${ctx.durationInSeconds}s = ${ctx.durationInFrames} frames at ${ctx.fps}fps
+Video size     : ${ctx.width}x${ctx.height}
+
+Scene description:
+${ctx.description}
+
+Requirements:
+- The component must be named exactly \`${ctx.componentName}\` and exported as a named export
+- Fill the full ${ctx.width}x${ctx.height} canvas
+- Use smooth frame-based animations (interpolate / spring)
+- Keep text readable and well-positioned
+- Use colors and typography appropriate for the scene's content
+- Do NOT include any Composition registration
+
+Return ONLY the raw TSX file content. No markdown code fences, no explanation.`;
+}
+
+// ---------------------------------------------------------------------------
+// Response parser: extract JSON plan from LLM response
+// ---------------------------------------------------------------------------
+export interface ScenePlan {
+  videoTitle: string;
+  scenes: Array<{
+    id: string;
+    componentName: string;
+    title: string;
+    description: string;
+    durationInSeconds: number;
+  }>;
+}
+
+export function parsePlanResponse(text: string): ScenePlan {
+  // Strip markdown code fences if the model included them anyway
+  const cleaned = text
+    .replace(/^```(?:json)?\s*/m, '')
+    .replace(/\s*```\s*$/m, '')
+    .trim();
+
+  let plan: ScenePlan;
+  try {
+    plan = JSON.parse(cleaned);
+  } catch {
+    throw new Error(
+      `LLM returned invalid JSON for scene plan.\nRaw response:\n${text}`
+    );
+  }
+
+  if (!plan.videoTitle || !Array.isArray(plan.scenes) || plan.scenes.length === 0) {
+    throw new Error(
+      `LLM scene plan is missing required fields.\nParsed:\n${JSON.stringify(plan, null, 2)}`
+    );
+  }
+
+  return plan;
+}
+
+/**
+ * Strip markdown code fences from a raw TSX response, if present.
+ */
+export function parseCodeResponse(text: string): string {
+  return text
+    .replace(/^```(?:tsx?|jsx?|typescript|javascript)?\s*\n?/m, '')
+    .replace(/\n?```\s*$/m, '')
+    .trim();
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f09b245..8ab3b01 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -47,7 +47,7 @@ importers:
     dependencies:
       '@open-motion/cli':
         specifier: file:../../packages/cli
-        version: file:packages/cli
+        version: file:packages/cli(react@18.3.1)(zod@3.25.76)
       '@open-motion/core':
         specifier: workspace:*
         version: link:../../packages/core
@@ -82,6 +82,15 @@ importers:
 
   packages/cli:
     dependencies:
+      '@ai-sdk/anthropic':
+        specifier: ^1.2.0
+        version: 1.2.12(zod@3.25.76)
+      '@ai-sdk/google':
+        specifier: ^1.2.0
+        version: 1.2.22(zod@3.25.76)
+      '@ai-sdk/openai':
+        specifier: ^1.3.0
+        version: 1.3.24(zod@3.25.76)
       '@open-motion/core':
         specifier: workspace:*
         version: link:../core
@@ -91,12 +100,24 @@ importers:
       '@open-motion/renderer':
         specifier: workspace:*
         version: link:../renderer
+      ai:
+        specifier: ^4.3.0
+        version: 4.3.19(react@18.3.1)(zod@3.25.76)
+      chalk:
+        specifier: ^4.1.2
+        version: 4.1.2
       cli-progress:
         specifier: ^3.12.0
         version: 3.12.0
       commander:
         specifier: ^11.0.0
         version: 11.1.0
+      diff:
+        specifier: ^5.2.0
+        version: 5.2.2
+      ollama-ai-provider:
+        specifier: ^1.2.0
+        version: 1.2.0(zod@3.25.76)
       playwright:
         specifier: ^1.58.1
         version: 1.58.1
@@ -104,6 +125,9 @@ importers:
       '@types/cli-progress':
         specifier: ^3.11.6
         version: 3.11.6
+      '@types/diff':
+        specifier: ^5.2.1
+        version: 5.2.3
 
   packages/core:
     dependencies:
@@ -137,6 +161,50 @@ importers:
 
 packages:
 
+  '@ai-sdk/anthropic@1.2.12':
+    resolution: {integrity: sha512-YSzjlko7JvuiyQFmI9RN1tNZdEiZxc+6xld/0tq/VkJaHpEzGAb1yiNxxvmYVcjvfu/PcvCxAAYXmTYQQ63IHQ==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      zod: ^3.0.0
+
+  '@ai-sdk/google@1.2.22':
+    resolution: {integrity: sha512-Ppxu3DIieF1G9pyQ5O1Z646GYR0gkC57YdBqXJ82qvCdhEhZHu0TWhmnOoeIWe2olSbuDeoOY+MfJrW8dzS3Hw==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      zod: ^3.0.0
+
+  '@ai-sdk/openai@1.3.24':
+    resolution: {integrity: sha512-GYXnGJTHRTZc4gJMSmFRgEQudjqd4PUN0ZjQhPwOAYH1yOAvQoG/Ikqs+HyISRbLPCrhbZnPKCNHuRU4OfpW0Q==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      zod: ^3.0.0
+
+  '@ai-sdk/provider-utils@2.2.8':
+    resolution: {integrity: sha512-fqhG+4sCVv8x7nFzYnFo19ryhAa3w096Kmc3hWxMQfW/TubPOmt3A6tYZhl4mUfQWWQMsuSkLrtjlWuXBVSGQA==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      zod: ^3.23.8
+
+  '@ai-sdk/provider@1.1.3':
+    resolution: {integrity: sha512-qZMxYJ0qqX/RfnuIaab+zp8UAeJn/ygXXAffR5I4N0n1IrvA6qBsjc8hXLmBiMV2zoXlifkacF7sEFnYnjBcqg==}
+    engines: {node: '>=18'}
+
+  '@ai-sdk/react@1.2.12':
+    resolution: {integrity: sha512-jK1IZZ22evPZoQW3vlkZ7wvjYGYF+tRBKXtrcolduIkQ/m/sOAVcVeVDUDvh1T91xCnWCdUGCPZg2avZ90mv3g==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      react: ^18 || ^19 || ^19.0.0-rc
+      zod: ^3.23.8
+    peerDependenciesMeta:
+      zod:
+        optional: true
+
+  '@ai-sdk/ui-utils@1.2.11':
+    resolution: {integrity: sha512-3zcwCc8ezzFlwp3ZD15wAPjf2Au4s3vAbKsXQVyhxODHcmu0iyPO2Eua6D/vicq/AUm/BAo60r97O6HU+EI0+w==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      zod: ^3.23.8
+
   '@babel/code-frame@7.29.0':
     resolution: {integrity: sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==}
     engines: {node: '>=6.9.0'}
@@ -473,6 +541,10 @@ packages:
       react: ^18.0.0
       react-dom: ^18.0.0
 
+  '@opentelemetry/api@1.9.0':
+    resolution: {integrity: sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg==}
+    engines: {node: '>=8.0.0'}
+
   '@rolldown/pluginutils@1.0.0-beta.27':
     resolution: {integrity: sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA==}
 
@@ -619,6 +691,12 @@ packages:
   '@types/cli-progress@3.11.6':
     resolution: {integrity: sha512-cE3+jb9WRlu+uOSAugewNpITJDt1VF8dHOopPO4IABFc3SXYL5WE/+PTz/FCdZRRfIujiWW3n3aMbv1eIGVRWA==}
 
+  '@types/diff-match-patch@1.0.36':
+    resolution: {integrity: sha512-xFdR6tkm0MWvBfO8xXCSsinYxHcqkQUlcHeSpMC2ukzOb6lwQAfDmW+Qt0AvlGd8HpsS28qKsB+oPeJn9I39jg==}
+
+  '@types/diff@5.2.3':
+    resolution: {integrity: sha512-K0Oqlrq3kQMaO2RhfrNQX5trmt+XLyom88zS0u84nnIcLvFnRUMRRHmrGny5GSM+kNO9IZLARsdQHDzkhAgmrQ==}
+
   '@types/estree@1.0.8':
     resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
 
@@ -660,6 +738,16 @@ packages:
   '@webgpu/types@0.1.69':
     resolution: {integrity: sha512-RPmm6kgRbI8e98zSD3RVACvnuktIja5+yLgDAkTmxLr90BEwdTXRQWNLF3ETTTyH/8mKhznZuN5AveXYFEsMGQ==}
 
+  ai@4.3.19:
+    resolution: {integrity: sha512-dIE2bfNpqHN3r6IINp9znguYdhIOheKW2LDigAMrgt/upT3B8eBGPSCblENvaZGoq+hxaN9fSMzjWpbqloP+7Q==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      react: ^18 || ^19 || ^19.0.0-rc
+      zod: ^3.23.8
+    peerDependenciesMeta:
+      react:
+        optional: true
+
   ansi-colors@4.1.3:
     resolution: {integrity: sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw==}
     engines: {node: '>=6'}
@@ -676,6 +764,10 @@ packages:
     resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==}
     engines: {node: '>=12'}
 
+  ansi-styles@4.3.0:
+    resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==}
+    engines: {node: '>=8'}
+
   ansi-styles@6.2.3:
     resolution: {integrity: sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==}
     engines: {node: '>=12'}
@@ -713,6 +805,10 @@ packages:
   caniuse-lite@1.0.30001767:
     resolution: {integrity: sha512-34+zUAMhSH+r+9eKmYG+k2Rpt8XttfE4yXAjoZvkAPs15xcYQhyBYdalJ65BzivAvGRMViEjy6oKr/S91loekQ==}
 
+  chalk@4.1.2:
+    resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
+    engines: {node: '>=10'}
+
   chalk@5.3.0:
     resolution: {integrity: sha512-dLitG79d+GV1Nb/VYcCDFivJeK1hiukt9QjRNVOsUtTy1rR1YJsmpGGTZ3qJos+uw7WmWF4wUwBd9jxjocFC2w==}
     engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
@@ -736,6 +832,13 @@ packages:
     resolution: {integrity: sha512-wfOBkjXteqSnI59oPcJkcPl/ZmwvMMOj340qUIY1SKZCv0B9Cf4D4fAucRkIKQmsIuYK3x1rrgU7MeGRruiuiA==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
 
+  color-convert@2.0.1:
+    resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
+    engines: {node: '>=7.0.0'}
+
+  color-name@1.1.4:
+    resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
+
   colorette@2.0.20:
     resolution: {integrity: sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==}
 
@@ -775,10 +878,21 @@ packages:
       supports-color:
         optional: true
 
+  dequal@2.0.3:
+    resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==}
+    engines: {node: '>=6'}
+
   detect-indent@6.1.0:
     resolution: {integrity: sha512-reYkTUJAZb9gUuZ2RvVCNhVHdg62RHnJ7WJl8ftMi4diZ6NWlciOzQN88pUhSELEwflJht4oQDv0F0BMlwaYtA==}
     engines: {node: '>=8'}
 
+  diff-match-patch@1.0.5:
+    resolution: {integrity: sha512-IayShXAgj/QMXgB0IWmKx+rOPuGMhqm5w6jvFxmVenXKIzRqTAAsbBPT3kWQeGANj3jGgvcvv4yK6SxqYmikgw==}
+
+  diff@5.2.2:
+    resolution: {integrity: sha512-vtcDfH3TOjP8UekytvnHH1o1P4FcUdt4eQ1Y+Abap1tk/OB2MWQvcwS2ClCd1zuIhc3JKOx6p3kod8Vfys3E+A==}
+    engines: {node: '>=0.3.1'}
+
   dir-glob@3.0.1:
     resolution: {integrity: sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==}
     engines: {node: '>=8'}
@@ -883,6 +997,10 @@ packages:
   graceful-fs@4.2.11:
     resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==}
 
+  has-flag@4.0.0:
+    resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==}
+    engines: {node: '>=8'}
+
   human-id@4.1.3:
     resolution: {integrity: sha512-tsYlhAYpjCKa//8rXZ9DqKEawhPoSytweBC2eNvcaDK+57RZLHGqNs3PZTQO6yekLFSuvA6AlnAfrw1uBvtb+Q==}
     hasBin: true
@@ -955,11 +1073,19 @@ packages:
     engines: {node: '>=6'}
     hasBin: true
 
+  json-schema@0.4.0:
+    resolution: {integrity: sha512-es94M3nTIfsEPisRafak+HDLfHXnKBhV3vU5eqPcS3flIWqcxJWgXHXiey3YrpaNsanY5ei1VoYEbOzijuq9BA==}
+
   json5@2.2.3:
     resolution: {integrity: sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==}
     engines: {node: '>=6'}
     hasBin: true
 
+  jsondiffpatch@0.6.0:
+    resolution: {integrity: sha512-3QItJOXp2AP1uv7waBkao5nCvhEv+QmJAd38Ybq7wNI74Q+BBmnLn4EDKz6yI9xGAIQoUF87qHt+kc1IVxB4zQ==}
+    engines: {node: ^18.0.0 || >=20.0.0}
+    hasBin: true
+
   jsonfile@4.0.0:
     resolution: {integrity: sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==}
 
@@ -1052,6 +1178,15 @@ packages:
     resolution: {integrity: sha512-ppwTtiJZq0O/ai0z7yfudtBpWIoxM8yE6nHi1X47eFR2EWORqfbu6CnPlNsjeN683eT0qG6H/Pyf9fCcvjnnnQ==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
 
+  ollama-ai-provider@1.2.0:
+    resolution: {integrity: sha512-jTNFruwe3O/ruJeppI/quoOUxG7NA6blG3ZyQj3lei4+NnJo7bi3eIRWqlVpRlu/mbzbFXeJSBuYQWF6pzGKww==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      zod: ^3.0.0
+    peerDependenciesMeta:
+      zod:
+        optional: true
+
   onetime@5.1.2:
     resolution: {integrity: sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==}
     engines: {node: '>=6'}
@@ -1086,6 +1221,9 @@ packages:
   package-manager-detector@0.2.11:
     resolution: {integrity: sha512-BEnLolu+yuz22S56CU1SUKq3XC3PkwD5wv4ikR4MfGvnRVcmzXR9DwSlW2fEamyTPyXHomBJRzgapeuBvRNzJQ==}
 
+  partial-json@0.1.7:
+    resolution: {integrity: sha512-Njv/59hHaokb/hRUjce3Hdv12wd60MtM9Z5Olmn+nehe0QDAsRtRbJPvJ0Z91TusF0SuZRIvnM+S4l6EIP8leA==}
+
   path-exists@4.0.0:
     resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==}
     engines: {node: '>=8'}
@@ -1189,6 +1327,9 @@ packages:
   scheduler@0.23.2:
     resolution: {integrity: sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==}
 
+  secure-json-parse@2.7.0:
+    resolution: {integrity: sha512-6aU+Rwsezw7VR8/nyvKTx8QpWH9FrcYiXXlqC4z5d5XQBDRqtbfsRjnwGyqbi3gddNtWHuEk9OANUotL26qKUw==}
+
   semver@6.3.1:
     resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==}
     hasBin: true
@@ -1259,6 +1400,15 @@ packages:
     resolution: {integrity: sha512-dOESqjYr96iWYylGObzd39EuNTa5VJxyvVAEm5Jnh7KGo75V43Hk1odPQkNDyXNmUR6k+gEiDVXnjB8HJ3crXw==}
     engines: {node: '>=12'}
 
+  supports-color@7.2.0:
+    resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
+    engines: {node: '>=8'}
+
+  swr@2.4.0:
+    resolution: {integrity: sha512-sUlC20T8EOt1pHmDiqueUWMmRRX03W7w5YxovWX7VR2KHEPCTMly85x05vpkP5i6Bu4h44ePSMD9Tc+G2MItFw==}
+    peerDependencies:
+      react: ^16.11.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
   term-size@2.2.1:
     resolution: {integrity: sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg==}
     engines: {node: '>=8'}
@@ -1266,6 +1416,10 @@ packages:
   three@0.182.0:
     resolution: {integrity: sha512-GbHabT+Irv+ihI1/f5kIIsZ+Ef9Sl5A1Y7imvS5RQjWgtTPfPnZ43JmlYI7NtCRDK9zir20lQpfg8/9Yd02OvQ==}
 
+  throttleit@2.1.0:
+    resolution: {integrity: sha512-nt6AMGKW1p/70DF/hGBdJB57B8Tspmbp5gfJ8ilhLnt7kkr2ye7hzD6NVG8GGErk2HWF34igrL2CXmNIkzKqKw==}
+    engines: {node: '>=18'}
+
   to-regex-range@5.0.1:
     resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==}
     engines: {node: '>=8.0'}
@@ -1326,6 +1480,11 @@ packages:
     peerDependencies:
       browserslist: '>= 4.21.0'
 
+  use-sync-external-store@1.6.0:
+    resolution: {integrity: sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
   vite@5.4.21:
     resolution: {integrity: sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==}
     engines: {node: ^18.0.0 || >=20.0.0}
@@ -1377,8 +1536,62 @@ packages:
     resolution: {integrity: sha512-2eHWfjaoXgTBC2jNM1LRef62VQa0umtvRiDSk6HSzW7RvS5YtkabJrwYLLEKWBc8a5U2PTSCs+dJjUTJdlHsWQ==}
     engines: {node: '>= 14'}
 
+  zod-to-json-schema@3.25.1:
+    resolution: {integrity: sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA==}
+    peerDependencies:
+      zod: ^3.25 || ^4
+
+  zod@3.25.76:
+    resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==}
+
 snapshots:
 
+  '@ai-sdk/anthropic@1.2.12(zod@3.25.76)':
+    dependencies:
+      '@ai-sdk/provider': 1.1.3
+      '@ai-sdk/provider-utils': 2.2.8(zod@3.25.76)
+      zod: 3.25.76
+
+  '@ai-sdk/google@1.2.22(zod@3.25.76)':
+    dependencies:
+      '@ai-sdk/provider': 1.1.3
+      '@ai-sdk/provider-utils': 2.2.8(zod@3.25.76)
+      zod: 3.25.76
+
+  '@ai-sdk/openai@1.3.24(zod@3.25.76)':
+    dependencies:
+      '@ai-sdk/provider': 1.1.3
+      '@ai-sdk/provider-utils': 2.2.8(zod@3.25.76)
+      zod: 3.25.76
+
+  '@ai-sdk/provider-utils@2.2.8(zod@3.25.76)':
+    dependencies:
+      '@ai-sdk/provider': 1.1.3
+      nanoid: 3.3.11
+      secure-json-parse: 2.7.0
+      zod: 3.25.76
+
+  '@ai-sdk/provider@1.1.3':
+    dependencies:
+      json-schema: 0.4.0
+
+  '@ai-sdk/react@1.2.12(react@18.3.1)(zod@3.25.76)':
+    dependencies:
+      '@ai-sdk/provider-utils': 2.2.8(zod@3.25.76)
+      '@ai-sdk/ui-utils': 1.2.11(zod@3.25.76)
+      react: 18.3.1
+      swr: 2.4.0(react@18.3.1)
+      throttleit: 2.1.0
+    optionalDependencies:
+      zod: 3.25.76
+
+  '@ai-sdk/ui-utils@1.2.11(zod@3.25.76)':
+    dependencies:
+      '@ai-sdk/provider': 1.1.3
+      '@ai-sdk/provider-utils': 2.2.8(zod@3.25.76)
+      zod: 3.25.76
+      zod-to-json-schema: 3.25.1(zod@3.25.76)
+
   '@babel/code-frame@7.29.0':
     dependencies:
       '@babel/helper-validator-identifier': 7.28.5
@@ -1762,14 +1975,24 @@ snapshots:
       '@nodelib/fs.scandir': 2.1.5
       fastq: 1.20.1
 
-  '@open-motion/cli@file:packages/cli':
+  '@open-motion/cli@file:packages/cli(react@18.3.1)(zod@3.25.76)':
     dependencies:
+      '@ai-sdk/anthropic': 1.2.12(zod@3.25.76)
+      '@ai-sdk/google': 1.2.22(zod@3.25.76)
+      '@ai-sdk/openai': 1.3.24(zod@3.25.76)
       '@open-motion/core': link:packages/core
       '@open-motion/encoder': link:packages/encoder
       '@open-motion/renderer': link:packages/renderer
+      ai: 4.3.19(react@18.3.1)(zod@3.25.76)
+      chalk: 4.1.2
       cli-progress: 3.12.0
       commander: 11.1.0
+      diff: 5.2.2
+      ollama-ai-provider: 1.2.0(zod@3.25.76)
       playwright: 1.58.1
+    transitivePeerDependencies:
+      - react
+      - zod
 
   '@open-motion/renderer@file:packages/renderer(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
@@ -1778,6 +2001,8 @@ snapshots:
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
 
+  '@opentelemetry/api@1.9.0': {}
+
   '@rolldown/pluginutils@1.0.0-beta.27': {}
 
   '@rollup/rollup-android-arm-eabi@4.57.1':
@@ -1882,6 +2107,10 @@ snapshots:
     dependencies:
       '@types/node': 25.2.0
 
+  '@types/diff-match-patch@1.0.36': {}
+
+  '@types/diff@5.2.3': {}
+
   '@types/estree@1.0.8': {}
 
   '@types/fluent-ffmpeg@2.1.28':
@@ -1933,6 +2162,18 @@ snapshots:
 
   '@webgpu/types@0.1.69': {}
 
+  ai@4.3.19(react@18.3.1)(zod@3.25.76):
+    dependencies:
+      '@ai-sdk/provider': 1.1.3
+      '@ai-sdk/provider-utils': 2.2.8(zod@3.25.76)
+      '@ai-sdk/react': 1.2.12(react@18.3.1)(zod@3.25.76)
+      '@ai-sdk/ui-utils': 1.2.11(zod@3.25.76)
+      '@opentelemetry/api': 1.9.0
+      jsondiffpatch: 0.6.0
+      zod: 3.25.76
+    optionalDependencies:
+      react: 18.3.1
+
   ansi-colors@4.1.3: {}
 
   ansi-escapes@5.0.0:
@@ -1943,6 +2184,10 @@ snapshots:
 
   ansi-regex@6.2.2: {}
 
+  ansi-styles@4.3.0:
+    dependencies:
+      color-convert: 2.0.1
+
   ansi-styles@6.2.3: {}
 
   argparse@1.0.10:
@@ -1975,6 +2220,11 @@ snapshots:
 
   caniuse-lite@1.0.30001767: {}
 
+  chalk@4.1.2:
+    dependencies:
+      ansi-styles: 4.3.0
+      supports-color: 7.2.0
+
   chalk@5.3.0: {}
 
   chardet@2.1.1: {}
@@ -1994,6 +2244,12 @@ snapshots:
       slice-ansi: 5.0.0
       string-width: 5.1.2
 
+  color-convert@2.0.1:
+    dependencies:
+      color-name: 1.1.4
+
+  color-name@1.1.4: {}
+
   colorette@2.0.20: {}
 
   commander@11.0.0: {}
@@ -2018,8 +2274,14 @@ snapshots:
     dependencies:
       ms: 2.1.3
 
+  dequal@2.0.3: {}
+
   detect-indent@6.1.0: {}
 
+  diff-match-patch@1.0.5: {}
+
+  diff@5.2.2: {}
+
   dir-glob@3.0.1:
     dependencies:
       path-type: 4.0.0
@@ -2148,6 +2410,8 @@ snapshots:
 
   graceful-fs@4.2.11: {}
 
+  has-flag@4.0.0: {}
+
   human-id@4.1.3: {}
 
   human-signals@4.3.1: {}
@@ -2195,8 +2459,16 @@ snapshots:
 
   jsesc@3.1.0: {}
 
+  json-schema@0.4.0: {}
+
   json5@2.2.3: {}
 
+  jsondiffpatch@0.6.0:
+    dependencies:
+      '@types/diff-match-patch': 1.0.36
+      chalk: 5.3.0
+      diff-match-patch: 1.0.5
+
   jsonfile@4.0.0:
     optionalDependencies:
       graceful-fs: 4.2.11
@@ -2290,6 +2562,14 @@ snapshots:
     dependencies:
       path-key: 4.0.0
 
+  ollama-ai-provider@1.2.0(zod@3.25.76):
+    dependencies:
+      '@ai-sdk/provider': 1.1.3
+      '@ai-sdk/provider-utils': 2.2.8(zod@3.25.76)
+      partial-json: 0.1.7
+    optionalDependencies:
+      zod: 3.25.76
+
   onetime@5.1.2:
     dependencies:
       mimic-fn: 2.1.0
@@ -2320,6 +2600,8 @@ snapshots:
     dependencies:
       quansync: 0.2.11
 
+  partial-json@0.1.7: {}
+
   path-exists@4.0.0: {}
 
   path-key@3.1.1: {}
@@ -2427,6 +2709,8 @@ snapshots:
     dependencies:
       loose-envify: 1.4.0
 
+  secure-json-parse@2.7.0: {}
+
   semver@6.3.1: {}
 
   semver@7.7.3: {}
@@ -2483,10 +2767,22 @@ snapshots:
 
   strip-final-newline@3.0.0: {}
 
+  supports-color@7.2.0:
+    dependencies:
+      has-flag: 4.0.0
+
+  swr@2.4.0(react@18.3.1):
+    dependencies:
+      dequal: 2.0.3
+      react: 18.3.1
+      use-sync-external-store: 1.6.0(react@18.3.1)
+
   term-size@2.2.1: {}
 
   three@0.182.0: {}
 
+  throttleit@2.1.0: {}
+
   to-regex-range@5.0.1:
     dependencies:
       is-number: 7.0.0
@@ -2532,6 +2828,10 @@ snapshots:
       escalade: 3.2.0
       picocolors: 1.1.1
 
+  use-sync-external-store@1.6.0(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+
   vite@5.4.21(@types/node@25.2.0):
     dependencies:
       esbuild: 0.21.5
@@ -2558,3 +2858,9 @@ snapshots:
   yallist@3.1.1: {}
 
   yaml@2.3.1: {}
+
+  zod-to-json-schema@3.25.1(zod@3.25.76):
+    dependencies:
+      zod: 3.25.76
+
+  zod@3.25.76: {}

From be88b67b76acc64903c60f73ad4e50ea4a5c5d74 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Wed, 25 Feb 2026 22:53:12 +0900
Subject: [PATCH 06/28] fix(cli): translate all Japanese strings to English

---
 packages/cli/src/commands/config.ts   |  24 +++---
 packages/cli/src/commands/edit.ts     |  56 ++++++------
 packages/cli/src/commands/generate.ts |  36 ++++----
 packages/cli/src/index.ts             | 120 +++++++++++++-------------
 4 files changed, 118 insertions(+), 118 deletions(-)

diff --git a/packages/cli/src/commands/config.ts b/packages/cli/src/commands/config.ts
index d243269..2a32e06 100644
--- a/packages/cli/src/commands/config.ts
+++ b/packages/cli/src/commands/config.ts
@@ -60,13 +60,13 @@ export function runConfigSet(key: string, value: string): void {
   setConfigKey(key, value);
   const displayVal = maskSecret(key, value);
   console.log(chalk.green(`✓ ${key} = ${displayVal}`));
-  console.log(chalk.dim(`  保存先: ${CONFIG_FILE}`));
+  console.log(chalk.dim(`  Saved to: ${CONFIG_FILE}`));
 }
 
 export function runConfigGet(key: string): void {
   const value = getConfigKey(key);
   if (value === undefined) {
-    console.log(chalk.yellow(`  "${key}" は設定されていません`));
+    console.log(chalk.yellow(`  "${key}" is not set`));
   } else {
     console.log(`${key} = ${maskSecret(key, value)}`);
   }
@@ -77,16 +77,16 @@ export function runConfigList(): void {
   const pairs = flattenConfig(config);
 
   if (pairs.length === 0) {
-    console.log(chalk.dim('設定がありません'));
-    console.log(chalk.dim(`設定ファイル: ${CONFIG_FILE}`));
+    console.log(chalk.dim('No configuration found'));
+    console.log(chalk.dim(`Config file: ${CONFIG_FILE}`));
     console.log('');
-    console.log('例:');
+    console.log('Example:');
     console.log(chalk.cyan('  open-motion config set provider openai'));
     console.log(chalk.cyan('  open-motion config set openai.apiKey sk-...'));
     return;
   }
 
-  console.log(chalk.bold(`設定ファイル: ${CONFIG_FILE}`));
+  console.log(chalk.bold(`Config file: ${CONFIG_FILE}`));
   console.log('');
 
   for (const [key, value] of pairs) {
@@ -102,21 +102,21 @@ export function runConfigList(): void {
 export function printConfigHelp(): void {
   console.log(chalk.bold('open-motion config'));
   console.log('');
-  console.log('使用可能なコマンド:');
+  console.log('Available commands:');
   console.log(
-    `  ${chalk.cyan('open-motion config set <key> <value>')}  設定値を保存`
+    `  ${chalk.cyan('open-motion config set <key> <value>')}  Save a configuration value`
   );
   console.log(
-    `  ${chalk.cyan('open-motion config get <key>')}          設定値を表示`
+    `  ${chalk.cyan('open-motion config get <key>')}          Show a configuration value`
   );
   console.log(
-    `  ${chalk.cyan('open-motion config list')}               全設定を一覧表示`
+    `  ${chalk.cyan('open-motion config list')}               List all configuration values`
   );
   console.log('');
-  console.log('設定可能なキー:');
+  console.log('Configurable keys:');
   VALID_KEYS.forEach((k) => console.log(`  ${chalk.dim(k)}`));
   console.log('');
-  console.log('例:');
+  console.log('Example:');
   console.log(chalk.cyan('  open-motion config set provider anthropic'));
   console.log(chalk.cyan('  open-motion config set anthropic.apiKey sk-ant-...'));
   console.log(chalk.cyan('  open-motion config set openai-compatible.baseURL https://api.example.com/v1'));
diff --git a/packages/cli/src/commands/edit.ts b/packages/cli/src/commands/edit.ts
index 971c1ca..38cc186 100644
--- a/packages/cli/src/commands/edit.ts
+++ b/packages/cli/src/commands/edit.ts
@@ -74,11 +74,11 @@ function printDiff(oldContent: string, newContent: string, filePath: string): vo
   );
 
   if (oldContent === newContent) {
-    console.log(chalk.yellow('\n  (変更なし)'));
+    console.log(chalk.yellow('\n  (no changes)'));
     return;
   }
 
-  console.log('\n' + chalk.bold('--- 変更内容 ---'));
+  console.log('\n' + chalk.bold('--- Changes ---'));
   hunks.split('\n').forEach((line) => {
     if (line.startsWith('+++') || line.startsWith('---')) {
       console.log(chalk.bold(line));
@@ -200,7 +200,7 @@ export async function runEdit(
   const lineCount = fs.readFileSync(absPath, 'utf8').split('\n').length;
 
   console.log(chalk.bold('\nopen-motion edit'));
-  console.log(chalk.dim(`ファイル : ${relPath} (${lineCount}行)`));
+  console.log(chalk.dim(`File     : ${relPath} (${lineCount} lines)`));
   console.log(chalk.dim(`Provider : ${resolvedCfg.provider}  Model: ${resolvedCfg.model}`));
   console.log('');
 
@@ -221,7 +221,7 @@ export async function runEdit(
     terminal: true,
   });
 
-  console.log(chalk.dim("指示を入力してください ('exit' で終了)\n"));
+  console.log(chalk.dim("Enter an instruction (type 'exit' to quit)\n"));
 
   // Keep previous instruction for retry
   let lastInstruction = '';
@@ -236,14 +236,14 @@ export async function runEdit(
     }
 
     if (instruction.toLowerCase() === 'exit' || instruction.toLowerCase() === 'quit') {
-      console.log(chalk.dim('終了しました。'));
+      console.log(chalk.dim('Exited.'));
       rl.close();
       return;
     }
 
     const effectiveInstruction = instruction !== '' ? instruction : lastInstruction;
     if (!effectiveInstruction) {
-      console.log(chalk.yellow('指示を入力してください。'));
+      console.log(chalk.yellow('Please enter an instruction.'));
       continue;
     }
 
@@ -253,61 +253,61 @@ export async function runEdit(
     const currentContent = fs.readFileSync(absPath, 'utf8');
 
     const spinner = new Spinner();
-    spinner.start('編集中...');
+    spinner.start('Editing...');
 
     let edited: string;
     try {
       edited = await applyEdit(model, currentContent, effectiveInstruction);
     } catch (err) {
-      spinner.fail('編集に失敗しました');
+      spinner.fail('Edit failed');
       console.error(chalk.red((err as Error).message));
       continue;
     }
 
-    spinner.succeed('編集完了');
+    spinner.succeed('Edit complete');
     lastEditedContent = edited;
 
     printDiff(currentContent, edited, absPath);
 
     if (currentContent === edited) {
-      console.log(chalk.yellow('\n変更がありませんでした。指示を具体的にしてみてください。\n'));
+      console.log(chalk.yellow('\nNo changes were made. Try a more specific instruction.\n'));
       continue;
     }
 
     const answer = await askConfirm(
       rl,
-      chalk.bold('\n変更を適用しますか？') + chalk.dim(' (Y/n/retry) ')
+      chalk.bold('\nApply changes?') + chalk.dim(' (Y/n/retry) ')
     );
 
     if (answer === 'yes') {
       fs.writeFileSync(absPath, edited, 'utf8');
-      console.log(chalk.green('\n保存しました!\n'));
+      console.log(chalk.green('\nSaved!\n'));
     } else if (answer === 'retry') {
-      console.log(chalk.dim('\n再生成します...\n'));
+      console.log(chalk.dim('\nRegenerating...\n'));
       const spinner2 = new Spinner();
-      spinner2.start('再生成中...');
+      spinner2.start('Regenerating...');
       try {
         edited = await applyEdit(model, currentContent, effectiveInstruction);
-        spinner2.succeed('再生成完了');
+        spinner2.succeed('Regeneration complete');
         lastEditedContent = edited;
         printDiff(currentContent, edited, absPath);
 
         const ans2 = await askConfirm(
           rl,
-          chalk.bold('\n変更を適用しますか？') + chalk.dim(' (Y/n) ')
+          chalk.bold('\nApply changes?') + chalk.dim(' (Y/n) ')
         );
         if (ans2 === 'yes') {
           fs.writeFileSync(absPath, edited, 'utf8');
-          console.log(chalk.green('\n保存しました!\n'));
+          console.log(chalk.green('\nSaved!\n'));
         } else {
-          console.log(chalk.dim('\nスキップしました。\n'));
+          console.log(chalk.dim('\nSkipped.\n'));
         }
       } catch (err) {
-        spinner2.fail('再生成に失敗しました');
+        spinner2.fail('Regeneration failed');
         console.error(chalk.red((err as Error).message));
       }
     } else {
-      console.log(chalk.dim('\nスキップしました。\n'));
+      console.log(chalk.dim('\nSkipped.\n'));
     }
   }
 }
@@ -326,28 +326,28 @@ async function runOneShot(
   const currentContent = fs.readFileSync(absPath, 'utf8');
 
   const spinner = new Spinner();
-  spinner.start('編集中...');
+  spinner.start('Editing...');
 
   let edited: string;
   try {
     edited = await applyEdit(model, currentContent, instruction);
   } catch (err) {
-    spinner.fail('編集に失敗しました');
+    spinner.fail('Edit failed');
     console.error(chalk.red((err as Error).message));
     process.exit(1);
   }
 
-  spinner.succeed('編集完了');
+  spinner.succeed('Edit complete');
   printDiff(currentContent, edited, absPath);
 
   if (currentContent === edited) {
-    console.log(chalk.yellow('変更がありませんでした。'));
+    console.log(chalk.yellow('No changes were made.'));
     return;
   }
 
   if (autoApply) {
     fs.writeFileSync(absPath, edited, 'utf8');
-    console.log(chalk.green('\n保存しました!'));
+    console.log(chalk.green('\nSaved!'));
     return;
   }
 
@@ -360,14 +360,14 @@ async function runOneShot(
 
   const answer = await askConfirm(
     rl,
-    chalk.bold('\n変更を適用しますか？') + chalk.dim(' (Y/n) ')
+    chalk.bold('\nApply changes?') + chalk.dim(' (Y/n) ')
   );
   rl.close();
 
   if (answer === 'yes') {
     fs.writeFileSync(absPath, edited, 'utf8');
-    console.log(chalk.green('\n保存しました!'));
+    console.log(chalk.green('\nSaved!'));
   } else {
-    console.log(chalk.dim('\nキャンセルしました。'));
+    console.log(chalk.dim('\nCancelled.'));
   }
 }
diff --git a/packages/cli/src/commands/generate.ts b/packages/cli/src/commands/generate.ts
index 9bce8ec..a5d0866 100644
--- a/packages/cli/src/commands/generate.ts
+++ b/packages/cli/src/commands/generate.ts
@@ -266,7 +266,7 @@ export async function runGenerate(
   // 2. Plan scenes
   // ------------------------------------------------------------------
   const spinner = new Spinner();
-  spinner.start('[1/3] シーン構成を検討中...');
+  spinner.start('[1/3] Planning scene structure...');
 
   let plan: ScenePlan;
   try {
@@ -278,7 +278,7 @@ export async function runGenerate(
     });
     plan = parsePlanResponse(text);
   } catch (err) {
-    spinner.fail('シーン構成の生成に失敗しました');
+    spinner.fail('Failed to generate scene structure');
     console.error(chalk.red((err as Error).message));
     process.exit(1);
   }
@@ -294,7 +294,7 @@ export async function runGenerate(
     );
   }
 
-  spinner.succeed(`[1/3] シーン構成: ${plan.scenes.length}シーン`);
+  spinner.succeed(`[1/3] Scene structure: ${plan.scenes.length} scene(s)`);
   plan.scenes.forEach((s, i) => {
     console.log(
       chalk.dim(`       Scene ${i + 1}: ${s.title} (${s.durationInSeconds}s)`)
@@ -305,7 +305,7 @@ export async function runGenerate(
   // ------------------------------------------------------------------
   // 3. Generate TSX for each scene
   // ------------------------------------------------------------------
-  spinner.start(`[2/3] TSXを生成中... (0/${plan.scenes.length})`);
+  spinner.start(`[2/3] Generating TSX... (0/${plan.scenes.length})`);
 
   const scenesDir = path.join(outputDir);
   fs.mkdirSync(scenesDir, { recursive: true });
@@ -314,7 +314,7 @@ export async function runGenerate(
 
   for (let i = 0; i < plan.scenes.length; i++) {
     const scene = plan.scenes[i];
-    spinner.update(`[2/3] TSXを生成中... (${i + 1}/${plan.scenes.length}) — ${scene.title}`);
+    spinner.update(`[2/3] Generating TSX... (${i + 1}/${plan.scenes.length}) — ${scene.title}`);
 
     const durationInFrames = Math.round(scene.durationInSeconds * fps);
 
@@ -342,19 +342,19 @@ export async function runGenerate(
       fs.writeFileSync(filePath, code + '\n', 'utf8');
       generatedFiles.push(filePath);
     } catch (err) {
-      spinner.fail(`Scene "${scene.title}" の生成に失敗しました`);
+      spinner.fail(`Failed to generate scene "${scene.title}"`);
       console.error(chalk.red((err as Error).message));
       process.exit(1);
     }
   }
 
-  spinner.succeed(`[2/3] TSX生成完了 (${plan.scenes.length}シーン)`);
+  spinner.succeed(`[2/3] TSX generation complete (${plan.scenes.length} scene(s))`);
   console.log('');
 
   // ------------------------------------------------------------------
   // 4. Generate composition wrapper
   // ------------------------------------------------------------------
-  spinner.start('[3/3] コンポジションファイルを生成中...');
+  spinner.start('[3/3] Generating composition file...');
 
   const compositionCode = buildCompositionFile(plan.videoTitle, plan, fps, width, height);
   const compositionComponentName = toPascalCase(plan.videoTitle) + 'Video';
@@ -383,34 +383,34 @@ export async function runGenerate(
   });
 
   const updatedMainTsx = fs.existsSync(mainTsxPath);
-  spinner.succeed('[3/3] コンポジション生成完了');
+  spinner.succeed('[3/3] Composition generation complete');
   console.log('');
 
   // ------------------------------------------------------------------
   // 5. Summary
   // ------------------------------------------------------------------
-  console.log(chalk.bold.green('完了!'));
+  console.log(chalk.bold.green('Done!'));
   console.log('');
-  console.log(chalk.bold('生成されたファイル:'));
+  console.log(chalk.bold('Generated files:'));
   generatedFiles.forEach((f) => {
     const rel = path.relative(process.cwd(), f);
     console.log(chalk.green('  ✓') + '  ' + rel);
   });
   const relComp = path.relative(process.cwd(), compositionFilePath);
-  console.log(chalk.green('  ✓') + '  ' + relComp + chalk.dim('  (コンポジション)'));
+  console.log(chalk.green('  ✓') + '  ' + relComp + chalk.dim('  (composition)'));
   if (updatedMainTsx) {
     const relMain = path.relative(process.cwd(), mainTsxPath);
-    console.log(chalk.green('  ✓') + '  ' + relMain + chalk.dim('  (Composition を追記)'));
+    console.log(chalk.green('  ✓') + '  ' + relMain + chalk.dim('  (Composition appended)'));
   }
   console.log('');
   console.log(
     chalk.dim(
-      `合計: ${plan.scenes.length}シーン, ${totalFrames}フレーム ` +
-      `(${(totalFrames / fps).toFixed(1)}秒 @ ${fps}fps)`
+      `Total: ${plan.scenes.length} scene(s), ${totalFrames} frame(s) ` +
+      `(${(totalFrames / fps).toFixed(1)}s @ ${fps}fps)`
     )
   );
   console.log('');
-  console.log('次のステップ:');
-  console.log(chalk.cyan('  pnpm dev') + '  でプレビュー');
-  console.log(chalk.cyan('  pnpm render') + '  で動画をレンダリング');
+  console.log('Next steps:');
+  console.log(chalk.cyan('  pnpm dev') + '  to preview');
+  console.log(chalk.cyan('  pnpm render') + '  to render the video');
 }
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 7b33532..0ac0590 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -375,15 +375,15 @@ Quick Start:
   3. Install deps:        $ pnpm install
   4. Configure LLM:       $ open-motion config set provider openai
                           $ open-motion config set openai.apiKey sk-...
-  5. Generate scenes:     $ open-motion generate "Reactのライフサイクルを説明する動画"
+  5. Generate scenes:     $ open-motion generate "A video explaining the React lifecycle"
   6. Edit a scene:        $ open-motion edit src/scenes/IntroScene.tsx
   7. Start dev server:    $ pnpm dev
   8. Render video:        $ pnpm render
 
 Example Usage:
   $ open-motion init my-project
-  $ open-motion generate "TypeScriptの型システム解説動画"
-  $ open-motion edit src/scenes/IntroScene.tsx --message "背景を青に変えて"
+  $ open-motion generate "TypeScript type system explainer"
+  $ open-motion edit src/scenes/IntroScene.tsx --message "Change the background to blue"
   $ open-motion render -u http://localhost:5173 -o output.mp4 --composition main
 `);
 
@@ -450,16 +450,16 @@ Examples:
   // ---------------------------------------------------------------------------
   const generateCommand = program
     .command('generate <description>')
-    .description('LLMを使用して動画のシーンTSXを自動生成する')
-    .option('--provider <name>', 'LLMプロバイダ (openai/anthropic/google/ollama/openai-compatible)')
-    .option('--model <name>', '使用するモデル名')
-    .option('--api-key <key>', 'APIキー (設定ファイル・環境変数より優先)')
-    .option('--base-url <url>', 'ベースURL (openai-compatible / ollama)')
-    .option('--scenes <number>', '生成するシーン数 (省略時はLLMが決定)', parseInt)
-    .option('--fps <number>', 'フレームレート (デフォルト: 30)', parseInt)
-    .option('--width <number>', '動画の幅 (デフォルト: 1280)', parseInt)
-    .option('--height <number>', '動画の高さ (デフォルト: 720)', parseInt)
-    .option('--output <dir>', 'シーンファイルの出力ディレクトリ (デフォルト: src/scenes)')
+    .description('Auto-generate video scene TSX files using an LLM')
+    .option('--provider <name>', 'LLM provider (openai/anthropic/google/ollama/openai-compatible)')
+    .option('--model <name>', 'Model name to use')
+    .option('--api-key <key>', 'API key (overrides config file and environment variables)')
+    .option('--base-url <url>', 'Base URL (for openai-compatible / ollama)')
+    .option('--scenes <number>', 'Number of scenes to generate (default: decided by LLM)', parseInt)
+    .option('--fps <number>', 'Frame rate (default: 30)', parseInt)
+    .option('--width <number>', 'Video width (default: 1280)', parseInt)
+    .option('--height <number>', 'Video height (default: 720)', parseInt)
+    .option('--output <dir>', 'Output directory for scene files (default: src/scenes)')
     .action(async (description: string, options) => {
       try {
         await runGenerate(description, {
@@ -481,15 +481,15 @@ Examples:
 
   generateCommand.addHelpText('after', `
 Examples:
-  $ open-motion generate "Reactのライフサイクルを説明する動画"
-  $ open-motion generate "TypeScriptの型システム解説" --scenes 4 --fps 30
-  $ open-motion generate "AWS S3の使い方" --provider anthropic --model claude-opus-4-5
-  $ open-motion generate "Dockerの仕組み" --provider ollama --model llama3
-  $ open-motion generate "CI/CDパイプライン解説" --width 1920 --height 1080
+  $ open-motion generate "A video explaining the React lifecycle"
+  $ open-motion generate "TypeScript type system explainer" --scenes 4 --fps 30
+  $ open-motion generate "How to use AWS S3" --provider anthropic --model claude-opus-4-5
+  $ open-motion generate "How Docker works" --provider ollama --model llama3
+  $ open-motion generate "CI/CD pipeline explainer" --width 1920 --height 1080
 
 Note:
-  - 事前に LLM の設定が必要です: open-motion config set provider openai
-  - 既存プロジェクト (open-motion init で作成したもの) のルートで実行してください
+  - LLM must be configured first: open-motion config set provider openai
+  - Run this command from the root of an existing project (created with open-motion init)
 `);
 
   // ---------------------------------------------------------------------------
@@ -497,13 +497,13 @@ Note:
   // ---------------------------------------------------------------------------
   const editCommand = program
     .command('edit <file>')
-    .description('LLMを使用してTSXシーンファイルをインタラクティブに編集する')
-    .option('-m, --message <instruction>', 'ワンショットモード: 指示を文字列で渡す')
-    .option('--provider <name>', 'LLMプロバイダ (openai/anthropic/google/ollama/openai-compatible)')
-    .option('--model <name>', '使用するモデル名')
-    .option('--api-key <key>', 'APIキー (設定ファイル・環境変数より優先)')
-    .option('--base-url <url>', 'ベースURL (openai-compatible / ollama)')
-    .option('-y, --yes', '確認なしで変更を自動適用 (ワンショットモード時)')
+    .description('Interactively edit a TSX scene file using an LLM')
+    .option('-m, --message <instruction>', 'One-shot mode: pass instruction as a string')
+    .option('--provider <name>', 'LLM provider (openai/anthropic/google/ollama/openai-compatible)')
+    .option('--model <name>', 'Model name to use')
+    .option('--api-key <key>', 'API key (overrides config file and environment variables)')
+    .option('--base-url <url>', 'Base URL (for openai-compatible / ollama)')
+    .option('-y, --yes', 'Auto-apply changes without confirmation (one-shot mode only)')
     .action(async (file: string, options) => {
       try {
         await runEdit(file, {
@@ -522,15 +522,15 @@ Note:
 
   editCommand.addHelpText('after', `
 Examples:
-  # インタラクティブモード (対話形式で繰り返し編集)
+  # Interactive mode (edit repeatedly in a conversation)
   $ open-motion edit src/scenes/IntroScene.tsx
 
-  # ワンショットモード (1回だけ指示を渡す)
-  $ open-motion edit src/scenes/IntroScene.tsx --message "背景を青にして"
-  $ open-motion edit src/scenes/IntroScene.tsx -m "テキストを大きくして" --yes
+  # One-shot mode (pass a single instruction)
+  $ open-motion edit src/scenes/IntroScene.tsx --message "Change the background to blue"
+  $ open-motion edit src/scenes/IntroScene.tsx -m "Make the text larger" --yes
 
-  # プロバイダを指定
-  $ open-motion edit src/scenes/IntroScene.tsx --provider anthropic -m "アニメーションを滑らかに"
+  # Specify a provider
+  $ open-motion edit src/scenes/IntroScene.tsx --provider anthropic -m "Smooth out the animation"
 `);
 
   // ---------------------------------------------------------------------------
@@ -538,56 +538,56 @@ Examples:
   // ---------------------------------------------------------------------------
   const configCommand = program
     .command('config')
-    .description('LLMプロバイダの設定を管理する (~/.open-motion/config.json)')
+    .description('Manage LLM provider configuration (~/.open-motion/config.json)')
     .action(() => {
       printConfigHelp();
     });
 
   configCommand
     .command('set <key> <value>')
-    .description('設定値を保存する')
+    .description('Save a configuration value')
     .action((key: string, value: string) => {
       runConfigSet(key, value);
     });
 
   configCommand
     .command('get <key>')
-    .description('設定値を表示する')
+    .description('Show a configuration value')
     .action((key: string) => {
       runConfigGet(key);
     });
 
   configCommand
     .command('list')
-    .description('全設定を一覧表示する')
+    .description('List all configuration values')
     .action(() => {
       runConfigList();
     });
 
   configCommand.addHelpText('after', `
-設定可能なキー:
-  provider                      使用するプロバイダ (openai/anthropic/google/ollama/openai-compatible)
-  model                         グローバルモデル上書き
-  openai.apiKey                 OpenAI APIキー
-  openai.model                  OpenAIモデル (デフォルト: gpt-4o)
-  anthropic.apiKey              Anthropic APIキー
-  anthropic.model               Anthropicモデル (デフォルト: claude-3-5-sonnet-20241022)
-  google.apiKey                 Google AIキー
-  google.model                  Googleモデル (デフォルト: gemini-1.5-pro)
-  ollama.baseURL                OllamaサーバURL (デフォルト: http://localhost:11434)
-  ollama.model                  Ollamaモデル (デフォルト: llama3)
-  openai-compatible.baseURL     カスタムAPIのベースURL
-  openai-compatible.apiKey      カスタムAPIのAPIキー
-  openai-compatible.model       カスタムAPIのモデル名
-
-環境変数 (設定ファイルより優先):
-  OPEN_MOTION_PROVIDER          プロバイダ上書き
-  OPEN_MOTION_MODEL             モデル上書き
-  OPENAI_API_KEY                OpenAI APIキー
-  ANTHROPIC_API_KEY             Anthropic APIキー
-  GOOGLE_API_KEY / GEMINI_API_KEY  Google AIキー
-  OPEN_MOTION_BASE_URL          カスタムベースURL
-  OPEN_MOTION_API_KEY           カスタムAPIキー
+Configurable keys:
+  provider                      LLM provider to use (openai/anthropic/google/ollama/openai-compatible)
+  model                         Global model override
+  openai.apiKey                 OpenAI API key
+  openai.model                  OpenAI model (default: gpt-4o)
+  anthropic.apiKey              Anthropic API key
+  anthropic.model               Anthropic model (default: claude-3-5-sonnet-20241022)
+  google.apiKey                 Google AI API key
+  google.model                  Google model (default: gemini-1.5-pro)
+  ollama.baseURL                Ollama server URL (default: http://localhost:11434)
+  ollama.model                  Ollama model (default: llama3)
+  openai-compatible.baseURL     Base URL for custom API
+  openai-compatible.apiKey      API key for custom API
+  openai-compatible.model       Model name for custom API
+
+Environment variables (override config file):
+  OPEN_MOTION_PROVIDER          Provider override
+  OPEN_MOTION_MODEL             Model override
+  OPENAI_API_KEY                OpenAI API key
+  ANTHROPIC_API_KEY             Anthropic API key
+  GOOGLE_API_KEY / GEMINI_API_KEY  Google AI API key
+  OPEN_MOTION_BASE_URL          Custom base URL
+  OPEN_MOTION_API_KEY           Custom API key
 
 Examples:
   $ open-motion config set provider openai

From fdf21c80d3e5a1cd42096eac8472f3d6672a810c Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Wed, 25 Feb 2026 23:15:02 +0900
Subject: [PATCH 07/28] feat(cli): add .npmrc to init template to disable
 workspaces

---
 packages/cli/src/index.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 0ac0590..4ba9cfb 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -37,6 +37,7 @@ export const runInit = async (projectName: string) => {
 
   // Template files
   const files = {
+    '.npmrc': 'workspaces=false\n',
     'package.json': JSON.stringify({
       name: projectName,
       private: true,

From bbbf37250c59e33709509e93d7cd518dbcdda44b Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Wed, 25 Feb 2026 23:25:31 +0900
Subject: [PATCH 08/28] fix(cli): handle case-insensitive config keys and
 normalize on set

---
 packages/cli/src/commands/config.ts | 18 ++++++++++++------
 packages/cli/src/llm/config.ts      | 16 +++++++++++-----
 2 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/packages/cli/src/commands/config.ts b/packages/cli/src/commands/config.ts
index 2a32e06..5af8fda 100644
--- a/packages/cli/src/commands/config.ts
+++ b/packages/cli/src/commands/config.ts
@@ -57,18 +57,24 @@ function flattenConfig(obj: any, prefix = ''): Array<[string, string]> {
 // ---------------------------------------------------------------------------
 
 export function runConfigSet(key: string, value: string): void {
-  setConfigKey(key, value);
-  const displayVal = maskSecret(key, value);
-  console.log(chalk.green(`✓ ${key} = ${displayVal}`));
+  // Normalize key to canonical case if it matches a valid key case-insensitively
+  const canonicalKey = VALID_KEYS.find(vk => vk.toLowerCase() === key.toLowerCase());
+  const finalKey = canonicalKey || key;
+
+  setConfigKey(finalKey, value);
+  const displayVal = maskSecret(finalKey, value);
+  console.log(chalk.green(`✓ ${finalKey} = ${displayVal}`));
   console.log(chalk.dim(`  Saved to: ${CONFIG_FILE}`));
 }
 
 export function runConfigGet(key: string): void {
-  const value = getConfigKey(key);
+  const canonicalKey = VALID_KEYS.find(vk => vk.toLowerCase() === key.toLowerCase());
+  const finalKey = canonicalKey || key;
+  const value = getConfigKey(finalKey);
   if (value === undefined) {
-    console.log(chalk.yellow(`  "${key}" is not set`));
+    console.log(chalk.yellow(`  "${finalKey}" is not set`));
   } else {
-    console.log(`${key} = ${maskSecret(key, value)}`);
+    console.log(`${finalKey} = ${maskSecret(finalKey, value)}`);
   }
 }
 
diff --git a/packages/cli/src/llm/config.ts b/packages/cli/src/llm/config.ts
index 2834476..815f356 100644
--- a/packages/cli/src/llm/config.ts
+++ b/packages/cli/src/llm/config.ts
@@ -116,37 +116,43 @@ export function resolveConfig(overrides: CliConfigOverrides = {}): ResolvedLLMCo
       apiKey =
         overrides.apiKey ||
         env('OPENAI_API_KEY') ||
-        file.openai?.apiKey;
+        file.openai?.apiKey ||
+        (file.openai as any)?.apikey;
       break;
     case 'anthropic':
       apiKey =
         overrides.apiKey ||
         env('ANTHROPIC_API_KEY') ||
-        file.anthropic?.apiKey;
+        file.anthropic?.apiKey ||
+        (file.anthropic as any)?.apikey;
       break;
     case 'google':
       apiKey =
         overrides.apiKey ||
         env('GOOGLE_API_KEY') ||
         env('GEMINI_API_KEY') ||
-        file.google?.apiKey;
+        file.google?.apiKey ||
+        (file.google as any)?.apikey;
       break;
     case 'ollama':
       baseURL =
         overrides.baseURL ||
         env('OPEN_MOTION_BASE_URL') ||
         file.ollama?.baseURL ||
+        (file.ollama as any)?.baseUrl ||
         'http://localhost:11434';
       break;
     case 'openai-compatible':
       apiKey =
         overrides.apiKey ||
         env('OPEN_MOTION_API_KEY') ||
-        file['openai-compatible']?.apiKey;
+        file['openai-compatible']?.apiKey ||
+        (file['openai-compatible'] as any)?.apikey;
       baseURL =
         overrides.baseURL ||
         env('OPEN_MOTION_BASE_URL') ||
-        file['openai-compatible']?.baseURL;
+        file['openai-compatible']?.baseURL ||
+        (file['openai-compatible'] as any)?.baseUrl;
       break;
   }
 

From c8e545c754b79dc5b111f60422d90120584007b8 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Thu, 26 Feb 2026 17:31:53 +0900
Subject: [PATCH 09/28] feat(cli): add environment check and warning to
 generate command

---
 packages/cli/src/commands/generate.ts | 108 ++++++++++++++++++++++++++
 1 file changed, 108 insertions(+)

diff --git a/packages/cli/src/commands/generate.ts b/packages/cli/src/commands/generate.ts
index a5d0866..82f83fe 100644
--- a/packages/cli/src/commands/generate.ts
+++ b/packages/cli/src/commands/generate.ts
@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import readline from 'readline';
 import { generateText } from 'ai';
 import chalk from 'chalk';
 import { resolveConfig, validateConfig, type CliConfigOverrides } from '../llm/config';
@@ -90,6 +91,71 @@ function toPascalCase(str: string): string {
     .join('');
 }
 
+/**
+ * Check if the directory is initialized with open-motion init.
+ */
+function isInitialized(cwd: string): boolean {
+  const pkgPath = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgPath)) return false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return !!(pkg.dependencies && pkg.dependencies['@open-motion/core']);
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Check for files not created by "open-motion init".
+ */
+function getUnexpectedFiles(cwd: string): string[] {
+  const initialFiles = new Set([
+    '.npmrc',
+    'package.json',
+    'index.html',
+    'vite.config.ts',
+    'src/main.tsx',
+    'src/App.tsx',
+  ]);
+
+  const allowedExtras = new Set([
+    'node_modules',
+    'pnpm-lock.yaml',
+    'package-lock.json',
+    'yarn.lock',
+    '.git',
+    '.gitignore',
+    'dist',
+    '.open-motion-tmp',
+    '.DS_Store',
+  ]);
+
+  const unexpected: string[] = [];
+  if (!fs.existsSync(cwd)) return [];
+
+  const files = fs.readdirSync(cwd);
+  for (const f of files) {
+    if (initialFiles.has(f) || allowedExtras.has(f)) continue;
+    if (f === 'src') {
+      if (fs.statSync(path.join(cwd, f)).isDirectory()) {
+        const srcFiles = fs.readdirSync(path.join(cwd, 'src'));
+        for (const sf of srcFiles) {
+          const relSf = path.join('src', sf);
+          if (!initialFiles.has(relSf)) {
+            unexpected.push(relSf);
+          }
+        }
+      } else {
+        unexpected.push(f);
+      }
+      continue;
+    }
+    unexpected.push(f);
+  }
+
+  return unexpected;
+}
+
 /**
  * Build the main composition TSX that assembles all scenes in a Sequence.
  */
@@ -217,6 +283,48 @@ export async function runGenerate(
   description: string,
   options: GenerateOptions
 ): Promise<void> {
+  // ------------------------------------------------------------------
+  // 0. Environment check
+  // ------------------------------------------------------------------
+  const initialized = isInitialized(process.cwd());
+  const unexpectedFiles = getUnexpectedFiles(process.cwd());
+
+  if (!initialized || unexpectedFiles.length > 0) {
+    console.log(chalk.yellow('\n⚠️  Warning: Existing files may be overwritten.'));
+    if (!initialized) {
+      console.log(
+        chalk.yellow(
+          'This directory does not appear to be an OpenMotion project (run "open-motion init" first).'
+        )
+      );
+    } else {
+      console.log(
+        chalk.yellow('This directory contains files not created by "open-motion init".')
+      );
+    }
+    console.log('');
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    const answer = await new Promise<string>((resolve) => {
+      rl.question(
+        chalk.bold('Do you want to continue? ') + chalk.dim('(y/N) '),
+        (a) => {
+          resolve(a.trim().toLowerCase());
+        }
+      );
+    });
+    rl.close();
+
+    if (answer !== 'y' && answer !== 'yes') {
+      console.log(chalk.dim('\nAborted.'));
+      return;
+    }
+  }
+
   const fps = options.fps ?? 30;
   const width = options.width ?? 1280;
   const height = options.height ?? 720;

From 8734884c8a3692ed2ddf9b988b43f2624dc9cf57 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Thu, 26 Feb 2026 19:29:06 +0900
Subject: [PATCH 10/28] feat(cli): load config from .env/env vars

Use dotenv for per-project settings and stop reading/writing ~/.open-motion config.json.
---
 .env.example                        |  23 +++++
 .gitignore                          |   4 +
 packages/cli/package.json           |   1 +
 packages/cli/src/bin.ts             |   1 +
 packages/cli/src/commands/config.ts | 138 +++++++++++-----------------
 packages/cli/src/llm/config.ts      | 130 +++-----------------------
 6 files changed, 99 insertions(+), 198 deletions(-)
 create mode 100644 .env.example

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..909d361
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,23 @@
+# Open Motion - Environment Variables
+# Copy this file to .env and fill in your API keys.
+# .env is listed in .gitignore and will NOT be committed to version control.
+
+# --- LLM Provider (optional, defaults to "openai") ---
+# OPEN_MOTION_PROVIDER=openai
+
+# --- Model override (optional) ---
+# OPEN_MOTION_MODEL=gpt-4o
+
+# --- OpenAI ---
+# OPENAI_API_KEY=sk-...
+
+# --- Anthropic ---
+# ANTHROPIC_API_KEY=sk-ant-...
+
+# --- Google / Gemini ---
+# GOOGLE_API_KEY=...
+# GEMINI_API_KEY=...
+
+# --- OpenAI-compatible providers (e.g. Azure, Groq, local OpenAI-proxy) ---
+# OPEN_MOTION_API_KEY=...
+# OPEN_MOTION_BASE_URL=https://your-custom-endpoint/v1
diff --git a/.gitignore b/.gitignore
index 4cba80e..3f986dd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,8 @@
 node_modules
 dist
+.env
+.env.local
+.env.*.local
 .open-motion-tmp
 *.mp4
 *.png
@@ -14,3 +17,4 @@ progress.md.worktrees/
 *.avi
 *.mkv
 *.webm
+video_projects
\ No newline at end of file
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 32ac6b8..bd7022a 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -21,6 +21,7 @@
   ],
   "dependencies": {
     "@ai-sdk/anthropic": "^1.2.0",
+    "dotenv": "^16.0.0",
     "@ai-sdk/google": "^1.2.0",
     "@ai-sdk/openai": "^1.3.0",
     "@open-motion/core": "workspace:*",
diff --git a/packages/cli/src/bin.ts b/packages/cli/src/bin.ts
index 027d182..ab279a6 100644
--- a/packages/cli/src/bin.ts
+++ b/packages/cli/src/bin.ts
@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import 'dotenv/config';
 import { main } from './index';
 
 main();
diff --git a/packages/cli/src/commands/config.ts b/packages/cli/src/commands/config.ts
index 5af8fda..12cc879 100644
--- a/packages/cli/src/commands/config.ts
+++ b/packages/cli/src/commands/config.ts
@@ -1,103 +1,77 @@
-import path from 'path';
-import os from 'os';
 import chalk from 'chalk';
-import {
-  readConfigFile,
-  setConfigKey,
-  getConfigKey,
-} from '../llm/config';
-
-const CONFIG_FILE = path.join(os.homedir(), '.open-motion', 'config.json');
+import { resolveConfig } from '../llm/config';
 
 // ---------------------------------------------------------------------------
-// Helpers
+// Environment variables recognised by open-motion
 // ---------------------------------------------------------------------------
 
-const VALID_KEYS = [
-  'provider',
-  'model',
-  'openai.apiKey',
-  'openai.model',
-  'anthropic.apiKey',
-  'anthropic.model',
-  'google.apiKey',
-  'google.model',
-  'ollama.baseURL',
-  'ollama.model',
-  'openai-compatible.baseURL',
-  'openai-compatible.apiKey',
-  'openai-compatible.model',
-] as const;
+const ENV_VARS: Array<{ key: string; description: string }> = [
+  { key: 'OPEN_MOTION_PROVIDER',  description: 'LLM provider (openai | anthropic | google | ollama | openai-compatible)' },
+  { key: 'OPEN_MOTION_MODEL',     description: 'Model name override' },
+  { key: 'OPENAI_API_KEY',        description: 'API key for OpenAI' },
+  { key: 'ANTHROPIC_API_KEY',     description: 'API key for Anthropic' },
+  { key: 'GOOGLE_API_KEY',        description: 'API key for Google / Gemini' },
+  { key: 'GEMINI_API_KEY',        description: 'Alias for GOOGLE_API_KEY' },
+  { key: 'OPEN_MOTION_API_KEY',   description: 'API key for openai-compatible providers' },
+  { key: 'OPEN_MOTION_BASE_URL',  description: 'Base URL for ollama / openai-compatible providers' },
+];
 
 function maskSecret(key: string, value: string): string {
   const lk = key.toLowerCase();
-  if (lk.endsWith('apikey') || lk.endsWith('api_key')) {
+  if (lk.endsWith('api_key') || lk.endsWith('apikey')) {
     if (value.length <= 8) return '****';
     return value.slice(0, 6) + '...' + value.slice(-4);
   }
   return value;
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function flattenConfig(obj: any, prefix = ''): Array<[string, string]> {
-  const pairs: Array<[string, string]> = [];
-  for (const [k, v] of Object.entries(obj)) {
-    const fullKey = prefix ? `${prefix}.${k}` : k;
-    if (v !== null && typeof v === 'object') {
-      pairs.push(...flattenConfig(v, fullKey));
-    } else {
-      pairs.push([fullKey, String(v)]);
-    }
-  }
-  return pairs;
-}
-
 // ---------------------------------------------------------------------------
 // Sub-command handlers
 // ---------------------------------------------------------------------------
 
-export function runConfigSet(key: string, value: string): void {
-  // Normalize key to canonical case if it matches a valid key case-insensitively
-  const canonicalKey = VALID_KEYS.find(vk => vk.toLowerCase() === key.toLowerCase());
-  const finalKey = canonicalKey || key;
-
-  setConfigKey(finalKey, value);
-  const displayVal = maskSecret(finalKey, value);
-  console.log(chalk.green(`✓ ${finalKey} = ${displayVal}`));
-  console.log(chalk.dim(`  Saved to: ${CONFIG_FILE}`));
+export function runConfigSet(_key: string, _value: string): void {
+  console.log(chalk.yellow('The config set command is no longer supported.'));
+  console.log('API keys and settings are read from environment variables only.');
+  console.log('');
+  console.log('Add your values to a ' + chalk.cyan('.env') + ' file in your project directory:');
+  console.log('');
+  console.log(chalk.dim('  # .env'));
+  console.log(chalk.dim('  OPENAI_API_KEY=sk-...'));
+  console.log('');
+  console.log('Run ' + chalk.cyan('open-motion config list') + ' to see all recognised variables.');
 }
 
 export function runConfigGet(key: string): void {
-  const canonicalKey = VALID_KEYS.find(vk => vk.toLowerCase() === key.toLowerCase());
-  const finalKey = canonicalKey || key;
-  const value = getConfigKey(finalKey);
-  if (value === undefined) {
-    console.log(chalk.yellow(`  "${finalKey}" is not set`));
+  const value = process.env[key.toUpperCase()];
+  if (!value || value.trim() === '') {
+    console.log(chalk.yellow(`  "${key}" is not set`));
   } else {
-    console.log(`${finalKey} = ${maskSecret(finalKey, value)}`);
+    console.log(`${key} = ${maskSecret(key, value.trim())}`);
   }
 }
 
 export function runConfigList(): void {
-  const config = readConfigFile();
-  const pairs = flattenConfig(config);
+  const cfg = resolveConfig();
 
-  if (pairs.length === 0) {
-    console.log(chalk.dim('No configuration found'));
-    console.log(chalk.dim(`Config file: ${CONFIG_FILE}`));
-    console.log('');
-    console.log('Example:');
-    console.log(chalk.cyan('  open-motion config set provider openai'));
-    console.log(chalk.cyan('  open-motion config set openai.apiKey sk-...'));
-    return;
-  }
-
-  console.log(chalk.bold(`Config file: ${CONFIG_FILE}`));
+  console.log(chalk.bold('Active configuration'));
+  console.log(chalk.dim('  (resolved from environment variables and .env file)'));
   console.log('');
+  console.log(`  ${'provider'.padEnd(20)} ${cfg.provider}`);
+  console.log(`  ${'model'.padEnd(20)} ${cfg.model}`);
+  if (cfg.apiKey)  console.log(`  ${'apiKey'.padEnd(20)} ${maskSecret('apiKey', cfg.apiKey)}`);
+  if (cfg.baseURL) console.log(`  ${'baseURL'.padEnd(20)} ${cfg.baseURL}`);
 
-  for (const [key, value] of pairs) {
-    const displayVal = maskSecret(key, value);
-    console.log(`  ${chalk.dim(key.padEnd(36))} ${displayVal}`);
+  console.log('');
+  console.log(chalk.bold('Recognised environment variables'));
+  console.log('');
+  for (const { key, description } of ENV_VARS) {
+    const val = process.env[key];
+    const status = val && val.trim() !== ''
+      ? chalk.green(maskSecret(key, val.trim()))
+      : chalk.dim('(not set)');
+    console.log(`  ${key.padEnd(28)} ${status}`);
+    console.log(`  ${' '.repeat(28)} ${chalk.dim(description)}`);
+    console.log('');
   }
 }
 
@@ -108,22 +82,20 @@ export function runConfigList(): void {
 export function printConfigHelp(): void {
   console.log(chalk.bold('open-motion config'));
   console.log('');
-  console.log('Available commands:');
-  console.log(
-    `  ${chalk.cyan('open-motion config set <key> <value>')}  Save a configuration value`
-  );
+  console.log('Commands:');
   console.log(
-    `  ${chalk.cyan('open-motion config get <key>')}          Show a configuration value`
+    `  ${chalk.cyan('open-motion config list')}               Show active config and all recognised env vars`
   );
   console.log(
-    `  ${chalk.cyan('open-motion config list')}               List all configuration values`
+    `  ${chalk.cyan('open-motion config get <VAR>')}          Show the value of a single env var`
   );
   console.log('');
-  console.log('Configurable keys:');
-  VALID_KEYS.forEach((k) => console.log(`  ${chalk.dim(k)}`));
+  console.log('API keys and settings are configured via environment variables.');
+  console.log('You can place them in a ' + chalk.cyan('.env') + ' file in your project directory.');
+  console.log('');
+  console.log('Example .env:');
+  console.log(chalk.dim('  OPEN_MOTION_PROVIDER=openai'));
+  console.log(chalk.dim('  OPENAI_API_KEY=sk-...'));
   console.log('');
-  console.log('Example:');
-  console.log(chalk.cyan('  open-motion config set provider anthropic'));
-  console.log(chalk.cyan('  open-motion config set anthropic.apiKey sk-ant-...'));
-  console.log(chalk.cyan('  open-motion config set openai-compatible.baseURL https://api.example.com/v1'));
+  console.log('See ' + chalk.cyan('.env.example') + ' for all available variables.');
 }
diff --git a/packages/cli/src/llm/config.ts b/packages/cli/src/llm/config.ts
index 815f356..31bc0af 100644
--- a/packages/cli/src/llm/config.ts
+++ b/packages/cli/src/llm/config.ts
@@ -1,70 +1,6 @@
-import fs from 'fs';
-import path from 'path';
-import os from 'os';
-import type { OpenMotionLLMConfig, ProviderName, ResolvedLLMConfig } from './types';
+import type { ProviderName, ResolvedLLMConfig } from './types';
 import { DEFAULT_MODELS } from './types';
 
-const CONFIG_DIR = path.join(os.homedir(), '.open-motion');
-const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
-
-// ---------------------------------------------------------------------------
-// File I/O
-// ---------------------------------------------------------------------------
-
-export function readConfigFile(): OpenMotionLLMConfig {
-  if (!fs.existsSync(CONFIG_FILE)) {
-    return {};
-  }
-  try {
-    const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
-    return JSON.parse(raw) as OpenMotionLLMConfig;
-  } catch {
-    return {};
-  }
-}
-
-export function writeConfigFile(config: OpenMotionLLMConfig): void {
-  if (!fs.existsSync(CONFIG_DIR)) {
-    fs.mkdirSync(CONFIG_DIR, { recursive: true });
-  }
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n', 'utf8');
-}
-
-/**
- * Set a nested key using dot notation.
- * e.g. setConfigKey('openai.apiKey', 'sk-...') sets config.openai.apiKey
- */
-export function setConfigKey(key: string, value: string): void {
-  const config = readConfigFile();
-  const parts = key.split('.');
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let obj: any = config;
-  for (let i = 0; i < parts.length - 1; i++) {
-    if (obj[parts[i]] === undefined || typeof obj[parts[i]] !== 'object') {
-      obj[parts[i]] = {};
-    }
-    obj = obj[parts[i]];
-  }
-  obj[parts[parts.length - 1]] = value;
-  writeConfigFile(config);
-}
-
-/**
- * Get a nested key using dot notation.
- */
-export function getConfigKey(key: string): string | undefined {
-  const config = readConfigFile();
-  const parts = key.split('.');
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let obj: any = config;
-  for (const part of parts) {
-    if (obj === undefined || obj === null) return undefined;
-    obj = obj[part];
-  }
-  return obj !== undefined && obj !== null ? String(obj) : undefined;
-}
-
 // ---------------------------------------------------------------------------
 // Environment variable helpers
 // ---------------------------------------------------------------------------
@@ -86,26 +22,22 @@ export interface CliConfigOverrides {
 }
 
 /**
- * Merge config file + environment variables + CLI overrides into a single
- * ResolvedLLMConfig. Priority (high → low):
- *   CLI flags > ENV vars > config file > built-in defaults
+ * Merge environment variables + CLI overrides into a single ResolvedLLMConfig.
+ * Priority (high → low):
+ *   CLI flags > ENV vars (.env file values are loaded as ENV vars by dotenv)
  */
 export function resolveConfig(overrides: CliConfigOverrides = {}): ResolvedLLMConfig {
-  const file = readConfigFile();
-
   // 1. Provider
   const provider: ProviderName =
     (overrides.provider as ProviderName | undefined) ||
     (env('OPEN_MOTION_PROVIDER') as ProviderName | undefined) ||
-    file.provider ||
     'openai';
 
   // 2. Model — global override, then provider-specific, then default
-  const modelFromEnv = env('OPEN_MOTION_MODEL');
-  const modelFromFile =
-    file.model || (file[provider] as { model?: string } | undefined)?.model;
   const model =
-    overrides.model || modelFromEnv || modelFromFile || DEFAULT_MODELS[provider];
+    overrides.model ||
+    env('OPEN_MOTION_MODEL') ||
+    DEFAULT_MODELS[provider];
 
   // 3. API key / base URL (provider-specific)
   let apiKey: string | undefined;
@@ -113,46 +45,23 @@ export function resolveConfig(overrides: CliConfigOverrides = {}): ResolvedLLMCo
 
   switch (provider) {
     case 'openai':
-      apiKey =
-        overrides.apiKey ||
-        env('OPENAI_API_KEY') ||
-        file.openai?.apiKey ||
-        (file.openai as any)?.apikey;
+      apiKey = overrides.apiKey || env('OPENAI_API_KEY');
       break;
     case 'anthropic':
-      apiKey =
-        overrides.apiKey ||
-        env('ANTHROPIC_API_KEY') ||
-        file.anthropic?.apiKey ||
-        (file.anthropic as any)?.apikey;
+      apiKey = overrides.apiKey || env('ANTHROPIC_API_KEY');
       break;
     case 'google':
-      apiKey =
-        overrides.apiKey ||
-        env('GOOGLE_API_KEY') ||
-        env('GEMINI_API_KEY') ||
-        file.google?.apiKey ||
-        (file.google as any)?.apikey;
+      apiKey = overrides.apiKey || env('GOOGLE_API_KEY') || env('GEMINI_API_KEY');
       break;
     case 'ollama':
       baseURL =
         overrides.baseURL ||
         env('OPEN_MOTION_BASE_URL') ||
-        file.ollama?.baseURL ||
-        (file.ollama as any)?.baseUrl ||
         'http://localhost:11434';
       break;
     case 'openai-compatible':
-      apiKey =
-        overrides.apiKey ||
-        env('OPEN_MOTION_API_KEY') ||
-        file['openai-compatible']?.apiKey ||
-        (file['openai-compatible'] as any)?.apikey;
-      baseURL =
-        overrides.baseURL ||
-        env('OPEN_MOTION_BASE_URL') ||
-        file['openai-compatible']?.baseURL ||
-        (file['openai-compatible'] as any)?.baseUrl;
+      apiKey = overrides.apiKey || env('OPEN_MOTION_API_KEY');
+      baseURL = overrides.baseURL || env('OPEN_MOTION_BASE_URL');
       break;
   }
 
@@ -171,8 +80,7 @@ export function validateConfig(cfg: ResolvedLLMConfig): void {
     if (!cfg.baseURL) {
       throw new Error(
         'openai-compatible provider requires a base URL.\n' +
-        'Set it with: open-motion config set openai-compatible.baseURL <url>\n' +
-        'or set the OPEN_MOTION_BASE_URL environment variable.'
+        'Set the OPEN_MOTION_BASE_URL environment variable, or pass --base-url.'
       );
     }
     return;
@@ -185,18 +93,10 @@ export function validateConfig(cfg: ResolvedLLMConfig): void {
       ollama: '',
       'openai-compatible': 'OPEN_MOTION_API_KEY',
     };
-    const configKey: Record<ProviderName, string> = {
-      openai: 'openai.apiKey',
-      anthropic: 'anthropic.apiKey',
-      google: 'google.apiKey',
-      ollama: '',
-      'openai-compatible': 'openai-compatible.apiKey',
-    };
     throw new Error(
       `No API key found for provider "${cfg.provider}".\n` +
-      `Set it with one of:\n` +
-      `  open-motion config set ${configKey[cfg.provider]} <key>\n` +
-      `  export ${envVar[cfg.provider]}=<key>`
+      `Set the ${envVar[cfg.provider]} environment variable, or pass --api-key.\n` +
+      `You can also add it to a .env file in your project directory.`
     );
   }
 }

From 496d68474f5b14315b856cd439edcae8ac3f922e Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Thu, 26 Feb 2026 20:06:25 +0900
Subject: [PATCH 11/28] fix(cli): tailor next steps for npm

Print npm run dev/render when pnpm is unavailable and add prompt rules to prevent invalid identifier component names.
---
 packages/cli/src/commands/generate.ts | 19 +++++++++++++++++--
 packages/cli/src/index.ts             | 11 ++++++++---
 packages/cli/src/prompts/generate.ts  | 12 +++++++++++-
 3 files changed, 36 insertions(+), 6 deletions(-)

diff --git a/packages/cli/src/commands/generate.ts b/packages/cli/src/commands/generate.ts
index 82f83fe..82038e3 100644
--- a/packages/cli/src/commands/generate.ts
+++ b/packages/cli/src/commands/generate.ts
@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import readline from 'readline';
+import { execSync } from 'child_process';
 import { generateText } from 'ai';
 import chalk from 'chalk';
 import { resolveConfig, validateConfig, type CliConfigOverrides } from '../llm/config';
@@ -74,6 +75,19 @@ class Spinner {
   }
 }
 
+function getPackageManager(): 'pnpm' | 'npm' {
+  try {
+    execSync('pnpm -v', { stdio: 'ignore' });
+    return 'pnpm';
+  } catch {
+    return 'npm';
+  }
+}
+
+function formatRun(pm: 'pnpm' | 'npm', script: string): string {
+  return pm === 'npm' ? `npm run ${script}` : `pnpm ${script}`;
+}
+
 /**
  * Convert a video title (or scene title) to a valid PascalCase component name.
  * E.g. "React Lifecycle" → "ReactLifecycle"
@@ -519,6 +533,7 @@ export async function runGenerate(
   );
   console.log('');
   console.log('Next steps:');
-  console.log(chalk.cyan('  pnpm dev') + '  to preview');
-  console.log(chalk.cyan('  pnpm render') + '  to render the video');
+  const pm = getPackageManager();
+  console.log(chalk.cyan(`  ${formatRun(pm, 'dev')}`) + '  to preview');
+  console.log(chalk.cyan(`  ${formatRun(pm, 'render')}`) + '  to render the video');
 }
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 4ba9cfb..3b92fa2 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -19,6 +19,10 @@ const getPackageManager = () => {
   }
 };
 
+const formatRun = (pm: string, script: string) => {
+  return pm === 'npm' ? `npm run ${script}` : `${pm} ${script}`;
+};
+
 export const runInit = async (projectName: string) => {
   const targetDir = path.join(process.cwd(), projectName);
   if (fs.existsSync(targetDir)) {
@@ -364,6 +368,7 @@ const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '../package.json'),
 
 export const main = () => {
   const program = new Command();
+  const pm = getPackageManager();
 
   program
     .name('open-motion')
@@ -373,13 +378,13 @@ export const main = () => {
 Quick Start:
   1. Initialize project:  $ open-motion init my-video
   2. Enter directory:     $ cd my-video
-  3. Install deps:        $ pnpm install
+  3. Install deps:        $ ${pm} install
   4. Configure LLM:       $ open-motion config set provider openai
                           $ open-motion config set openai.apiKey sk-...
   5. Generate scenes:     $ open-motion generate "A video explaining the React lifecycle"
   6. Edit a scene:        $ open-motion edit src/scenes/IntroScene.tsx
-  7. Start dev server:    $ pnpm dev
-  8. Render video:        $ pnpm render
+  7. Start dev server:    $ ${formatRun(pm, 'dev')}
+  8. Render video:        $ ${formatRun(pm, 'render')}
 
 Example Usage:
   $ open-motion init my-project
diff --git a/packages/cli/src/prompts/generate.ts b/packages/cli/src/prompts/generate.ts
index 28681ac..df7ff24 100644
--- a/packages/cli/src/prompts/generate.ts
+++ b/packages/cli/src/prompts/generate.ts
@@ -36,6 +36,12 @@ setTimeout, setInterval, or any real-time mechanism for animation.
 6. The component must be **completely self-contained** with no props required
 7. Use visually appealing designs: thoughtful colors, smooth animations, readable typography
 
+## Naming rules (critical)
+- Any exported component name MUST be a valid TypeScript/JavaScript identifier in PascalCase.
+- The name MUST start with a letter A-Z (do not start with a digit).
+- Use ASCII letters and digits only for identifiers (A-Z, a-z, 0-9). Do NOT use Japanese text, spaces, hyphens, emoji, or punctuation in identifiers.
+- If the title is non-Latin (e.g. Japanese), romanize/translate it for the identifier (e.g. "30秒でわかるRemotion" -> "RemotionIn30Seconds").
+
 ## Minimal valid example
 \`\`\`tsx
 import React from 'react';
@@ -97,7 +103,10 @@ Respond with a JSON object (and nothing else) in this exact shape:
 Guidelines:
 - Total video duration should feel natural for the content (typically 20-90 seconds)
 - Each scene should be self-contained and visually distinct
-- \`componentName\` must be a valid PascalCase React component name (e.g. "IntroScene", "DataFlowScene")
+- \`componentName\` must be a valid PascalCase React component name AND a valid JS/TS identifier:
+  - start with A-Z (never start with a number)
+  - ASCII letters/digits only (no Japanese/non-ASCII characters, no spaces, no hyphens)
+  - examples: "IntroScene", "HowItWorksScene", "RemotionIn30SecondsScene"
 - \`id\` must be unique kebab-case (e.g. "intro-scene", "data-flow-scene")
 - Aim for 3-6 scenes unless the content clearly needs more or fewer
 - Describe animations concretely (e.g. "text fades in from bottom, then a line draws across")
@@ -135,6 +144,7 @@ ${ctx.description}
 
 Requirements:
 - The component must be named exactly \`${ctx.componentName}\` and exported as a named export
+- The component name must be a valid JS/TS identifier (ASCII PascalCase, must not start with a digit)
 - Fill the full ${ctx.width}x${ctx.height} canvas
 - Use smooth frame-based animations (interpolate / spring)
 - Keep text readable and well-positioned

From bc2350358b2d7cad38466d2f03ddb00178cb0f2c Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Thu, 26 Feb 2026 21:44:40 +0900
Subject: [PATCH 12/28] feat(cli): improve composition preview/render flow

---
 packages/cli/src/commands/generate.ts |  16 ++-
 packages/cli/src/index.ts             | 158 +++++++++++++++++++++++---
 2 files changed, 150 insertions(+), 24 deletions(-)

diff --git a/packages/cli/src/commands/generate.ts b/packages/cli/src/commands/generate.ts
index 82038e3..6afe4e1 100644
--- a/packages/cli/src/commands/generate.ts
+++ b/packages/cli/src/commands/generate.ts
@@ -245,15 +245,13 @@ function updateMainTsx(
     return; // Already imported
   }
 
-  // Insert import after the last import block
-  const lastImportIndex = content.lastIndexOf('\nimport ');
-  if (lastImportIndex !== -1) {
-    const endOfLastImport = content.indexOf('\n', lastImportIndex + 1);
-    content =
-      content.slice(0, endOfLastImport + 1) +
-      importStatement +
-      '\n' +
-      content.slice(endOfLastImport + 1);
+  // Insert import after the last import statement (supports multi-line imports)
+  const importRe = /^import[\s\S]*?;\s*$/gm;
+  const matches = Array.from(content.matchAll(importRe));
+  if (matches.length > 0) {
+    const last = matches[matches.length - 1];
+    const insertAt = (last.index ?? 0) + last[0].length;
+    content = content.slice(0, insertAt) + '\n' + importStatement + '\n' + content.slice(insertAt);
   } else {
     content = importStatement + '\n' + content;
   }
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 3b92fa2..0bce55e 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -93,36 +93,164 @@ export default defineConfig({
     'src/main.tsx': `import React from 'react';
 import ReactDOM from 'react-dom/client';
 import { App } from './App.tsx';
-import { CompositionProvider, Composition, Player } from '@open-motion/core';
+import {
+  CompositionProvider,
+  Composition,
+  Player,
+  getCompositions,
+  getCompositionById,
+  type VideoConfig,
+} from '@open-motion/core';
 
-const Root = () => {
-  const config = { width: 1920, height: 1080, fps: 30, durationInFrames: 120 };
-  const isRendering = typeof (window as any).__OPEN_MOTION_FRAME__ === 'number';
+const STORAGE_KEY = 'open-motion:preview:compositionId';
+
+const RegisterCompositions = () => {
+  const mainConfig: VideoConfig = {
+    width: 1920,
+    height: 1080,
+    fps: 30,
+    durationInFrames: 120,
+  };
+
+  return (
+    <div style={{ display: 'none' }}>
+      <Composition id="main" component={App} {...mainConfig} />
+    </div>
+  );
+};
+
+const pickInitialCompositionId = (ids: string[]) => {
+  if (typeof window === 'undefined') return ids[0] ?? 'main';
+
+  const url = new URL(window.location.href);
+  const fromQuery = url.searchParams.get('comp');
+  if (fromQuery && ids.includes(fromQuery)) return fromQuery;
+
+  const fromStorage = window.localStorage.getItem(STORAGE_KEY);
+  if (fromStorage && ids.includes(fromStorage)) return fromStorage;
+
+  return ids[ids.length - 1] ?? 'main';
+};
+
+const PreviewMode = () => {
+  const compositions = getCompositions();
+  const ids = compositions.map((c) => c.id);
+  const [selectedId, setSelectedId] = React.useState(() => pickInitialCompositionId(ids));
+
+  const selected = compositions.find((c) => c.id === selectedId) ?? compositions[compositions.length - 1];
 
   React.useEffect(() => {
-    if (isRendering) {
-      (window as any).__OPEN_MOTION_READY__ = true;
+    if (!selected && ids.length > 0) {
+      setSelectedId(pickInitialCompositionId(ids));
     }
-  }, [isRendering]);
+  }, [ids.join('|')]);
+
+  React.useEffect(() => {
+    if (typeof window === 'undefined') return;
+    window.localStorage.setItem(STORAGE_KEY, selectedId);
 
-  if (isRendering) {
+    const url = new URL(window.location.href);
+    url.searchParams.set('comp', selectedId);
+    window.history.replaceState({}, '', url.toString());
+  }, [selectedId]);
+
+  if (!selected) {
     return (
-      <CompositionProvider config={config} frame={(window as any).__OPEN_MOTION_FRAME__}>
-        <App />
-      </CompositionProvider>
+      <div style={{ padding: 16, fontFamily: 'ui-sans-serif, system-ui' }}>
+        No compositions registered.
+      </div>
     );
   }
 
+  const config: VideoConfig = {
+    width: selected.width,
+    height: selected.height,
+    fps: selected.fps,
+    durationInFrames: selected.durationInFrames,
+  };
+
+  const renderUrl = typeof window !== 'undefined' ? window.location.origin : 'http://127.0.0.1:5173';
+  const renderCmd = 'open-motion render -u ' + renderUrl + ' -o out.mp4 --composition ' + selectedId;
+
   return (
-    <div style={{ padding: '20px' }}>
-      <Player component={App} config={config} />
-      <div style={{ display: 'none' }}>
-        <Composition id="main" component={App} {...config} />
+    <div style={{ minHeight: '100vh', padding: 16, background: '#f6f6f7', boxSizing: 'border-box' }}>
+      <div style={{ display: 'flex', gap: 12, alignItems: 'center', marginBottom: 12, flexWrap: 'wrap' }}>
+        <div style={{ fontSize: 12, color: '#333', fontFamily: 'ui-sans-serif, system-ui' }}>Composition</div>
+        <select
+          value={selectedId}
+          onChange={(e) => setSelectedId(e.target.value)}
+          style={{ padding: '6px 8px', borderRadius: 6, border: '1px solid #ccc', background: '#fff' }}
+        >
+          {compositions.map((c) => (
+            <option key={c.id} value={c.id}>
+              {c.id}
+            </option>
+          ))}
+        </select>
+        <div style={{ fontSize: 12, color: '#666', fontFamily: 'ui-sans-serif, system-ui' }}>
+          {config.width}x{config.height} / {config.fps}fps / {config.durationInFrames}f
+        </div>
+
+        <div style={{ flex: 1 }} />
+
+        <div style={{ display: 'flex', gap: 8, alignItems: 'center', marginLeft: 'auto', flex: '1 1 520px', justifyContent: 'flex-end' }}>
+          <div style={{ fontSize: 12, color: '#333', fontFamily: 'ui-sans-serif, system-ui' }}>Render</div>
+          <div
+            style={{
+              fontSize: 12,
+              color: '#111',
+              fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
+              background: '#fff',
+              border: '1px solid #ddd',
+              borderRadius: 6,
+              padding: '6px 8px',
+              maxWidth: 'min(720px, 100%)',
+              wordBreak: 'break-all',
+            }}
+          >
+            {renderCmd}
+          </div>
+        </div>
       </div>
+
+      <Player key={selectedId} component={selected.component} config={config} />
     </div>
   );
 };
 
+const RenderMode = () => {
+  const frame = (window as any).__OPEN_MOTION_FRAME__ as number;
+  const compositionId = ((window as any).__OPEN_MOTION_COMPOSITION_ID__ as string | undefined) ?? 'main';
+  const inputProps = (window as any).__OPEN_MOTION_INPUT_PROPS__ ?? {};
+
+  const selected = getCompositionById(compositionId) ?? getCompositions()[0];
+  if (!selected) return null;
+
+  const config: VideoConfig = {
+    width: selected.width,
+    height: selected.height,
+    fps: selected.fps,
+    durationInFrames: selected.durationInFrames,
+  };
+
+  const Component = selected.component;
+  return (
+    <CompositionProvider config={config} frame={frame} inputProps={inputProps}>
+      <Component />
+    </CompositionProvider>
+  );
+};
+
+const Root = () => {
+  const isRendering = typeof (window as any).__OPEN_MOTION_FRAME__ === 'number';
+  return (
+    <>
+      <RegisterCompositions />
+      {isRendering ? <RenderMode /> : <PreviewMode />}
+    </>
+  );
+};
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <Root />

From 6af7ad570b7e99c926ccdaf87ccf4932867dac78 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Fri, 27 Feb 2026 09:02:53 +0900
Subject: [PATCH 13/28] remove 'config set', add 'config get'

---
 README.ja.md           | 14 ++++++++++++++
 README.md              | 12 ++++++++++--
 README.zh.md           | 14 ++++++++++++++
 packages/cli/README.md | 10 ++++++++--
 4 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/README.ja.md b/README.ja.md
index c5efdae..de195ea 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -87,6 +87,20 @@ open-motion render -u http://localhost:5173 -o out.mp4
 ### `open-motion init <name>`
 事前設定されたReactテンプレートを使用して、新しいOpenMotionプロジェクトを初期化します。
 
+### `open-motion config`
+LLMの設定（APIキー、モデルなど）を管理します。
+
+- `open-motion config list`
+- `open-motion config get <VAR>`
+
+設定は環境変数から読み込まれます（プロジェクト直下の `.env` に置けます）：
+
+```bash
+# .env
+OPEN_MOTION_PROVIDER=openai
+OPENAI_API_KEY=sk-...
+```
+
 ### `open-motion render`
 実行中のOpenMotionアプリケーションからビデオをレンダリングします。
 
diff --git a/README.md b/README.md
index 4bdd888..7c026e9 100644
--- a/README.md
+++ b/README.md
@@ -95,7 +95,7 @@ Automatically generate video scenes and code from a text description using an LL
 | Option | Description |
 | :--- | :--- |
 | `--provider <name>` | LLM provider (`openai`, `anthropic`, `google`, `ollama`, `openai-compatible`) |
-| `--model <name>` | Model name (e.g., `gpt-4o`, `claude-3-5-sonnet`) |
+| `--model <name>` | Model name (e.g., `gpt-5.2`, `claude-4-6-sonnet`) |
 | `--scenes <number>` | Number of scenes to generate |
 | `--fps <number>` | Frames per second (default: 30) |
 | `--width <number>` | Video width (default: 1280) |
@@ -112,8 +112,16 @@ Edit a TSX scene file using natural language instructions.
 ### `open-motion config`
 Manage LLM provider settings (API keys, models).
 
-- `open-motion config set <key> <value>`
 - `open-motion config list`
+- `open-motion config get <VAR>`
+
+LLM settings are read from environment variables (you can put them in a project-local `.env` file):
+
+```bash
+# .env
+OPEN_MOTION_PROVIDER=openai
+OPENAI_API_KEY=sk-...
+```
 
 ### `open-motion render`
 Render a video from a running OpenMotion application.
diff --git a/README.zh.md b/README.zh.md
index 50890d0..df76e48 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -87,6 +87,20 @@ open-motion render -u http://localhost:5173 -o out.mp4
 ### `open-motion init <name>`
 使用预配置的 React 模板初始化一个新的 OpenMotion 项目。
 
+### `open-motion config`
+管理 LLM 配置（API Key、模型等）。
+
+- `open-motion config list`
+- `open-motion config get <VAR>`
+
+配置从环境变量读取（也支持放在项目目录下的 `.env` 文件中）：
+
+```bash
+# .env
+OPEN_MOTION_PROVIDER=openai
+OPENAI_API_KEY=sk-...
+```
+
 ### `open-motion render`
 从正在运行的 OpenMotion 应用程序渲染视频。
 
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 9407df1..145fb7d 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -28,8 +28,14 @@ open-motion init my-video
 
 ### Configure LLM (Optional for AI features)
 ```bash
-open-motion config set provider openai
-open-motion config set openai.apiKey sk-...
+# Configure via environment variables (project-local .env supported)
+# .env
+OPEN_MOTION_PROVIDER=openai
+OPENAI_API_KEY=sk-...
+
+# Verify what the CLI sees
+open-motion config list
+open-motion config get OPENAI_API_KEY
 ```
 
 ### Generate a video from description

From ba4ce152099a7054065c9c979f68839f3707b292 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Fri, 27 Feb 2026 11:17:31 +0900
Subject: [PATCH 14/28] feat(cli): add automated caption generation and improve
 scene generation robustness

---
 packages/cli/src/commands/generate.ts | 458 ++++++++++++++++++--------
 packages/cli/src/prompts/generate.ts  |  98 ++++++
 2 files changed, 420 insertions(+), 136 deletions(-)

diff --git a/packages/cli/src/commands/generate.ts b/packages/cli/src/commands/generate.ts
index 6afe4e1..163a5d6 100644
--- a/packages/cli/src/commands/generate.ts
+++ b/packages/cli/src/commands/generate.ts
@@ -8,10 +8,14 @@ import { resolveConfig, validateConfig, type CliConfigOverrides } from '../llm/c
 import { createModel } from '../llm/factory';
 import {
   GENERATE_SYSTEM_PROMPT,
+  CAPTIONS_SYSTEM_PROMPT,
   buildPlanningPrompt,
+  buildCaptionsPrompt,
   buildSceneCodePrompt,
   parsePlanResponse,
+  parseCaptionsResponse,
   parseCodeResponse,
+  validateSceneCode,
   type ScenePlan,
 } from '../prompts/generate';
 
@@ -122,52 +126,32 @@ function isInitialized(cwd: string): boolean {
 /**
  * Check for files not created by "open-motion init".
  */
-function getUnexpectedFiles(cwd: string): string[] {
-  const initialFiles = new Set([
-    '.npmrc',
-    'package.json',
-    'index.html',
-    'vite.config.ts',
-    'src/main.tsx',
-    'src/App.tsx',
-  ]);
-
-  const allowedExtras = new Set([
-    'node_modules',
-    'pnpm-lock.yaml',
-    'package-lock.json',
-    'yarn.lock',
-    '.git',
-    '.gitignore',
-    'dist',
-    '.open-motion-tmp',
-    '.DS_Store',
-  ]);
-
-  const unexpected: string[] = [];
-  if (!fs.existsSync(cwd)) return [];
-
-  const files = fs.readdirSync(cwd);
-  for (const f of files) {
-    if (initialFiles.has(f) || allowedExtras.has(f)) continue;
-    if (f === 'src') {
-      if (fs.statSync(path.join(cwd, f)).isDirectory()) {
-        const srcFiles = fs.readdirSync(path.join(cwd, 'src'));
-        for (const sf of srcFiles) {
-          const relSf = path.join('src', sf);
-          if (!initialFiles.has(relSf)) {
-            unexpected.push(relSf);
-          }
-        }
-      } else {
-        unexpected.push(f);
+function getOverwriteHints(cwd: string, outputDir: string): string[] {
+  const hints: string[] = [];
+
+  if (!fs.existsSync(cwd)) return hints;
+
+  // If the output directory exists and has content, we may overwrite.
+  if (fs.existsSync(outputDir)) {
+    try {
+      const entries = fs.readdirSync(outputDir);
+      const meaningful = entries.filter((e) => e !== '.DS_Store');
+      if (meaningful.length > 0) {
+        hints.push(`Output directory is not empty: ${path.relative(cwd, outputDir)}`);
       }
-      continue;
+    } catch {
+      // Ignore read errors; still proceed.
     }
-    unexpected.push(f);
   }
 
-  return unexpected;
+  // We will attempt to append a Composition into src/main.tsx (if it exists).
+  const srcDir = path.dirname(outputDir);
+  const mainTsxPath = path.join(srcDir, 'main.tsx');
+  if (fs.existsSync(mainTsxPath)) {
+    hints.push(`src/main.tsx will be updated`);
+  }
+
+  return hints;
 }
 
 /**
@@ -178,7 +162,8 @@ function buildCompositionFile(
   plan: ScenePlan,
   fps: number,
   width: number,
-  height: number
+  height: number,
+  srtContent: string
 ): string {
   const imports = plan.scenes
     .map((s) => `import { ${s.componentName} } from './scenes/${s.componentName}';`)
@@ -197,19 +182,121 @@ function buildCompositionFile(
   const totalFrames = offset;
   const componentName = toPascalCase(videoTitle) + 'Video';
 
-  return `import React from 'react';
-import { Sequence, useVideoConfig } from '@open-motion/core';
-${imports}
-
-/** Auto-generated composition: ${videoTitle} */
-export const ${componentName} = () => {
-  const { width, height } = useVideoConfig();
-  return (
-    <div style={{ width, height, overflow: 'hidden', backgroundColor: '#000' }}>
-${sequences}
-    </div>
-  );
-};
+  // Use JSON string escaping so we can embed arbitrary caption text safely.
+  const srtLiteral = JSON.stringify(srtContent);
+
+  return `import React, { useMemo } from 'react';
+ import {
+   Sequence,
+   useCurrentFrame,
+   useVideoConfig,
+   interpolate,
+   spring,
+   parseSrt,
+   type SubtitleItem,
+ } from '@open-motion/core';
+ ${imports}
+
+ /** Auto-generated composition: ${videoTitle} */
+ const SRT_CAPTIONS: string = ${srtLiteral};
+
+  const CaptionOverlay: React.FC<{ subtitles: SubtitleItem[] }> = ({ subtitles }) => {
+    const frame = useCurrentFrame();
+    const { fps } = useVideoConfig();
+    const currentTime = frame / fps;
+
+    const active = subtitles.find(
+      (s) => currentTime >= s.startInSeconds && currentTime < s.endInSeconds
+    );
+    if (!active) return null;
+
+   const startFrame = Math.round(active.startInSeconds * fps);
+   const relFrame = Math.max(0, frame - startFrame);
+
+   const enter = spring({ frame: relFrame, fps, config: { stiffness: 120, damping: 14 } });
+   const opacity = interpolate(enter, [0, 1], [0, 1], { extrapolateRight: 'clamp' });
+   const scale = interpolate(enter, [0, 1], [0.96, 1], { extrapolateRight: 'clamp' });
+
+    // Simple TikTok-ish word highlight sweep.
+    // Sweep exactly once across the whole subtitle block (no looping).
+    const words = active.text.replace(/\s+/g, ' ').trim().split(' ').filter(Boolean);
+    const displayedWords = words.length > 0 ? words : [active.text];
+    const blockDurationInFrames = Math.max(
+      1,
+      Math.round((active.endInSeconds - active.startInSeconds) * fps)
+    );
+    const sweep = interpolate(
+      relFrame,
+      [0, blockDurationInFrames],
+      [0, displayedWords.length],
+      { extrapolateRight: 'clamp' }
+    );
+    const highlightIndex = Math.min(displayedWords.length - 1, Math.floor(sweep));
+
+   return (
+     <div
+       style={{
+         position: 'absolute',
+         left: 0,
+         right: 0,
+         bottom: 72,
+         display: 'flex',
+         justifyContent: 'center',
+          padding: '0 48px',
+          pointerEvents: 'none',
+          opacity,
+          transform: \`scale(\${scale})\`,
+        }}
+      >
+       <div
+         style={{
+           maxWidth: '92%',
+           backgroundColor: 'rgba(0,0,0,0.6)',
+           border: '2px solid rgba(255,255,255,0.14)',
+           borderRadius: 18,
+           padding: '14px 18px',
+           color: '#fff',
+           fontSize: 46,
+           fontWeight: 900,
+           lineHeight: 1.15,
+           letterSpacing: '-0.02em',
+           textAlign: 'center',
+           textShadow: '4px 4px 0px rgba(0,0,0,0.85)',
+           display: 'flex',
+           flexWrap: 'wrap',
+           justifyContent: 'center',
+           gap: 12,
+         }}
+       >
+          {displayedWords.map((w, i) => (
+            <span
+              key={i}
+              style={{
+                padding: '2px 10px',
+                borderRadius: 10,
+                backgroundColor: highlightIndex === i ? '#ff0050' : 'transparent',
+                transform: highlightIndex === i ? 'scale(1.06)' : 'scale(1)',
+                transition: 'transform 80ms linear',
+              }}
+            >
+              {w}
+            </span>
+          ))}
+       </div>
+     </div>
+   );
+ };
+
+ export const ${componentName} = () => {
+   const { width, height } = useVideoConfig();
+   const subtitles = useMemo(() => parseSrt(SRT_CAPTIONS), []);
+   return (
+     <div style={{ width, height, overflow: 'hidden', backgroundColor: '#000', position: 'relative' }}>
+ ${sequences}
+       <CaptionOverlay subtitles={subtitles} />
+     </div>
+   );
+ };
 
 /** Total duration in frames: ${totalFrames} (${(totalFrames / fps).toFixed(1)}s at ${fps}fps) */
 export const ${componentName}Config = {
@@ -220,7 +307,36 @@ export const ${componentName}Config = {
   fps: ${fps},
   durationInFrames: ${totalFrames},
 } as const;
-`;
+ `;
+}
+
+function formatSrtTimestamp(totalSeconds: number): string {
+  const clamped = Math.max(0, totalSeconds);
+  const hours = Math.floor(clamped / 3600);
+  const minutes = Math.floor((clamped % 3600) / 60);
+  const seconds = Math.floor(clamped % 60);
+  const millis = Math.floor((clamped - Math.floor(clamped)) * 1000);
+  const pad2 = (n: number) => String(n).padStart(2, '0');
+  const pad3 = (n: number) => String(n).padStart(3, '0');
+  return `${pad2(hours)}:${pad2(minutes)}:${pad2(seconds)},${pad3(millis)}`;
+}
+
+function buildFallbackSrt(plan: ScenePlan): string {
+  let t = 0;
+  let id = 1;
+  const blocks: string[] = [];
+  for (const s of plan.scenes) {
+    const start = t;
+    const end = t + Math.max(0.5, s.durationInSeconds);
+    const text = (s.title || s.description || '...').toString().trim() || '...';
+    const safeText = text.split(/\r?\n/).slice(0, 2).join('\n');
+    blocks.push(
+      `${id}\n${formatSrtTimestamp(start)} --> ${formatSrtTimestamp(end)}\n${safeText}`
+    );
+    id++;
+    t = end;
+  }
+  return blocks.join('\n\n') + '\n';
 }
 
 /**
@@ -295,48 +411,6 @@ export async function runGenerate(
   description: string,
   options: GenerateOptions
 ): Promise<void> {
-  // ------------------------------------------------------------------
-  // 0. Environment check
-  // ------------------------------------------------------------------
-  const initialized = isInitialized(process.cwd());
-  const unexpectedFiles = getUnexpectedFiles(process.cwd());
-
-  if (!initialized || unexpectedFiles.length > 0) {
-    console.log(chalk.yellow('\n⚠️  Warning: Existing files may be overwritten.'));
-    if (!initialized) {
-      console.log(
-        chalk.yellow(
-          'This directory does not appear to be an OpenMotion project (run "open-motion init" first).'
-        )
-      );
-    } else {
-      console.log(
-        chalk.yellow('This directory contains files not created by "open-motion init".')
-      );
-    }
-    console.log('');
-
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-
-    const answer = await new Promise<string>((resolve) => {
-      rl.question(
-        chalk.bold('Do you want to continue? ') + chalk.dim('(y/N) '),
-        (a) => {
-          resolve(a.trim().toLowerCase());
-        }
-      );
-    });
-    rl.close();
-
-    if (answer !== 'y' && answer !== 'yes') {
-      console.log(chalk.dim('\nAborted.'));
-      return;
-    }
-  }
-
   const fps = options.fps ?? 30;
   const width = options.width ?? 1280;
   const height = options.height ?? 720;
@@ -383,10 +457,49 @@ export async function runGenerate(
   }
 
   // ------------------------------------------------------------------
-  // 2. Plan scenes
+  // 2. Environment / overwrite check (after config validation)
+  // ------------------------------------------------------------------
+  const initialized = isInitialized(process.cwd());
+  const overwriteHints = getOverwriteHints(process.cwd(), outputDir);
+
+  if (!initialized || overwriteHints.length > 0) {
+    console.log(chalk.yellow('\n⚠️  Warning: Existing files may be overwritten.'));
+    if (!initialized) {
+      console.log(
+        chalk.yellow(
+          'This directory does not appear to be an OpenMotion project (run "open-motion init" first).'
+        )
+      );
+    }
+    overwriteHints.forEach((h) => console.log(chalk.yellow(`- ${h}`)));
+    console.log('');
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    const answer = await new Promise<string>((resolve) => {
+      rl.question(
+        chalk.bold('Do you want to continue? ') + chalk.dim('(y/N) '),
+        (a) => {
+          resolve(a.trim().toLowerCase());
+        }
+      );
+    });
+    rl.close();
+
+    if (answer !== 'y' && answer !== 'yes') {
+      console.log(chalk.dim('\nAborted.'));
+      return;
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // 3. Plan scenes
   // ------------------------------------------------------------------
   const spinner = new Spinner();
-  spinner.start('[1/3] Planning scene structure...');
+  spinner.start('[1/4] Planning scene structure...');
 
   let plan: ScenePlan;
   try {
@@ -414,7 +527,7 @@ export async function runGenerate(
     );
   }
 
-  spinner.succeed(`[1/3] Scene structure: ${plan.scenes.length} scene(s)`);
+  spinner.succeed(`[1/4] Scene structure: ${plan.scenes.length} scene(s)`);
   plan.scenes.forEach((s, i) => {
     console.log(
       chalk.dim(`       Scene ${i + 1}: ${s.title} (${s.durationInSeconds}s)`)
@@ -423,9 +536,53 @@ export async function runGenerate(
   console.log('');
 
   // ------------------------------------------------------------------
-  // 3. Generate TSX for each scene
+  // 3. Generate captions (SRT)
+  // ------------------------------------------------------------------
+  spinner.start('[2/4] Generating captions (SRT)...');
+
+  // Build a deterministic scene timeline for caption planning.
+  let cursor = 0;
+  const timeline = plan.scenes.map((s) => {
+    const startInSeconds = cursor;
+    const endInSeconds = cursor + s.durationInSeconds;
+    cursor = endInSeconds;
+    return {
+      title: s.title,
+      description: s.description,
+      startInSeconds,
+      endInSeconds,
+    };
+  });
+
+  let srtContent = '';
+  try {
+    const { text } = await generateText({
+      model,
+      system: CAPTIONS_SYSTEM_PROMPT,
+      prompt: buildCaptionsPrompt({
+        videoTitle: plan.videoTitle,
+        description,
+        scenes: timeline,
+      }),
+      maxTokens: 2048,
+    });
+    srtContent = parseCaptionsResponse(text).srt;
+    spinner.succeed('[2/4] Captions generated');
+  } catch (err) {
+    srtContent = buildFallbackSrt(plan);
+    spinner.succeed('[2/4] Captions generated (fallback)');
+    console.log(
+      chalk.yellow(
+        `  Note: failed to generate captions via LLM; using a simple fallback. (${(err as Error).message})`
+      )
+    );
+  }
+  console.log('');
+
+  // ------------------------------------------------------------------
+  // 4. Generate TSX for each scene
   // ------------------------------------------------------------------
-  spinner.start(`[2/3] Generating TSX... (0/${plan.scenes.length})`);
+  spinner.start(`[3/4] Generating TSX... (0/${plan.scenes.length})`);
 
   const scenesDir = path.join(outputDir);
   fs.mkdirSync(scenesDir, { recursive: true });
@@ -434,49 +591,78 @@ export async function runGenerate(
 
   for (let i = 0; i < plan.scenes.length; i++) {
     const scene = plan.scenes[i];
-    spinner.update(`[2/3] Generating TSX... (${i + 1}/${plan.scenes.length}) — ${scene.title}`);
+    spinner.update(`[3/4] Generating TSX... (${i + 1}/${plan.scenes.length}) — ${scene.title}`);
 
     const durationInFrames = Math.round(scene.durationInSeconds * fps);
 
-    try {
-      const { text } = await generateText({
-        model,
-        system: GENERATE_SYSTEM_PROMPT,
-        prompt: buildSceneCodePrompt({
-          componentName: scene.componentName,
-          title: scene.title,
-          description: scene.description,
-          durationInSeconds: scene.durationInSeconds,
-          durationInFrames,
-          fps,
-          width,
-          height,
-          sceneIndex: i,
-          totalScenes: plan.scenes.length,
-        }),
-        maxTokens: 4096,
-      });
-
-      const code = parseCodeResponse(text);
-      const filePath = path.join(scenesDir, `${scene.componentName}.tsx`);
-      fs.writeFileSync(filePath, code + '\n', 'utf8');
-      generatedFiles.push(filePath);
-    } catch (err) {
-      spinner.fail(`Failed to generate scene "${scene.title}"`);
-      console.error(chalk.red((err as Error).message));
+    const scenePromptArgs = {
+      componentName: scene.componentName,
+      title: scene.title,
+      description: scene.description,
+      durationInSeconds: scene.durationInSeconds,
+      durationInFrames,
+      fps,
+      width,
+      height,
+      sceneIndex: i,
+      totalScenes: plan.scenes.length,
+    };
+
+    const MAX_ATTEMPTS = 2;
+    let lastError: Error | null = null;
+    let succeeded = false;
+
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+      try {
+        if (attempt > 1) {
+          spinner.update(
+            `[3/4] Retrying TSX... (${i + 1}/${plan.scenes.length}) — ${scene.title} [attempt ${attempt}/${MAX_ATTEMPTS}]`
+          );
+        }
+
+        const { text } = await generateText({
+          model,
+          system: GENERATE_SYSTEM_PROMPT,
+          prompt: buildSceneCodePrompt(scenePromptArgs),
+          maxTokens: 4096,
+        });
+
+        const code = parseCodeResponse(text);
+        validateSceneCode(code, scene.componentName);
+
+        const filePath = path.join(scenesDir, `${scene.componentName}.tsx`);
+        fs.writeFileSync(filePath, code + '\n', 'utf8');
+        generatedFiles.push(filePath);
+        succeeded = true;
+        break;
+      } catch (err) {
+        lastError = err as Error;
+        if (attempt < MAX_ATTEMPTS) {
+          console.log(
+            chalk.yellow(
+              `\n  Warning (attempt ${attempt}/${MAX_ATTEMPTS}): ${lastError.message}\n  Retrying...`
+            )
+          );
+        }
+      }
+    }
+
+    if (!succeeded) {
+      spinner.fail(`Failed to generate scene "${scene.title}" after ${MAX_ATTEMPTS} attempts`);
+      console.error(chalk.red(lastError?.message ?? 'Unknown error'));
       process.exit(1);
     }
   }
 
-  spinner.succeed(`[2/3] TSX generation complete (${plan.scenes.length} scene(s))`);
+  spinner.succeed(`[3/4] TSX generation complete (${plan.scenes.length} scene(s))`);
   console.log('');
 
   // ------------------------------------------------------------------
-  // 4. Generate composition wrapper
+  // 5. Generate composition wrapper
   // ------------------------------------------------------------------
-  spinner.start('[3/3] Generating composition file...');
+  spinner.start('[4/4] Generating composition file...');
 
-  const compositionCode = buildCompositionFile(plan.videoTitle, plan, fps, width, height);
+  const compositionCode = buildCompositionFile(plan.videoTitle, plan, fps, width, height, srtContent);
   const compositionComponentName = toPascalCase(plan.videoTitle) + 'Video';
 
   // Total duration for the composition
@@ -503,7 +689,7 @@ export async function runGenerate(
   });
 
   const updatedMainTsx = fs.existsSync(mainTsxPath);
-  spinner.succeed('[3/3] Composition generation complete');
+  spinner.succeed('[4/4] Composition generation complete');
   console.log('');
 
   // ------------------------------------------------------------------
diff --git a/packages/cli/src/prompts/generate.ts b/packages/cli/src/prompts/generate.ts
index df7ff24..9ecdea9 100644
--- a/packages/cli/src/prompts/generate.ts
+++ b/packages/cli/src/prompts/generate.ts
@@ -78,6 +78,80 @@ export const ExampleScene = () => {
 \`\`\`
 `;
 
+// ---------------------------------------------------------------------------
+// Caption (SRT) generation
+// ---------------------------------------------------------------------------
+
+export const CAPTIONS_SYSTEM_PROMPT = `You generate subtitle captions for videos.
+
+You must output VALID JSON only (no markdown, no extra keys).
+The JSON must contain a single key: { "srt": "..." } where the value is a complete SRT file contents.
+
+SRT rules:
+- Use standard time format: HH:MM:SS,mmm --> HH:MM:SS,mmm
+- Number captions starting from 1
+- Separate each caption block with a blank line
+- Do not include backticks in the SRT text
+- Keep each caption to 1-2 lines
+- Ensure times are strictly increasing and do not overlap
+`;
+
+export interface CaptionsContext {
+  videoTitle: string;
+  description: string;
+  scenes: Array<{
+    title: string;
+    description: string;
+    startInSeconds: number;
+    endInSeconds: number;
+  }>;
+}
+
+export function buildCaptionsPrompt(ctx: CaptionsContext): string {
+  return `Create subtitles (SRT) for the following video.
+
+Video title: ${ctx.videoTitle}
+Video description: ${ctx.description}
+
+Scene timeline (must keep captions within these bounds):
+${ctx.scenes
+  .map(
+    (s, i) =>
+      `${i + 1}. ${s.title} (${s.startInSeconds.toFixed(3)}s - ${s.endInSeconds.toFixed(3)}s): ${s.description}`
+  )
+  .join('\n')}
+
+Guidelines:
+- Write captions that match what the viewer sees on-screen in each scene (short, punchy)
+- Prefer 1-3 caption blocks per scene
+- Keep the total captions aligned to the total timeline (from 0s to ${ctx.scenes[ctx.scenes.length - 1].endInSeconds.toFixed(
+    3
+  )}s)
+
+Respond with JSON only in this exact shape:
+{ "srt": "<SRT content>" }`;
+}
+
+export function parseCaptionsResponse(text: string): { srt: string } {
+  const cleaned = text
+    .replace(/^```(?:json)?\s*/m, '')
+    .replace(/\s*```\s*$/m, '')
+    .trim();
+
+  let out: { srt: string };
+  try {
+    out = JSON.parse(cleaned);
+  } catch {
+    throw new Error(`LLM returned invalid JSON for captions.\nRaw response:\n${text}`);
+  }
+
+  if (!out || typeof out.srt !== 'string' || out.srt.trim().length === 0) {
+    throw new Error(`LLM captions response is missing required field "srt".\nParsed:\n${JSON.stringify(out, null, 2)}`);
+  }
+
+  return { srt: out.srt };
+}
+
 // ---------------------------------------------------------------------------
 // Planning prompt: ask the LLM to break a description into scenes
 // ---------------------------------------------------------------------------
@@ -202,3 +276,27 @@ export function parseCodeResponse(text: string): string {
     .replace(/\n?```\s*$/m, '')
     .trim();
 }
+
+/**
+ * Validate that generated scene code contains the expected named export.
+ * Throws a descriptive error if the code is empty or the export is missing.
+ */
+export function validateSceneCode(code: string, componentName: string): void {
+  if (!code || code.trim().length === 0) {
+    throw new Error(
+      `LLM returned empty code for component "${componentName}". The scene file would be blank.`
+    );
+  }
+
+  // Accept: export const Foo, export function Foo, export class Foo
+  const namedExportRe = new RegExp(
+    `export\\s+(const|function|class)\\s+${componentName}\\b`
+  );
+  if (!namedExportRe.test(code)) {
+    throw new Error(
+      `Generated code for "${componentName}" is missing the required named export.\n` +
+      `Expected: \`export const ${componentName} = ...\` (or export function/class).\n` +
+      `The exported name in the file must exactly match "${componentName}".`
+    );
+  }
+}

From 726d43270f225e886ca86e127fa723e1926eb07b Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Fri, 27 Feb 2026 12:44:54 +0900
Subject: [PATCH 15/28] fix(cli): harden generated component identifiers

---
 packages/cli/src/commands/generate.ts | 28 +++++++++++++++------
 packages/cli/src/prompts/generate.ts  | 36 +++++++++++++++++++++------
 pnpm-lock.yaml                        | 10 ++++++++
 3 files changed, 60 insertions(+), 14 deletions(-)

diff --git a/packages/cli/src/commands/generate.ts b/packages/cli/src/commands/generate.ts
index 163a5d6..49063b3 100644
--- a/packages/cli/src/commands/generate.ts
+++ b/packages/cli/src/commands/generate.ts
@@ -95,18 +95,32 @@ function formatRun(pm: 'pnpm' | 'npm', script: string): string {
 /**
  * Convert a video title (or scene title) to a valid PascalCase component name.
  * E.g. "React Lifecycle" → "ReactLifecycle"
+ *
+ * Rules enforced here (defense-in-depth, even if LLM follows the prompt):
+ * - Only ASCII letters and digits are kept; all other characters (CJK, spaces,
+ *   hyphens, emoji, …) are treated as word separators.
+ * - Each word is capitalised so the result is PascalCase.
+ * - If the result starts with a digit (e.g. "20秒…" → "20"), a "Video" prefix
+ *   is prepended so the identifier is always valid.
+ * - If nothing survives the filter, "VideoProject" is used as a fallback.
  */
 function toPascalCase(str: string): string {
-  return str
-    .replace(/[^a-zA-Z0-9\u3040-\u30FF\u4E00-\u9FFF]+/g, ' ')
+  // Replace any run of non-ASCII-alphanumeric characters with a single space,
+  // then split, capitalise each word and join.
+  const result = str
+    .replace(/[^a-zA-Z0-9]+/g, ' ')
     .trim()
     .split(/\s+/)
-    .map((word) =>
-      /^[a-zA-Z]/.test(word)
-        ? word.charAt(0).toUpperCase() + word.slice(1)
-        : word
-    )
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
     .join('');
+
+  if (!result) return 'VideoProject';
+
+  // Ensure the identifier does not start with a digit.
+  if (/^[0-9]/.test(result)) return 'Video' + result;
+
+  return result;
 }
 
 /**
diff --git a/packages/cli/src/prompts/generate.ts b/packages/cli/src/prompts/generate.ts
index 9ecdea9..8853959 100644
--- a/packages/cli/src/prompts/generate.ts
+++ b/packages/cli/src/prompts/generate.ts
@@ -38,9 +38,14 @@ setTimeout, setInterval, or any real-time mechanism for animation.
 
 ## Naming rules (critical)
 - Any exported component name MUST be a valid TypeScript/JavaScript identifier in PascalCase.
-- The name MUST start with a letter A-Z (do not start with a digit).
-- Use ASCII letters and digits only for identifiers (A-Z, a-z, 0-9). Do NOT use Japanese text, spaces, hyphens, emoji, or punctuation in identifiers.
-- If the title is non-Latin (e.g. Japanese), romanize/translate it for the identifier (e.g. "30秒でわかるRemotion" -> "RemotionIn30Seconds").
+- The name MUST start with a letter A-Z (NEVER start with a digit or any non-ASCII character).
+- Use ASCII letters and digits only for identifiers (A-Z, a-z, 0-9). Do NOT use Japanese text, Chinese text, spaces, hyphens, underscores at the start, emoji, or punctuation in identifiers.
+- If the title is non-Latin (e.g. Japanese or Chinese), you MUST romanize/translate it for the identifier.
+  - BAD:  "20秒でわかる三権分立" → identifier starts with digit AND contains Japanese → INVALID
+  - GOOD: "20秒でわかる三権分立" → "SankenbunritsuIn20Seconds" (romanized + digit moved inside) → VALID
+  - BAD:  "量子コンピュータ入門" → contains Japanese → INVALID
+  - GOOD: "量子コンピュータ入門" → "IntroToQuantumComputers" → VALID
+- This rule applies to EVERY identifier: componentName in scenes AND any name derived from videoTitle.
 
 ## Minimal valid example
 \`\`\`tsx
@@ -162,7 +167,7 @@ Video description: "${description}"
 
 Respond with a JSON object (and nothing else) in this exact shape:
 {
-  "videoTitle": "A concise title for the entire video",
+  "videoTitle": "A concise title for the entire video (may contain any language/characters)",
   "scenes": [
     {
       "id": "kebab-case-unique-id",
@@ -177,10 +182,12 @@ Respond with a JSON object (and nothing else) in this exact shape:
 Guidelines:
 - Total video duration should feel natural for the content (typically 20-90 seconds)
 - Each scene should be self-contained and visually distinct
+- \`videoTitle\` is a human-readable display title and may use any language or characters.
 - \`componentName\` must be a valid PascalCase React component name AND a valid JS/TS identifier:
-  - start with A-Z (never start with a number)
-  - ASCII letters/digits only (no Japanese/non-ASCII characters, no spaces, no hyphens)
-  - examples: "IntroScene", "HowItWorksScene", "RemotionIn30SecondsScene"
+  - start with A-Z (NEVER start with a digit or non-ASCII character)
+  - ASCII letters/digits only (no Japanese/Chinese/non-ASCII characters, no spaces, no hyphens)
+  - If the scene title is Japanese/Chinese, romanize it: e.g. "三権分立とは" → "WhatIsSankenbunritsu"
+  - examples: "IntroScene", "HowItWorksScene", "SankenbunritsuIn20SecondsScene"
 - \`id\` must be unique kebab-case (e.g. "intro-scene", "data-flow-scene")
 - Aim for 3-6 scenes unless the content clearly needs more or fewer
 - Describe animations concretely (e.g. "text fades in from bottom, then a line draws across")
@@ -264,6 +271,21 @@ export function parsePlanResponse(text: string): ScenePlan {
     );
   }
 
+  // Validate that every componentName is a legal JS/TS identifier.
+  // This is a defence-in-depth check: the prompt already instructs the LLM,
+  // but we must not trust LLM output blindly.
+  const validIdentifier = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+  for (const scene of plan.scenes) {
+    if (!scene.componentName || !validIdentifier.test(scene.componentName)) {
+      throw new Error(
+        `LLM returned an invalid componentName: "${scene.componentName}".\n` +
+        `componentName must be a valid JS/TS identifier (ASCII PascalCase, must not start with a digit).\n` +
+        `If the title is non-Latin (e.g. Japanese), the LLM must romanize it.\n` +
+        `Please retry the generation.`
+      );
+    }
+  }
+
   return plan;
 }
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8ab3b01..0df376c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -115,6 +115,9 @@ importers:
       diff:
         specifier: ^5.2.0
         version: 5.2.2
+      dotenv:
+        specifier: ^16.0.0
+        version: 16.6.1
       ollama-ai-provider:
         specifier: ^1.2.0
         version: 1.2.0(zod@3.25.76)
@@ -897,6 +900,10 @@ packages:
     resolution: {integrity: sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==}
     engines: {node: '>=8'}
 
+  dotenv@16.6.1:
+    resolution: {integrity: sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==}
+    engines: {node: '>=12'}
+
   eastasianwidth@0.2.0:
     resolution: {integrity: sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==}
 
@@ -1988,6 +1995,7 @@ snapshots:
       cli-progress: 3.12.0
       commander: 11.1.0
       diff: 5.2.2
+      dotenv: 16.6.1
       ollama-ai-provider: 1.2.0(zod@3.25.76)
       playwright: 1.58.1
     transitivePeerDependencies:
@@ -2286,6 +2294,8 @@ snapshots:
     dependencies:
       path-type: 4.0.0
 
+  dotenv@16.6.1: {}
+
   eastasianwidth@0.2.0: {}
 
   electron-to-chromium@1.5.283: {}

From 436b7b2a7cd18be61e8a14e998ae8cbe9043c3c8 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Fri, 27 Feb 2026 12:48:16 +0900
Subject: [PATCH 16/28] feat(cli): add OpenRouter provider

---
 .env.example                        |  6 ++++++
 packages/cli/src/commands/config.ts |  8 +++++---
 packages/cli/src/index.ts           | 29 ++++++++++++++++++++---------
 packages/cli/src/llm/config.ts      | 16 ++++++++++++++++
 packages/cli/src/llm/factory.ts     |  6 ++++++
 packages/cli/src/llm/types.ts       |  2 ++
 6 files changed, 55 insertions(+), 12 deletions(-)

diff --git a/.env.example b/.env.example
index 909d361..807bb3c 100644
--- a/.env.example
+++ b/.env.example
@@ -4,13 +4,19 @@
 
 # --- LLM Provider (optional, defaults to "openai") ---
 # OPEN_MOTION_PROVIDER=openai
+# OPEN_MOTION_PROVIDER=openrouter
 
 # --- Model override (optional) ---
 # OPEN_MOTION_MODEL=gpt-4o
+# OPEN_MOTION_MODEL=openai/gpt-4o
 
 # --- OpenAI ---
 # OPENAI_API_KEY=sk-...
 
+# --- OpenRouter ---
+# OPENROUTER_API_KEY=sk-or-...
+# OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+
 # --- Anthropic ---
 # ANTHROPIC_API_KEY=sk-ant-...
 
diff --git a/packages/cli/src/commands/config.ts b/packages/cli/src/commands/config.ts
index 12cc879..c38169c 100644
--- a/packages/cli/src/commands/config.ts
+++ b/packages/cli/src/commands/config.ts
@@ -6,9 +6,11 @@ import { resolveConfig } from '../llm/config';
 // ---------------------------------------------------------------------------
 
 const ENV_VARS: Array<{ key: string; description: string }> = [
-  { key: 'OPEN_MOTION_PROVIDER',  description: 'LLM provider (openai | anthropic | google | ollama | openai-compatible)' },
+  { key: 'OPEN_MOTION_PROVIDER',  description: 'LLM provider (openai | openrouter | anthropic | google | ollama | openai-compatible)' },
   { key: 'OPEN_MOTION_MODEL',     description: 'Model name override' },
   { key: 'OPENAI_API_KEY',        description: 'API key for OpenAI' },
+  { key: 'OPENROUTER_API_KEY',    description: 'API key for OpenRouter' },
+  { key: 'OPENROUTER_BASE_URL',   description: 'Optional base URL for OpenRouter (default: https://openrouter.ai/api/v1)' },
   { key: 'ANTHROPIC_API_KEY',     description: 'API key for Anthropic' },
   { key: 'GOOGLE_API_KEY',        description: 'API key for Google / Gemini' },
   { key: 'GEMINI_API_KEY',        description: 'Alias for GOOGLE_API_KEY' },
@@ -94,8 +96,8 @@ export function printConfigHelp(): void {
   console.log('You can place them in a ' + chalk.cyan('.env') + ' file in your project directory.');
   console.log('');
   console.log('Example .env:');
-  console.log(chalk.dim('  OPEN_MOTION_PROVIDER=openai'));
-  console.log(chalk.dim('  OPENAI_API_KEY=sk-...'));
+  console.log(chalk.dim('  OPEN_MOTION_PROVIDER=openrouter'));
+  console.log(chalk.dim('  OPENROUTER_API_KEY=sk-or-...'));
   console.log('');
   console.log('See ' + chalk.cyan('.env.example') + ' for all available variables.');
 }
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 0bce55e..27dd0c8 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -585,10 +585,13 @@ Examples:
   const generateCommand = program
     .command('generate <description>')
     .description('Auto-generate video scene TSX files using an LLM')
-    .option('--provider <name>', 'LLM provider (openai/anthropic/google/ollama/openai-compatible)')
+    .option(
+      '--provider <name>',
+      'LLM provider (openai/openrouter/anthropic/google/ollama/openai-compatible)'
+    )
     .option('--model <name>', 'Model name to use')
     .option('--api-key <key>', 'API key (overrides config file and environment variables)')
-    .option('--base-url <url>', 'Base URL (for openai-compatible / ollama)')
+    .option('--base-url <url>', 'Base URL (for openrouter / openai-compatible / ollama)')
     .option('--scenes <number>', 'Number of scenes to generate (default: decided by LLM)', parseInt)
     .option('--fps <number>', 'Frame rate (default: 30)', parseInt)
     .option('--width <number>', 'Video width (default: 1280)', parseInt)
@@ -618,11 +621,13 @@ Examples:
   $ open-motion generate "A video explaining the React lifecycle"
   $ open-motion generate "TypeScript type system explainer" --scenes 4 --fps 30
   $ open-motion generate "How to use AWS S3" --provider anthropic --model claude-opus-4-5
+  $ open-motion generate "React hooks overview" --provider openrouter --model openai/gpt-4o
   $ open-motion generate "How Docker works" --provider ollama --model llama3
+  $ open-motion generate "CI/CD pipeline explainer" --provider openai-compatible --base-url https://example.com/v1
   $ open-motion generate "CI/CD pipeline explainer" --width 1920 --height 1080
 
 Note:
-  - LLM must be configured first: open-motion config set provider openai
+  - LLM configuration is read from environment variables (you can put them in a .env file)
   - Run this command from the root of an existing project (created with open-motion init)
 `);
 
@@ -633,10 +638,13 @@ Note:
     .command('edit <file>')
     .description('Interactively edit a TSX scene file using an LLM')
     .option('-m, --message <instruction>', 'One-shot mode: pass instruction as a string')
-    .option('--provider <name>', 'LLM provider (openai/anthropic/google/ollama/openai-compatible)')
+    .option(
+      '--provider <name>',
+      'LLM provider (openai/openrouter/anthropic/google/ollama/openai-compatible)'
+    )
     .option('--model <name>', 'Model name to use')
     .option('--api-key <key>', 'API key (overrides config file and environment variables)')
-    .option('--base-url <url>', 'Base URL (for openai-compatible / ollama)')
+    .option('--base-url <url>', 'Base URL (for openrouter / openai-compatible / ollama)')
     .option('-y, --yes', 'Auto-apply changes without confirmation (one-shot mode only)')
     .action(async (file: string, options) => {
       try {
@@ -700,10 +708,12 @@ Examples:
 
   configCommand.addHelpText('after', `
 Configurable keys:
-  provider                      LLM provider to use (openai/anthropic/google/ollama/openai-compatible)
+  provider                      LLM provider to use (openai/openrouter/anthropic/google/ollama/openai-compatible)
   model                         Global model override
   openai.apiKey                 OpenAI API key
   openai.model                  OpenAI model (default: gpt-4o)
+  openrouter.apiKey             OpenRouter API key
+  openrouter.model              OpenRouter model (default: openai/gpt-4o)
   anthropic.apiKey              Anthropic API key
   anthropic.model               Anthropic model (default: claude-3-5-sonnet-20241022)
   google.apiKey                 Google AI API key
@@ -718,15 +728,16 @@ Environment variables (override config file):
   OPEN_MOTION_PROVIDER          Provider override
   OPEN_MOTION_MODEL             Model override
   OPENAI_API_KEY                OpenAI API key
+  OPENROUTER_API_KEY            OpenRouter API key
+  OPENROUTER_BASE_URL           OpenRouter base URL override
   ANTHROPIC_API_KEY             Anthropic API key
   GOOGLE_API_KEY / GEMINI_API_KEY  Google AI API key
   OPEN_MOTION_BASE_URL          Custom base URL
   OPEN_MOTION_API_KEY           Custom API key
 
 Examples:
-  $ open-motion config set provider openai
-  $ open-motion config set openai.apiKey sk-...
-  $ open-motion config set openai.model gpt-4o
+  $ open-motion config list
+  $ OPEN_MOTION_PROVIDER=openrouter OPENROUTER_API_KEY=sk-or-... open-motion generate "Explain closures"
   $ open-motion config list
 `);
 
diff --git a/packages/cli/src/llm/config.ts b/packages/cli/src/llm/config.ts
index 31bc0af..84401eb 100644
--- a/packages/cli/src/llm/config.ts
+++ b/packages/cli/src/llm/config.ts
@@ -21,6 +21,8 @@ export interface CliConfigOverrides {
   baseURL?: string;
 }
 
+const OPENROUTER_DEFAULT_BASE_URL = 'https://openrouter.ai/api/v1';
+
 /**
  * Merge environment variables + CLI overrides into a single ResolvedLLMConfig.
  * Priority (high → low):
@@ -47,6 +49,19 @@ export function resolveConfig(overrides: CliConfigOverrides = {}): ResolvedLLMCo
     case 'openai':
       apiKey = overrides.apiKey || env('OPENAI_API_KEY');
       break;
+    case 'openrouter':
+      apiKey =
+        overrides.apiKey ||
+        env('OPENROUTER_API_KEY') ||
+        // Back-compat: allow users to reuse the generic key env var.
+        env('OPEN_MOTION_API_KEY');
+      baseURL =
+        overrides.baseURL ||
+        env('OPENROUTER_BASE_URL') ||
+        // Back-compat: allow using the generic base URL env var.
+        env('OPEN_MOTION_BASE_URL') ||
+        OPENROUTER_DEFAULT_BASE_URL;
+      break;
     case 'anthropic':
       apiKey = overrides.apiKey || env('ANTHROPIC_API_KEY');
       break;
@@ -88,6 +103,7 @@ export function validateConfig(cfg: ResolvedLLMConfig): void {
   if (!cfg.apiKey) {
     const envVar: Record<ProviderName, string> = {
       openai: 'OPENAI_API_KEY',
+      openrouter: 'OPENROUTER_API_KEY',
       anthropic: 'ANTHROPIC_API_KEY',
       google: 'GOOGLE_API_KEY',
       ollama: '',
diff --git a/packages/cli/src/llm/factory.ts b/packages/cli/src/llm/factory.ts
index 5810ff9..38e207c 100644
--- a/packages/cli/src/llm/factory.ts
+++ b/packages/cli/src/llm/factory.ts
@@ -14,6 +14,12 @@ export async function createModel(cfg: ResolvedLLMConfig): Promise<LanguageModel
       return client(cfg.model) as LanguageModelV1;
     }
 
+    case 'openrouter': {
+      const { createOpenAI } = await import('@ai-sdk/openai');
+      const client = createOpenAI({ apiKey: cfg.apiKey, baseURL: cfg.baseURL });
+      return client(cfg.model) as LanguageModelV1;
+    }
+
     case 'anthropic': {
       const { createAnthropic } = await import('@ai-sdk/anthropic');
       const client = createAnthropic({ apiKey: cfg.apiKey });
diff --git a/packages/cli/src/llm/types.ts b/packages/cli/src/llm/types.ts
index ce0439c..0ab2fde 100644
--- a/packages/cli/src/llm/types.ts
+++ b/packages/cli/src/llm/types.ts
@@ -1,5 +1,6 @@
 export type ProviderName =
   | 'openai'
+  | 'openrouter'
   | 'anthropic'
   | 'google'
   | 'ollama'
@@ -58,6 +59,7 @@ export interface ResolvedLLMConfig {
 /** Default models for each provider */
 export const DEFAULT_MODELS: Record<ProviderName, string> = {
   openai: 'gpt-4o',
+  openrouter: 'openai/gpt-4o',
   anthropic: 'claude-3-5-sonnet-20241022',
   google: 'gemini-1.5-pro',
   ollama: 'llama3',

From 170433e9c29970237b0826dfe9a9e2c37a273556 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Fri, 27 Feb 2026 13:59:19 +0900
Subject: [PATCH 17/28] fix(cli): correct template literal handling in syntax
 validation

---
 packages/cli/src/commands/generate.ts |  10 +-
 packages/cli/src/prompts/generate.ts  | 141 +++++++++++++++++++++++++-
 2 files changed, 147 insertions(+), 4 deletions(-)

diff --git a/packages/cli/src/commands/generate.ts b/packages/cli/src/commands/generate.ts
index 49063b3..b7f0110 100644
--- a/packages/cli/src/commands/generate.ts
+++ b/packages/cli/src/commands/generate.ts
@@ -622,7 +622,7 @@ export async function runGenerate(
       totalScenes: plan.scenes.length,
     };
 
-    const MAX_ATTEMPTS = 2;
+    const MAX_ATTEMPTS = 3;
     let lastError: Error | null = null;
     let succeeded = false;
 
@@ -634,11 +634,15 @@ export async function runGenerate(
           );
         }
 
+        const retryContext = attempt > 1 && lastError
+          ? `IMPORTANT: The previous attempt failed with this error:\n${lastError.message}\n\nCommon causes:\n- The file was cut off mid-way (truncated output). Write simpler, shorter code to avoid this.\n- A bracket, parenthesis, or JSX tag was left unclosed.\n- A string or template literal was not terminated.\nFix these issues and output a COMPLETE, syntactically valid TSX file.`
+          : undefined;
+
         const { text } = await generateText({
           model,
           system: GENERATE_SYSTEM_PROMPT,
-          prompt: buildSceneCodePrompt(scenePromptArgs),
-          maxTokens: 4096,
+          prompt: buildSceneCodePrompt({ ...scenePromptArgs, retryContext }),
+          maxTokens: 32768,
         });
 
         const code = parseCodeResponse(text);
diff --git a/packages/cli/src/prompts/generate.ts b/packages/cli/src/prompts/generate.ts
index 8853959..d3d4327 100644
--- a/packages/cli/src/prompts/generate.ts
+++ b/packages/cli/src/prompts/generate.ts
@@ -47,6 +47,15 @@ setTimeout, setInterval, or any real-time mechanism for animation.
   - GOOD: "量子コンピュータ入門" → "IntroToQuantumComputers" → VALID
 - This rule applies to EVERY identifier: componentName in scenes AND any name derived from videoTitle.
 
+## Output completeness rules (CRITICAL)
+- You MUST output the **entire file** from the first \`import\` to the final closing \`};\` — never truncate.
+- Every opened bracket \`{\`, parenthesis \`(\`, and square bracket \`[\` MUST have a matching close.
+- Every JSX tag that is opened MUST be closed (self-closing or with a closing tag).
+- Every string literal started with \`"\`, \`'\`, or a template literal \`\`\` MUST be terminated on the same line or properly closed.
+- The last line of the file MUST be \`};\` (the closing of the exported component arrow function) followed by a newline.
+- If the component logic is becoming long, **simplify the design** — reduce the number of animated elements, use fewer style properties, or combine logic. Do NOT emit a partial file.
+- Never rely on the reader to "complete" your output. The file must be runnable exactly as emitted.
+
 ## Minimal valid example
 \`\`\`tsx
 import React from 'react';
@@ -209,10 +218,16 @@ export interface SceneCodeContext {
   height: number;
   sceneIndex: number;
   totalScenes: number;
+  /** Populated on retry attempts with a description of the previous failure. */
+  retryContext?: string;
 }
 
 export function buildSceneCodePrompt(ctx: SceneCodeContext): string {
-  return `Generate a complete TSX file for the following open-motion scene:
+  const retrySection = ctx.retryContext
+    ? `\n## Previous attempt failed — read carefully before writing\n${ctx.retryContext}\n`
+    : '';
+
+  return `${retrySection}Generate a complete TSX file for the following open-motion scene:
 
 Component name : ${ctx.componentName}
 Scene title    : ${ctx.title}
@@ -232,6 +247,15 @@ Requirements:
 - Use colors and typography appropriate for the scene's content
 - Do NOT include any Composition registration
 
+Completeness rules (CRITICAL — violations cause build errors):
+- Output the ENTIRE file: from the first \`import\` line to the final \`};\` closing line.
+- Every \`{\` must have a matching \`}\`, every \`(\` a \`)\`, every \`[\` a \`]\`.
+- Every JSX attribute string value started with \`"\` must be closed with \`"\` on the same line.
+- Every JSX element opened must be closed (self-closing \`/>\` or with a \`</tag>\`).
+- Every template literal \`\`\`\` must be terminated with a closing \`\`\`\`\`.
+- The very last line must be \`};\` (end of the exported component), then a newline.
+- If the design is growing too complex, simplify it — use fewer animated elements, fewer style properties. NEVER emit a partial or truncated file.
+
 Return ONLY the raw TSX file content. No markdown code fences, no explanation.`;
 }
 
@@ -302,6 +326,13 @@ export function parseCodeResponse(text: string): string {
 /**
  * Validate that generated scene code contains the expected named export.
  * Throws a descriptive error if the code is empty or the export is missing.
+ *
+ * Also runs a set of lightweight syntactic integrity checks that catch the
+ * most common truncation / partial-output failures:
+ *   1. Named export presence
+ *   2. Bracket / parenthesis / square-bracket balance (outside string literals)
+ *   3. JSX attribute string value closure on the same line
+ *   4. File ends with a closing `}` or `};`
  */
 export function validateSceneCode(code: string, componentName: string): void {
   if (!code || code.trim().length === 0) {
@@ -310,6 +341,7 @@ export function validateSceneCode(code: string, componentName: string): void {
     );
   }
 
+  // ── 1. Named export check ──────────────────────────────────────────────────
   // Accept: export const Foo, export function Foo, export class Foo
   const namedExportRe = new RegExp(
     `export\\s+(const|function|class)\\s+${componentName}\\b`
@@ -321,4 +353,111 @@ export function validateSceneCode(code: string, componentName: string): void {
       `The exported name in the file must exactly match "${componentName}".`
     );
   }
+
+  // ── 2. Bracket balance check (skip contents of string/template literals) ───
+  //
+  // Strategy: walk character-by-character, tracking whether we are inside a
+  // string literal ('…', "…") or template literal (`…`).  Inside a literal we
+  // ignore brackets entirely.  This is not a full parser but catches the most
+  // common truncation patterns (e.g. an object literal whose value was cut off).
+  //
+  // Template literal nesting is handled with a stack:
+  //   - Entering `` ` `` pushes 'template' onto the context stack.
+  //   - Inside a template, `${` begins an expression: we count the opening `{`
+  //     in curly and push 'expr' so we know when the matching `}` exits back
+  //     into the template (rather than decrementing curly a second time).
+  //   - Inside 'expr' context, all normal bracket counting applies, and a
+  //     nested `` ` `` pushes another 'template' level.
+  {
+    let inSingle = false;   // inside '…'
+    let inDouble = false;   // inside "…"
+    // Stack entries: 'template' | 'expr'
+    // 'template' = we are inside `…` (template literal body)
+    // 'expr'     = we are inside ${…} inside a template literal
+    const templateStack: Array<'template' | 'expr'> = [];
+    let curly = 0;
+    let paren = 0;
+    let square = 0;
+
+    const inTemplateBody = () =>
+      templateStack.length > 0 && templateStack[templateStack.length - 1] === 'template';
+    const inString = () => inSingle || inDouble || inTemplateBody();
+
+    for (let ci = 0; ci < code.length; ci++) {
+      const ch = code[ci];
+
+      // Handle escape sequences inside string/template literals
+      if (inString() && ch === '\\') {
+        ci++; // skip the escaped character
+        continue;
+      }
+
+      if (!inString()) {
+        if (ch === "'") { inSingle = true; }
+        else if (ch === '"') { inDouble = true; }
+        else if (ch === '`') { templateStack.push('template'); }
+        else if (ch === '{') { curly++; }
+        else if (ch === '}') {
+          // If we are inside a template expression (${…}), this `}` closes
+          // the expression and returns us to the template literal body.
+          if (templateStack.length > 0 && templateStack[templateStack.length - 1] === 'expr') {
+            templateStack.pop();
+            curly--; // the matching `{` from `${` was already counted
+          } else {
+            curly--;
+          }
+        }
+        else if (ch === '(') { paren++; }
+        else if (ch === ')') { paren--; }
+        else if (ch === '[') { square++; }
+        else if (ch === ']') { square--; }
+      } else {
+        // Inside a string — check for closing delimiter
+        if (inSingle && ch === "'") { inSingle = false; }
+        else if (inDouble && ch === '"') { inDouble = false; }
+        else if (inTemplateBody()) {
+          if (ch === '`') {
+            templateStack.pop(); // close this template literal level
+          } else if (ch === '$' && code[ci + 1] === '{') {
+            // Start of a template expression — count the `{` and enter expr context
+            ci++; // skip the `{`
+            curly++;
+            templateStack.push('expr');
+          }
+        }
+      }
+    }
+
+    const imbalanced: string[] = [];
+    if (curly !== 0) imbalanced.push(`curly braces {} (net ${curly > 0 ? '+' : ''}${curly})`);
+    if (paren !== 0) imbalanced.push(`parentheses () (net ${paren > 0 ? '+' : ''}${paren})`);
+    if (square !== 0) imbalanced.push(`square brackets [] (net ${square > 0 ? '+' : ''}${square})`);
+    if (inSingle) imbalanced.push(`unterminated single-quoted string`);
+    if (inDouble) imbalanced.push(`unterminated double-quoted string`);
+    if (templateStack.length > 0) imbalanced.push(`unterminated template literal`);
+
+    if (imbalanced.length > 0) {
+      throw new Error(
+        `Generated code for "${componentName}" appears to be incomplete or truncated.\n` +
+        `Syntax issues detected:\n` +
+        imbalanced.map(s => `  • ${s}`).join('\n') + '\n' +
+        `The file was likely cut off mid-way. The LLM should produce a shorter, simpler component.`
+      );
+    }
+  }
+
+  // ── 3. File-end check ─────────────────────────────────────────────────────
+  // The last non-empty line should close the exported component: `}` or `};`
+  {
+    const lines = code.split('\n');
+    const lastNonEmpty = [...lines].reverse().find(l => l.trim().length > 0) ?? '';
+    const trimmed = lastNonEmpty.trim();
+    if (trimmed !== '}' && trimmed !== '};') {
+      throw new Error(
+        `Generated code for "${componentName}" does not end with \`};\` or \`}\`.\n` +
+        `Last non-empty line is: ${JSON.stringify(lastNonEmpty)}\n` +
+        `The file was likely truncated before the component was fully closed.`
+      );
+    }
+  }
 }

From 9b189079633a58056e43a51f1948e25dc4b2ae75 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Fri, 27 Feb 2026 15:02:21 +0900
Subject: [PATCH 18/28] feat(cli,encoder): add background music (BGM) support
 for rendering

---
 README.ja.md                  | 12 ++++++++++++
 README.md                     | 12 ++++++++++++
 packages/cli/README.md        |  5 +++++
 packages/cli/src/index.ts     | 27 ++++++++++++++++++++++++++-
 packages/encoder/src/index.ts | 18 +++++++++++++++++-
 5 files changed, 72 insertions(+), 2 deletions(-)

diff --git a/README.ja.md b/README.ja.md
index de195ea..f2ff491 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -119,6 +119,18 @@ OPENAI_API_KEY=sk-...
 | `--public-dir <path>` | 静的アセットの公開ディレクトリ (デフォルト: `./public`) |
 | `--chromium-path <path>`| カスタムChromium実行ファイルのパス |
 | `--timeout <number>` | ブラウザ操作のタイムアウト (ミリ秒) |
+| `--bgm <path>` | ローカルのMP3ファイルをBGMとして追加 |
+| `--bgm-volume <number>` | BGM音量 (0.0-1.0, デフォルト: 1.0) |
+
+例 (レンダー時にBGMを追加):
+
+```bash
+open-motion render -u http://localhost:5173 -o out.mp4 --bgm ./music/bgm.mp3 --bgm-volume 0.5
+```
+
+補足:
+- BGMが動画より短い場合、動画の最後までループします。
+- BGMが動画より長い場合、動画の長さでカットされます。
 
 ## 📚 API リファレンス
 
diff --git a/README.md b/README.md
index 7c026e9..716e819 100644
--- a/README.md
+++ b/README.md
@@ -141,6 +141,18 @@ Render a video from a running OpenMotion application.
 | `--public-dir <path>` | Public directory for static assets (default: `./public`) |
 | `--chromium-path <path>`| Path to custom Chromium executable |
 | `--timeout <number>` | Timeout for browser operations in ms |
+| `--bgm <path>` | Add a background music track from a local MP3 file |
+| `--bgm-volume <number>` | BGM volume (0.0-1.0, default: 1.0) |
+
+Example (render-time BGM):
+
+```bash
+open-motion render -u http://localhost:5173 -o out.mp4 --bgm ./music/bgm.mp3 --bgm-volume 0.5
+```
+
+Notes:
+- If the BGM is shorter than the video, it will loop to cover the full duration.
+- If the BGM is longer than the video, it will be trimmed to the video duration.
 
 ## 📚 API Reference
 
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 145fb7d..50a72be 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -57,4 +57,9 @@ open-motion edit src/scenes/IntroScene.tsx -m "Make the text color blue" --yes
 open-motion render --url http://localhost:5173 --out out.mp4 --concurrency 4
 ```
 
+### Render with background music (BGM)
+```bash
+open-motion render --url http://localhost:5173 --out out.mp4 --bgm ./music/bgm.mp3 --bgm-volume 0.5
+```
+
 Learn more at the [main OpenMotion repository](https://github.com/jsongo/open-motion).
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 27dd0c8..b92ae6b 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -311,6 +311,8 @@ export const runRender = async (options: {
   format?: 'mp4' | 'gif' | 'webp' | 'webm' | 'auto';
   chromiumPath?: string;
   timeout?: number;
+  bgm?: string;
+  bgmVolume?: number;
 }) => {
   const timeout = options.timeout || parseInt(process.env.OPEN_MOTION_RENDER_TIMEOUT || '300000', 10);
 
@@ -440,6 +442,24 @@ export const runRender = async (options: {
     return asset;
   });
 
+  // Inject a render-time BGM track (file path on disk)
+  if (options.bgm) {
+    const bgmPath = path.resolve(process.cwd(), options.bgm);
+
+    if (!fs.existsSync(bgmPath)) {
+      console.error(`BGM file not found: ${bgmPath}`);
+      process.exit(1);
+    }
+
+    resolvedAudioAssets.push({
+      src: bgmPath,
+      startFrame: 0,
+      startFrom: 0,
+      volume: options.bgmVolume ?? 1.0,
+      isBgm: true,
+    });
+  }
+
   const encodeBar = multibar.create(100, 0, { task: 'Encoding ' });
 
   // Determine output format
@@ -476,6 +496,7 @@ export const runRender = async (options: {
       framesDir: tmpDir,
       fps: config.fps,
       outputFile: options.out,
+      durationInFrames: config.durationInFrames,
       audioAssets: resolvedAudioAssets,
       onProgress: (percent) => encodeBar.update(Math.round(percent))
     });
@@ -549,6 +570,8 @@ Example Usage:
     .option('--format <format>', 'Output format (mp4, webm, gif, webp, auto)', 'auto')
     .option('--chromium-path <path>', 'Custom path to Chromium executable')
     .option('--timeout <number>', 'Timeout for browser operations in milliseconds', parseInt)
+    .option('--bgm <path>', 'Path to an MP3 file to use as background music')
+    .option('--bgm-volume <number>', 'BGM volume (0.0-1.0, default: 1.0)', parseFloat)
     .action(async (options) => {
       try {
         await runRender({
@@ -564,7 +587,9 @@ Example Usage:
           publicDir: options.publicDir,
           format: options.format,
           chromiumPath: options.chromiumPath,
-          timeout: options.timeout
+          timeout: options.timeout,
+          bgm: options.bgm,
+          bgmVolume: options.bgmVolume,
         });
       } catch (err) {
         console.error('Render failed:', err);
diff --git a/packages/encoder/src/index.ts b/packages/encoder/src/index.ts
index 344b6d5..90a0a8f 100644
--- a/packages/encoder/src/index.ts
+++ b/packages/encoder/src/index.ts
@@ -7,6 +7,7 @@ export interface AudioAsset {
   startFrame: number;
   startFrom?: number;
   volume?: number;
+  isBgm?: boolean;
 }
 
 export interface EncodeOptions {
@@ -14,6 +15,7 @@ export interface EncodeOptions {
   fps: number;
   outputFile: string;
   audioAssets?: AudioAsset[];
+  durationInFrames?: number;
   onProgress?: (percent: number) => void;
 }
 
@@ -128,7 +130,7 @@ export const encodeWebP = ({ framesDir, fps, outputFile, width, height, onProgre
   });
 };
 
-export const encodeVideo = ({ framesDir, fps, outputFile, audioAssets = [], onProgress }: EncodeOptions) => {
+export const encodeVideo = ({ framesDir, fps, outputFile, audioAssets = [], durationInFrames, onProgress }: EncodeOptions) => {
   // Verify frames exist
   const files = fs.readdirSync(framesDir).filter(f => f.startsWith('frame-') && f.endsWith('.png'));
   if (files.length === 0) {
@@ -144,6 +146,12 @@ export const encodeVideo = ({ framesDir, fps, outputFile, audioAssets = [], onPr
     // Add audio inputs
     audioAssets.forEach(asset => {
       command.input(asset.src);
+
+      // For render-time BGM we loop the input so short tracks cover the full video.
+      // This is an input option and must be applied to the corresponding input.
+      if (asset.isBgm) {
+        command.inputOptions(['-stream_loop -1']);
+      }
     });
 
     const videoOptions = [
@@ -153,12 +161,20 @@ export const encodeVideo = ({ framesDir, fps, outputFile, audioAssets = [], onPr
     ];
 
     if (audioAssets.length > 0) {
+      const durationSec = durationInFrames ? (durationInFrames / fps) : undefined;
+
       const filters = audioAssets.map((asset, i) => {
         const delayMs = Math.round((asset.startFrame / fps) * 1000);
         const startFromSec = (asset.startFrom || 0) / fps;
         const volume = asset.volume ?? 1;
 
         // Use a more robust filter chain for each audio input
+        if (asset.isBgm) {
+          const delay = delayMs > 0 ? `,adelay=${delayMs}|${delayMs}` : '';
+          const trimEnd = durationSec != null ? `,atrim=end=${durationSec}` : '';
+          return `[${i + 1}:a]atrim=start=${startFromSec},asetpts=PTS-STARTPTS${delay}${trimEnd},volume=${volume}[a${i}]`;
+        }
+
         return `[${i + 1}:a]atrim=start=${startFromSec},asetpts=PTS-STARTPTS,adelay=${delayMs}|${delayMs},volume=${volume}[a${i}]`;
       });
 

From b9559675a24798f942d46ca52975071068cce277 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Fri, 27 Feb 2026 15:31:12 +0900
Subject: [PATCH 19/28] feat: add support for loading local fonts during render
 to fix text garbling

---
 README.ja.md                   |  6 +++
 README.md                      |  6 +++
 packages/cli/src/index.ts      | 34 +++++++++++-
 packages/renderer/src/index.ts | 98 ++++++++++++++++++++++++++++++++--
 4 files changed, 139 insertions(+), 5 deletions(-)

diff --git a/README.ja.md b/README.ja.md
index f2ff491..e704559 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -66,6 +66,11 @@ pnpm install -g @open-motion/cli @open-motion/renderer
 npx playwright install chromium
 ```
 
+Linuxのヘッドレス環境で日本語/中国語などが文字化けする場合は、フォントが入っていないことが原因です。
+
+- OSにフォントを入れる (推奨): `sudo apt-get update && sudo apt-get install -y fonts-noto-cjk`
+- もしくはレンダー時にローカルフォントを読み込む: `open-motion render ... --font "Noto Sans JP=./public/fonts/NotoSansJP-Regular.woff2"`
+
 ### 2. プロジェクトの作成
 ```bash
 open-motion init my-video
@@ -119,6 +124,7 @@ OPENAI_API_KEY=sk-...
 | `--public-dir <path>` | 静的アセットの公開ディレクトリ (デフォルト: `./public`) |
 | `--chromium-path <path>`| カスタムChromium実行ファイルのパス |
 | `--timeout <number>` | ブラウザ操作のタイムアウト (ミリ秒) |
+| `--font <spec>` | レンダー時にローカルフォントを読み込む（繰り返し指定可）。形式: `Family=path` または `path` |
 | `--bgm <path>` | ローカルのMP3ファイルをBGMとして追加 |
 | `--bgm-volume <number>` | BGM音量 (0.0-1.0, デフォルト: 1.0) |
 
diff --git a/README.md b/README.md
index 716e819..ac15abb 100644
--- a/README.md
+++ b/README.md
@@ -68,6 +68,11 @@ pnpm install -g @open-motion/cli @open-motion/renderer
 npx playwright install chromium
 ```
 
+If Japanese/Chinese/Korean text renders as squares in headless Linux, it's usually missing system fonts. Either install CJK fonts (recommended) or load a local font at render time.
+
+- Install system fonts (Ubuntu/Debian): `sudo apt-get update && sudo apt-get install -y fonts-noto-cjk`
+- Or load a local font file: `open-motion render ... --font "Noto Sans JP=./public/fonts/NotoSansJP-Regular.woff2"`
+
 ### 2. Create Project
 ```bash
 open-motion init my-video
@@ -141,6 +146,7 @@ Render a video from a running OpenMotion application.
 | `--public-dir <path>` | Public directory for static assets (default: `./public`) |
 | `--chromium-path <path>`| Path to custom Chromium executable |
 | `--timeout <number>` | Timeout for browser operations in ms |
+| `--font <spec>` | Load a local font file for rendering (repeatable). Format: `Family=path` or just `path` |
 | `--bgm <path>` | Add a background music track from a local MP3 file |
 | `--bgm-volume <number>` | BGM volume (0.0-1.0, default: 1.0) |
 
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index b92ae6b..0fbfdfb 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -1,4 +1,4 @@
-import { renderFrames, getCompositions } from '@open-motion/renderer';
+import { renderFrames, getCompositions, type RenderFont } from '@open-motion/renderer';
 import { chromium } from 'playwright';
 import { encodeVideo, encodeGif, encodeWebP } from '@open-motion/encoder';
 import path from 'path';
@@ -313,6 +313,7 @@ export const runRender = async (options: {
   timeout?: number;
   bgm?: string;
   bgmVolume?: number;
+  font?: string[];
 }) => {
   const timeout = options.timeout || parseInt(process.env.OPEN_MOTION_RENDER_TIMEOUT || '300000', 10);
 
@@ -323,6 +324,24 @@ export const runRender = async (options: {
   const inputProps = options.props ? JSON.parse(options.props) : {};
   const startTime = Date.now();
 
+  const parseFontSpecs = (specs?: string[]): RenderFont[] => {
+    if (!specs || specs.length === 0) return [];
+
+    return specs
+      .map((raw) => String(raw).trim())
+      .filter(Boolean)
+      .map((raw) => {
+        const eq = raw.indexOf('=');
+        if (eq === -1) {
+          return { family: 'OpenMotionFont', path: raw };
+        }
+        const family = raw.slice(0, eq).trim() || 'OpenMotionFont';
+        const p = raw.slice(eq + 1).trim();
+        return { family, path: p };
+      })
+      .filter((f) => Boolean(f.path));
+  };
+
   // Check for browser installation before starting
   try {
     chromium.executablePath();
@@ -393,7 +412,8 @@ export const runRender = async (options: {
     concurrency: options.concurrency || 1,
     publicDir: options.publicDir ? path.join(process.cwd(), options.publicDir) : undefined,
     onProgress: (frame) => renderBar.update(frame),
-    timeout
+    timeout,
+    fonts: parseFontSpecs(options.font),
   });
 
   renderBar.update(config.durationInFrames);
@@ -570,6 +590,15 @@ Example Usage:
     .option('--format <format>', 'Output format (mp4, webm, gif, webp, auto)', 'auto')
     .option('--chromium-path <path>', 'Custom path to Chromium executable')
     .option('--timeout <number>', 'Timeout for browser operations in milliseconds', parseInt)
+    .option(
+      '--font <spec>',
+      'Load a local font file for rendering (repeatable). Format: "Family=path" or just "path".',
+      (value, previous: string[] = []) => {
+        previous.push(value);
+        return previous;
+      },
+      [] as string[]
+    )
     .option('--bgm <path>', 'Path to an MP3 file to use as background music')
     .option('--bgm-volume <number>', 'BGM volume (0.0-1.0, default: 1.0)', parseFloat)
     .action(async (options) => {
@@ -588,6 +617,7 @@ Example Usage:
           format: options.format,
           chromiumPath: options.chromiumPath,
           timeout: options.timeout,
+          font: options.font,
           bgm: options.bgm,
           bgmVolume: options.bgmVolume,
         });
diff --git a/packages/renderer/src/index.ts b/packages/renderer/src/index.ts
index 5fbec6e..e95afb6 100644
--- a/packages/renderer/src/index.ts
+++ b/packages/renderer/src/index.ts
@@ -73,6 +73,16 @@ export interface RenderOptions {
   onProgress?: (frame: number) => void;
   publicDir?: string;
   timeout?: number;
+  fonts?: RenderFont[];
+}
+
+export interface RenderFont {
+  /** CSS font-family name to register (e.g. "Noto Sans JP") */
+  family: string;
+  /** Path to a local font file (woff2/woff/ttf/otf) */
+  path: string;
+  weight?: string | number;
+  style?: string;
 }
 
 export interface GetCompositionsOptions {
@@ -124,7 +134,23 @@ export const getCompositions = async (url: string, options: GetCompositionsOptio
   return processedCompositions;
 };
 
-export const renderFrames = async ({ url, config, outputDir, compositionId, inputProps = {}, concurrency = 1, publicDir, onProgress, timeout = 300000 }: RenderOptions) => {
+const getFontMimeAndFormat = (fontPath: string): { mime: string; format?: string } => {
+  const ext = path.extname(fontPath).toLowerCase();
+  switch (ext) {
+    case '.woff2':
+      return { mime: 'font/woff2', format: 'woff2' };
+    case '.woff':
+      return { mime: 'font/woff', format: 'woff' };
+    case '.ttf':
+      return { mime: 'font/ttf', format: 'truetype' };
+    case '.otf':
+      return { mime: 'font/otf', format: 'opentype' };
+    default:
+      return { mime: 'application/octet-stream' };
+  }
+};
+
+export const renderFrames = async ({ url, config, outputDir, compositionId, inputProps = {}, concurrency = 1, publicDir, onProgress, timeout = 300000, fonts = [] }: RenderOptions) => {
   if (!fs.existsSync(outputDir)) {
     fs.mkdirSync(outputDir, { recursive: true });
   }
@@ -149,15 +175,60 @@ export const renderFrames = async ({ url, config, outputDir, compositionId, inpu
     const workerAudioAssets: any[] = [];
     const videoCache = new Map<string, string>(); // Path to local resolved path
 
+    const fontPayloads = (fonts || []).flatMap((f) => {
+      const resolvedPath = path.isAbsolute(f.path) ? f.path : path.resolve(process.cwd(), f.path);
+      try {
+        const { mime, format } = getFontMimeAndFormat(resolvedPath);
+        const base64 = fs.readFileSync(resolvedPath, { encoding: 'base64' });
+        return [
+          {
+            family: f.family,
+            weight: f.weight,
+            style: f.style,
+            base64,
+            mime,
+            format,
+          },
+        ];
+      } catch (e) {
+        console.warn(`[open-motion] Failed to read font file: ${resolvedPath}`);
+        return [];
+      }
+    });
+
     for (let i = startFrame; i <= endFrame && i < config.durationInFrames; i++) {
       if (i === startFrame) {
-        await page.addInitScript(({ frame, fps, hijackScript, compositionId, inputProps }) => {
+        await page.addInitScript(({ frame, fps, hijackScript, compositionId, inputProps, fontPayloads }) => {
           (window as any).__OPEN_MOTION_FRAME__ = frame;
           (window as any).__OPEN_MOTION_COMPOSITION_ID__ = compositionId;
           (window as any).__OPEN_MOTION_INPUT_PROPS__ = inputProps;
           (window as any).__OPEN_MOTION_READY__ = false;
           (window as any).__OPEN_MOTION_VIDEO_FRAMES__ = {};
 
+          (window as any).__OPEN_MOTION_FONTS_READY__ = Promise.resolve();
+          if (fontPayloads && Array.isArray(fontPayloads) && 'fonts' in document) {
+            (window as any).__OPEN_MOTION_FONTS_READY__ = (async () => {
+              for (const f of fontPayloads) {
+                try {
+                  const src = `url(data:${f.mime};base64,${f.base64})${f.format ? ` format('${f.format}')` : ''}`;
+                  const face = new FontFace(f.family, src, {
+                    weight: f.weight ? String(f.weight) : undefined,
+                    style: f.style ? String(f.style) : undefined,
+                  });
+                  await face.load();
+                  (document as any).fonts.add(face);
+                } catch (e) {
+                  // ignore
+                }
+              }
+              try {
+                await (document as any).fonts.ready;
+              } catch (e) {
+                // ignore
+              }
+            })();
+          }
+
           // Execute hijack script
           const script = document.createElement('script');
           script.textContent = hijackScript;
@@ -173,7 +244,8 @@ export const renderFrames = async ({ url, config, outputDir, compositionId, inpu
           fps: config.fps,
           hijackScript: getTimeHijackScript(i, config.fps),
           compositionId,
-          inputProps
+          inputProps,
+          fontPayloads,
         });
 
         await page.goto(url);
@@ -234,6 +306,26 @@ export const renderFrames = async ({ url, config, outputDir, compositionId, inpu
       // Additional small wait to ensure style/layout stability
       await page.evaluate(() => new Promise(resolve => setTimeout(resolve, 150)));
 
+      // Ensure webfonts (if any) are loaded before screenshot
+      await page.evaluate(async () => {
+        try {
+          const p = (window as any).__OPEN_MOTION_FONTS_READY__;
+          if (p && typeof p.then === 'function') {
+            await p;
+          }
+        } catch (e) {
+          // ignore
+        }
+
+        try {
+          if ('fonts' in document) {
+            await (document as any).fonts.ready;
+          }
+        } catch (e) {
+          // ignore
+        }
+      });
+
       // Extract audio assets
       const assets = await page.evaluate(() => (window as any).__OPEN_MOTION_AUDIO_ASSETS__ || []);
       workerAudioAssets.push(...assets);

From 0b801581819ffca7b00c8ee9f1e2b547d2d54ee4 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Fri, 27 Feb 2026 22:34:33 +0900
Subject: [PATCH 20/28] docs: add building from source instructions and
 openrouter provider

---
 README.md | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index ac15abb..8ebb5b3 100644
--- a/README.md
+++ b/README.md
@@ -59,6 +59,17 @@ OpenMotion is a high-performance, open-source alternative to Remotion. It allows
 npm install @open-motion/core @open-motion/components
 ```
 
+## 🔧 Building from Source
+
+To build from source, you'll need [Node.js](https://nodejs.org/) and [pnpm](https://pnpm.io/).
+
+```bash
+git clone https://github.com/jsongo/open-motion.git
+cd open-motion
+pnpm install
+pnpm build
+```
+
 ## 🚀 Quick Start
 
 ### 1. Setup
@@ -99,7 +110,7 @@ Automatically generate video scenes and code from a text description using an LL
 
 | Option | Description |
 | :--- | :--- |
-| `--provider <name>` | LLM provider (`openai`, `anthropic`, `google`, `ollama`, `openai-compatible`) |
+| `--provider <name>` | LLM provider (`openai`, `anthropic`, `google`, `openrouter`, `ollama`, `openai-compatible`) |
 | `--model <name>` | Model name (e.g., `gpt-5.2`, `claude-4-6-sonnet`) |
 | `--scenes <number>` | Number of scenes to generate |
 | `--fps <number>` | Frames per second (default: 30) |

From 8cca14fe3f6605a7c0a4cbf9d1e1887934c5be01 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Sat, 28 Feb 2026 06:57:53 +0900
Subject: [PATCH 21/28] fix(cli): remove Unix-only chmod from build script for
 Windows compatibility

---
 packages/cli/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/cli/package.json b/packages/cli/package.json
index bd7022a..c0209fb 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -6,7 +6,7 @@
   },
   "license": "MIT",
   "scripts": {
-    "build": "tsc && chmod +x dist/bin.js"
+    "build": "tsc"
   },
   "repository": {
     "type": "git",

From 061ddd0c49e43be08d8d545ba1ea13487301c3c4 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Sat, 28 Feb 2026 14:50:36 +0900
Subject: [PATCH 22/28] docs: add Windows pnpm global link setup instructions

---
 README.md              | 13 +++++++++++++
 packages/cli/README.md | 13 +++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/README.md b/README.md
index 8ebb5b3..fe80ba4 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,19 @@ pnpm install
 pnpm build
 ```
 
+### Windows: Setting up pnpm global link
+
+If you want to use `pnpm link --global` on Windows, you may need to set up the global bin directory first:
+
+```powershell
+$env:PNPM_HOME = "C:\Users\<YourUser>\AppData\Local\pnpm"
+$env:PATH += ";$env:PNPM_HOME"
+cd packages/cli
+pnpm link --global
+```
+
+Alternatively, run `pnpm setup` and restart your terminal to apply the environment variables automatically.
+
 ## 🚀 Quick Start
 
 ### 1. Setup
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 50a72be..9af761c 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -19,6 +19,19 @@ npm install -g @open-motion/cli
 npx @open-motion/cli --help
 ```
 
+### Windows: Setting up pnpm global link
+
+If you're building from source and using `pnpm link --global` on Windows, you may need to set up the global bin directory first:
+
+```powershell
+$env:PNPM_HOME = "C:\Users\<YourUser>\AppData\Local\pnpm"
+$env:PATH += ";$env:PNPM_HOME"
+cd packages/cli
+pnpm link --global
+```
+
+Alternatively, run `pnpm setup` and restart your terminal to apply the environment variables automatically.
+
 ## 📖 Usage
 
 ### Initialize a project

From 25efdbcf1ca707cc92b51ce5e20b88b2c6567b20 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Sat, 28 Feb 2026 19:58:48 +0900
Subject: [PATCH 23/28] docs: update Quick Start to use my_videos workspace for
 video projects

---
 .gitignore          |   2 +-
 README.md           |  18 ++-
 pnpm-lock.yaml      | 319 ++++++++++++++++++++++++++++++++++++++++++++
 pnpm-workspace.yaml |   1 +
 4 files changed, 336 insertions(+), 4 deletions(-)

diff --git a/.gitignore b/.gitignore
index 3f986dd..4712e94 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,4 +17,4 @@ progress.md.worktrees/
 *.avi
 *.mkv
 *.webm
-video_projects
\ No newline at end of file
+my_videos
\ No newline at end of file
diff --git a/README.md b/README.md
index fe80ba4..f56ef52 100644
--- a/README.md
+++ b/README.md
@@ -99,18 +99,30 @@ If Japanese/Chinese/Korean text renders as squares in headless Linux, it's usual
 
 ### 2. Create Project
 ```bash
-open-motion init my-video
-cd my-video && pnpm install
+mkdir -p my_videos && cd my_videos
+open-motion init my-video1
+cd ../..  # Return to monorepo root
+pnpm install
 ```
 
 ### 3. Develop & Render
+
 Start the dev server in one terminal:
+
 ```bash
+cd my_videos/my-video1
 pnpm run dev
 ```
+
+or
+
+```bash
+pnpm --filter my-video1 dev
+```
+
 In another terminal, render your video using the server URL:
 ```bash
-open-motion render -u http://localhost:5173 -o out.mp4
+open-motion render -u http://localhost:5173 -o out.mp4 --composition my-video1
 ```
 
 ## 💻 CLI Reference
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0df376c..b04d7ac 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -80,6 +80,28 @@ importers:
         specifier: ^5.0.0
         version: 5.4.21(@types/node@25.2.0)
 
+  my_videos/v1:
+    dependencies:
+      '@open-motion/core':
+        specifier: latest
+        version: 0.1.9(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
+      react-dom:
+        specifier: ^18.2.0
+        version: 18.3.1(react@18.3.1)
+    devDependencies:
+      '@vitejs/plugin-react':
+        specifier: ^4.0.0
+        version: 4.7.0(vite@4.5.14(@types/node@25.2.0))
+      typescript:
+        specifier: ^5.0.0
+        version: 5.9.3
+      vite:
+        specifier: ^4.4.0
+        version: 4.5.14(@types/node@25.2.0)
+
   packages/cli:
     dependencies:
       '@ai-sdk/anthropic':
@@ -359,132 +381,264 @@ packages:
     cpu: [ppc64]
     os: [aix]
 
+  '@esbuild/android-arm64@0.18.20':
+    resolution: {integrity: sha512-Nz4rJcchGDtENV0eMKUNa6L12zz2zBDXuhj/Vjh18zGqB44Bi7MBMSXjgunJgjRhCmKOjnPuZp4Mb6OKqtMHLQ==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [android]
+
   '@esbuild/android-arm64@0.21.5':
     resolution: {integrity: sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==}
     engines: {node: '>=12'}
     cpu: [arm64]
     os: [android]
 
+  '@esbuild/android-arm@0.18.20':
+    resolution: {integrity: sha512-fyi7TDI/ijKKNZTUJAQqiG5T7YjJXgnzkURqmGj13C6dCqckZBLdl4h7bkhHt/t0WP+zO9/zwroDvANaOqO5Sw==}
+    engines: {node: '>=12'}
+    cpu: [arm]
+    os: [android]
+
   '@esbuild/android-arm@0.21.5':
     resolution: {integrity: sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==}
     engines: {node: '>=12'}
     cpu: [arm]
     os: [android]
 
+  '@esbuild/android-x64@0.18.20':
+    resolution: {integrity: sha512-8GDdlePJA8D6zlZYJV/jnrRAi6rOiNaCC/JclcXpB+KIuvfBN4owLtgzY2bsxnx666XjJx2kDPUmnTtR8qKQUg==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [android]
+
   '@esbuild/android-x64@0.21.5':
     resolution: {integrity: sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [android]
 
+  '@esbuild/darwin-arm64@0.18.20':
+    resolution: {integrity: sha512-bxRHW5kHU38zS2lPTPOyuyTm+S+eobPUnTNkdJEfAddYgEcll4xkT8DB9d2008DtTbl7uJag2HuE5NZAZgnNEA==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [darwin]
+
   '@esbuild/darwin-arm64@0.21.5':
     resolution: {integrity: sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==}
     engines: {node: '>=12'}
     cpu: [arm64]
     os: [darwin]
 
+  '@esbuild/darwin-x64@0.18.20':
+    resolution: {integrity: sha512-pc5gxlMDxzm513qPGbCbDukOdsGtKhfxD1zJKXjCCcU7ju50O7MeAZ8c4krSJcOIJGFR+qx21yMMVYwiQvyTyQ==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [darwin]
+
   '@esbuild/darwin-x64@0.21.5':
     resolution: {integrity: sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [darwin]
 
+  '@esbuild/freebsd-arm64@0.18.20':
+    resolution: {integrity: sha512-yqDQHy4QHevpMAaxhhIwYPMv1NECwOvIpGCZkECn8w2WFHXjEwrBn3CeNIYsibZ/iZEUemj++M26W3cNR5h+Tw==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [freebsd]
+
   '@esbuild/freebsd-arm64@0.21.5':
     resolution: {integrity: sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==}
     engines: {node: '>=12'}
     cpu: [arm64]
     os: [freebsd]
 
+  '@esbuild/freebsd-x64@0.18.20':
+    resolution: {integrity: sha512-tgWRPPuQsd3RmBZwarGVHZQvtzfEBOreNuxEMKFcd5DaDn2PbBxfwLcj4+aenoh7ctXcbXmOQIn8HI6mCSw5MQ==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [freebsd]
+
   '@esbuild/freebsd-x64@0.21.5':
     resolution: {integrity: sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [freebsd]
 
+  '@esbuild/linux-arm64@0.18.20':
+    resolution: {integrity: sha512-2YbscF+UL7SQAVIpnWvYwM+3LskyDmPhe31pE7/aoTMFKKzIc9lLbyGUpmmb8a8AixOL61sQ/mFh3jEjHYFvdA==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [linux]
+
   '@esbuild/linux-arm64@0.21.5':
     resolution: {integrity: sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==}
     engines: {node: '>=12'}
     cpu: [arm64]
     os: [linux]
 
+  '@esbuild/linux-arm@0.18.20':
+    resolution: {integrity: sha512-/5bHkMWnq1EgKr1V+Ybz3s1hWXok7mDFUMQ4cG10AfW3wL02PSZi5kFpYKrptDsgb2WAJIvRcDm+qIvXf/apvg==}
+    engines: {node: '>=12'}
+    cpu: [arm]
+    os: [linux]
+
   '@esbuild/linux-arm@0.21.5':
     resolution: {integrity: sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==}
     engines: {node: '>=12'}
     cpu: [arm]
     os: [linux]
 
+  '@esbuild/linux-ia32@0.18.20':
+    resolution: {integrity: sha512-P4etWwq6IsReT0E1KHU40bOnzMHoH73aXp96Fs8TIT6z9Hu8G6+0SHSw9i2isWrD2nbx2qo5yUqACgdfVGx7TA==}
+    engines: {node: '>=12'}
+    cpu: [ia32]
+    os: [linux]
+
   '@esbuild/linux-ia32@0.21.5':
     resolution: {integrity: sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==}
     engines: {node: '>=12'}
     cpu: [ia32]
     os: [linux]
 
+  '@esbuild/linux-loong64@0.18.20':
+    resolution: {integrity: sha512-nXW8nqBTrOpDLPgPY9uV+/1DjxoQ7DoB2N8eocyq8I9XuqJ7BiAMDMf9n1xZM9TgW0J8zrquIb/A7s3BJv7rjg==}
+    engines: {node: '>=12'}
+    cpu: [loong64]
+    os: [linux]
+
   '@esbuild/linux-loong64@0.21.5':
     resolution: {integrity: sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==}
     engines: {node: '>=12'}
     cpu: [loong64]
     os: [linux]
 
+  '@esbuild/linux-mips64el@0.18.20':
+    resolution: {integrity: sha512-d5NeaXZcHp8PzYy5VnXV3VSd2D328Zb+9dEq5HE6bw6+N86JVPExrA6O68OPwobntbNJ0pzCpUFZTo3w0GyetQ==}
+    engines: {node: '>=12'}
+    cpu: [mips64el]
+    os: [linux]
+
   '@esbuild/linux-mips64el@0.21.5':
     resolution: {integrity: sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==}
     engines: {node: '>=12'}
     cpu: [mips64el]
     os: [linux]
 
+  '@esbuild/linux-ppc64@0.18.20':
+    resolution: {integrity: sha512-WHPyeScRNcmANnLQkq6AfyXRFr5D6N2sKgkFo2FqguP44Nw2eyDlbTdZwd9GYk98DZG9QItIiTlFLHJHjxP3FA==}
+    engines: {node: '>=12'}
+    cpu: [ppc64]
+    os: [linux]
+
   '@esbuild/linux-ppc64@0.21.5':
     resolution: {integrity: sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==}
     engines: {node: '>=12'}
     cpu: [ppc64]
     os: [linux]
 
+  '@esbuild/linux-riscv64@0.18.20':
+    resolution: {integrity: sha512-WSxo6h5ecI5XH34KC7w5veNnKkju3zBRLEQNY7mv5mtBmrP/MjNBCAlsM2u5hDBlS3NGcTQpoBvRzqBcRtpq1A==}
+    engines: {node: '>=12'}
+    cpu: [riscv64]
+    os: [linux]
+
   '@esbuild/linux-riscv64@0.21.5':
     resolution: {integrity: sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==}
     engines: {node: '>=12'}
     cpu: [riscv64]
     os: [linux]
 
+  '@esbuild/linux-s390x@0.18.20':
+    resolution: {integrity: sha512-+8231GMs3mAEth6Ja1iK0a1sQ3ohfcpzpRLH8uuc5/KVDFneH6jtAJLFGafpzpMRO6DzJ6AvXKze9LfFMrIHVQ==}
+    engines: {node: '>=12'}
+    cpu: [s390x]
+    os: [linux]
+
   '@esbuild/linux-s390x@0.21.5':
     resolution: {integrity: sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==}
     engines: {node: '>=12'}
     cpu: [s390x]
     os: [linux]
 
+  '@esbuild/linux-x64@0.18.20':
+    resolution: {integrity: sha512-UYqiqemphJcNsFEskc73jQ7B9jgwjWrSayxawS6UVFZGWrAAtkzjxSqnoclCXxWtfwLdzU+vTpcNYhpn43uP1w==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [linux]
+
   '@esbuild/linux-x64@0.21.5':
     resolution: {integrity: sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [linux]
 
+  '@esbuild/netbsd-x64@0.18.20':
+    resolution: {integrity: sha512-iO1c++VP6xUBUmltHZoMtCUdPlnPGdBom6IrO4gyKPFFVBKioIImVooR5I83nTew5UOYrk3gIJhbZh8X44y06A==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [netbsd]
+
   '@esbuild/netbsd-x64@0.21.5':
     resolution: {integrity: sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [netbsd]
 
+  '@esbuild/openbsd-x64@0.18.20':
+    resolution: {integrity: sha512-e5e4YSsuQfX4cxcygw/UCPIEP6wbIL+se3sxPdCiMbFLBWu0eiZOJ7WoD+ptCLrmjZBK1Wk7I6D/I3NglUGOxg==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [openbsd]
+
   '@esbuild/openbsd-x64@0.21.5':
     resolution: {integrity: sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [openbsd]
 
+  '@esbuild/sunos-x64@0.18.20':
+    resolution: {integrity: sha512-kDbFRFp0YpTQVVrqUd5FTYmWo45zGaXe0X8E1G/LKFC0v8x0vWrhOWSLITcCn63lmZIxfOMXtCfti/RxN/0wnQ==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [sunos]
+
   '@esbuild/sunos-x64@0.21.5':
     resolution: {integrity: sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [sunos]
 
+  '@esbuild/win32-arm64@0.18.20':
+    resolution: {integrity: sha512-ddYFR6ItYgoaq4v4JmQQaAI5s7npztfV4Ag6NrhiaW0RrnOXqBkgwZLofVTlq1daVTQNhtI5oieTvkRPfZrePg==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [win32]
+
   '@esbuild/win32-arm64@0.21.5':
     resolution: {integrity: sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==}
     engines: {node: '>=12'}
     cpu: [arm64]
     os: [win32]
 
+  '@esbuild/win32-ia32@0.18.20':
+    resolution: {integrity: sha512-Wv7QBi3ID/rROT08SABTS7eV4hX26sVduqDOTe1MvGMjNd3EjOz4b7zeexIR62GTIEKrfJXKL9LFxTYgkyeu7g==}
+    engines: {node: '>=12'}
+    cpu: [ia32]
+    os: [win32]
+
   '@esbuild/win32-ia32@0.21.5':
     resolution: {integrity: sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==}
     engines: {node: '>=12'}
     cpu: [ia32]
     os: [win32]
 
+  '@esbuild/win32-x64@0.18.20':
+    resolution: {integrity: sha512-kTdfRcSiDfQca/y9QIkng02avJ+NCaQvrMejlsB3RRv5sE9rRoeBPISaZpKxHELzRxZyLvNts1P27W3wV+8geQ==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [win32]
+
   '@esbuild/win32-x64@0.21.5':
     resolution: {integrity: sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==}
     engines: {node: '>=12'}
@@ -538,6 +692,12 @@ packages:
     resolution: {directory: packages/cli, type: directory}
     hasBin: true
 
+  '@open-motion/core@0.1.9':
+    resolution: {integrity: sha512-TdHxUAigWWdM3GRvHfT6hvMDyatlisRboOjVAWrVRHMVrvyRYWN/NswWbEIIf9nLN7P4N9BNX51nEmQEgc7+xg==}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
   '@open-motion/renderer@file:packages/renderer':
     resolution: {directory: packages/renderer, type: directory}
     peerDependencies:
@@ -920,6 +1080,11 @@ packages:
     resolution: {integrity: sha512-rRqJg/6gd538VHvR3PSrdRBb/1Vy2YfzHqzvbhGIQpDRKIa4FgV/54b5Q1xYSxOOwKvjXweS26E0Q+nAMwp2pQ==}
     engines: {node: '>=8.6'}
 
+  esbuild@0.18.20:
+    resolution: {integrity: sha512-ceqxoedUrcayh7Y7ZX6NdbbDzGROiyVBgC4PriJThBKSVPWnnFHZAkfI1lJT8QFkOwH4qOS2SJkS4wvpGl8BpA==}
+    engines: {node: '>=12'}
+    hasBin: true
+
   esbuild@0.21.5:
     resolution: {integrity: sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==}
     engines: {node: '>=12'}
@@ -1320,6 +1485,11 @@ packages:
   rfdc@1.4.1:
     resolution: {integrity: sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==}
 
+  rollup@3.30.0:
+    resolution: {integrity: sha512-kQvGasUgN+AlWGliFn2POSajRQEsULVYFGTvOZmK06d7vCD+YhZztt70kGk3qaeAXeWYL5eO7zx+rAubBc55eA==}
+    engines: {node: '>=14.18.0', npm: '>=8.0.0'}
+    hasBin: true
+
   rollup@4.57.1:
     resolution: {integrity: sha512-oQL6lgK3e2QZeQ7gcgIkS2YZPg5slw37hYufJ3edKlfQSGGm8ICoxswK15ntSzF/a8+h7ekRy7k7oWc3BQ7y8A==}
     engines: {node: '>=18.0.0', npm: '>=8.0.0'}
@@ -1492,6 +1662,34 @@ packages:
     peerDependencies:
       react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
+  vite@4.5.14:
+    resolution: {integrity: sha512-+v57oAaoYNnO3hIu5Z/tJRZjq5aHM2zDve9YZ8HngVHbhk66RStobhb1sqPMIPEleV6cNKYK4eGrAbE9Ulbl2g==}
+    engines: {node: ^14.18.0 || >=16.0.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': '>= 14'
+      less: '*'
+      lightningcss: ^1.21.0
+      sass: '*'
+      stylus: '*'
+      sugarss: '*'
+      terser: ^5.4.0
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      less:
+        optional: true
+      lightningcss:
+        optional: true
+      sass:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+
   vite@5.4.21:
     resolution: {integrity: sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==}
     engines: {node: ^18.0.0 || >=20.0.0}
@@ -1862,69 +2060,135 @@ snapshots:
   '@esbuild/aix-ppc64@0.21.5':
     optional: true
 
+  '@esbuild/android-arm64@0.18.20':
+    optional: true
+
   '@esbuild/android-arm64@0.21.5':
     optional: true
 
+  '@esbuild/android-arm@0.18.20':
+    optional: true
+
   '@esbuild/android-arm@0.21.5':
     optional: true
 
+  '@esbuild/android-x64@0.18.20':
+    optional: true
+
   '@esbuild/android-x64@0.21.5':
     optional: true
 
+  '@esbuild/darwin-arm64@0.18.20':
+    optional: true
+
   '@esbuild/darwin-arm64@0.21.5':
     optional: true
 
+  '@esbuild/darwin-x64@0.18.20':
+    optional: true
+
   '@esbuild/darwin-x64@0.21.5':
     optional: true
 
+  '@esbuild/freebsd-arm64@0.18.20':
+    optional: true
+
   '@esbuild/freebsd-arm64@0.21.5':
     optional: true
 
+  '@esbuild/freebsd-x64@0.18.20':
+    optional: true
+
   '@esbuild/freebsd-x64@0.21.5':
     optional: true
 
+  '@esbuild/linux-arm64@0.18.20':
+    optional: true
+
   '@esbuild/linux-arm64@0.21.5':
     optional: true
 
+  '@esbuild/linux-arm@0.18.20':
+    optional: true
+
   '@esbuild/linux-arm@0.21.5':
     optional: true
 
+  '@esbuild/linux-ia32@0.18.20':
+    optional: true
+
   '@esbuild/linux-ia32@0.21.5':
     optional: true
 
+  '@esbuild/linux-loong64@0.18.20':
+    optional: true
+
   '@esbuild/linux-loong64@0.21.5':
     optional: true
 
+  '@esbuild/linux-mips64el@0.18.20':
+    optional: true
+
   '@esbuild/linux-mips64el@0.21.5':
     optional: true
 
+  '@esbuild/linux-ppc64@0.18.20':
+    optional: true
+
   '@esbuild/linux-ppc64@0.21.5':
     optional: true
 
+  '@esbuild/linux-riscv64@0.18.20':
+    optional: true
+
   '@esbuild/linux-riscv64@0.21.5':
     optional: true
 
+  '@esbuild/linux-s390x@0.18.20':
+    optional: true
+
   '@esbuild/linux-s390x@0.21.5':
     optional: true
 
+  '@esbuild/linux-x64@0.18.20':
+    optional: true
+
   '@esbuild/linux-x64@0.21.5':
     optional: true
 
+  '@esbuild/netbsd-x64@0.18.20':
+    optional: true
+
   '@esbuild/netbsd-x64@0.21.5':
     optional: true
 
+  '@esbuild/openbsd-x64@0.18.20':
+    optional: true
+
   '@esbuild/openbsd-x64@0.21.5':
     optional: true
 
+  '@esbuild/sunos-x64@0.18.20':
+    optional: true
+
   '@esbuild/sunos-x64@0.21.5':
     optional: true
 
+  '@esbuild/win32-arm64@0.18.20':
+    optional: true
+
   '@esbuild/win32-arm64@0.21.5':
     optional: true
 
+  '@esbuild/win32-ia32@0.18.20':
+    optional: true
+
   '@esbuild/win32-ia32@0.21.5':
     optional: true
 
+  '@esbuild/win32-x64@0.18.20':
+    optional: true
+
   '@esbuild/win32-x64@0.21.5':
     optional: true
 
@@ -2002,6 +2266,11 @@ snapshots:
       - react
       - zod
 
+  '@open-motion/core@0.1.9(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
   '@open-motion/renderer@file:packages/renderer(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@open-motion/core': link:packages/core
@@ -2156,6 +2425,18 @@ snapshots:
 
   '@types/webxr@0.5.24': {}
 
+  '@vitejs/plugin-react@4.7.0(vite@4.5.14(@types/node@25.2.0))':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.29.0)
+      '@babel/plugin-transform-react-jsx-source': 7.27.1(@babel/core@7.29.0)
+      '@rolldown/pluginutils': 1.0.0-beta.27
+      '@types/babel__core': 7.20.5
+      react-refresh: 0.17.0
+      vite: 4.5.14(@types/node@25.2.0)
+    transitivePeerDependencies:
+      - supports-color
+
   '@vitejs/plugin-react@4.7.0(vite@5.4.21(@types/node@25.2.0))':
     dependencies:
       '@babel/core': 7.29.0
@@ -2309,6 +2590,31 @@ snapshots:
       ansi-colors: 4.1.3
       strip-ansi: 6.0.1
 
+  esbuild@0.18.20:
+    optionalDependencies:
+      '@esbuild/android-arm': 0.18.20
+      '@esbuild/android-arm64': 0.18.20
+      '@esbuild/android-x64': 0.18.20
+      '@esbuild/darwin-arm64': 0.18.20
+      '@esbuild/darwin-x64': 0.18.20
+      '@esbuild/freebsd-arm64': 0.18.20
+      '@esbuild/freebsd-x64': 0.18.20
+      '@esbuild/linux-arm': 0.18.20
+      '@esbuild/linux-arm64': 0.18.20
+      '@esbuild/linux-ia32': 0.18.20
+      '@esbuild/linux-loong64': 0.18.20
+      '@esbuild/linux-mips64el': 0.18.20
+      '@esbuild/linux-ppc64': 0.18.20
+      '@esbuild/linux-riscv64': 0.18.20
+      '@esbuild/linux-s390x': 0.18.20
+      '@esbuild/linux-x64': 0.18.20
+      '@esbuild/netbsd-x64': 0.18.20
+      '@esbuild/openbsd-x64': 0.18.20
+      '@esbuild/sunos-x64': 0.18.20
+      '@esbuild/win32-arm64': 0.18.20
+      '@esbuild/win32-ia32': 0.18.20
+      '@esbuild/win32-x64': 0.18.20
+
   esbuild@0.21.5:
     optionalDependencies:
       '@esbuild/aix-ppc64': 0.21.5
@@ -2678,6 +2984,10 @@ snapshots:
 
   rfdc@1.4.1: {}
 
+  rollup@3.30.0:
+    optionalDependencies:
+      fsevents: 2.3.3
+
   rollup@4.57.1:
     dependencies:
       '@types/estree': 1.0.8
@@ -2842,6 +3152,15 @@ snapshots:
     dependencies:
       react: 18.3.1
 
+  vite@4.5.14(@types/node@25.2.0):
+    dependencies:
+      esbuild: 0.18.20
+      postcss: 8.5.6
+      rollup: 3.30.0
+    optionalDependencies:
+      '@types/node': 25.2.0
+      fsevents: 2.3.3
+
   vite@5.4.21(@types/node@25.2.0):
     dependencies:
       esbuild: 0.21.5
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 89723f9..4913bf5 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,3 +1,4 @@
 packages:
   - "packages/*"
   - "examples/*"
+  - "my_videos/*"

From 3668dfa0042f978a9a94ea3f1ab730240b931a63 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Sat, 28 Feb 2026 19:59:41 +0900
Subject: [PATCH 24/28] chore: simplify .env.example by removing redundant env
 vars

---
 .env.example | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/.env.example b/.env.example
index 807bb3c..2addcd4 100644
--- a/.env.example
+++ b/.env.example
@@ -2,7 +2,7 @@
 # Copy this file to .env and fill in your API keys.
 # .env is listed in .gitignore and will NOT be committed to version control.
 
-# --- LLM Provider (optional, defaults to "openai") ---
+# --- LLM Provider for the 'generate' command (optional, defaults to "openai") ---
 # OPEN_MOTION_PROVIDER=openai
 # OPEN_MOTION_PROVIDER=openrouter
 
@@ -15,14 +15,12 @@
 
 # --- OpenRouter ---
 # OPENROUTER_API_KEY=sk-or-...
-# OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
 
 # --- Anthropic ---
 # ANTHROPIC_API_KEY=sk-ant-...
 
 # --- Google / Gemini ---
 # GOOGLE_API_KEY=...
-# GEMINI_API_KEY=...
 
 # --- OpenAI-compatible providers (e.g. Azure, Groq, local OpenAI-proxy) ---
 # OPEN_MOTION_API_KEY=...

From d84d90edfca2d823b80630be32fc34c2f9caee32 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Sat, 28 Feb 2026 21:11:31 +0900
Subject: [PATCH 25/28] feat: add VIDEO_* env vars for video settings and
 update docs

- Add VIDEO_FPS, VIDEO_WIDTH, VIDEO_HEIGHT env vars for generate command
- Priority: CLI options > env vars > hard-coded defaults
- Update README translations (zh, ja) to reflect current features
- Add AI-powered generation and AI-assisted editing features to docs
- Add building from source and Windows pnpm setup instructions
---
 .env.example                          |  5 ++
 README.ja.md                          | 75 ++++++++++++++++++++---
 README.md                             |  5 +-
 README.zh.md                          | 87 +++++++++++++++++++++++++--
 packages/cli/README.md                |  8 +++
 packages/cli/src/bin.ts               | 12 +++-
 packages/cli/src/commands/edit.ts     |  4 --
 packages/cli/src/commands/generate.ts | 19 +++---
 packages/cli/src/index.ts             | 33 +++-------
 packages/cli/src/llm/config.ts        | 13 +---
 10 files changed, 199 insertions(+), 62 deletions(-)

diff --git a/.env.example b/.env.example
index 2addcd4..409493e 100644
--- a/.env.example
+++ b/.env.example
@@ -25,3 +25,8 @@
 # --- OpenAI-compatible providers (e.g. Azure, Groq, local OpenAI-proxy) ---
 # OPEN_MOTION_API_KEY=...
 # OPEN_MOTION_BASE_URL=https://your-custom-endpoint/v1
+
+# --- Video settings for generate command ---
+# VIDEO_FPS=30
+# VIDEO_WIDTH=1280
+# VIDEO_HEIGHT=720
diff --git a/README.ja.md b/README.ja.md
index e704559..cfe5a2c 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -31,6 +31,8 @@ OpenMotionは、Remotionに代わる高性能なオープンソースの選択
 ## ✨ 機能
 
 - ⚛️ **Reactファースト**: Reactエコシステムのパワーを最大限に活用。
+- 🤖 **AI駆動の生成**: LLMを使用してテキスト記述から完全なビデオを作成。
+- ✍️ **AIアシスト編集**: 自然言語を使用してTSXシーンを編集。
 - ⏱️ **フレーム精度の決定論**: 高度なタイムジャック技術により、すべてのフレームが同一であることを保証。
 - 🚀 **並列レンダリング**: すべてのCPUコアを利用してレンダリング速度をスケール。
 - 🎵 **マルチトラック・オーディオミキシング**: 独立した音量制御を持つ複数の `<Audio />` をサポート。
@@ -57,6 +59,30 @@ OpenMotionは、Remotionに代わる高性能なオープンソースの選択
 npm install @open-motion/core @open-motion/components
 ```
 
+## 🔧 ソースからのビルド
+
+ソースからビルドするには、[Node.js](https://nodejs.org/) と [pnpm](https://pnpm.io/) が必要です。
+
+```bash
+git clone https://github.com/jsongo/open-motion.git
+cd open-motion
+pnpm install
+pnpm build
+```
+
+### Windows: pnpm グローバルリンクの設定
+
+Windowsで `pnpm link --global` を使用する場合、先にグローバルbinディレクトリを設定する必要がある場合があります：
+
+```powershell
+$env:PNPM_HOME = "C:\Users\<YourUser>\AppData\Local\pnpm"
+$env:PATH += ";$env:PNPM_HOME"
+cd packages/cli
+pnpm link --global
+```
+
+または、`pnpm setup` を実行してターミナルを再起動すると、環境変数が自動的に適用されます。
+
 ## 🚀 クイックスタート
 
 ### 1. セットアップ
@@ -66,25 +92,37 @@ pnpm install -g @open-motion/cli @open-motion/renderer
 npx playwright install chromium
 ```
 
-Linuxのヘッドレス環境で日本語/中国語などが文字化けする場合は、フォントが入っていないことが原因です。
+Linuxのヘッドレス環境で日本語/中国語などが文字化けする場合は、フォントが入っていないことが原因です。システムフォントをインストールする（推奨）か、レンダー時にローカルフォントを読み込んでください。
 
-- OSにフォントを入れる (推奨): `sudo apt-get update && sudo apt-get install -y fonts-noto-cjk`
-- もしくはレンダー時にローカルフォントを読み込む: `open-motion render ... --font "Noto Sans JP=./public/fonts/NotoSansJP-Regular.woff2"`
+- システムフォントをインストール (Ubuntu/Debian): `sudo apt-get update && sudo apt-get install -y fonts-noto-cjk`
+- またはローカルフォントを読み込む: `open-motion render ... --font "Noto Sans JP=./public/fonts/NotoSansJP-Regular.woff2"`
 
 ### 2. プロジェクトの作成
 ```bash
-open-motion init my-video
-cd my-video && pnpm install
+mkdir -p my_videos && cd my_videos
+open-motion init my-video1
+cd ../..  # monorepoのルートに戻る
+pnpm install
 ```
 
 ### 3. 開発とレンダリング
+
 ターミナルで開発サーバーを起動します：
+
 ```bash
+cd my_videos/my-video1
 pnpm run dev
 ```
+
+または
+
+```bash
+pnpm --filter my-video1 dev
+```
+
 別のターミナルで、サーバーのURLを使用してビデオをレンダリングします：
 ```bash
-open-motion render -u http://localhost:5173 -o out.mp4
+open-motion render -u http://localhost:5173 -o out.mp4 --composition my-video1
 ```
 
 ## 💻 CLI リファレンス
@@ -92,17 +130,38 @@ open-motion render -u http://localhost:5173 -o out.mp4
 ### `open-motion init <name>`
 事前設定されたReactテンプレートを使用して、新しいOpenMotionプロジェクトを初期化します。
 
+### `open-motion generate <description>`
+LLMを使用してテキスト記述からビデオシーンとコードを自動生成します。
+
+| オプション | 説明 |
+| :--- | :--- |
+| `--env <path>` | .envファイルのパス (デフォルト: カレントディレクトリの .env) |
+| `--scenes <number>` | 生成するシーン数 |
+| `--fps <number>` | フレームレート (デフォルト: 30) |
+| `--width <number>` | ビデオ幅 (デフォルト: 1280) |
+| `--height <number>` | ビデオ高さ (デフォルト: 720) |
+
+### `open-motion edit <file>`
+自然言語の指示を使用してTSXシーンファイルを編集します。
+
+| オプション | 説明 |
+| :--- | :--- |
+| `--env <path>` | .envファイルのパス (デフォルト: カレントディレクトリの .env) |
+| `-m, --message <msg>` | 編集指示 |
+| `-y, --yes` | 変更を自動適用 (ワンショットモード) |
+
 ### `open-motion config`
-LLMの設定（APIキー、モデルなど）を管理します。
+LLMプロバイダーの設定（APIキー、モデル）を管理します。
 
 - `open-motion config list`
 - `open-motion config get <VAR>`
 
-設定は環境変数から読み込まれます（プロジェクト直下の `.env` に置けます）：
+LLM設定は環境変数から読み込まれます（プロジェクトローカルの `.env` ファイルに記述できます）：
 
 ```bash
 # .env
 OPEN_MOTION_PROVIDER=openai
+OPEN_MOTION_MODEL=gpt-5.1
 OPENAI_API_KEY=sk-...
 ```
 
diff --git a/README.md b/README.md
index f56ef52..bef9226 100644
--- a/README.md
+++ b/README.md
@@ -135,8 +135,7 @@ Automatically generate video scenes and code from a text description using an LL
 
 | Option | Description |
 | :--- | :--- |
-| `--provider <name>` | LLM provider (`openai`, `anthropic`, `google`, `openrouter`, `ollama`, `openai-compatible`) |
-| `--model <name>` | Model name (e.g., `gpt-5.2`, `claude-4-6-sonnet`) |
+| `--env <path>` | Path to .env file (default: .env in current directory) |
 | `--scenes <number>` | Number of scenes to generate |
 | `--fps <number>` | Frames per second (default: 30) |
 | `--width <number>` | Video width (default: 1280) |
@@ -147,6 +146,7 @@ Edit a TSX scene file using natural language instructions.
 
 | Option | Description |
 | :--- | :--- |
+| `--env <path>` | Path to .env file (default: .env in current directory) |
 | `-m, --message <msg>` | Instruction for editing |
 | `-y, --yes` | Auto-apply changes (one-shot mode) |
 
@@ -161,6 +161,7 @@ LLM settings are read from environment variables (you can put them in a project-
 ```bash
 # .env
 OPEN_MOTION_PROVIDER=openai
+OPEN_MOTION_MODEL=gpt-5.1
 OPENAI_API_KEY=sk-...
 ```
 
diff --git a/README.zh.md b/README.zh.md
index df76e48..d51308d 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -31,6 +31,8 @@ OpenMotion 是 Remotion 的高性能开源替代方案。它允许你使用熟
 ## ✨ 特性
 
 - ⚛️ **React 优先**: 充分利用 React 生态系统的全部力量。
+- 🤖 **AI 驱动生成**: 使用 LLM 从文本描述创建完整视频。
+- ✍️ **AI 辅助编辑**: 使用自然语言编辑 TSX 场景。
 - ⏱️ **帧准确的确定性**: 先进的时间劫持技术确保每一帧都完全一致。
 - 🚀 **并行渲染**: 通过利用所有 CPU 核心来提升渲染速度。
 - 🎵 **多轨音频混合**: 支持多个 `<Audio />` 且具有独立音量控制。
@@ -57,6 +59,30 @@ OpenMotion 是 Remotion 的高性能开源替代方案。它允许你使用熟
 npm install @open-motion/core @open-motion/components
 ```
 
+## 🔧 从源码构建
+
+从源码构建需要 [Node.js](https://nodejs.org/) 和 [pnpm](https://pnpm.io/)。
+
+```bash
+git clone https://github.com/jsongo/open-motion.git
+cd open-motion
+pnpm install
+pnpm build
+```
+
+### Windows: 设置 pnpm 全局链接
+
+如果要在 Windows 上使用 `pnpm link --global`，可能需要先设置全局 bin 目录：
+
+```powershell
+$env:PNPM_HOME = "C:\Users\<YourUser>\AppData\Local\pnpm"
+$env:PATH += ";$env:PNPM_HOME"
+cd packages/cli
+pnpm link --global
+```
+
+或者运行 `pnpm setup` 并重启终端以自动应用环境变量。
+
 ## 🚀 快速开始
 
 ### 1. 设置
@@ -66,20 +92,37 @@ pnpm install -g @open-motion/cli @open-motion/renderer
 npx playwright install chromium
 ```
 
+如果在 Linux 无头环境中日文/中文/韩文显示为方块，通常是因为缺少系统字体。可以安装 CJK 字体（推荐）或在渲染时加载本地字体。
+
+- 安装系统字体 (Ubuntu/Debian): `sudo apt-get update && sudo apt-get install -y fonts-noto-cjk`
+- 或加载本地字体文件: `open-motion render ... --font "Noto Sans JP=./public/fonts/NotoSansJP-Regular.woff2"`
+
 ### 2. 创建项目
 ```bash
-open-motion init my-video
-cd my-video && pnpm install
+mkdir -p my_videos && cd my_videos
+open-motion init my-video1
+cd ../..  # 返回 monorepo 根目录
+pnpm install
 ```
 
 ### 3. 开发与渲染
+
 在一个终端中启动开发服务器：
+
 ```bash
+cd my_videos/my-video1
 pnpm run dev
 ```
+
+或
+
+```bash
+pnpm --filter my-video1 dev
+```
+
 在另一个终端中，使用服务器 URL 渲染视频：
 ```bash
-open-motion render -u http://localhost:5173 -o out.mp4
+open-motion render -u http://localhost:5173 -o out.mp4 --composition my-video1
 ```
 
 ## 💻 CLI 参考
@@ -87,17 +130,38 @@ open-motion render -u http://localhost:5173 -o out.mp4
 ### `open-motion init <name>`
 使用预配置的 React 模板初始化一个新的 OpenMotion 项目。
 
+### `open-motion generate <description>`
+使用 LLM 从文本描述自动生成视频场景和代码。
+
+| 选项 | 描述 |
+| :--- | :--- |
+| `--env <path>` | .env 文件路径 (默认: 当前目录下的 .env) |
+| `--scenes <number>` | 要生成的场景数量 |
+| `--fps <number>` | 每秒帧数 (默认: 30) |
+| `--width <number>` | 视频宽度 (默认: 1280) |
+| `--height <number>` | 视频高度 (默认: 720) |
+
+### `open-motion edit <file>`
+使用自然语言指令编辑 TSX 场景文件。
+
+| 选项 | 描述 |
+| :--- | :--- |
+| `--env <path>` | .env 文件路径 (默认: 当前目录下的 .env) |
+| `-m, --message <msg>` | 编辑指令 |
+| `-y, --yes` | 自动应用更改 (一次性模式) |
+
 ### `open-motion config`
-管理 LLM 配置（API Key、模型等）。
+管理 LLM 提供商设置（API 密钥、模型）。
 
 - `open-motion config list`
 - `open-motion config get <VAR>`
 
-配置从环境变量读取（也支持放在项目目录下的 `.env` 文件中）：
+LLM 设置从环境变量读取（可以放在项目本地的 `.env` 文件中）：
 
 ```bash
 # .env
 OPEN_MOTION_PROVIDER=openai
+OPEN_MOTION_MODEL=gpt-5.1
 OPENAI_API_KEY=sk-...
 ```
 
@@ -119,6 +183,19 @@ OPENAI_API_KEY=sk-...
 | `--public-dir <path>` | 静态资源的公共目录 (默认: `./public`) |
 | `--chromium-path <path>`| 自定义 Chromium 可执行文件路径 |
 | `--timeout <number>` | 浏览器操作超时时间 (毫秒) |
+| `--font <spec>` | 加载本地字体文件用于渲染 (可重复指定)。格式: `Family=path` 或 `path` |
+| `--bgm <path>` | 从本地 MP3 文件添加背景音乐 |
+| `--bgm-volume <number>` | BGM 音量 (0.0-1.0, 默认: 1.0) |
+
+示例 (渲染时添加 BGM):
+
+```bash
+open-motion render -u http://localhost:5173 -o out.mp4 --bgm ./music/bgm.mp3 --bgm-volume 0.5
+```
+
+注意:
+- 如果 BGM 比视频短，它会循环播放以覆盖整个时长。
+- 如果 BGM 比视频长，它会被裁剪到视频时长。
 
 ## 📚 API 参考
 
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 9af761c..5d53e02 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -44,6 +44,7 @@ open-motion init my-video
 # Configure via environment variables (project-local .env supported)
 # .env
 OPEN_MOTION_PROVIDER=openai
+OPEN_MOTION_MODEL=gpt-4o
 OPENAI_API_KEY=sk-...
 
 # Verify what the CLI sees
@@ -53,7 +54,11 @@ open-motion config get OPENAI_API_KEY
 
 ### Generate a video from description
 ```bash
+# Uses .env in current directory by default
 open-motion generate "Explain how React hooks work"
+
+# Or specify a custom .env file
+open-motion generate "Explain how React hooks work" --env .env.anthropic
 ```
 
 ### Edit a scene file
@@ -63,6 +68,9 @@ open-motion edit src/scenes/IntroScene.tsx
 
 # One-shot mode
 open-motion edit src/scenes/IntroScene.tsx -m "Make the text color blue" --yes
+
+# Use a custom .env file
+open-motion edit src/scenes/IntroScene.tsx -m "Make the text color blue" --env .env.anthropic --yes
 ```
 
 ### Render a video
diff --git a/packages/cli/src/bin.ts b/packages/cli/src/bin.ts
index ab279a6..cec6018 100644
--- a/packages/cli/src/bin.ts
+++ b/packages/cli/src/bin.ts
@@ -1,5 +1,15 @@
 #!/usr/bin/env node
-import 'dotenv/config';
+import { config } from 'dotenv';
+import { resolve } from 'path';
+
+const envIndex = process.argv.indexOf('--env');
+if (envIndex !== -1 && process.argv[envIndex + 1]) {
+  config({ path: resolve(process.cwd(), process.argv[envIndex + 1]) });
+  process.argv.splice(envIndex, 2);
+} else {
+  config();
+}
+
 import { main } from './index';
 
 main();
diff --git a/packages/cli/src/commands/edit.ts b/packages/cli/src/commands/edit.ts
index 38cc186..826e4bc 100644
--- a/packages/cli/src/commands/edit.ts
+++ b/packages/cli/src/commands/edit.ts
@@ -14,8 +14,6 @@ import { EDIT_SYSTEM_PROMPT, buildEditPrompt, parseEditResponse } from '../promp
 
 export interface EditOptions {
   message?: string;
-  provider?: string;
-  model?: string;
   apiKey?: string;
   baseURL?: string;
   yes?: boolean;
@@ -173,8 +171,6 @@ export async function runEdit(
   // Resolve LLM config
   // ------------------------------------------------------------------
   const configOverrides: CliConfigOverrides = {
-    provider: options.provider,
-    model: options.model,
     apiKey: options.apiKey,
     baseURL: options.baseURL,
   };
diff --git a/packages/cli/src/commands/generate.ts b/packages/cli/src/commands/generate.ts
index b7f0110..ca5b62f 100644
--- a/packages/cli/src/commands/generate.ts
+++ b/packages/cli/src/commands/generate.ts
@@ -24,8 +24,6 @@ import {
 // ---------------------------------------------------------------------------
 
 export interface GenerateOptions {
-  provider?: string;
-  model?: string;
   apiKey?: string;
   baseURL?: string;
   scenes?: number;
@@ -421,13 +419,22 @@ function updateMainTsx(
 // Main command
 // ---------------------------------------------------------------------------
 
+function envInt(key: string): number | undefined {
+  const v = process.env[key];
+  if (v && v.trim() !== '') {
+    const n = parseInt(v.trim(), 10);
+    return Number.isNaN(n) ? undefined : n;
+  }
+  return undefined;
+}
+
 export async function runGenerate(
   description: string,
   options: GenerateOptions
 ): Promise<void> {
-  const fps = options.fps ?? 30;
-  const width = options.width ?? 1280;
-  const height = options.height ?? 720;
+  const fps = options.fps ?? envInt('VIDEO_FPS') ?? 30;
+  const width = options.width ?? envInt('VIDEO_WIDTH') ?? 1280;
+  const height = options.height ?? envInt('VIDEO_HEIGHT') ?? 720;
 
   // Resolve output directory (default: src/scenes relative to cwd)
   const outputDir = options.output
@@ -443,8 +450,6 @@ export async function runGenerate(
   // 1. Resolve & validate LLM config
   // ------------------------------------------------------------------
   const configOverrides: CliConfigOverrides = {
-    provider: options.provider,
-    model: options.model,
     apiKey: options.apiKey,
     baseURL: options.baseURL,
   };
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 0fbfdfb..5fe8987 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -640,12 +640,8 @@ Examples:
   const generateCommand = program
     .command('generate <description>')
     .description('Auto-generate video scene TSX files using an LLM')
-    .option(
-      '--provider <name>',
-      'LLM provider (openai/openrouter/anthropic/google/ollama/openai-compatible)'
-    )
-    .option('--model <name>', 'Model name to use')
-    .option('--api-key <key>', 'API key (overrides config file and environment variables)')
+    .option('--env <path>', 'Path to .env file (default: .env in current directory)')
+    .option('--api-key <key>', 'API key (overrides environment variables)')
     .option('--base-url <url>', 'Base URL (for openrouter / openai-compatible / ollama)')
     .option('--scenes <number>', 'Number of scenes to generate (default: decided by LLM)', parseInt)
     .option('--fps <number>', 'Frame rate (default: 30)', parseInt)
@@ -655,8 +651,6 @@ Examples:
     .action(async (description: string, options) => {
       try {
         await runGenerate(description, {
-          provider: options.provider,
-          model: options.model,
           apiKey: options.apiKey,
           baseURL: options.baseUrl,
           scenes: options.scenes,
@@ -675,14 +669,13 @@ Examples:
 Examples:
   $ open-motion generate "A video explaining the React lifecycle"
   $ open-motion generate "TypeScript type system explainer" --scenes 4 --fps 30
-  $ open-motion generate "How to use AWS S3" --provider anthropic --model claude-opus-4-5
-  $ open-motion generate "React hooks overview" --provider openrouter --model openai/gpt-4o
-  $ open-motion generate "How Docker works" --provider ollama --model llama3
-  $ open-motion generate "CI/CD pipeline explainer" --provider openai-compatible --base-url https://example.com/v1
   $ open-motion generate "CI/CD pipeline explainer" --width 1920 --height 1080
+  $ open-motion generate "How Docker works" --env .env.ollama
 
 Note:
-  - LLM configuration is read from environment variables (you can put them in a .env file)
+  - LLM configuration is read from environment variables
+  - By default, .env in the current directory is loaded
+  - Use --env to specify a custom .env file path
   - Run this command from the root of an existing project (created with open-motion init)
 `);
 
@@ -693,20 +686,14 @@ Note:
     .command('edit <file>')
     .description('Interactively edit a TSX scene file using an LLM')
     .option('-m, --message <instruction>', 'One-shot mode: pass instruction as a string')
-    .option(
-      '--provider <name>',
-      'LLM provider (openai/openrouter/anthropic/google/ollama/openai-compatible)'
-    )
-    .option('--model <name>', 'Model name to use')
-    .option('--api-key <key>', 'API key (overrides config file and environment variables)')
+    .option('--env <path>', 'Path to .env file (default: .env in current directory)')
+    .option('--api-key <key>', 'API key (overrides environment variables)')
     .option('--base-url <url>', 'Base URL (for openrouter / openai-compatible / ollama)')
     .option('-y, --yes', 'Auto-apply changes without confirmation (one-shot mode only)')
     .action(async (file: string, options) => {
       try {
         await runEdit(file, {
           message: options.message,
-          provider: options.provider,
-          model: options.model,
           apiKey: options.apiKey,
           baseURL: options.baseUrl,
           yes: options.yes,
@@ -725,9 +712,7 @@ Examples:
   # One-shot mode (pass a single instruction)
   $ open-motion edit src/scenes/IntroScene.tsx --message "Change the background to blue"
   $ open-motion edit src/scenes/IntroScene.tsx -m "Make the text larger" --yes
-
-  # Specify a provider
-  $ open-motion edit src/scenes/IntroScene.tsx --provider anthropic -m "Smooth out the animation"
+  $ open-motion edit src/scenes/IntroScene.tsx -m "Smooth out the animation" --env .env.anthropic
 `);
 
   // ---------------------------------------------------------------------------
diff --git a/packages/cli/src/llm/config.ts b/packages/cli/src/llm/config.ts
index 84401eb..143b894 100644
--- a/packages/cli/src/llm/config.ts
+++ b/packages/cli/src/llm/config.ts
@@ -15,8 +15,6 @@ function env(key: string): string | undefined {
 // ---------------------------------------------------------------------------
 
 export interface CliConfigOverrides {
-  provider?: string;
-  model?: string;
   apiKey?: string;
   baseURL?: string;
 }
@@ -29,17 +27,10 @@ const OPENROUTER_DEFAULT_BASE_URL = 'https://openrouter.ai/api/v1';
  *   CLI flags > ENV vars (.env file values are loaded as ENV vars by dotenv)
  */
 export function resolveConfig(overrides: CliConfigOverrides = {}): ResolvedLLMConfig {
-  // 1. Provider
   const provider: ProviderName =
-    (overrides.provider as ProviderName | undefined) ||
-    (env('OPEN_MOTION_PROVIDER') as ProviderName | undefined) ||
-    'openai';
+    (env('OPEN_MOTION_PROVIDER') as ProviderName | undefined) || 'openai';
 
-  // 2. Model — global override, then provider-specific, then default
-  const model =
-    overrides.model ||
-    env('OPEN_MOTION_MODEL') ||
-    DEFAULT_MODELS[provider];
+  const model = env('OPEN_MOTION_MODEL') || DEFAULT_MODELS[provider];
 
   // 3. API key / base URL (provider-specific)
   let apiKey: string | undefined;

From ad11da7b37d1fca9ec2f6949b251593570879003 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Mon, 2 Mar 2026 21:12:30 +0900
Subject: [PATCH 26/28] feat(core): add Audio component and fix CommonJS module
 resolution

- Add Audio.tsx and AudioSync.tsx for audio playback support
- Add context.ts with AbsoluteFrameContext
- Export Audio and AbsoluteFrameContext from index
- Fix tsconfig: switch module from ESNext to CommonJS and moduleResolution
  from bundler to node to resolve ERR_MODULE_NOT_FOUND in Node.js ESM

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 packages/core/package.json      |   8 ++
 packages/core/src/Audio.tsx     |  31 +++++++
 packages/core/src/AudioSync.tsx | 139 ++++++++++++++++++++++++++++++++
 packages/core/src/Player.tsx    |   7 ++
 packages/core/src/context.ts    |   3 +
 packages/core/src/index.tsx     |  32 +-------
 packages/core/tsconfig.json     |   4 +-
 7 files changed, 194 insertions(+), 30 deletions(-)
 create mode 100644 packages/core/src/Audio.tsx
 create mode 100644 packages/core/src/AudioSync.tsx
 create mode 100644 packages/core/src/context.ts

diff --git a/packages/core/package.json b/packages/core/package.json
index 067deb7..498063b 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -2,7 +2,15 @@
   "name": "@open-motion/core",
   "version": "0.1.9",
   "main": "dist/index.js",
+  "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
   "license": "MIT",
   "scripts": {
     "build": "tsc"
diff --git a/packages/core/src/Audio.tsx b/packages/core/src/Audio.tsx
new file mode 100644
index 0000000..d509670
--- /dev/null
+++ b/packages/core/src/Audio.tsx
@@ -0,0 +1,31 @@
+import React from 'react';
+
+export interface AudioProps {
+  src: string;
+  startFrom?: number;
+  startFrame?: number;
+  volume?: number;
+}
+
+export const Audio: React.FC<AudioProps> = (props) => {
+  const startFrame = props.startFrame ?? 0;
+
+  if (typeof window !== 'undefined') {
+    (window as any).__OPEN_MOTION_AUDIO_ASSETS__ = (window as any).__OPEN_MOTION_AUDIO_ASSETS__ || [];
+    const exists = (window as any).__OPEN_MOTION_AUDIO_ASSETS__.find(
+      (a: any) =>
+        a.src === props.src &&
+        (a.startFrom || 0) === (props.startFrom || 0) &&
+        (a.volume || 1) === (props.volume || 1) &&
+        a.startFrame === startFrame
+    );
+    if (!exists) {
+      console.log('[Audio] Registering asset:', props.src, 'startFrame:', startFrame, 'volume:', props.volume);
+      (window as any).__OPEN_MOTION_AUDIO_ASSETS__.push({
+        ...props,
+        startFrame,
+      });
+    }
+  }
+  return null;
+};
diff --git a/packages/core/src/AudioSync.tsx b/packages/core/src/AudioSync.tsx
new file mode 100644
index 0000000..a6b8ff7
--- /dev/null
+++ b/packages/core/src/AudioSync.tsx
@@ -0,0 +1,139 @@
+import React, { useRef, useEffect } from 'react';
+
+export interface AudioOptions {
+  startFrom?: number;
+  startFrame?: number;
+  volume?: number;
+}
+
+export interface AudioSyncManagerProps {
+  frame: number;
+  fps: number;
+  isPlaying: boolean;
+  durationInFrames: number;
+}
+
+interface AudioEntry {
+  audio: HTMLAudioElement;
+  loaded: boolean;
+  pendingPlay: boolean;
+}
+
+export const AudioSyncManager: React.FC<AudioSyncManagerProps> = ({
+  frame,
+  fps,
+  isPlaying,
+}) => {
+  const audioElementsRef = useRef<Map<string, AudioEntry>>(new Map());
+  const lastSyncedFrameRef = useRef<number>(-1);
+
+  // Register audio elements for newly discovered assets (runs each frame to pick up
+  // assets added by Sequence-gated <Audio> components that appear mid-playback).
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const assets: any[] = (window as any).__OPEN_MOTION_AUDIO_ASSETS__ || [];
+
+    assets.forEach((asset: any) => {
+      const id = `${asset.src}-${asset.startFrame || 0}-${asset.startFrom || 0}`;
+
+      if (!audioElementsRef.current.has(id)) {
+        const audio = new Audio();
+        audio.src = asset.src;
+        audio.volume = asset.volume ?? 1;
+        audio.preload = 'auto';
+
+        const entry: AudioEntry = { audio, loaded: false, pendingPlay: false };
+
+        audio.addEventListener('canplaythrough', () => {
+          entry.loaded = true;
+        }, { once: true });
+
+        audio.addEventListener('error', (e) => {
+          console.error('[AudioSync] Audio error:', asset.src, e);
+        });
+
+        audio.load();
+        audioElementsRef.current.set(id, entry);
+      }
+    });
+  }, [frame]);
+
+  // Synchronise audio playback position and play/pause state.
+  useEffect(() => {
+    if (lastSyncedFrameRef.current === frame) return;
+    lastSyncedFrameRef.current = frame;
+
+    const assets: any[] = (window as any).__OPEN_MOTION_AUDIO_ASSETS__ || [];
+
+    audioElementsRef.current.forEach((entry, id) => {
+      const { audio } = entry;
+
+      const asset = assets.find((a: any) =>
+        `${a.src}-${a.startFrame || 0}-${a.startFrom || 0}` === id
+      );
+      if (!asset) return;
+
+      const startFrame: number = asset.startFrame || 0;
+      const startFrom: number = asset.startFrom || 0;
+
+      // Before the asset's start frame: keep silent and reset.
+      if (frame < startFrame) {
+        if (!audio.paused) audio.pause();
+        entry.pendingPlay = false;
+        audio.currentTime = 0;
+        return;
+      }
+
+      const relativeFrame = frame - startFrame;
+      const targetTime = relativeFrame / fps + startFrom;
+
+      if (!isPlaying) {
+        // Intentionally paused — seek to keep position in sync with scrubbing.
+        if (!audio.paused) audio.pause();
+        entry.pendingPlay = false;
+        audio.currentTime = targetTime;
+        return;
+      }
+
+      // isPlaying === true from here on.
+      if (!audio.paused) {
+        // Audio is already running — correct large drift only.
+        const drift = Math.abs(audio.currentTime - targetTime);
+        if (drift > 0.3) {
+          audio.currentTime = targetTime;
+        }
+        return;
+      }
+
+      // Audio is paused but should be playing.
+      if (!entry.loaded || entry.pendingPlay) {
+        // Not ready yet, or play() already in-flight — do nothing.
+        return;
+      }
+
+      // Set position once, then kick off play().
+      audio.currentTime = targetTime;
+      entry.pendingPlay = true;
+      audio.play()
+        .then(() => { entry.pendingPlay = false; })
+        .catch((e) => {
+          entry.pendingPlay = false;
+          console.error('[AudioSync] Play failed:', e);
+        });
+    });
+  }, [frame, fps, isPlaying]);
+
+  // Cleanup on unmount.
+  useEffect(() => {
+    return () => {
+      audioElementsRef.current.forEach(entry => {
+        entry.audio.pause();
+        entry.audio.src = '';
+      });
+      audioElementsRef.current.clear();
+    };
+  }, []);
+
+  return null;
+};
diff --git a/packages/core/src/Player.tsx b/packages/core/src/Player.tsx
index 2fcb070..0387c06 100644
--- a/packages/core/src/Player.tsx
+++ b/packages/core/src/Player.tsx
@@ -1,5 +1,6 @@
 import React, { useState, useEffect, useCallback, useRef } from 'react';
 import { CompositionProvider, VideoConfig } from './index';
+import { AudioSyncManager } from './AudioSync';
 
 export interface PlayerProps {
   component: React.ComponentType<any>;
@@ -106,6 +107,12 @@ export const Player: React.FC<PlayerProps> = ({
       >
         <CompositionProvider config={config} frame={frame} inputProps={inputProps}>
           <Component />
+          <AudioSyncManager
+            frame={frame}
+            fps={config.fps}
+            isPlaying={isPlaying}
+            durationInFrames={config.durationInFrames}
+          />
         </CompositionProvider>
       </div>
 
diff --git a/packages/core/src/context.ts b/packages/core/src/context.ts
new file mode 100644
index 0000000..0c78a69
--- /dev/null
+++ b/packages/core/src/context.ts
@@ -0,0 +1,3 @@
+import { createContext } from 'react';
+
+export const AbsoluteFrameContext = createContext<number>(0);
diff --git a/packages/core/src/index.tsx b/packages/core/src/index.tsx
index 468f517..05ea05c 100644
--- a/packages/core/src/index.tsx
+++ b/packages/core/src/index.tsx
@@ -1,4 +1,7 @@
 import React, { createContext, useContext } from 'react';
+import { AbsoluteFrameContext } from './context';
+
+export { AbsoluteFrameContext };
 
 export interface VideoConfig {
   width: number;
@@ -9,7 +12,6 @@ export interface VideoConfig {
 
 const VideoConfigContext = createContext<VideoConfig | null>(null);
 const FrameContext = createContext<number>(0);
-const AbsoluteFrameContext = createContext<number>(0);
 const InputPropsContext = createContext<any>({});
 
 export const CompositionProvider: React.FC<{
@@ -360,33 +362,7 @@ export const Loop: React.FC<{
   );
 };
 
-/**
- * Audio Component
- */
-export const Audio: React.FC<{
-  src: string;
-  startFrom?: number;
-  volume?: number;
-}> = (props) => {
-  const startFrame = useAbsoluteFrame();
-  if (typeof window !== 'undefined') {
-    (window as any).__OPEN_MOTION_AUDIO_ASSETS__ = (window as any).__OPEN_MOTION_AUDIO_ASSETS__ || [];
-    const exists = (window as any).__OPEN_MOTION_AUDIO_ASSETS__.find(
-      (a: any) =>
-        a.src === props.src &&
-        (a.startFrom || 0) === (props.startFrom || 0) &&
-        (a.volume || 1) === (props.volume || 1) &&
-        a.startFrame === startFrame
-    );
-    if (!exists) {
-      (window as any).__OPEN_MOTION_AUDIO_ASSETS__.push({
-        ...props,
-        startFrame,
-      });
-    }
-  }
-  return null;
-};
+export { Audio, type AudioProps } from './Audio';
 
 /**
  * Video Component
diff --git a/packages/core/tsconfig.json b/packages/core/tsconfig.json
index 88c2ec7..c07986e 100644
--- a/packages/core/tsconfig.json
+++ b/packages/core/tsconfig.json
@@ -1,8 +1,8 @@
 {
   "compilerOptions": {
     "target": "ESNext",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
+    "module": "CommonJS",
+    "moduleResolution": "node",
     "outDir": "dist",
     "rootDir": "src",
     "strict": true,

From 242044eff3d8bf947bf619e4dcad7d7857f53b74 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Mon, 2 Mar 2026 21:12:43 +0900
Subject: [PATCH 27/28] feat(cli): add BGM support to generate command and
 update init template

- Add --bgm and --bgm-volume options to generate command
- Copy BGM file to public/audio/bgm/ and embed in composition
- Update init template to use workspace-compatible pnpm install flow
- Update generate prompts and output formatting

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 packages/cli/src/commands/generate.ts | 152 ++++++++++++++++----------
 packages/cli/src/index.ts             |   6 +-
 packages/cli/src/prompts/generate.ts  |  31 +++++-
 3 files changed, 131 insertions(+), 58 deletions(-)

diff --git a/packages/cli/src/commands/generate.ts b/packages/cli/src/commands/generate.ts
index ca5b62f..5a0732f 100644
--- a/packages/cli/src/commands/generate.ts
+++ b/packages/cli/src/commands/generate.ts
@@ -31,6 +31,8 @@ export interface GenerateOptions {
   width?: number;
   height?: number;
   output?: string;
+  bgm?: string;
+  bgmVolume?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -175,7 +177,9 @@ function buildCompositionFile(
   fps: number,
   width: number,
   height: number,
-  srtContent: string
+  srtContent: string,
+  bgmSrc?: string,
+  bgmVolume?: number
 ): string {
   const imports = plan.scenes
     .map((s) => `import { ${s.componentName} } from './scenes/${s.componentName}';`)
@@ -197,6 +201,11 @@ function buildCompositionFile(
   // Use JSON string escaping so we can embed arbitrary caption text safely.
   const srtLiteral = JSON.stringify(srtContent);
 
+  // BGM audio element
+  const bgmAudio = bgmSrc 
+    ? `    <Audio src="${bgmSrc}" volume={${bgmVolume ?? 0.5}} />`
+    : '';
+
   return `import React, { useMemo } from 'react';
  import {
    Sequence,
@@ -205,6 +214,7 @@ function buildCompositionFile(
    interpolate,
    spring,
    parseSrt,
+   Audio,
    type SubtitleItem,
  } from '@open-motion/core';
  ${imports}
@@ -212,15 +222,15 @@ function buildCompositionFile(
  /** Auto-generated composition: ${videoTitle} */
  const SRT_CAPTIONS: string = ${srtLiteral};
 
-  const CaptionOverlay: React.FC<{ subtitles: SubtitleItem[] }> = ({ subtitles }) => {
-    const frame = useCurrentFrame();
-    const { fps } = useVideoConfig();
-    const currentTime = frame / fps;
+ const CaptionOverlay: React.FC<{ subtitles: SubtitleItem[] }> = ({ subtitles }) => {
+   const frame = useCurrentFrame();
+   const { fps } = useVideoConfig();
+   const currentTime = frame / fps;
 
-    const active = subtitles.find(
-      (s) => currentTime >= s.startInSeconds && currentTime < s.endInSeconds
-    );
-    if (!active) return null;
+   const active = subtitles.find(
+     (s) => currentTime >= s.startInSeconds && currentTime < s.endInSeconds
+   );
+   if (!active) return null;
 
    const startFrame = Math.round(active.startInSeconds * fps);
    const relFrame = Math.max(0, frame - startFrame);
@@ -229,21 +239,21 @@ function buildCompositionFile(
    const opacity = interpolate(enter, [0, 1], [0, 1], { extrapolateRight: 'clamp' });
    const scale = interpolate(enter, [0, 1], [0.96, 1], { extrapolateRight: 'clamp' });
 
-    // Simple TikTok-ish word highlight sweep.
-    // Sweep exactly once across the whole subtitle block (no looping).
-    const words = active.text.replace(/\s+/g, ' ').trim().split(' ').filter(Boolean);
-    const displayedWords = words.length > 0 ? words : [active.text];
-    const blockDurationInFrames = Math.max(
-      1,
-      Math.round((active.endInSeconds - active.startInSeconds) * fps)
-    );
-    const sweep = interpolate(
-      relFrame,
-      [0, blockDurationInFrames],
-      [0, displayedWords.length],
-      { extrapolateRight: 'clamp' }
-    );
-    const highlightIndex = Math.min(displayedWords.length - 1, Math.floor(sweep));
+   // Simple TikTok-ish word highlight sweep.
+   // Sweep exactly once across the whole subtitle block (no looping).
+   const words = active.text.replace(/\\s+/g, ' ').trim().split(' ').filter(Boolean);
+   const displayedWords = words.length > 0 ? words : [active.text];
+   const blockDurationInFrames = Math.max(
+     1,
+     Math.round((active.endInSeconds - active.startInSeconds) * fps)
+   );
+   const sweep = interpolate(
+     relFrame,
+     [0, blockDurationInFrames],
+     [0, displayedWords.length],
+     { extrapolateRight: 'clamp' }
+   );
+   const highlightIndex = Math.min(displayedWords.length - 1, Math.floor(sweep));
 
    return (
      <div
@@ -254,12 +264,12 @@ function buildCompositionFile(
          bottom: 72,
          display: 'flex',
          justifyContent: 'center',
-          padding: '0 48px',
-          pointerEvents: 'none',
-          opacity,
-          transform: \`scale(\${scale})\`,
-        }}
-      >
+         padding: '0 48px',
+         pointerEvents: 'none',
+         opacity,
+         transform: \`scale(\${scale})\`,
+       }}
+     >
        <div
          style={{
            maxWidth: '92%',
@@ -280,20 +290,20 @@ function buildCompositionFile(
            gap: 12,
          }}
        >
-          {displayedWords.map((w, i) => (
-            <span
-              key={i}
-              style={{
-                padding: '2px 10px',
-                borderRadius: 10,
-                backgroundColor: highlightIndex === i ? '#ff0050' : 'transparent',
-                transform: highlightIndex === i ? 'scale(1.06)' : 'scale(1)',
-                transition: 'transform 80ms linear',
-              }}
-            >
-              {w}
-            </span>
-          ))}
+         {displayedWords.map((w, i) => (
+           <span
+             key={i}
+             style={{
+               padding: '2px 10px',
+               borderRadius: 10,
+               backgroundColor: highlightIndex === i ? '#ff0050' : 'transparent',
+               transform: highlightIndex === i ? 'scale(1.06)' : 'scale(1)',
+               transition: 'transform 80ms linear',
+             }}
+           >
+             {w}
+           </span>
+         ))}
        </div>
      </div>
    );
@@ -306,19 +316,20 @@ function buildCompositionFile(
      <div style={{ width, height, overflow: 'hidden', backgroundColor: '#000', position: 'relative' }}>
  ${sequences}
        <CaptionOverlay subtitles={subtitles} />
+ ${bgmAudio}
      </div>
    );
  };
 
-/** Total duration in frames: ${totalFrames} (${(totalFrames / fps).toFixed(1)}s at ${fps}fps) */
-export const ${componentName}Config = {
-  id: '${componentName.replace(/([A-Z])/g, (m, l, i) => (i === 0 ? l.toLowerCase() : '-' + l.toLowerCase()))}',
-  component: ${componentName},
-  width: ${width},
-  height: ${height},
-  fps: ${fps},
-  durationInFrames: ${totalFrames},
-} as const;
+ /** Total duration in frames: ${totalFrames} (${(totalFrames / fps).toFixed(1)}s at ${fps}fps) */
+ export const ${componentName}Config = {
+   id: '${componentName.replace(/([A-Z])/g, (m, l, i) => (i === 0 ? l.toLowerCase() : '-' + l.toLowerCase()))}',
+   component: ${componentName},
+   width: ${width},
+   height: ${height},
+   fps: ${fps},
+   durationInFrames: ${totalFrames},
+ } as const;
  `;
 }
 
@@ -681,11 +692,37 @@ export async function runGenerate(
   console.log('');
 
   // ------------------------------------------------------------------
-  // 5. Generate composition wrapper
+  // 5. Handle BGM
+  // ------------------------------------------------------------------
+  let bgmSrc: string | undefined;
+  if (options.bgm) {
+    const bgmPath = path.resolve(process.cwd(), options.bgm);
+
+    if (!fs.existsSync(bgmPath)) {
+      console.error(chalk.red(`BGM file not found: ${bgmPath}`));
+      process.exit(1);
+    }
+
+    // Create public/audio/bgm directory and copy BGM file
+    const publicDir = path.join(process.cwd(), 'public');
+    const audioDir = path.join(publicDir, 'audio', 'bgm');
+    fs.mkdirSync(audioDir, { recursive: true });
+
+    const bgmFileName = path.basename(bgmPath);
+    const destPath = path.join(audioDir, bgmFileName);
+    fs.copyFileSync(bgmPath, destPath);
+
+    bgmSrc = `/audio/bgm/${bgmFileName}`;
+    console.log(chalk.dim(`BGM copied to: public/audio/bgm/${bgmFileName}`));
+    console.log('');
+  }
+
+  // ------------------------------------------------------------------
+  // 6. Generate composition wrapper
   // ------------------------------------------------------------------
   spinner.start('[4/4] Generating composition file...');
 
-  const compositionCode = buildCompositionFile(plan.videoTitle, plan, fps, width, height, srtContent);
+  const compositionCode = buildCompositionFile(plan.videoTitle, plan, fps, width, height, srtContent, bgmSrc, options.bgmVolume);
   const compositionComponentName = toPascalCase(plan.videoTitle) + 'Video';
 
   // Total duration for the composition
@@ -716,7 +753,7 @@ export async function runGenerate(
   console.log('');
 
   // ------------------------------------------------------------------
-  // 5. Summary
+  // 7. Summary
   // ------------------------------------------------------------------
   console.log(chalk.bold.green('Done!'));
   console.log('');
@@ -731,6 +768,9 @@ export async function runGenerate(
     const relMain = path.relative(process.cwd(), mainTsxPath);
     console.log(chalk.green('  ✓') + '  ' + relMain + chalk.dim('  (Composition appended)'));
   }
+  if (bgmSrc) {
+    console.log(chalk.green('  ✓') + '  public/audio/bgm/' + path.basename(bgmSrc) + chalk.dim('  (BGM)'));
+  }
   console.log('');
   console.log(
     chalk.dim(
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 5fe8987..20dd5dd 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -34,7 +34,7 @@ export const runInit = async (projectName: string) => {
   console.log(`Initializing OpenMotion project: ${projectName} using ${pm}...`);
 
   // Basic template structure
-  const dirs = ['', 'src'];
+  const dirs = ['', 'src', 'public', 'public/audio'];
   for (const dir of dirs) {
     fs.mkdirSync(path.join(targetDir, dir), { recursive: true });
   }
@@ -648,6 +648,8 @@ Examples:
     .option('--width <number>', 'Video width (default: 1280)', parseInt)
     .option('--height <number>', 'Video height (default: 720)', parseInt)
     .option('--output <dir>', 'Output directory for scene files (default: src/scenes)')
+    .option('--bgm <path>', 'Path to BGM audio file (MP3/WAV)')
+    .option('--bgm-volume <number>', 'BGM volume (0.0-1.0, default: 0.5)', parseFloat)
     .action(async (description: string, options) => {
       try {
         await runGenerate(description, {
@@ -658,6 +660,8 @@ Examples:
           width: options.width,
           height: options.height,
           output: options.output,
+          bgm: options.bgm,
+          bgmVolume: options.bgmVolume,
         });
       } catch (err) {
         console.error('Generate failed:', err);
diff --git a/packages/cli/src/prompts/generate.ts b/packages/cli/src/prompts/generate.ts
index d3d4327..52bdc11 100644
--- a/packages/cli/src/prompts/generate.ts
+++ b/packages/cli/src/prompts/generate.ts
@@ -27,11 +27,40 @@ setTimeout, setInterval, or any real-time mechanism for animation.
   - Children are only rendered during frames [from, from+durationInFrames)
   - Inside Sequence, \`useCurrentFrame()\` returns a frame relative to \`from\`
 
+### Easing functions (import from '@open-motion/core')
+- \`Easing.linear\`, \`Easing.easeIn\`, \`Easing.easeOut\`, \`Easing.easeInOut\`
+- \`Easing.inOutCubic\`, \`Easing.outBack\`, \`Easing.inExpo\`, \`Easing.outExpo\`, and more
+- Example: \`interpolate(frame, [0, 30], [0, 100], { easing: Easing.outCubic })\`
+
+### Animation & Transitions (import from '@open-motion/components')
+- \`<Loop durationInFrames={n}>\` — Create looping time contexts for sub-animations
+  - Example: \`<Loop durationInFrames={60}><SpinningLogo /></Loop>\`
+- \`<Transition type="fade|wipe|slide|zoom" direction="left|right|up|down">\` — Smooth enter/exit transitions
+  - Example: \`<Transition type="wipe" direction="right"><Title /></Transition>\`
+
+### Media components (import from '@open-motion/core')
+- \`<Audio src="..." volume={0.5} startFrom={n} startFrame={n} />\` — Multi-track audio with independent volume and timing
+  - Example: \`<Audio src="/music.mp3" volume={0.5} startFrom={30} startFrame={60} />\`
+- \`<OffthreadVideo src="..." />\` — High-performance video decoding in background processes
+- \`getVideoMetadata(url)\` — Fetch video dimensions and duration (async)
+  - Example: \`const { width, height, durationInSeconds } = await getVideoMetadata('/video.mp4');\`
+- \`parseSrt(srtContent)\` — Convert SRT subtitle files to arrays
+  - Example: \`const subtitles = parseSrt(await fetch('/subtitles.srt').then(r => r.text()));\`
+
+### Caption components (import from '@open-motion/components')
+- \`<Captions subtitles={subtitles} color="white" fontSize={24} />\` — Flexible subtitle renderer with styling options
+- \`<TikTokCaption />\` — Pre-styled component for TikTok-like animated captions
+
+### 3D & Lottie (import from '@open-motion/components')
+- \`<ThreeCanvas />\` — Render Three.js scenes synced with video frames
+- \`<Lottie url="..." />\` — Declarative Lottie animations with frame-accurate control
+  - Example: \`<Lottie url="/animations/logo.json" />\`
+
 ## Coding rules
 1. Export the component as a **named export** (not default)
 2. All styles must be **inline React styles** (no CSS files, no styled-components)
 3. The root element MUST fill the full \`width\` and \`height\` from \`useVideoConfig()\`
-4. Never import anything outside of \`react\` and \`@open-motion/core\`
+4. Never import anything outside of \`react\`, \`@open-motion/core\`, and \`@open-motion/components\`
 5. Do NOT add \`<Composition>\` registration inside scene files — that belongs in main.tsx
 6. The component must be **completely self-contained** with no props required
 7. Use visually appealing designs: thoughtful colors, smooth animations, readable typography

From 5f5417dcbb38d5c61b92c3febf8ef609637e8666 Mon Sep 17 00:00:00 2001
From: straygizmo <straygizmo@gmail.com>
Date: Mon, 2 Mar 2026 21:12:55 +0900
Subject: [PATCH 28/28] docs: align Quick Start steps with init command tips
 and update gitignore

- Simplify Quick Start: cd into project, pnpm install, pnpm run dev
  (pnpm auto-detects workspace root, no need for cd ../..)
- Remove redundant pnpm --filter alternative from all three READMEs
- Add .claude to .gitignore

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .gitignore   | 3 ++-
 README.ja.md | 9 +--------
 README.md    | 9 +--------
 README.zh.md | 9 +--------
 4 files changed, 5 insertions(+), 25 deletions(-)

diff --git a/.gitignore b/.gitignore
index 4712e94..2dea71c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,4 +17,5 @@ progress.md.worktrees/
 *.avi
 *.mkv
 *.webm
-my_videos
\ No newline at end of file
+my_videos
+.claude
diff --git a/README.ja.md b/README.ja.md
index cfe5a2c..a7bc588 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -101,7 +101,7 @@ Linuxのヘッドレス環境で日本語/中国語などが文字化けする
 ```bash
 mkdir -p my_videos && cd my_videos
 open-motion init my-video1
-cd ../..  # monorepoのルートに戻る
+cd my-video1
 pnpm install
 ```
 
@@ -110,16 +110,9 @@ pnpm install
 ターミナルで開発サーバーを起動します：
 
 ```bash
-cd my_videos/my-video1
 pnpm run dev
 ```
 
-または
-
-```bash
-pnpm --filter my-video1 dev
-```
-
 別のターミナルで、サーバーのURLを使用してビデオをレンダリングします：
 ```bash
 open-motion render -u http://localhost:5173 -o out.mp4 --composition my-video1
diff --git a/README.md b/README.md
index bef9226..014a66d 100644
--- a/README.md
+++ b/README.md
@@ -101,7 +101,7 @@ If Japanese/Chinese/Korean text renders as squares in headless Linux, it's usual
 ```bash
 mkdir -p my_videos && cd my_videos
 open-motion init my-video1
-cd ../..  # Return to monorepo root
+cd my-video1
 pnpm install
 ```
 
@@ -110,16 +110,9 @@ pnpm install
 Start the dev server in one terminal:
 
 ```bash
-cd my_videos/my-video1
 pnpm run dev
 ```
 
-or
-
-```bash
-pnpm --filter my-video1 dev
-```
-
 In another terminal, render your video using the server URL:
 ```bash
 open-motion render -u http://localhost:5173 -o out.mp4 --composition my-video1
diff --git a/README.zh.md b/README.zh.md
index d51308d..48abb61 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -101,7 +101,7 @@ npx playwright install chromium
 ```bash
 mkdir -p my_videos && cd my_videos
 open-motion init my-video1
-cd ../..  # 返回 monorepo 根目录
+cd my-video1
 pnpm install
 ```
 
@@ -110,16 +110,9 @@ pnpm install
 在一个终端中启动开发服务器：
 
 ```bash
-cd my_videos/my-video1
 pnpm run dev
 ```
 
-或
-
-```bash
-pnpm --filter my-video1 dev
-```
-
 在另一个终端中，使用服务器 URL 渲染视频：
 ```bash
 open-motion render -u http://localhost:5173 -o out.mp4 --composition my-video1