From 5abe92ad7a91a50cb7e091b78b3d566282ce6ad1 Mon Sep 17 00:00:00 2001
From: GitHub Action <action@github.com>
Date: Thu, 5 Mar 2026 00:22:34 +0000
Subject: [PATCH 01/20] =?UTF-8?q?SpaceStudyShip-FE=20=EB=B2=84=EC=A0=84=20?=
 =?UTF-8?q?=EA=B4=80=EB=A6=AC=20:=20docs=20:=20v1.1.31=20README=20?=
 =?UTF-8?q?=EB=B2=84=EC=A0=84=20=EC=A0=95=EB=B3=B4=20=EC=97=85=EB=8D=B0?=
 =?UTF-8?q?=EC=9D=B4=ED=8A=B8=20[skip=20ci]?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index a6671f0..7d63c0b 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,7 @@ samples, guidance on mobile development, and a full API reference.
 <!-- 이 섹션은 .github/workflows/PROJECT-README-VERSION-UPDATE.yaml에 의해 자동으로 업데이트됩니다 -->
 <!-- 수정하지마세요 자동으로 동기화 됩니다 -->
 <!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->
-## 최신 버전 : v1.1.27 (2026-02-21)
+## 최신 버전 : v1.1.31 (2026-03-05)
 
 [전체 버전 기록 보기](CHANGELOG.md)
 <!-- END-AUTO-VERSION-SECTION -->

From e91ef16677694693acb79794234c2a01a07ad827 Mon Sep 17 00:00:00 2001
From: SUH SAECHAN <chan4760@gmail.com>
Date: Thu, 5 Mar 2026 13:53:16 +0900
Subject: [PATCH 02/20] =?UTF-8?q?@suh-lab=20=EB=8C=93=EA=B8=80=20=EB=B9=8C?=
 =?UTF-8?q?=EB=93=9C=20=ED=8A=B8=EB=A6=AC=EA=B1=B0=20=EC=A0=95=EC=83=81=20?=
 =?UTF-8?q?=EC=9E=91=EB=8F=99=20:=20fix=20:=20=ED=85=8C=EC=8A=A4=ED=8A=B8?=
 =?UTF-8?q?=EB=B9=8C=EB=93=9C=20=EB=A1=9C=EC=A7=81=20=EC=A0=95=EC=83=81?=
 =?UTF-8?q?=ED=99=94=20https://github.com/SpaceStudyShip/SpaceStudyShip-FE?=
 =?UTF-8?q?/issues/49?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../PROJECT-FLUTTER-ANDROID-TEST-APK.yaml     | 509 +++++++++-----
 .../PROJECT-FLUTTER-IOS-TEST-TESTFLIGHT.yaml  | 638 ++++++++++++++----
 ...ECT-FLUTTER-SUH-LAB-APP-BUILD-TRIGGER.yaml | 235 +++++--
 3 files changed, 1045 insertions(+), 337 deletions(-)

diff --git a/.github/workflows/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml b/.github/workflows/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml
index 6279a24..eee4070 100644
--- a/.github/workflows/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml
+++ b/.github/workflows/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml
@@ -13,6 +13,7 @@
 # - APK 파일만 생성 (Play Store 배포 제거)
 # - 아티팩트로 업로드하여 다운로드 가능 (최대 500MB/아티팩트)
 # - 아티팩트 이름에 브랜치명 포함하여 구분 용이
+# - 진행 상황 댓글 시스템: 준비→빌드 단계별 실시간 업데이트
 #
 # 사용 방법:
 # 1. 기능 브랜치로 체크아웃
@@ -21,13 +22,18 @@
 # 4. 빌드 완료 후 아티팩트에서 APK 다운로드
 #
 # ===================================================================
-# 📋 필요한 GitHub Secrets
+# 🔑 필수 GitHub Secrets
 # ===================================================================
 #
+# 🔐 Release Keystore (Play Store 배포와 동일):
+# RELEASE_KEYSTORE_BASE64: 릴리즈 키스토어 파일 (base64)
+# RELEASE_KEYSTORE_PASSWORD: 키스토어 비밀번호
+# RELEASE_KEY_ALIAS: 키 별칭
+# RELEASE_KEY_PASSWORD: 키 비밀번호
+#
 # 📝 환경 설정 (선택):
-#   - ENV_FILE                  : .env 파일 내용 (앱에서 사용하는 환경변수)
-#   - DEBUG_KEYSTORE            : debug.keystore 파일 (base64 인코딩)
-#   - GOOGLE_SERVICES_JSON      : google-services.json 내용 (Firebase 사용 시)
+# ENV_FILE (선택): .env 파일 내용
+# GOOGLE_SERVICES_JSON (선택): google-services.json 내용 (Firebase 사용 시)
 #
 # ===================================================================
 
@@ -38,9 +44,9 @@ on:
   repository_dispatch:
     types: [build-android-app]
 
-# ============================================
+# ===================================================================
 # 🔧 프로젝트별 설정 (아래 값들을 수정하세요)
-# ============================================
+# ===================================================================
 env:
   FLUTTER_VERSION: "3.35.5"
   JAVA_VERSION: "17"
@@ -60,8 +66,111 @@ jobs:
       commit_hash: ${{ steps.build_info.outputs.commit_hash }}
       pr_number: ${{ steps.build_info.outputs.pr_number }}
       build_number: ${{ steps.build_info.outputs.build_number }}
+      progress_comment_id: ${{ steps.progress.outputs.comment_id }}
+      prepare_start: ${{ steps.progress.outputs.start_time }}
 
     steps:
+      - name: 브랜치 존재 여부 사전 확인
+        id: verify_branch
+        if: github.event_name == 'repository_dispatch'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const branchName = '${{ github.event.client_payload.branch_name }}';
+            const prNumber = '${{ github.event.client_payload.pr_number }}';
+            const runId = '${{ github.run_id }}';
+            const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
+
+            console.log(`🔍 브랜치 존재 여부 확인: ${branchName}`);
+
+            try {
+              await github.rest.repos.getBranch({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                branch: branchName
+              });
+              console.log(`✅ 브랜치 존재 확인됨: ${branchName}`);
+            } catch (error) {
+              if (error.status === 404) {
+                console.log(`❌ 브랜치를 찾을 수 없음: ${branchName}`);
+
+                const body = [
+                  '🤖 ❌ **Android 테스트 APK 빌드 실패 - 브랜치를 찾을 수 없습니다**',
+                  '',
+                  '| 항목 | 값 |',
+                  '|------|-----|',
+                  `| **요청된 브랜치** | \`${branchName}\` |`,
+                  `| **이슈/PR** | #${prNumber} |`,
+                  '',
+                  '### 💡 확인 사항',
+                  '1. 브랜치가 원격 저장소에 push되었는지 확인하세요',
+                  '2. "Guide by SUH-LAB" 댓글의 브랜치명이 올바른지 확인하세요',
+                  '3. 브랜치명에 오타가 없는지 확인하세요',
+                  '',
+                  `🔗 [워크플로우 로그](${runUrl})`
+                ].join('\n');
+
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: parseInt(prNumber),
+                  body: body
+                });
+
+                core.setFailed(`브랜치를 찾을 수 없습니다: ${branchName}`);
+              } else {
+                core.setFailed(`브랜치 확인 중 오류: ${error.message}`);
+              }
+            }
+
+      # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      # 진행 상황 댓글 시스템
+      # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      - name: 진행 상황 댓글 생성
+        id: progress
+        if: github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != ''
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const prNumber = parseInt('${{ github.event.client_payload.pr_number }}');
+            const branchName = '${{ github.event.client_payload.branch_name }}';
+            const buildNumber = '${{ github.event.client_payload.build_number }}';
+            const runId = '${{ github.run_id }}';
+            const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
+            const startTime = Date.now();
+
+            const body = [
+              '## 🤖 Android 테스트 APK 빌드 진행 중...',
+              '',
+              '| 단계 | 상태 | 소요 시간 |',
+              '|------|------|----------|',
+              '| 🔧 준비 | ⏳ 진행 중... | - |',
+              '| 🔨 APK 빌드 | ⏸️ 대기 | - |',
+              '',
+              '| 항목 | 값 |',
+              '|------|-----|',
+              `| **앱 버전** | \`0.0.0(${buildNumber})\` |`,
+              `| **브랜치** | \`${branchName}\` |`,
+              '',
+              `**[📋 실시간 로그 보기](${runUrl})**`,
+              '',
+              '---',
+              '*🤖 이 댓글은 자동으로 업데이트됩니다.*'
+            ].join('\n');
+
+            const { data: comment } = await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+              body: body
+            });
+
+            console.log(`✅ 진행 상황 댓글 생성 완료: #${comment.id}`);
+            core.setOutput('comment_id', comment.id);
+            core.setOutput('start_time', startTime);
+
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
@@ -160,12 +269,115 @@ jobs:
           echo "  커밋 해시: $COMMIT_SHORT"
           echo "  빌드 날짜: $BUILD_DATE"
 
+      # 진행 상황 업데이트 - 준비 완료
+      - name: 진행 상황 업데이트 - 준비 완료
+        if: github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != '' && steps.progress.outputs.comment_id != ''
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const commentId = parseInt('${{ steps.progress.outputs.comment_id }}');
+            const startTime = parseInt('${{ steps.progress.outputs.start_time }}');
+            const branchName = '${{ github.event.client_payload.branch_name }}';
+            const buildNumber = '${{ github.event.client_payload.build_number }}';
+            const runId = '${{ github.run_id }}';
+            const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
+
+            const now = Date.now();
+            const elapsed = now - startTime;
+            const minutes = Math.floor(elapsed / 60000);
+            const seconds = Math.floor((elapsed % 60000) / 1000);
+            const duration = minutes > 0 ? `${minutes}분 ${seconds}초` : `${seconds}초`;
+
+            const body = [
+              '## 🤖 Android 테스트 APK 빌드 진행 중...',
+              '',
+              '| 단계 | 상태 | 소요 시간 |',
+              '|------|------|----------|',
+              `| 🔧 준비 | ✅ 완료 | ${duration} |`,
+              '| 🔨 APK 빌드 | ⏳ 진행 중... | - |',
+              '',
+              '| 항목 | 값 |',
+              '|------|-----|',
+              `| **앱 버전** | \`0.0.0(${buildNumber})\` |`,
+              `| **브랜치** | \`${branchName}\` |`,
+              '',
+              `**[📋 실시간 로그 보기](${runUrl})**`,
+              '',
+              '---',
+              '*🤖 이 댓글은 자동으로 업데이트됩니다.*'
+            ].join('\n');
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body: body
+            });
+
+            console.log(`✅ 진행 상황 업데이트 완료: 준비 완료 (${duration})`);
+
+      # 진행 상황 업데이트 - 준비 실패
+      - name: 진행 상황 업데이트 - 준비 실패
+        if: failure() && github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != '' && steps.progress.outputs.comment_id != ''
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const commentId = parseInt('${{ steps.progress.outputs.comment_id }}');
+            const startTime = parseInt('${{ steps.progress.outputs.start_time }}');
+            const branchName = '${{ github.event.client_payload.branch_name }}';
+            const buildNumber = '${{ github.event.client_payload.build_number }}';
+            const runId = '${{ github.run_id }}';
+            const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
+
+            const now = Date.now();
+            const elapsed = now - startTime;
+            const minutes = Math.floor(elapsed / 60000);
+            const seconds = Math.floor((elapsed % 60000) / 1000);
+            const duration = minutes > 0 ? `${minutes}분 ${seconds}초` : `${seconds}초`;
+
+            const body = [
+              '## 🤖 ❌ Android 테스트 APK 빌드 실패',
+              '',
+              '| 단계 | 상태 | 소요 시간 |',
+              '|------|------|----------|',
+              `| 🔧 준비 | ❌ 실패 | ${duration} |`,
+              '| 🔨 APK 빌드 | ⏸️ 취소됨 | - |',
+              '',
+              '| 항목 | 값 |',
+              '|------|-----|',
+              `| **앱 버전** | \`0.0.0(${buildNumber})\` |`,
+              `| **브랜치** | \`${branchName}\` |`,
+              '',
+              '❌ **환경 준비 중 오류가 발생했습니다.**',
+              '',
+              `🔗 [워크플로우 실행 로그 확인](${runUrl})`
+            ].join('\n');
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body: body
+            });
+
+            console.log(`❌ 진행 상황 업데이트 완료: 준비 실패`);
+
   build-android-test:
     name: Android 테스트 APK 빌드
     runs-on: ubuntu-latest
     needs: prepare-test-build
 
     steps:
+      # 빌드 시작 시간 기록
+      - name: 빌드 시작 시간 기록
+        id: build_start
+        uses: actions/github-script@v7
+        with:
+          script: |
+            core.setOutput('time', Date.now().toString());
+
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
@@ -175,55 +387,36 @@ jobs:
       - name: Pull latest changes
         run: git pull origin ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.branch_name || github.ref_name }}
 
-      # Debug Keystore 설정 (선택적)
-      - name: Setup Debug Keystore
-        run: |
-          mkdir -p ~/.android
-          if [ -n "${{ secrets.DEBUG_KEYSTORE }}" ]; then
-            echo "${{ secrets.DEBUG_KEYSTORE }}" | base64 -d > ~/.android/debug.keystore
-            echo "✅ Debug Keystore created from secrets"
-          else
-            echo "ℹ️ DEBUG_KEYSTORE secret not provided, using default"
-          fi
-          ls -la ~/.android/ || true
-
-      # .env 파일 생성
       - name: Create .env file
         run: |
-          cat << 'EOF' > ${{ env.ENV_FILE_PATH }}
-          ${{ secrets.ENV_FILE }}
-          EOF
+          echo "${{ secrets.ENV_FILE || secrets.ENV }}" > ${{ env.ENV_FILE_PATH }}
           echo "✅ ${{ env.ENV_FILE_PATH }} file created"
 
-      # Keystore와 key.properties 설정 (선택적)
-      - name: Setup Keystore and key.properties
+      # Release Keystore 설정 (PLAYSTORE-CICD와 동일한 경로)
+      - name: Setup Release Keystore
         run: |
           mkdir -p android/app/keystore
-          if [ -n "${{ secrets.DEBUG_KEYSTORE }}" ]; then
-            echo "${{ secrets.DEBUG_KEYSTORE }}" | base64 -d > android/app/keystore/key.jks
-            echo "✅ Keystore created from DEBUG_KEYSTORE"
-            echo "storeFile=keystore/key.jks" > android/key.properties
-            echo "storePassword=android" >> android/key.properties
-            echo "keyAlias=androiddebugkey" >> android/key.properties
-            echo "keyPassword=android" >> android/key.properties
-            echo "✅ key.properties created"
-          else
-            echo "ℹ️ DEBUG_KEYSTORE not provided, skipping keystore setup"
-          fi
-          ls -la android/ || true
+          echo "${{ secrets.RELEASE_KEYSTORE_BASE64 }}" | base64 -d > android/app/keystore/key.jks
+          echo "✅ Release Keystore 생성 완료"
+          ls -la android/app/keystore/
+
+      - name: Create key.properties
+        run: |
+          cat > android/key.properties << EOF
+          storeFile=keystore/key.jks
+          storePassword=${{ secrets.RELEASE_KEYSTORE_PASSWORD }}
+          keyAlias=${{ secrets.RELEASE_KEY_ALIAS }}
+          keyPassword=${{ secrets.RELEASE_KEY_PASSWORD }}
+          EOF
+          echo "✅ key.properties 생성 완료"
 
-      # google-services.json 생성 (선택적)
-      - name: Create google-services.json
+      # Google-services.json 생성 (PLAYSTORE-CICD와 동일한 방식)
+      - name: Create Google-services.json
         run: |
-          if [ -n "${{ secrets.GOOGLE_SERVICES_JSON }}" ]; then
-            mkdir -p android/app
-            cat << 'EOF' > android/app/google-services.json
+          cat << 'EOF' > android/app/google-services.json
           ${{ secrets.GOOGLE_SERVICES_JSON }}
           EOF
-            echo "✅ google-services.json created"
-          else
-            echo "ℹ️ GOOGLE_SERVICES_JSON secret not provided, skipping"
-          fi
+          echo "✅ Google-services.json 생성 완료"
 
       # Flutter 설정
       - name: Set up Flutter
@@ -280,32 +473,24 @@ jobs:
           echo "✅ Java setup completed"
           java -version
 
-      # Android SDK 설정
-      - name: Set up Android SDK
-        uses: android-actions/setup-android@v3
-
-      - name: Verify Android SDK setup
-        run: echo "✅ Android SDK setup completed"
-
       # Ruby 설정
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "3.3"
-          bundler-cache: false
+          ruby-version: "3.4.1"
+          bundler-cache: true
 
       - name: Verify Ruby version
         run: |
           echo "✅ Ruby setup completed"
           ruby -v
 
-      # Fastlane 설치 (Bundler 방식으로 CFPropertyList 의존성 충돌 방지)
+      # Fastlane 설치
       - name: Install Fastlane
         run: |
-          printf 'source "https://rubygems.org"\ngem "fastlane"\n' > Gemfile
-          bundle install
-          echo "✅ Fastlane 설치 완료"
-          bundle exec fastlane --version
+          gem install fastlane --force
+          echo "✅ Fastlane installed"
+          fastlane --version
 
       # APK 파일명 생성
       - name: Generate APK filename
@@ -324,7 +509,7 @@ jobs:
           if [ -f "android/fastlane/Fastfile" ]; then
             echo "📦 Fastlane을 사용하여 빌드..."
             cd android
-            bundle exec fastlane build --verbose || flutter build apk --release
+            fastlane build --verbose || flutter build apk --release
           else
             echo "📦 Flutter 직접 빌드..."
             flutter build apk --release
@@ -448,115 +633,127 @@ jobs:
           echo "❌ Android 테스트 APK 빌드 실패!"
           echo "로그를 확인해주세요."
 
-      # PR/ISSUE에 빌드 완료 댓글 작성 (repository_dispatch로 트리거된 경우)
-      - name: 빌드 성공 댓글 작성
-        if: success() && github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != ''
+      # 진행 상황 최종 업데이트 - 성공
+      - name: 진행 상황 최종 업데이트 - 성공
+        if: success() && github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != '' && needs.prepare-test-build.outputs.progress_comment_id != ''
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
-            const sourceType = '${{ github.event.client_payload.source_type }}' || 'PR';
-            const prNumber = parseInt('${{ github.event.client_payload.pr_number }}');
-            const issueNumber = '${{ needs.prepare-test-build.outputs.issue_number }}';
-            const buildNumber = '${{ needs.prepare-test-build.outputs.build_number }}';
+            const commentId = parseInt('${{ needs.prepare-test-build.outputs.progress_comment_id }}');
+            const prepareStart = parseInt('${{ needs.prepare-test-build.outputs.prepare_start }}');
+            const buildStart = parseInt('${{ steps.build_start.outputs.time }}');
+            const branchName = '${{ github.event.client_payload.branch_name }}';
+            const buildNumber = '${{ github.event.client_payload.build_number }}';
             const commitHash = '${{ needs.prepare-test-build.outputs.commit_hash }}';
-            const branchName = '${{ needs.prepare-test-build.outputs.branch_name }}';
             const runId = '${{ github.run_id }}';
             const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
             const artifactUrl = `${runUrl}#artifacts`;
 
-            const body = `🤖 ✅ **Android 테스트 APK 빌드 완료**
-
-            - 앱 버전: \`0.0.0(${buildNumber})\`
-            - 브랜치: \`${branchName}\`
-            - 커밋: \`${commitHash}\`
-
-            📦 **[아티팩트 다운로드](${artifactUrl})**
-
-            🔗 [워크플로우 실행 로그](${runUrl})`;
-
-            if (sourceType === 'PR') {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: prNumber,
-                body: body
-              });
-              console.log(`✅ PR #${prNumber}에 빌드 성공 댓글 작성 완료`);
-
-              if (issueNumber && issueNumber !== '' && parseInt(issueNumber) !== prNumber) {
-                const issueBody = `🤖 ✅ **Android 테스트 APK 빌드 완료**
-
-            - 앱 버전: \`0.0.0(${buildNumber})\`
-            - 커밋: \`${commitHash}\`
-
-            📦 **[아티팩트 다운로드](${artifactUrl})**`;
-
-                await github.rest.issues.createComment({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  issue_number: parseInt(issueNumber),
-                  body: issueBody
-                });
-                console.log(`✅ 이슈 #${issueNumber}에도 빌드 성공 댓글 작성 완료`);
-              }
-            } else {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: prNumber,
-                body: body
-              });
-              console.log(`✅ ${sourceType} #${prNumber}에 빌드 성공 댓글 작성 완료`);
-            }
-
-      - name: 빌드 실패 댓글 작성
-        if: failure() && github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != ''
+            const now = Date.now();
+
+            // 준비 단계 소요 시간
+            const prepareElapsed = buildStart - prepareStart;
+            const prepareMin = Math.floor(prepareElapsed / 60000);
+            const prepareSec = Math.floor((prepareElapsed % 60000) / 1000);
+            const prepareDuration = prepareMin > 0 ? `${prepareMin}분 ${prepareSec}초` : `${prepareSec}초`;
+
+            // 빌드 단계 소요 시간
+            const buildElapsed = now - buildStart;
+            const buildMin = Math.floor(buildElapsed / 60000);
+            const buildSec = Math.floor((buildElapsed % 60000) / 1000);
+            const buildDuration = buildMin > 0 ? `${buildMin}분 ${buildSec}초` : `${buildSec}초`;
+
+            // 전체 소요 시간
+            const totalElapsed = now - prepareStart;
+            const totalMin = Math.floor(totalElapsed / 60000);
+            const totalSec = Math.floor((totalElapsed % 60000) / 1000);
+            const totalDuration = totalMin > 0 ? `${totalMin}분 ${totalSec}초` : `${totalSec}초`;
+
+            const body = [
+              '## 🤖 ✅ Android 테스트 APK 빌드 완료',
+              '',
+              '| 단계 | 상태 | 소요 시간 |',
+              '|------|------|----------|',
+              `| 🔧 준비 | ✅ 완료 | ${prepareDuration} |`,
+              `| 🔨 APK 빌드 | ✅ 완료 | ${buildDuration} |`,
+              '',
+              `**총 소요 시간: ${totalDuration}**`,
+              '',
+              '| 항목 | 값 |',
+              '|------|-----|',
+              `| **앱 버전** | \`0.0.0(${buildNumber})\` |`,
+              `| **브랜치** | \`${branchName}\` |`,
+              `| **커밋** | \`${commitHash}\` |`,
+              '',
+              `📦 **[아티팩트 다운로드](${artifactUrl})**`,
+              '',
+              `🔗 [워크플로우 실행 로그](${runUrl})`
+            ].join('\n');
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body: body
+            });
+
+            console.log(`✅ 진행 상황 최종 업데이트 완료: 전체 성공 (${totalDuration})`);
+
+      # 진행 상황 최종 업데이트 - 실패
+      - name: 진행 상황 최종 업데이트 - 실패
+        if: failure() && github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != '' && needs.prepare-test-build.outputs.progress_comment_id != ''
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
-            const sourceType = '${{ github.event.client_payload.source_type }}' || 'PR';
-            const prNumber = parseInt('${{ github.event.client_payload.pr_number }}');
-            const issueNumber = '${{ needs.prepare-test-build.outputs.issue_number }}';
-            const buildNumber = '${{ needs.prepare-test-build.outputs.build_number }}';
-            const branchName = '${{ needs.prepare-test-build.outputs.branch_name }}';
+            const commentId = parseInt('${{ needs.prepare-test-build.outputs.progress_comment_id }}');
+            const prepareStart = parseInt('${{ needs.prepare-test-build.outputs.prepare_start }}');
+            const buildStart = parseInt('${{ steps.build_start.outputs.time }}');
+            const branchName = '${{ github.event.client_payload.branch_name }}';
+            const buildNumber = '${{ github.event.client_payload.build_number }}';
+            const commitHash = '${{ needs.prepare-test-build.outputs.commit_hash }}';
             const runId = '${{ github.run_id }}';
             const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
 
-            const body = `🤖 ❌ **Android 테스트 APK 빌드 실패**
-
-            - 앱 버전: \`0.0.0(${buildNumber})\`
-            - 브랜치: \`${branchName}\`
-
-            ❌ 빌드 중 오류가 발생했습니다.
-
-            🔗 [워크플로우 실행 로그 확인](${runUrl})`;
-
-            if (sourceType === 'PR') {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: prNumber,
-                body: body
-              });
-              console.log(`✅ PR #${prNumber}에 빌드 실패 댓글 작성 완료`);
-
-              if (issueNumber && issueNumber !== '' && parseInt(issueNumber) !== prNumber) {
-                await github.rest.issues.createComment({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  issue_number: parseInt(issueNumber),
-                  body: body
-                });
-                console.log(`✅ 이슈 #${issueNumber}에도 빌드 실패 댓글 작성 완료`);
-              }
-            } else {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: prNumber,
-                body: body
-              });
-              console.log(`✅ ${sourceType} #${prNumber}에 빌드 실패 댓글 작성 완료`);
-            }
\ No newline at end of file
+            const now = Date.now();
+
+            // 준비 단계 소요 시간
+            const prepareElapsed = buildStart - prepareStart;
+            const prepareMin = Math.floor(prepareElapsed / 60000);
+            const prepareSec = Math.floor((prepareElapsed % 60000) / 1000);
+            const prepareDuration = prepareMin > 0 ? `${prepareMin}분 ${prepareSec}초` : `${prepareSec}초`;
+
+            // 빌드 단계 소요 시간
+            const buildElapsed = now - buildStart;
+            const buildMin = Math.floor(buildElapsed / 60000);
+            const buildSec = Math.floor((buildElapsed % 60000) / 1000);
+            const buildDuration = buildMin > 0 ? `${buildMin}분 ${buildSec}초` : `${buildSec}초`;
+
+            const body = [
+              '## 🤖 ❌ Android 테스트 APK 빌드 실패',
+              '',
+              '| 단계 | 상태 | 소요 시간 |',
+              '|------|------|----------|',
+              `| 🔧 준비 | ✅ 완료 | ${prepareDuration} |`,
+              `| 🔨 APK 빌드 | ❌ 실패 | ${buildDuration} |`,
+              '',
+              '| 항목 | 값 |',
+              '|------|-----|',
+              `| **앱 버전** | \`0.0.0(${buildNumber})\` |`,
+              `| **브랜치** | \`${branchName}\` |`,
+              `| **커밋** | \`${commitHash}\` |`,
+              '',
+              '❌ **APK 빌드 중 오류가 발생했습니다.**',
+              '',
+              `🔗 [워크플로우 실행 로그 확인](${runUrl})`
+            ].join('\n');
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body: body
+            });
+
+            console.log(`❌ 진행 상황 최종 업데이트 완료: APK 빌드 실패`);
diff --git a/.github/workflows/PROJECT-FLUTTER-IOS-TEST-TESTFLIGHT.yaml b/.github/workflows/PROJECT-FLUTTER-IOS-TEST-TESTFLIGHT.yaml
index fd8f94e..a76f8e5 100644
--- a/.github/workflows/PROJECT-FLUTTER-IOS-TEST-TESTFLIGHT.yaml
+++ b/.github/workflows/PROJECT-FLUTTER-IOS-TEST-TESTFLIGHT.yaml
@@ -16,6 +16,7 @@
 # - 빌드 번호는 PR번호 + 카운트 또는 GITHUB_RUN_NUMBER 사용
 # - 브랜치명에서 이슈 번호 자동 추출 (YYYYMMDD_#이슈번호_내용 형식)
 # - GitHub API로 이슈 정보 가져와서 릴리즈 노트에 포함
+# - 진행 상황 댓글 시스템: 준비→빌드→배포 단계별 실시간 업데이트
 #
 # 빌드 파이프라인:
 #   1. flutter build ios --no-codesign (Flutter 빌드)
@@ -24,23 +25,24 @@
 #   4. fastlane upload_testflight (마법사 생성 Fastfile 사용)
 #
 # ===================================================================
-# 📋 필요한 GitHub Secrets
+# 🔑 필수 GitHub Secrets
 # ===================================================================
 #
-# 🔐 Apple 인증서 & 프로비저닝 프로파일 (필수):
-#   - APPLE_CERTIFICATE_BASE64        : .p12 인증서 (base64 인코딩)
-#   - APPLE_CERTIFICATE_PASSWORD      : .p12 인증서 비밀번호
-#   - APPLE_PROVISIONING_PROFILE_BASE64 : .mobileprovision 파일 (base64 인코딩)
-#   - IOS_PROVISIONING_PROFILE_NAME   : 프로비저닝 프로파일 이름 (예: "MyApp Distribution")
+# 🔐 Apple 인증서 & 프로비저닝 프로파일:
+# APPLE_CERTIFICATE_BASE64: .p12 인증서 (base64 인코딩)
+# APPLE_CERTIFICATE_PASSWORD: .p12 인증서 비밀번호
+# APPLE_PROVISIONING_PROFILE_BASE64: .mobileprovision 파일 (base64 인코딩)
+# IOS_PROVISIONING_PROFILE_NAME: 프로비저닝 프로파일 이름
 #
-# 🔑 App Store Connect API (필수):
-#   - APP_STORE_CONNECT_API_KEY_ID    : API Key ID (10자리, 예: ABC123DEF4)
-#   - APP_STORE_CONNECT_ISSUER_ID     : Issuer ID (UUID 형식)
-#   - APP_STORE_CONNECT_API_KEY_BASE64: AuthKey_XXXXXX.p8 파일 (base64 인코딩)
+# 🔑 App Store Connect API:
+# APP_STORE_CONNECT_API_KEY_ID: API Key ID (10자리)
+# APP_STORE_CONNECT_ISSUER_ID: Issuer ID (UUID 형식)
+# APP_STORE_CONNECT_API_KEY_BASE64: AuthKey_XXXXXX.p8 파일 (base64 인코딩)
 #
 # 📝 환경 설정 (선택):
-#   - ENV_FILE                        : .env 파일 내용 (앱에서 사용하는 환경변수)
-#   - SECRETS_XCCONFIG                : ios/Flutter/Secrets.xcconfig 내용 (선택)
+# ENV_FILE (선택): .env 파일 내용
+# SECRETS_XCCONFIG (선택): ios/Flutter/Secrets.xcconfig 내용
+# GOOGLE_MAPS_API_KEY (선택): Google Maps API 키 (SECRETS_XCCONFIG 없을 때 사용)
 #
 # ===================================================================
 
@@ -51,9 +53,9 @@ on:
   repository_dispatch:
     types: [build-ios-app]
 
-# ============================================
+# ===================================================================
 # 🔧 프로젝트별 설정 (아래 값들을 수정하세요)
-# ============================================
+# ===================================================================
 env:
   FLUTTER_VERSION: "3.35.5"
   XCODE_VERSION: "26.0"  # macos-26 runner + iOS 26 SDK (TestFlight 경고 90725 대응 - 2026년 4월 필수)
@@ -61,9 +63,130 @@ env:
   ENV_FILE_PATH: ".env"
 
 jobs:
+  # ============================================
+  # 즉시 댓글 생성 (ubuntu-latest로 빠르게 실행)
+  # ============================================
+  notify-start:
+    name: 진행 상황 알림
+    runs-on: ubuntu-latest
+    if: github.event_name == 'repository_dispatch'
+
+    outputs:
+      comment_id: ${{ steps.progress.outputs.comment_id }}
+      start_time: ${{ steps.progress.outputs.start_time }}
+      branch_valid: ${{ steps.verify_branch.outputs.valid }}
+
+    steps:
+      - name: 브랜치 존재 여부 사전 확인
+        id: verify_branch
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const branchName = '${{ github.event.client_payload.branch_name }}';
+            const prNumber = '${{ github.event.client_payload.pr_number }}';
+            const runId = '${{ github.run_id }}';
+            const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
+
+            console.log(`🔍 브랜치 존재 여부 확인: ${branchName}`);
+
+            try {
+              await github.rest.repos.getBranch({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                branch: branchName
+              });
+              console.log(`✅ 브랜치 존재 확인됨: ${branchName}`);
+              core.setOutput('valid', 'true');
+            } catch (error) {
+              if (error.status === 404) {
+                console.log(`❌ 브랜치를 찾을 수 없음: ${branchName}`);
+
+                const body = [
+                  '🍎 ❌ **iOS TestFlight 빌드 실패 - 브랜치를 찾을 수 없습니다**',
+                  '',
+                  '| 항목 | 값 |',
+                  '|------|-----|',
+                  `| **요청된 브랜치** | \`${branchName}\` |`,
+                  `| **이슈/PR** | #${prNumber} |`,
+                  '',
+                  '### 💡 확인 사항',
+                  '1. 브랜치가 원격 저장소에 push되었는지 확인하세요',
+                  '2. "Guide by SUH-LAB" 댓글의 브랜치명이 올바른지 확인하세요',
+                  '3. 브랜치명에 오타가 없는지 확인하세요',
+                  '',
+                  `🔗 [워크플로우 로그](${runUrl})`
+                ].join('\n');
+
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: parseInt(prNumber),
+                  body: body
+                });
+
+                core.setFailed(`브랜치를 찾을 수 없습니다: ${branchName}`);
+              } else {
+                core.setFailed(`브랜치 확인 중 오류: ${error.message}`);
+              }
+            }
+
+      - name: 진행 상황 댓글 생성
+        id: progress
+        if: github.event.client_payload.pr_number != ''
+        continue-on-error: true
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const prNumber = parseInt('${{ github.event.client_payload.pr_number }}');
+            const branchName = '${{ github.event.client_payload.branch_name }}';
+            const buildNumber = '${{ github.event.client_payload.build_number }}';
+            const runId = '${{ github.run_id }}';
+            const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
+            const startTime = Date.now();
+
+            const body = [
+              '## 🍎 iOS TestFlight 빌드 진행 중...',
+              '',
+              '| 단계 | 상태 | 소요 시간 |',
+              '|------|------|----------|',
+              '| 🔧 준비 | ⏳ 진행 중... | - |',
+              '| 🔨 IPA 빌드 | ⏸️ 대기 | - |',
+              '| 📤 TestFlight 배포 | ⏸️ 대기 | - |',
+              '',
+              '| 항목 | 값 |',
+              '|------|-----|',
+              `| **앱 버전** | \`0.0.0(${buildNumber})\` |`,
+              `| **브랜치** | \`${branchName}\` |`,
+              '',
+              `**[📋 실시간 로그 보기](${runUrl})**`,
+              '',
+              '---',
+              '*🤖 이 댓글은 자동으로 업데이트됩니다.*'
+            ].join('\n');
+
+            const { data: comment } = await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+              body: body
+            });
+
+            console.log(`✅ 진행 상황 댓글 생성 완료: #${comment.id}`);
+            core.setOutput('comment_id', comment.id);
+            core.setOutput('start_time', startTime);
+
+  # ============================================
+  # 테스트 빌드 준비 (macOS 환경 설정)
+  # ============================================
   prepare-test-build:
     name: 테스트 빌드 준비
-    runs-on: macos-26  # iOS 26 SDK 지원 (2026년 4월 App Store 정책 대응)
+    runs-on: macos-26
+    needs: notify-start
+    if: |
+      always() &&
+      (needs.notify-start.result == 'skipped' || needs.notify-start.outputs.branch_valid == 'true')
 
     outputs:
       version: ${{ steps.test_version.outputs.version }}
@@ -87,24 +210,19 @@ jobs:
 
       - name: Select Xcode 26 and verify SDK
         run: |
-          # Xcode 26 명시적 선택
           sudo xcode-select -s /Applications/Xcode_${{ env.XCODE_VERSION }}.app/Contents/Developer || true
 
-          # 현재 Xcode 버전 확인
           echo "📱 Current Xcode version:"
           xcodebuild -version
 
-          # 사용 가능한 iOS SDK 목록
           echo ""
           echo "📦 Available iOS SDKs:"
           xcodebuild -showsdks | grep "iOS"
 
-          # xcode-select 경로 확인
           echo ""
           echo "🎯 xcode-select path:"
           xcode-select -p
 
-          # iOS 26 SDK 존재 여부 확인 (필수)
           echo ""
           if xcodebuild -showsdks | grep -q "iOS 26"; then
             echo "✅ iOS 26 SDK available - TestFlight warning 90725 will be resolved"
@@ -118,10 +236,11 @@ jobs:
       - name: Create .env file
         run: |
           cat << 'EOF' > ${{ env.ENV_FILE_PATH }}
-          ${{ secrets.ENV_FILE }}
+          ${{ secrets.ENV_FILE || secrets.ENV }}
           EOF
           echo "✅ ${{ env.ENV_FILE_PATH }} file created"
 
+      # Secrets.xcconfig 생성 (IOS-TESTFLIGHT.yaml과 동일한 로직)
       - name: Create Secrets.xcconfig file
         run: |
           mkdir -p ios/Flutter
@@ -146,7 +265,6 @@ jobs:
         run: |
           echo "🔒 보안 검증: API 키가 노출되지 않았는지 확인"
 
-          # iOS Secrets.xcconfig 확인
           if [ -f ios/Flutter/Secrets.xcconfig ]; then
             echo "✅ ios/Flutter/Secrets.xcconfig exists"
             if grep -q "GOOGLE_MAPS_API_KEY" ios/Flutter/Secrets.xcconfig; then
@@ -290,15 +408,126 @@ jobs:
             assets/
           retention-days: 1
 
+      # 진행 상황 업데이트 - 준비 완료
+      - name: 진행 상황 업데이트 - 준비 완료
+        if: github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != '' && needs.notify-start.outputs.comment_id != ''
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const commentId = parseInt('${{ needs.notify-start.outputs.comment_id }}');
+            const startTime = parseInt('${{ needs.notify-start.outputs.start_time }}');
+            const branchName = '${{ github.event.client_payload.branch_name }}';
+            const buildNumber = '${{ github.event.client_payload.build_number }}';
+            const runId = '${{ github.run_id }}';
+            const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
+
+            const now = Date.now();
+            const elapsed = now - startTime;
+            const minutes = Math.floor(elapsed / 60000);
+            const seconds = Math.floor((elapsed % 60000) / 1000);
+            const duration = minutes > 0 ? `${minutes}분 ${seconds}초` : `${seconds}초`;
+
+            const body = [
+              '## 🍎 iOS TestFlight 빌드 진행 중...',
+              '',
+              '| 단계 | 상태 | 소요 시간 |',
+              '|------|------|----------|',
+              `| 🔧 준비 | ✅ 완료 | ${duration} |`,
+              '| 🔨 IPA 빌드 | ⏳ 진행 중... | - |',
+              '| 📤 TestFlight 배포 | ⏸️ 대기 | - |',
+              '',
+              '| 항목 | 값 |',
+              '|------|-----|',
+              `| **앱 버전** | \`0.0.0(${buildNumber})\` |`,
+              `| **브랜치** | \`${branchName}\` |`,
+              '',
+              `**[📋 실시간 로그 보기](${runUrl})**`,
+              '',
+              '---',
+              '*🤖 이 댓글은 자동으로 업데이트됩니다.*'
+            ].join('\n');
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body: body
+            });
+
+            console.log(`✅ 진행 상황 업데이트 완료: 준비 완료 (${duration})`);
+
+      # 진행 상황 업데이트 - 준비 실패
+      - name: 진행 상황 업데이트 - 준비 실패
+        if: failure() && github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != '' && needs.notify-start.outputs.comment_id != ''
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const commentId = parseInt('${{ needs.notify-start.outputs.comment_id }}');
+            const startTime = parseInt('${{ needs.notify-start.outputs.start_time }}');
+            const branchName = '${{ github.event.client_payload.branch_name }}';
+            const buildNumber = '${{ github.event.client_payload.build_number }}';
+            const runId = '${{ github.run_id }}';
+            const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
+
+            const now = Date.now();
+            const elapsed = now - startTime;
+            const minutes = Math.floor(elapsed / 60000);
+            const seconds = Math.floor((elapsed % 60000) / 1000);
+            const duration = minutes > 0 ? `${minutes}분 ${seconds}초` : `${seconds}초`;
+
+            const body = [
+              '## 🍎 ❌ iOS TestFlight 빌드 실패',
+              '',
+              '| 단계 | 상태 | 소요 시간 |',
+              '|------|------|----------|',
+              `| 🔧 준비 | ❌ 실패 | ${duration} |`,
+              '| 🔨 IPA 빌드 | ⏸️ 취소됨 | - |',
+              '| 📤 TestFlight 배포 | ⏸️ 취소됨 | - |',
+              '',
+              '| 항목 | 값 |',
+              '|------|-----|',
+              `| **앱 버전** | \`0.0.0(${buildNumber})\` |`,
+              `| **브랜치** | \`${branchName}\` |`,
+              '',
+              '❌ **환경 준비 중 오류가 발생했습니다.**',
+              '',
+              `🔗 [워크플로우 실행 로그 확인](${runUrl})`
+            ].join('\n');
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body: body
+            });
+
+            console.log(`❌ 진행 상황 업데이트 완료: 준비 실패`);
+
   # ============================================
   # iOS 빌드 (xcodebuild 직접 사용)
   # ============================================
   build-ios-test:
     name: iOS 테스트 빌드
-    runs-on: macos-26  # iOS 26 SDK 지원 (2026년 4월 App Store 정책 대응)
-    needs: prepare-test-build
+    runs-on: macos-26
+    needs: [notify-start, prepare-test-build]
+    if: |
+      !cancelled() &&
+      needs.prepare-test-build.result == 'success'
+
+    outputs:
+      build_start: ${{ steps.build_start.outputs.time }}
 
     steps:
+      # 빌드 시작 시간 기록
+      - name: 빌드 시작 시간 기록
+        id: build_start
+        uses: actions/github-script@v7
+        with:
+          script: |
+            core.setOutput('time', Date.now().toString());
+
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
@@ -310,24 +539,19 @@ jobs:
 
       - name: Select Xcode 26 and verify SDK
         run: |
-          # Xcode 26 명시적 선택
           sudo xcode-select -s /Applications/Xcode_${{ env.XCODE_VERSION }}.app/Contents/Developer || true
 
-          # 현재 Xcode 버전 확인
           echo "📱 Current Xcode version:"
           xcodebuild -version
 
-          # 사용 가능한 iOS SDK 목록
           echo ""
           echo "📦 Available iOS SDKs:"
           xcodebuild -showsdks | grep "iOS"
 
-          # xcode-select 경로 확인
           echo ""
           echo "🎯 xcode-select path:"
           xcode-select -p
 
-          # iOS 26 SDK 존재 여부 확인 (필수)
           echo ""
           if xcodebuild -showsdks | grep -q "iOS 26"; then
             echo "✅ iOS 26 SDK available - TestFlight warning 90725 will be resolved"
@@ -348,7 +572,7 @@ jobs:
         run: |
           if [ ! -f "${{ env.ENV_FILE_PATH }}" ]; then
             cat << 'EOF' > ${{ env.ENV_FILE_PATH }}
-          ${{ secrets.ENV_FILE }}
+          ${{ secrets.ENV_FILE || secrets.ENV }}
           EOF
             echo "✅ ${{ env.ENV_FILE_PATH }} file created (fallback)"
           fi
@@ -454,15 +678,143 @@ jobs:
             build-metadata.json
           retention-days: 1
 
+      # 진행 상황 업데이트 - IPA 빌드 완료
+      - name: 진행 상황 업데이트 - IPA 빌드 완료
+        if: success() && github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != '' && needs.notify-start.outputs.comment_id != ''
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const commentId = parseInt('${{ needs.notify-start.outputs.comment_id }}');
+            const prepareStart = parseInt('${{ needs.notify-start.outputs.start_time }}');
+            const buildStart = parseInt('${{ steps.build_start.outputs.time }}');
+            const branchName = '${{ github.event.client_payload.branch_name }}';
+            const buildNumber = '${{ github.event.client_payload.build_number }}';
+            const runId = '${{ github.run_id }}';
+            const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
+
+            const now = Date.now();
+
+            // 준비 단계 소요 시간
+            const prepareElapsed = buildStart - prepareStart;
+            const prepareMin = Math.floor(prepareElapsed / 60000);
+            const prepareSec = Math.floor((prepareElapsed % 60000) / 1000);
+            const prepareDuration = prepareMin > 0 ? `${prepareMin}분 ${prepareSec}초` : `${prepareSec}초`;
+
+            // 빌드 단계 소요 시간
+            const buildElapsed = now - buildStart;
+            const buildMin = Math.floor(buildElapsed / 60000);
+            const buildSec = Math.floor((buildElapsed % 60000) / 1000);
+            const buildDuration = buildMin > 0 ? `${buildMin}분 ${buildSec}초` : `${buildSec}초`;
+
+            const body = [
+              '## 🍎 ✅ iOS 빌드 완료',
+              '',
+              '| 단계 | 상태 | 소요 시간 |',
+              '|------|------|----------|',
+              `| 🔧 준비 | ✅ 완료 | ${prepareDuration} |`,
+              `| 🔨 IPA 빌드 | ✅ 완료 | ${buildDuration} |`,
+              '| 📤 TestFlight 배포 | ⏳ 진행 중... | - |',
+              '',
+              '| 항목 | 값 |',
+              '|------|-----|',
+              `| **앱 버전** | \`0.0.0(${buildNumber})\` |`,
+              `| **브랜치** | \`${branchName}\` |`,
+              '',
+              `**[📋 실시간 로그 보기](${runUrl})**`,
+              '',
+              '---',
+              '*🤖 이 댓글은 자동으로 업데이트됩니다.*'
+            ].join('\n');
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body: body
+            });
+
+            console.log(`✅ 진행 상황 업데이트 완료: IPA 빌드 완료 (${buildDuration})`);
+
+      # 빌드 실패 시 progress 댓글 업데이트
+      - name: 빌드 실패 시 progress 댓글 업데이트
+        if: failure() && github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != '' && needs.notify-start.outputs.comment_id != ''
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const commentId = parseInt('${{ needs.notify-start.outputs.comment_id }}');
+            const prepareStart = parseInt('${{ needs.notify-start.outputs.start_time }}');
+            const buildStart = parseInt('${{ steps.build_start.outputs.time }}');
+            const branchName = '${{ github.event.client_payload.branch_name }}';
+            const buildNumber = '${{ github.event.client_payload.build_number }}';
+            const commitHash = '${{ needs.prepare-test-build.outputs.commit_hash }}';
+            const runId = '${{ github.run_id }}';
+            const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
+
+            const now = Date.now();
+
+            // 준비 단계 소요 시간
+            const prepareElapsed = buildStart - prepareStart;
+            const prepareMin = Math.floor(prepareElapsed / 60000);
+            const prepareSec = Math.floor((prepareElapsed % 60000) / 1000);
+            const prepareDuration = prepareMin > 0 ? `${prepareMin}분 ${prepareSec}초` : `${prepareSec}초`;
+
+            // 빌드 단계 소요 시간
+            const buildElapsed = now - buildStart;
+            const buildMin = Math.floor(buildElapsed / 60000);
+            const buildSec = Math.floor((buildElapsed % 60000) / 1000);
+            const buildDuration = buildMin > 0 ? `${buildMin}분 ${buildSec}초` : `${buildSec}초`;
+
+            const body = [
+              '## 🍎 ❌ iOS TestFlight 빌드 실패',
+              '',
+              '| 단계 | 상태 | 소요 시간 |',
+              '|------|------|----------|',
+              `| 🔧 준비 | ✅ 완료 | ${prepareDuration} |`,
+              `| 🔨 IPA 빌드 | ❌ 실패 | ${buildDuration} |`,
+              '| 📤 TestFlight 배포 | ⏸️ 취소됨 | - |',
+              '',
+              '| 항목 | 값 |',
+              '|------|-----|',
+              `| **앱 버전** | \`0.0.0(${buildNumber})\` |`,
+              `| **브랜치** | \`${branchName}\` |`,
+              `| **커밋** | \`${commitHash}\` |`,
+              '',
+              '❌ **IPA 빌드 중 오류가 발생했습니다.**',
+              '',
+              `🔗 [워크플로우 실행 로그 확인](${runUrl})`
+            ].join('\n');
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body: body
+            });
+
+            console.log(`❌ 진행 상황 업데이트 완료: IPA 빌드 실패`);
+
   # ============================================
   # TestFlight 배포 (마법사 생성 Fastfile 사용)
   # ============================================
   deploy-testflight-test:
     name: TestFlight 테스트 배포
-    runs-on: macos-15
-    needs: [prepare-test-build, build-ios-test]
+    runs-on: macos-26
+    needs: [notify-start, prepare-test-build, build-ios-test]
+    if: |
+      !cancelled() &&
+      needs.build-ios-test.result == 'success'
 
     steps:
+      # 배포 시작 시간 기록
+      - name: 배포 시작 시간 기록
+        id: deploy_start
+        uses: actions/github-script@v7
+        with:
+          script: |
+            core.setOutput('time', Date.now().toString());
+
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
@@ -496,7 +848,7 @@ jobs:
           fi
           echo "✅ Fastfile 확인됨: ios/fastlane/Fastfile"
 
-      # Fastlane 설치 (Bundler 방식으로 CFPropertyList 의존성 충돌 방지)
+      # Fastlane 설치 (IOS-TESTFLIGHT.yaml과 동일한 Bundler 방식)
       - name: Install Fastlane
         run: |
           printf 'source "https://rubygems.org"\ngem "fastlane"\n' > Gemfile
@@ -563,114 +915,142 @@ jobs:
           echo "❌ TestFlight 테스트 빌드 업로드 실패!"
           echo "로그를 확인해주세요."
 
-      # PR/ISSUE에 빌드 완료 댓글 작성 (repository_dispatch로 트리거된 경우)
-      - name: 빌드 성공 댓글 작성
-        if: success() && github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != ''
+      # 진행 상황 최종 업데이트 - 성공
+      - name: 진행 상황 최종 업데이트 - 성공
+        if: success() && github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != '' && needs.notify-start.outputs.comment_id != ''
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
-            const sourceType = '${{ github.event.client_payload.source_type }}' || 'PR';
-            const prNumber = parseInt('${{ github.event.client_payload.pr_number }}');
-            const issueNumber = '${{ needs.prepare-test-build.outputs.issue_number }}';
-            const buildNumber = '${{ needs.prepare-test-build.outputs.build_number }}';
+            const commentId = parseInt('${{ needs.notify-start.outputs.comment_id }}');
+            const prepareStart = parseInt('${{ needs.notify-start.outputs.start_time }}');
+            const buildStart = parseInt('${{ needs.build-ios-test.outputs.build_start }}');
+            const deployStart = parseInt('${{ steps.deploy_start.outputs.time }}');
+            const branchName = '${{ github.event.client_payload.branch_name }}';
+            const buildNumber = '${{ github.event.client_payload.build_number }}';
             const commitHash = '${{ needs.prepare-test-build.outputs.commit_hash }}';
-            const branchName = '${{ needs.prepare-test-build.outputs.branch_name }}';
             const runId = '${{ github.run_id }}';
             const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
 
-            const body = `🍎 ✅ **iOS TestFlight 빌드 완료**
-
-            - 앱 버전: \`0.0.0(${buildNumber})\`
-            - 브랜치: \`${branchName}\`
-            - 커밋: \`${commitHash}\`
-
-            📱 **TestFlight에서 테스트 앱을 다운로드할 수 있습니다.**
-
-            🔗 [워크플로우 실행 로그](${runUrl})`;
-
-            if (sourceType === 'PR') {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: prNumber,
-                body: body
-              });
-              console.log(`✅ PR #${prNumber}에 빌드 성공 댓글 작성 완료`);
-
-              if (issueNumber && issueNumber !== '' && parseInt(issueNumber) !== prNumber) {
-                const issueBody = `🍎 ✅ **iOS TestFlight 빌드 완료**
-
-            - 앱 버전: \`0.0.0(${buildNumber})\`
-            - 커밋: \`${commitHash}\`
-
-            📱 **TestFlight에서 테스트 앱을 다운로드할 수 있습니다.**`;
-
-                await github.rest.issues.createComment({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  issue_number: parseInt(issueNumber),
-                  body: issueBody
-                });
-                console.log(`✅ 이슈 #${issueNumber}에도 빌드 성공 댓글 작성 완료`);
-              }
-            } else {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: prNumber,
-                body: body
-              });
-              console.log(`✅ ${sourceType} #${prNumber}에 빌드 성공 댓글 작성 완료`);
-            }
-
-      - name: 빌드 실패 댓글 작성
-        if: failure() && github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != ''
+            const now = Date.now();
+
+            // 준비 단계 소요 시간
+            const prepareElapsed = buildStart - prepareStart;
+            const prepareMin = Math.floor(prepareElapsed / 60000);
+            const prepareSec = Math.floor((prepareElapsed % 60000) / 1000);
+            const prepareDuration = prepareMin > 0 ? `${prepareMin}분 ${prepareSec}초` : `${prepareSec}초`;
+
+            // 빌드 단계 소요 시간
+            const buildElapsed = deployStart - buildStart;
+            const buildMin = Math.floor(buildElapsed / 60000);
+            const buildSec = Math.floor((buildElapsed % 60000) / 1000);
+            const buildDuration = buildMin > 0 ? `${buildMin}분 ${buildSec}초` : `${buildSec}초`;
+
+            // 배포 단계 소요 시간
+            const deployElapsed = now - deployStart;
+            const deployMin = Math.floor(deployElapsed / 60000);
+            const deploySec = Math.floor((deployElapsed % 60000) / 1000);
+            const deployDuration = deployMin > 0 ? `${deployMin}분 ${deploySec}초` : `${deploySec}초`;
+
+            // 전체 소요 시간
+            const totalElapsed = now - prepareStart;
+            const totalMin = Math.floor(totalElapsed / 60000);
+            const totalSec = Math.floor((totalElapsed % 60000) / 1000);
+            const totalDuration = totalMin > 0 ? `${totalMin}분 ${totalSec}초` : `${totalSec}초`;
+
+            const body = [
+              '## 🍎 ✅ iOS TestFlight 배포 완료',
+              '',
+              '| 단계 | 상태 | 소요 시간 |',
+              '|------|------|----------|',
+              `| 🔧 준비 | ✅ 완료 | ${prepareDuration} |`,
+              `| 🔨 IPA 빌드 | ✅ 완료 | ${buildDuration} |`,
+              `| 📤 TestFlight 배포 | ✅ 완료 | ${deployDuration} |`,
+              '',
+              `**총 소요 시간: ${totalDuration}**`,
+              '',
+              '| 항목 | 값 |',
+              '|------|-----|',
+              `| **앱 버전** | \`0.0.0(${buildNumber})\` |`,
+              `| **브랜치** | \`${branchName}\` |`,
+              `| **커밋** | \`${commitHash}\` |`,
+              '',
+              '📱 **TestFlight에서 테스트 앱을 다운로드할 수 있습니다.**',
+              '',
+              `🔗 [워크플로우 실행 로그](${runUrl})`
+            ].join('\n');
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body: body
+            });
+
+            console.log(`✅ 진행 상황 최종 업데이트 완료: 전체 성공 (${totalDuration})`);
+
+      # 진행 상황 최종 업데이트 - 실패
+      - name: 진행 상황 최종 업데이트 - 실패
+        if: failure() && github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != '' && needs.notify-start.outputs.comment_id != ''
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
-            const sourceType = '${{ github.event.client_payload.source_type }}' || 'PR';
-            const prNumber = parseInt('${{ github.event.client_payload.pr_number }}');
-            const issueNumber = '${{ needs.prepare-test-build.outputs.issue_number }}';
-            const buildNumber = '${{ needs.prepare-test-build.outputs.build_number }}';
-            const branchName = '${{ needs.prepare-test-build.outputs.branch_name }}';
+            const commentId = parseInt('${{ needs.notify-start.outputs.comment_id }}');
+            const prepareStart = parseInt('${{ needs.notify-start.outputs.start_time }}');
+            const buildStart = parseInt('${{ needs.build-ios-test.outputs.build_start }}');
+            const deployStart = parseInt('${{ steps.deploy_start.outputs.time }}');
+            const branchName = '${{ github.event.client_payload.branch_name }}';
+            const buildNumber = '${{ github.event.client_payload.build_number }}';
+            const commitHash = '${{ needs.prepare-test-build.outputs.commit_hash }}';
             const runId = '${{ github.run_id }}';
             const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
 
-            const body = `🍎 ❌ **iOS TestFlight 빌드 실패**
-
-            - 앱 버전: \`0.0.0(${buildNumber})\`
-            - 브랜치: \`${branchName}\`
-
-            ❌ 빌드 중 오류가 발생했습니다.
-
-            🔗 [워크플로우 실행 로그 확인](${runUrl})`;
-
-            if (sourceType === 'PR') {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: prNumber,
-                body: body
-              });
-              console.log(`✅ PR #${prNumber}에 빌드 실패 댓글 작성 완료`);
-
-              if (issueNumber && issueNumber !== '' && parseInt(issueNumber) !== prNumber) {
-                await github.rest.issues.createComment({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  issue_number: parseInt(issueNumber),
-                  body: body
-                });
-                console.log(`✅ 이슈 #${issueNumber}에도 빌드 실패 댓글 작성 완료`);
-              }
-            } else {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: prNumber,
-                body: body
-              });
-              console.log(`✅ ${sourceType} #${prNumber}에 빌드 실패 댓글 작성 완료`);
-            }
+            const now = Date.now();
+
+            // 준비 단계 소요 시간
+            const prepareElapsed = buildStart - prepareStart;
+            const prepareMin = Math.floor(prepareElapsed / 60000);
+            const prepareSec = Math.floor((prepareElapsed % 60000) / 1000);
+            const prepareDuration = prepareMin > 0 ? `${prepareMin}분 ${prepareSec}초` : `${prepareSec}초`;
+
+            // 빌드 단계 소요 시간
+            const buildElapsed = deployStart - buildStart;
+            const buildMin = Math.floor(buildElapsed / 60000);
+            const buildSec = Math.floor((buildElapsed % 60000) / 1000);
+            const buildDuration = buildMin > 0 ? `${buildMin}분 ${buildSec}초` : `${buildSec}초`;
+
+            // 배포 단계 소요 시간
+            const deployElapsed = now - deployStart;
+            const deployMin = Math.floor(deployElapsed / 60000);
+            const deploySec = Math.floor((deployElapsed % 60000) / 1000);
+            const deployDuration = deployMin > 0 ? `${deployMin}분 ${deploySec}초` : `${deploySec}초`;
+
+            const body = [
+              '## 🍎 ❌ iOS TestFlight 배포 실패',
+              '',
+              '| 단계 | 상태 | 소요 시간 |',
+              '|------|------|----------|',
+              `| 🔧 준비 | ✅ 완료 | ${prepareDuration} |`,
+              `| 🔨 IPA 빌드 | ✅ 완료 | ${buildDuration} |`,
+              `| 📤 TestFlight 배포 | ❌ 실패 | ${deployDuration} |`,
+              '',
+              '| 항목 | 값 |',
+              '|------|-----|',
+              `| **앱 버전** | \`0.0.0(${buildNumber})\` |`,
+              `| **브랜치** | \`${branchName}\` |`,
+              `| **커밋** | \`${commitHash}\` |`,
+              '',
+              '❌ **TestFlight 배포 중 오류가 발생했습니다.**',
+              '',
+              `🔗 [워크플로우 실행 로그 확인](${runUrl})`
+            ].join('\n');
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body: body
+            });
+
+            console.log(`❌ 진행 상황 최종 업데이트 완료: TestFlight 배포 실패`);
diff --git a/.github/workflows/PROJECT-FLUTTER-SUH-LAB-APP-BUILD-TRIGGER.yaml b/.github/workflows/PROJECT-FLUTTER-SUH-LAB-APP-BUILD-TRIGGER.yaml
index c693b4f..837b2ae 100644
--- a/.github/workflows/PROJECT-FLUTTER-SUH-LAB-APP-BUILD-TRIGGER.yaml
+++ b/.github/workflows/PROJECT-FLUTTER-SUH-LAB-APP-BUILD-TRIGGER.yaml
@@ -2,19 +2,21 @@
 # Flutter 테스트 앱 빌드 트리거 워크플로우 (SUH-LAB)
 # ===================================================================
 #
-# 이 워크플로우는 PR 또는 이슈에 댓글로 "@suh-lab build app"을 작성하면
+# 이 워크플로우는 PR 또는 이슈에 댓글로 빌드 명령어를 작성하면
 # Android와 iOS 테스트 앱 빌드를 자동으로 트리거합니다.
 #
 # 주요 특징:
-# - PR/이슈 댓글 감지: "@suh-lab build app" 키워드 감지
+# - PR/이슈 댓글 감지: "@suh-lab build app/apk build/ios build" 키워드 감지
 # - repository_dispatch 이벤트로 빌드 워크플로우 트리거
 # - PR/이슈 번호 + 빌드 횟수로 고유한 빌드 번호 생성 (예: 38700, 38701...)
 # - 브랜치명에서 이슈 번호 자동 추출 (YYYYMMDD_#이슈번호_내용 형식)
 # - 테스트 버전 0.0.0 고정으로 운영 버전과 분리
 #
 # 사용 방법:
-# - PR에 댓글 작성: "@suh-lab build app"
-# - 이슈에 댓글 작성: "@suh-lab build app" (Guide by SUH-LAB 댓글 필요)
+# - PR에 댓글 작성: "@suh-lab build app" (Android + iOS 모두 빌드)
+# - PR에 댓글 작성: "@suh-lab apk build" (Android만 빌드)
+# - PR에 댓글 작성: "@suh-lab ios build" (iOS만 빌드)
+# - 이슈에 댓글 작성: 위 명령어 동일 (Guide by SUH-LAB 댓글 필요)
 #
 # 트리거되는 워크플로우:
 # - PROJECT-FLUTTER-ANDROID-TEST-APK.yaml (event_type: build-android-app)
@@ -36,11 +38,14 @@ permissions:
 jobs:
   trigger-builds:
     name: 빌드 워크플로우 트리거
-    # @suh-lab, build, app 키워드가 모두 포함되어 있으면 실행
+    # @suh-lab build app / @suh-lab apk build / @suh-lab ios build 키워드 감지
     if: |
       contains(github.event.comment.body, '@suh-lab') &&
-      contains(github.event.comment.body, 'build') &&
-      contains(github.event.comment.body, 'app')
+      (
+        (contains(github.event.comment.body, 'build') && contains(github.event.comment.body, 'app')) ||
+        (contains(github.event.comment.body, 'apk') && contains(github.event.comment.body, 'build')) ||
+        (contains(github.event.comment.body, 'ios') && contains(github.event.comment.body, 'build'))
+      )
     runs-on: ubuntu-latest
 
     steps:
@@ -60,6 +65,39 @@ jobs:
 
             console.log('👀 댓글에 확인 리액션 추가 완료');
 
+      - name: 빌드 타입 판별
+        id: build_type
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const comment = context.payload.comment.body.toLowerCase();
+
+            let buildAndroid = false;
+            let buildIos = false;
+            let buildType = '';
+
+            if (comment.includes('build') && comment.includes('app')) {
+              // @suh-lab build app → 양쪽 모두
+              buildAndroid = true;
+              buildIos = true;
+              buildType = 'app';
+            } else if (comment.includes('apk') && comment.includes('build')) {
+              // @suh-lab apk build → Android만
+              buildAndroid = true;
+              buildType = 'apk';
+            } else if (comment.includes('ios') && comment.includes('build')) {
+              // @suh-lab ios build → iOS만
+              buildIos = true;
+              buildType = 'ios';
+            }
+
+            core.setOutput('buildAndroid', buildAndroid.toString());
+            core.setOutput('buildIos', buildIos.toString());
+            core.setOutput('buildType', buildType);
+
+            console.log(`📱 빌드 타입: ${buildType} (Android=${buildAndroid}, iOS=${buildIos})`);
+
       - name: PR/이슈 정보 확인 및 추출
         id: source_info
         uses: actions/github-script@v7
@@ -167,14 +205,85 @@ jobs:
             const issueNumber = context.payload.issue.number;
             const errorMessage = '${{ steps.source_info.outputs.errorMessage }}';
 
-            const body = `❌ **앱 빌드 트리거 실패**
+            const body = [
+              '❌ **앱 빌드 트리거 실패**',
+              '',
+              errorMessage,
+              '',
+              '**해결 방법:**',
+              '- PR에서 빌드하는 경우: PR 페이지에서 댓글을 작성해주세요.',
+              '- 이슈에서 빌드하는 경우: "Guide by SUH-LAB" 댓글이 있어야 합니다.',
+              '  - 댓글에 `### 브랜치` 섹션과 브랜치명이 포함되어 있어야 합니다.'
+            ].join('\n');
 
-            ${errorMessage}
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issueNumber,
+              body: body
+            });
+
+            core.setFailed(errorMessage);
 
-            **해결 방법:**
-            - PR에서 빌드하는 경우: PR 페이지에서 댓글을 작성해주세요.
-            - 이슈에서 빌드하는 경우: "Guide by SUH-LAB" 댓글이 있어야 합니다.
-              - 댓글에 \`### 브랜치\` 섹션과 브랜치명이 포함되어 있어야 합니다.`;
+      - name: 브랜치 존재 여부 확인
+        id: check_branch
+        if: steps.source_info.outputs.found == 'true'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const branchName = '${{ steps.source_info.outputs.branchName }}';
+            const runId = '${{ github.run_id }}';
+            const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
+
+            console.log(`🔍 브랜치 존재 여부 확인: ${branchName}`);
+
+            try {
+              await github.rest.repos.getBranch({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                branch: branchName
+              });
+              console.log(`✅ 브랜치 존재 확인됨: ${branchName}`);
+              core.setOutput('exists', 'true');
+            } catch (error) {
+              if (error.status === 404) {
+                console.log(`❌ 브랜치를 찾을 수 없음: ${branchName}`);
+                core.setOutput('exists', 'false');
+                core.setOutput('errorMessage', `브랜치 \`${branchName}\`를 찾을 수 없습니다.`);
+              } else {
+                console.log(`❌ 브랜치 확인 중 오류: ${error.message}`);
+                core.setOutput('exists', 'false');
+                core.setOutput('errorMessage', `브랜치 확인 중 오류가 발생했습니다: ${error.message}`);
+              }
+            }
+
+      - name: 브랜치가 존재하지 않는 경우 에러 댓글 작성
+        if: steps.source_info.outputs.found == 'true' && steps.check_branch.outputs.exists == 'false'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const issueNumber = context.payload.issue.number;
+            const branchName = '${{ steps.source_info.outputs.branchName }}';
+            const runId = '${{ github.run_id }}';
+            const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
+
+            const body = [
+              '❌ **앱 빌드 트리거 실패 - 브랜치를 찾을 수 없습니다**',
+              '',
+              '| 항목 | 값 |',
+              '|------|-----|',
+              `| **요청된 브랜치** | \`${branchName}\` |`,
+              `| **이슈/PR** | #${issueNumber} |`,
+              '',
+              '### 💡 확인 사항',
+              '1. 브랜치가 원격 저장소에 push되었는지 확인하세요',
+              '2. "Guide by SUH-LAB" 댓글의 브랜치명이 올바른지 확인하세요',
+              '3. 브랜치명에 오타가 없는지 확인하세요',
+              '',
+              `🔗 [워크플로우 로그](${runUrl})`
+            ].join('\n');
 
             await github.rest.issues.createComment({
               owner: context.repo.owner,
@@ -183,19 +292,21 @@ jobs:
               body: body
             });
 
-            core.setFailed(errorMessage);
+            core.setFailed(`브랜치를 찾을 수 없습니다: ${branchName}`);
 
       - name: 빌드 횟수 조회 및 빌드 번호 생성
         id: build_number_calc
-        if: steps.source_info.outputs.found == 'true'
+        if: steps.source_info.outputs.found == 'true' && steps.check_branch.outputs.exists == 'true'
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
             const sourceNumber = parseInt('${{ steps.source_info.outputs.sourceNumber }}');
             const sourceType = '${{ steps.source_info.outputs.sourceType }}';
+            const buildType = '${{ steps.build_type.outputs.buildType }}';
 
             console.log(`📊 ${sourceType} #${sourceNumber}의 빌드 횟수 조회 중...`);
+            console.log(`📱 빌드 타입: ${buildType}`);
 
             // PR/이슈의 모든 댓글 조회
             const comments = await github.rest.issues.listComments({
@@ -205,22 +316,61 @@ jobs:
               per_page: 100
             });
 
-            // "앱 빌드 트리거 완료" 댓글 개수 = 이전 빌드 횟수
-            const buildCount = comments.data.filter(c =>
-              c.body.includes('앱 빌드 트리거 완료')
-            ).length;
+            // 빌드 타입에 따라 해당 플랫폼의 빌드 횟수 카운트
+            // iOS: 'ios build' + 'build app' 통합 카운트 (App Store Connect는 앱 전체에서 빌드 번호 unique)
+            // Android: 'apk build' + 'build app' 통합 카운트 (Play Store도 동일)
+            // App: 모든 빌드 명령어 통합 카운트
+            let buildCount = 0;
+
+            if (buildType === 'ios') {
+              // iOS 빌드: 'ios build' + 'build app' 둘 다 카운트
+              buildCount = comments.data.filter(c => {
+                const body = c.body.toLowerCase();
+                return body.includes('@suh-lab') && (
+                  body.includes('ios build') ||
+                  (body.includes('build') && body.includes('app'))
+                );
+              }).length;
+              console.log(`📊 iOS 빌드 카운트: 'ios build' + 'build app' 통합`);
+
+            } else if (buildType === 'apk') {
+              // Android 빌드: 'apk build' + 'build app' 둘 다 카운트
+              buildCount = comments.data.filter(c => {
+                const body = c.body.toLowerCase();
+                return body.includes('@suh-lab') && (
+                  body.includes('apk build') ||
+                  (body.includes('build') && body.includes('app'))
+                );
+              }).length;
+              console.log(`📊 Android 빌드 카운트: 'apk build' + 'build app' 통합`);
+
+            } else if (buildType === 'app') {
+              // 전체 앱 빌드: 모든 빌드 명령어 카운트
+              buildCount = comments.data.filter(c => {
+                const body = c.body.toLowerCase();
+                return body.includes('@suh-lab') && (
+                  body.includes('ios build') ||
+                  body.includes('apk build') ||
+                  (body.includes('build') && body.includes('app'))
+                );
+              }).length;
+              console.log(`📊 전체 앱 빌드 카운트: 모든 빌드 명령어 통합`);
+            }
 
             // 빌드 번호: 소스번호 + 2자리 카운트 (38800, 38801, 38802...)
             const buildNumber = `${sourceNumber}${String(buildCount).padStart(2, '0')}`;
 
-            console.log(`📊 ${sourceType} #${sourceNumber}: ${buildCount}번째 빌드 (이전 빌드 ${buildCount}회)`);
+            console.log(`📊 ${sourceType} #${sourceNumber}: ${buildType} ${buildCount}번째 빌드`);
             console.log(`📦 생성된 빌드 번호: ${buildNumber}`);
 
             core.setOutput('buildCount', buildCount.toString());
             core.setOutput('buildNumber', buildNumber);
 
       - name: Android 빌드 워크플로우 트리거
-        if: steps.source_info.outputs.found == 'true'
+        if: |
+          steps.source_info.outputs.found == 'true' &&
+          steps.check_branch.outputs.exists == 'true' &&
+          steps.build_type.outputs.buildAndroid == 'true'
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -255,7 +405,10 @@ jobs:
             console.log('✅ Android 빌드 워크플로우 트리거 완료');
 
       - name: iOS 빌드 워크플로우 트리거
-        if: steps.source_info.outputs.found == 'true'
+        if: |
+          steps.source_info.outputs.found == 'true' &&
+          steps.check_branch.outputs.exists == 'true' &&
+          steps.build_type.outputs.buildIos == 'true'
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -289,33 +442,11 @@ jobs:
 
             console.log('✅ iOS 빌드 워크플로우 트리거 완료');
 
-      - name: 트리거 완료 댓글 작성
-        if: steps.source_info.outputs.found == 'true'
-        uses: actions/github-script@v7
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          script: |
-            const sourceType = '${{ steps.source_info.outputs.sourceType }}';
-            const sourceNumber = '${{ steps.source_info.outputs.sourceNumber }}';
-            const branchName = '${{ steps.source_info.outputs.branchName }}';
-            const buildNumber = '${{ steps.build_number_calc.outputs.buildNumber }}';
-            const buildCount = '${{ steps.build_number_calc.outputs.buildCount }}';
-
-            const body = `🚀 **앱 빌드 트리거 완료**
-
-            Android와 iOS 빌드 워크플로우를 시작했습니다.
-
-            - 앱 버전: \`0.0.0(${buildNumber})\`
-            - PR/ISSUE: **#${sourceNumber}** (${buildCount}번째 빌드)
-            - 브랜치: \`${branchName}\`
-
-            ⏳ 빌드가 완료되면 자동으로 결과 댓글이 작성됩니다.`;
-
-            await github.rest.issues.createComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: parseInt(sourceNumber),
-              body: body
-            });
-
-            console.log('✅ 트리거 완료 댓글 작성 완료');
+      # 트리거 완료 댓글은 제거됨 - Android/iOS 각각의 진행상황 댓글이 이 역할을 대체
+      - name: 트리거 완료 로그
+        if: steps.source_info.outputs.found == 'true' && steps.check_branch.outputs.exists == 'true'
+        run: |
+          echo "✅ Android 및 iOS 빌드 워크플로우 트리거 완료"
+          echo "📦 빌드 번호: ${{ steps.build_number_calc.outputs.buildNumber }}"
+          echo "🌿 브랜치: ${{ steps.source_info.outputs.branchName }}"
+          echo "📋 각 플랫폼별 진행상황 댓글이 자동으로 생성됩니다."

From 7a71cfbe36c5370a3b19c7067983594797e35f09 Mon Sep 17 00:00:00 2001
From: GitHub Action <action@github.com>
Date: Thu, 5 Mar 2026 05:44:05 +0000
Subject: [PATCH 03/20] =?UTF-8?q?SpaceStudyShip-FE=20=EB=B2=84=EC=A0=84=20?=
 =?UTF-8?q?=EC=A0=95=EB=B3=B4=20=EA=B4=80=EB=A6=AC:=20chore:=20=EB=B2=84?=
 =?UTF-8?q?=EC=A0=84=201.1.32=20[skip=20ci]?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pubspec.yaml | 2 +-
 version.yml  | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/pubspec.yaml b/pubspec.yaml
index 80aa84e..9c73162 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,7 +1,7 @@
 name: space_study_ship
 description: "Space Study Ship - 우주 테마 게이미피케이션 학습 관리 앱"
 publish_to: "none"
-version: 1.1.31+75
+version: 1.1.32+76
 environment:
   sdk: ^3.9.2
 dependencies:
diff --git a/version.yml b/version.yml
index 85afcf6..8aa23d6 100644
--- a/version.yml
+++ b/version.yml
@@ -34,12 +34,12 @@
 # - 버전은 항상 높은 버전으로 자동 동기화됩니다
 # ===================================================================
 
-version: "1.1.31" # 사용자에게 표시되는 버전
-version_code: 76 # app build number
+version: "1.1.32" # 사용자에게 표시되는 버전
+version_code: 77 # app build number
 project_type: "flutter" # spring, flutter, react, react-native, react-native-expo, node, python, basic
 metadata:
-  last_updated: "2026-03-05 00:17:48"
-  last_updated_by: "EM-H20"
+  last_updated: "2026-03-05 05:44:05"
+  last_updated_by: "Cassiiopeia"
   default_branch: "main"
   integrated_from: "SUH-DEVOPS-TEMPLATE"
   integration_date: "2026-02-06"

From de4feda0c0ccfa544a9d06573d7a862537a8421d Mon Sep 17 00:00:00 2001
From: SUH SAECHAN <chan4760@gmail.com>
Date: Thu, 5 Mar 2026 14:48:46 +0900
Subject: [PATCH 04/20] =?UTF-8?q?@suh-lab=20=EB=8C=93=EA=B8=80=20=EB=B9=8C?=
 =?UTF-8?q?=EB=93=9C=20=ED=8A=B8=EB=A6=AC=EA=B1=B0=20=EC=A0=95=EC=83=81=20?=
 =?UTF-8?q?=EC=9E=91=EB=8F=99=20:=20fix=20:=20=EB=8C=93=EA=B8=80=20write?=
 =?UTF-8?q?=20=EA=B6=8C=ED=95=9C=20=EC=B6=94=EA=B0=80=20https://github.com?=
 =?UTF-8?q?/SpaceStudyShip/SpaceStudyShip-FE/issues/49?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/workflows/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml    | 4 ++++
 .github/workflows/PROJECT-FLUTTER-IOS-TEST-TESTFLIGHT.yaml | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/.github/workflows/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml b/.github/workflows/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml
index 6279a24..21d7d84 100644
--- a/.github/workflows/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml
+++ b/.github/workflows/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml
@@ -38,6 +38,10 @@ on:
   repository_dispatch:
     types: [build-android-app]
 
+permissions:
+  issues: write
+  pull-requests: write
+
 # ============================================
 # 🔧 프로젝트별 설정 (아래 값들을 수정하세요)
 # ============================================
diff --git a/.github/workflows/PROJECT-FLUTTER-IOS-TEST-TESTFLIGHT.yaml b/.github/workflows/PROJECT-FLUTTER-IOS-TEST-TESTFLIGHT.yaml
index fd8f94e..675f14b 100644
--- a/.github/workflows/PROJECT-FLUTTER-IOS-TEST-TESTFLIGHT.yaml
+++ b/.github/workflows/PROJECT-FLUTTER-IOS-TEST-TESTFLIGHT.yaml
@@ -51,6 +51,10 @@ on:
   repository_dispatch:
     types: [build-ios-app]
 
+permissions:
+  issues: write
+  pull-requests: write
+
 # ============================================
 # 🔧 프로젝트별 설정 (아래 값들을 수정하세요)
 # ============================================

From da495dd10f12f0a9a72a7864cb7d2048fcff37f4 Mon Sep 17 00:00:00 2001
From: GitHub Action <action@github.com>
Date: Thu, 5 Mar 2026 05:49:54 +0000
Subject: [PATCH 05/20] =?UTF-8?q?SpaceStudyShip-FE=20=EB=B2=84=EC=A0=84=20?=
 =?UTF-8?q?=EC=A0=95=EB=B3=B4=20=EA=B4=80=EB=A6=AC:=20chore:=20=EB=B2=84?=
 =?UTF-8?q?=EC=A0=84=201.1.33=20[skip=20ci]?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pubspec.yaml | 2 +-
 version.yml  | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/pubspec.yaml b/pubspec.yaml
index 9c73162..c8efd9f 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,7 +1,7 @@
 name: space_study_ship
 description: "Space Study Ship - 우주 테마 게이미피케이션 학습 관리 앱"
 publish_to: "none"
-version: 1.1.32+76
+version: 1.1.33+77
 environment:
   sdk: ^3.9.2
 dependencies:
diff --git a/version.yml b/version.yml
index 8aa23d6..3739595 100644
--- a/version.yml
+++ b/version.yml
@@ -34,11 +34,11 @@
 # - 버전은 항상 높은 버전으로 자동 동기화됩니다
 # ===================================================================
 
-version: "1.1.32" # 사용자에게 표시되는 버전
-version_code: 77 # app build number
+version: "1.1.33" # 사용자에게 표시되는 버전
+version_code: 78 # app build number
 project_type: "flutter" # spring, flutter, react, react-native, react-native-expo, node, python, basic
 metadata:
-  last_updated: "2026-03-05 05:44:05"
+  last_updated: "2026-03-05 05:49:54"
   last_updated_by: "Cassiiopeia"
   default_branch: "main"
   integrated_from: "SUH-DEVOPS-TEMPLATE"

From c8907b0ea15c2f662814a79f2155925085ead462 Mon Sep 17 00:00:00 2001
From: SUH SAECHAN <chan4760@gmail.com>
Date: Thu, 5 Mar 2026 15:06:19 +0900
Subject: [PATCH 06/20] =?UTF-8?q?@suh-lab=20=EB=8C=93=EA=B8=80=20=EB=B9=8C?=
 =?UTF-8?q?=EB=93=9C=20=ED=8A=B8=EB=A6=AC=EA=B1=B0=20=EC=A0=95=EC=83=81=20?=
 =?UTF-8?q?=EC=9E=91=EB=8F=99=20:=20fix=20:=20=EB=B6=88=ED=95=84=EC=9A=94?=
 =?UTF-8?q?=ED=95=9C=20step=20=EC=A0=9C=EA=B1=B0=20https://github.com/Spac?=
 =?UTF-8?q?eStudyShip/SpaceStudyShip-FE/issues/49?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../PROJECT-FLUTTER-ANDROID-TEST-APK.yaml     | 56 ++++---------------
 1 file changed, 10 insertions(+), 46 deletions(-)

diff --git a/.github/workflows/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml b/.github/workflows/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml
index 2a8fdb2..9858f9d 100644
--- a/.github/workflows/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml
+++ b/.github/workflows/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml
@@ -452,49 +452,18 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-gradle-
 
-      # 프로젝트 의존성 설치
-      - name: Install dependencies
-        run: |
-          flutter pub get
-          echo "✅ Dependencies installed"
-
-      # Gradle 셋업
-      - name: Setup Gradle
-        working-directory: android
-        run: |
-          chmod +x gradlew
-          echo "✅ Gradle wrapper permissions set"
-
       # Java 설정
       - name: Set up Java
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v4
         with:
           distribution: "temurin"
           java-version: ${{ env.JAVA_VERSION }}
 
-      - name: Verify Java version
-        run: |
-          echo "✅ Java setup completed"
-          java -version
-
-      # Ruby 설정
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: "3.4.1"
-          bundler-cache: true
-
-      - name: Verify Ruby version
-        run: |
-          echo "✅ Ruby setup completed"
-          ruby -v
-
-      # Fastlane 설치
-      - name: Install Fastlane
+      # 프로젝트 의존성 설치
+      - name: Install dependencies
         run: |
-          gem install fastlane --force
-          echo "✅ Fastlane installed"
-          fastlane --version
+          flutter pub get
+          echo "✅ Dependencies installed"
 
       # APK 파일명 생성
       - name: Generate APK filename
@@ -506,18 +475,13 @@ jobs:
           echo "apk_name=$APK_NAME" >> $GITHUB_OUTPUT
           echo "📦 APK 파일명: $APK_NAME"
 
-      # APK 빌드 (Fastlane 또는 직접 빌드)
+      # APK 빌드
       - name: Build APK
         run: |
-          # Fastlane Fastfile이 있으면 사용, 없으면 직접 빌드
-          if [ -f "android/fastlane/Fastfile" ]; then
-            echo "📦 Fastlane을 사용하여 빌드..."
-            cd android
-            fastlane build --verbose || flutter build apk --release
-          else
-            echo "📦 Flutter 직접 빌드..."
-            flutter build apk --release
-          fi
+          BUILD_NUMBER="${{ needs.prepare-test-build.outputs.build_number }}"
+          flutter build apk --release \
+            --build-name="0.0.0" \
+            --build-number="$BUILD_NUMBER"
           ls -la ./build/app/outputs/flutter-apk/ || true
           echo "✅ APK built"
 

From 22438f37cb96a0a7d5bb146bd4761a74429b4745 Mon Sep 17 00:00:00 2001
From: GitHub Action <action@github.com>
Date: Thu, 5 Mar 2026 06:06:07 +0000
Subject: [PATCH 07/20] =?UTF-8?q?SpaceStudyShip-FE=20=EB=B2=84=EC=A0=84=20?=
 =?UTF-8?q?=EC=A0=95=EB=B3=B4=20=EA=B4=80=EB=A6=AC:=20chore:=20=EB=B2=84?=
 =?UTF-8?q?=EC=A0=84=201.1.34=20[skip=20ci]?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pubspec.yaml | 2 +-
 version.yml  | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/pubspec.yaml b/pubspec.yaml
index c8efd9f..f2f3115 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,7 +1,7 @@
 name: space_study_ship
 description: "Space Study Ship - 우주 테마 게이미피케이션 학습 관리 앱"
 publish_to: "none"
-version: 1.1.33+77
+version: 1.1.34+78
 environment:
   sdk: ^3.9.2
 dependencies:
diff --git a/version.yml b/version.yml
index 3739595..4760fbf 100644
--- a/version.yml
+++ b/version.yml
@@ -34,11 +34,11 @@
 # - 버전은 항상 높은 버전으로 자동 동기화됩니다
 # ===================================================================
 
-version: "1.1.33" # 사용자에게 표시되는 버전
-version_code: 78 # app build number
+version: "1.1.34" # 사용자에게 표시되는 버전
+version_code: 79 # app build number
 project_type: "flutter" # spring, flutter, react, react-native, react-native-expo, node, python, basic
 metadata:
-  last_updated: "2026-03-05 05:49:54"
+  last_updated: "2026-03-05 06:06:06"
   last_updated_by: "Cassiiopeia"
   default_branch: "main"
   integrated_from: "SUH-DEVOPS-TEMPLATE"

From 81a209137265b596c2d3bd0d6d79f8fa92744eea Mon Sep 17 00:00:00 2001
From: EM-H20 <ghd0106@gmail.com>
Date: Mon, 9 Mar 2026 13:37:01 +0900
Subject: [PATCH 08/20] =?UTF-8?q?docs=20:=20=EC=8A=A4=ED=82=AC=20=EC=B6=94?=
 =?UTF-8?q?=EA=B0=80=20=EB=B0=8F=20CLAUDE.md=20=EC=97=85=EB=8D=B0=EC=9D=B4?=
 =?UTF-8?q?=ED=8A=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .agents/skills/find-skills/SKILL.md           | 133 ++++++
 .agents/skills/frontend-design/LICENSE.txt    | 177 ++++++++
 .agents/skills/frontend-design/SKILL.md       |  42 ++
 .../skills/remotion-best-practices/SKILL.md   |  61 +++
 .../remotion-best-practices/rules/3d.md       |  86 ++++
 .../rules/animations.md                       |  27 ++
 .../remotion-best-practices/rules/assets.md   |  78 ++++
 .../rules/assets/charts-bar-chart.tsx         | 173 ++++++++
 .../assets/text-animations-typewriter.tsx     | 100 +++++
 .../assets/text-animations-word-highlight.tsx | 103 +++++
 .../rules/audio-visualization.md              | 198 +++++++++
 .../remotion-best-practices/rules/audio.md    | 169 +++++++
 .../rules/calculate-metadata.md               | 134 ++++++
 .../rules/can-decode.md                       |  75 ++++
 .../remotion-best-practices/rules/charts.md   | 120 +++++
 .../rules/compositions.md                     | 154 +++++++
 .../rules/display-captions.md                 | 184 ++++++++
 .../rules/extract-frames.md                   | 229 ++++++++++
 .../remotion-best-practices/rules/ffmpeg.md   |  38 ++
 .../remotion-best-practices/rules/fonts.md    | 152 +++++++
 .../rules/get-audio-duration.md               |  58 +++
 .../rules/get-video-dimensions.md             |  68 +++
 .../rules/get-video-duration.md               |  60 +++
 .../remotion-best-practices/rules/gifs.md     | 141 ++++++
 .../remotion-best-practices/rules/images.md   | 134 ++++++
 .../rules/import-srt-captions.md              |  69 +++
 .../rules/light-leaks.md                      |  73 ++++
 .../remotion-best-practices/rules/lottie.md   |  70 +++
 .../remotion-best-practices/rules/maps.md     | 412 ++++++++++++++++++
 .../rules/measuring-dom-nodes.md              |  34 ++
 .../rules/measuring-text.md                   | 140 ++++++
 .../rules/parameters.md                       | 109 +++++
 .../rules/sequencing.md                       | 118 +++++
 .../remotion-best-practices/rules/sfx.md      |  26 ++
 .../rules/subtitles.md                        |  36 ++
 .../remotion-best-practices/rules/tailwind.md |  11 +
 .../rules/text-animations.md                  |  20 +
 .../remotion-best-practices/rules/timing.md   | 179 ++++++++
 .../rules/transcribe-captions.md              |  70 +++
 .../rules/transitions.md                      | 197 +++++++++
 .../rules/transparent-videos.md               | 106 +++++
 .../remotion-best-practices/rules/trimming.md |  51 +++
 .../remotion-best-practices/rules/videos.md   | 171 ++++++++
 .../rules/voiceover.md                        |  99 +++++
 CLAUDE.md                                     |   8 +
 skills-lock.json                              |  20 +
 46 files changed, 4913 insertions(+)
 create mode 100644 .agents/skills/find-skills/SKILL.md
 create mode 100644 .agents/skills/frontend-design/LICENSE.txt
 create mode 100644 .agents/skills/frontend-design/SKILL.md
 create mode 100644 .agents/skills/remotion-best-practices/SKILL.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/3d.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/animations.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/assets.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/assets/charts-bar-chart.tsx
 create mode 100644 .agents/skills/remotion-best-practices/rules/assets/text-animations-typewriter.tsx
 create mode 100644 .agents/skills/remotion-best-practices/rules/assets/text-animations-word-highlight.tsx
 create mode 100644 .agents/skills/remotion-best-practices/rules/audio-visualization.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/audio.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/calculate-metadata.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/can-decode.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/charts.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/compositions.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/display-captions.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/extract-frames.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/ffmpeg.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/fonts.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/get-audio-duration.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/get-video-dimensions.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/get-video-duration.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/gifs.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/images.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/import-srt-captions.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/light-leaks.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/lottie.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/maps.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/measuring-dom-nodes.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/measuring-text.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/parameters.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/sequencing.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/sfx.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/subtitles.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/tailwind.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/text-animations.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/timing.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/transcribe-captions.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/transitions.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/transparent-videos.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/trimming.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/videos.md
 create mode 100644 .agents/skills/remotion-best-practices/rules/voiceover.md
 create mode 100644 skills-lock.json

diff --git a/.agents/skills/find-skills/SKILL.md b/.agents/skills/find-skills/SKILL.md
new file mode 100644
index 0000000..c797184
--- /dev/null
+++ b/.agents/skills/find-skills/SKILL.md
@@ -0,0 +1,133 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```
diff --git a/.agents/skills/frontend-design/LICENSE.txt b/.agents/skills/frontend-design/LICENSE.txt
new file mode 100644
index 0000000..f433b1a
--- /dev/null
+++ b/.agents/skills/frontend-design/LICENSE.txt
@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
diff --git a/.agents/skills/frontend-design/SKILL.md b/.agents/skills/frontend-design/SKILL.md
new file mode 100644
index 0000000..5be498e
--- /dev/null
+++ b/.agents/skills/frontend-design/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
diff --git a/.agents/skills/remotion-best-practices/SKILL.md b/.agents/skills/remotion-best-practices/SKILL.md
new file mode 100644
index 0000000..7ddaa0f
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: remotion-best-practices
+description: Best practices for Remotion - Video creation in React
+metadata:
+  tags: remotion, video, react, animation, composition
+---
+
+## When to use
+
+Use this skills whenever you are dealing with Remotion code to obtain the domain-specific knowledge.
+
+## Captions
+
+When dealing with captions or subtitles, load the [./rules/subtitles.md](./rules/subtitles.md) file for more information.
+
+## Using FFmpeg
+
+For some video operations, such as trimming videos or detecting silence, FFmpeg should be used. Load the [./rules/ffmpeg.md](./rules/ffmpeg.md) file for more information.
+
+## Audio visualization
+
+When needing to visualize audio (spectrum bars, waveforms, bass-reactive effects), load the [./rules/audio-visualization.md](./rules/audio-visualization.md) file for more information.
+
+## Sound effects
+
+When needing to use sound effects, load the [./rules/sound-effects.md](./rules/sound-effects.md) file for more information.
+
+## How to use
+
+Read individual rule files for detailed explanations and code examples:
+
+- [rules/3d.md](rules/3d.md) - 3D content in Remotion using Three.js and React Three Fiber
+- [rules/animations.md](rules/animations.md) - Fundamental animation skills for Remotion
+- [rules/assets.md](rules/assets.md) - Importing images, videos, audio, and fonts into Remotion
+- [rules/audio.md](rules/audio.md) - Using audio and sound in Remotion - importing, trimming, volume, speed, pitch
+- [rules/calculate-metadata.md](rules/calculate-metadata.md) - Dynamically set composition duration, dimensions, and props
+- [rules/can-decode.md](rules/can-decode.md) - Check if a video can be decoded by the browser using Mediabunny
+- [rules/charts.md](rules/charts.md) - Chart and data visualization patterns for Remotion (bar, pie, line, stock charts)
+- [rules/compositions.md](rules/compositions.md) - Defining compositions, stills, folders, default props and dynamic metadata
+- [rules/extract-frames.md](rules/extract-frames.md) - Extract frames from videos at specific timestamps using Mediabunny
+- [rules/fonts.md](rules/fonts.md) - Loading Google Fonts and local fonts in Remotion
+- [rules/get-audio-duration.md](rules/get-audio-duration.md) - Getting the duration of an audio file in seconds with Mediabunny
+- [rules/get-video-dimensions.md](rules/get-video-dimensions.md) - Getting the width and height of a video file with Mediabunny
+- [rules/get-video-duration.md](rules/get-video-duration.md) - Getting the duration of a video file in seconds with Mediabunny
+- [rules/gifs.md](rules/gifs.md) - Displaying GIFs synchronized with Remotion's timeline
+- [rules/images.md](rules/images.md) - Embedding images in Remotion using the Img component
+- [rules/light-leaks.md](rules/light-leaks.md) - Light leak overlay effects using @remotion/light-leaks
+- [rules/lottie.md](rules/lottie.md) - Embedding Lottie animations in Remotion
+- [rules/measuring-dom-nodes.md](rules/measuring-dom-nodes.md) - Measuring DOM element dimensions in Remotion
+- [rules/measuring-text.md](rules/measuring-text.md) - Measuring text dimensions, fitting text to containers, and checking overflow
+- [rules/sequencing.md](rules/sequencing.md) - Sequencing patterns for Remotion - delay, trim, limit duration of items
+- [rules/tailwind.md](rules/tailwind.md) - Using TailwindCSS in Remotion
+- [rules/text-animations.md](rules/text-animations.md) - Typography and text animation patterns for Remotion
+- [rules/timing.md](rules/timing.md) - Interpolation curves in Remotion - linear, easing, spring animations
+- [rules/transitions.md](rules/transitions.md) - Scene transition patterns for Remotion
+- [rules/transparent-videos.md](rules/transparent-videos.md) - Rendering out a video with transparency
+- [rules/trimming.md](rules/trimming.md) - Trimming patterns for Remotion - cut the beginning or end of animations
+- [rules/videos.md](rules/videos.md) - Embedding videos in Remotion - trimming, volume, speed, looping, pitch
+- [rules/parameters.md](rules/parameters.md) - Make a video parametrizable by adding a Zod schema
+- [rules/maps.md](rules/maps.md) - Add a map using Mapbox and animate it
+- [rules/voiceover.md](rules/voiceover.md) - Adding AI-generated voiceover to Remotion compositions using ElevenLabs TTS
diff --git a/.agents/skills/remotion-best-practices/rules/3d.md b/.agents/skills/remotion-best-practices/rules/3d.md
new file mode 100644
index 0000000..c9d254f
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/3d.md
@@ -0,0 +1,86 @@
+---
+name: 3d
+description: 3D content in Remotion using Three.js and React Three Fiber.
+metadata:
+  tags: 3d, three, threejs
+---
+
+# Using Three.js and React Three Fiber in Remotion
+
+Follow React Three Fiber and Three.js best practices.  
+Only the following Remotion-specific rules need to be followed:
+
+## Prerequisites
+
+First, the `@remotion/three` package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/three # If project uses npm
+bunx remotion add @remotion/three # If project uses bun
+yarn remotion add @remotion/three # If project uses yarn
+pnpm exec remotion add @remotion/three # If project uses pnpm
+```
+
+## Using ThreeCanvas
+
+You MUST wrap 3D content in `<ThreeCanvas>` and include proper lighting.  
+`<ThreeCanvas>` MUST have a `width` and `height` prop.
+
+```tsx
+import { ThreeCanvas } from "@remotion/three";
+import { useVideoConfig } from "remotion";
+
+const { width, height } = useVideoConfig();
+
+<ThreeCanvas width={width} height={height}>
+  <ambientLight intensity={0.4} />
+  <directionalLight position={[5, 5, 5]} intensity={0.8} />
+  <mesh>
+    <sphereGeometry args={[1, 32, 32]} />
+    <meshStandardMaterial color="red" />
+  </mesh>
+</ThreeCanvas>;
+```
+
+## No animations not driven by `useCurrentFrame()`
+
+Shaders, models etc MUST NOT animate by themselves.  
+No animations are allowed unless they are driven by `useCurrentFrame()`.  
+Otherwise, it will cause flickering during rendering.
+
+Using `useFrame()` from `@react-three/fiber` is forbidden.
+
+## Animate using `useCurrentFrame()`
+
+Use `useCurrentFrame()` to perform animations.
+
+```tsx
+const frame = useCurrentFrame();
+const rotationY = frame * 0.02;
+
+<mesh rotation={[0, rotationY, 0]}>
+  <boxGeometry args={[2, 2, 2]} />
+  <meshStandardMaterial color="#4a9eff" />
+</mesh>;
+```
+
+## Using `<Sequence>` inside `<ThreeCanvas>`
+
+The `layout` prop of any `<Sequence>` inside a `<ThreeCanvas>` must be set to `none`.
+
+```tsx
+import { Sequence } from "remotion";
+import { ThreeCanvas } from "@remotion/three";
+
+const { width, height } = useVideoConfig();
+
+<ThreeCanvas width={width} height={height}>
+  <Sequence layout="none">
+    <mesh>
+      <boxGeometry args={[2, 2, 2]} />
+      <meshStandardMaterial color="#4a9eff" />
+    </mesh>
+  </Sequence>
+</ThreeCanvas>;
+```
diff --git a/.agents/skills/remotion-best-practices/rules/animations.md b/.agents/skills/remotion-best-practices/rules/animations.md
new file mode 100644
index 0000000..619591e
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/animations.md
@@ -0,0 +1,27 @@
+---
+name: animations
+description: Fundamental animation skills for Remotion
+metadata:
+  tags: animations, transitions, frames, useCurrentFrame
+---
+
+All animations MUST be driven by the `useCurrentFrame()` hook.  
+Write animations in seconds and multiply them by the `fps` value from `useVideoConfig()`.
+
+```tsx
+import { useCurrentFrame } from "remotion";
+
+export const FadeIn = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const opacity = interpolate(frame, [0, 2 * fps], [0, 1], {
+    extrapolateRight: "clamp",
+  });
+
+  return <div style={{ opacity }}>Hello World!</div>;
+};
+```
+
+CSS transitions or animations are FORBIDDEN - they will not render correctly.  
+Tailwind animation class names are FORBIDDEN - they will not render correctly.
diff --git a/.agents/skills/remotion-best-practices/rules/assets.md b/.agents/skills/remotion-best-practices/rules/assets.md
new file mode 100644
index 0000000..a5d4015
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/assets.md
@@ -0,0 +1,78 @@
+---
+name: assets
+description: Importing images, videos, audio, and fonts into Remotion
+metadata:
+  tags: assets, staticFile, images, fonts, public
+---
+
+# Importing assets in Remotion
+
+## The public folder
+
+Place assets in the `public/` folder at your project root.
+
+## Using staticFile()
+
+You MUST use `staticFile()` to reference files from the `public/` folder:
+
+```tsx
+import { Img, staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Img src={staticFile("logo.png")} />;
+};
+```
+
+The function returns an encoded URL that works correctly when deploying to subdirectories.
+
+## Using with components
+
+**Images:**
+
+```tsx
+import { Img, staticFile } from "remotion";
+
+<Img src={staticFile("photo.png")} />;
+```
+
+**Videos:**
+
+```tsx
+import { Video } from "@remotion/media";
+import { staticFile } from "remotion";
+
+<Video src={staticFile("clip.mp4")} />;
+```
+
+**Audio:**
+
+```tsx
+import { Audio } from "@remotion/media";
+import { staticFile } from "remotion";
+
+<Audio src={staticFile("music.mp3")} />;
+```
+
+**Fonts:**
+
+```tsx
+import { staticFile } from "remotion";
+
+const fontFamily = new FontFace("MyFont", `url(${staticFile("font.woff2")})`);
+await fontFamily.load();
+document.fonts.add(fontFamily);
+```
+
+## Remote URLs
+
+Remote URLs can be used directly without `staticFile()`:
+
+```tsx
+<Img src="https://example.com/image.png" />
+<Video src="https://remotion.media/video.mp4" />
+```
+
+## Important notes
+
+- Remotion components (`<Img>`, `<Video>`, `<Audio>`) ensure assets are fully loaded before rendering
+- Special characters in filenames (`#`, `?`, `&`) are automatically encoded
diff --git a/.agents/skills/remotion-best-practices/rules/assets/charts-bar-chart.tsx b/.agents/skills/remotion-best-practices/rules/assets/charts-bar-chart.tsx
new file mode 100644
index 0000000..1313ebf
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/assets/charts-bar-chart.tsx
@@ -0,0 +1,173 @@
+import {loadFont} from '@remotion/google-fonts/Inter';
+import {AbsoluteFill, spring, useCurrentFrame, useVideoConfig} from 'remotion';
+
+const {fontFamily} = loadFont();
+
+const COLOR_BAR = '#D4AF37';
+const COLOR_TEXT = '#ffffff';
+const COLOR_MUTED = '#888888';
+const COLOR_BG = '#0a0a0a';
+const COLOR_AXIS = '#333333';
+
+// Ideal composition size: 1280x720
+
+const Title: React.FC<{children: React.ReactNode}> = ({children}) => (
+	<div style={{textAlign: 'center', marginBottom: 40}}>
+		<div style={{color: COLOR_TEXT, fontSize: 48, fontWeight: 600}}>
+			{children}
+		</div>
+	</div>
+);
+
+const YAxis: React.FC<{steps: number[]; height: number}> = ({
+	steps,
+	height,
+}) => (
+	<div
+		style={{
+			display: 'flex',
+			flexDirection: 'column',
+			justifyContent: 'space-between',
+			height,
+			paddingRight: 16,
+		}}
+	>
+		{steps
+			.slice()
+			.reverse()
+			.map((step) => (
+				<div
+					key={step}
+					style={{
+						color: COLOR_MUTED,
+						fontSize: 20,
+						textAlign: 'right',
+					}}
+				>
+					{step.toLocaleString()}
+				</div>
+			))}
+	</div>
+);
+
+const Bar: React.FC<{
+	height: number;
+	progress: number;
+}> = ({height, progress}) => (
+	<div
+		style={{
+			flex: 1,
+			display: 'flex',
+			flexDirection: 'column',
+			justifyContent: 'flex-end',
+		}}
+	>
+		<div
+			style={{
+				width: '100%',
+				height,
+				backgroundColor: COLOR_BAR,
+				borderRadius: '8px 8px 0 0',
+				opacity: progress,
+			}}
+		/>
+	</div>
+);
+
+const XAxis: React.FC<{
+	children: React.ReactNode;
+	labels: string[];
+	height: number;
+}> = ({children, labels, height}) => (
+	<div style={{flex: 1, display: 'flex', flexDirection: 'column'}}>
+		<div
+			style={{
+				display: 'flex',
+				alignItems: 'flex-end',
+				gap: 16,
+				height,
+				borderLeft: `2px solid ${COLOR_AXIS}`,
+				borderBottom: `2px solid ${COLOR_AXIS}`,
+				paddingLeft: 16,
+			}}
+		>
+			{children}
+		</div>
+		<div
+			style={{
+				display: 'flex',
+				gap: 16,
+				paddingLeft: 16,
+				marginTop: 12,
+			}}
+		>
+			{labels.map((label) => (
+				<div
+					key={label}
+					style={{
+						flex: 1,
+						textAlign: 'center',
+						color: COLOR_MUTED,
+						fontSize: 20,
+					}}
+				>
+					{label}
+				</div>
+			))}
+		</div>
+	</div>
+);
+
+export const MyAnimation = () => {
+	const frame = useCurrentFrame();
+	const {fps, height} = useVideoConfig();
+
+	const data = [
+		{month: 'Jan', price: 2039},
+		{month: 'Mar', price: 2160},
+		{month: 'May', price: 2327},
+		{month: 'Jul', price: 2426},
+		{month: 'Sep', price: 2634},
+		{month: 'Nov', price: 2672},
+	];
+
+	const minPrice = 2000;
+	const maxPrice = 2800;
+	const priceRange = maxPrice - minPrice;
+	const chartHeight = height - 280;
+	const yAxisSteps = [2000, 2400, 2800];
+
+	return (
+		<AbsoluteFill
+			style={{
+				backgroundColor: COLOR_BG,
+				padding: 60,
+				display: 'flex',
+				flexDirection: 'column',
+				fontFamily,
+			}}
+		>
+			<Title>Gold Price 2024</Title>
+
+			<div style={{display: 'flex', flex: 1}}>
+				<YAxis steps={yAxisSteps} height={chartHeight} />
+				<XAxis height={chartHeight} labels={data.map((d) => d.month)}>
+					{data.map((item, i) => {
+						const progress = spring({
+							frame: frame - i * 5 - 10,
+							fps,
+							config: {damping: 18, stiffness: 80},
+						});
+
+						const barHeight =
+							((item.price - minPrice) / priceRange) * chartHeight * progress;
+
+						return (
+							<Bar key={item.month} height={barHeight} progress={progress} />
+						);
+					})}
+				</XAxis>
+			</div>
+		</AbsoluteFill>
+	);
+};
diff --git a/.agents/skills/remotion-best-practices/rules/assets/text-animations-typewriter.tsx b/.agents/skills/remotion-best-practices/rules/assets/text-animations-typewriter.tsx
new file mode 100644
index 0000000..89f62ea
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/assets/text-animations-typewriter.tsx
@@ -0,0 +1,100 @@
+import {
+	AbsoluteFill,
+	interpolate,
+	useCurrentFrame,
+	useVideoConfig,
+} from 'remotion';
+
+const COLOR_BG = '#ffffff';
+const COLOR_TEXT = '#000000';
+const FULL_TEXT = 'From prompt to motion graphics. This is Remotion.';
+const PAUSE_AFTER = 'From prompt to motion graphics.';
+const FONT_SIZE = 72;
+const FONT_WEIGHT = 700;
+const CHAR_FRAMES = 2;
+const CURSOR_BLINK_FRAMES = 16;
+const PAUSE_SECONDS = 1;
+
+// Ideal composition size: 1280x720
+
+const getTypedText = ({
+	frame,
+	fullText,
+	pauseAfter,
+	charFrames,
+	pauseFrames,
+}: {
+	frame: number;
+	fullText: string;
+	pauseAfter: string;
+	charFrames: number;
+	pauseFrames: number;
+}): string => {
+	const pauseIndex = fullText.indexOf(pauseAfter);
+	const preLen =
+		pauseIndex >= 0 ? pauseIndex + pauseAfter.length : fullText.length;
+
+	let typedChars = 0;
+	if (frame < preLen * charFrames) {
+		typedChars = Math.floor(frame / charFrames);
+	} else if (frame < preLen * charFrames + pauseFrames) {
+		typedChars = preLen;
+	} else {
+		const postPhase = frame - preLen * charFrames - pauseFrames;
+		typedChars = Math.min(
+			fullText.length,
+			preLen + Math.floor(postPhase / charFrames),
+		);
+	}
+	return fullText.slice(0, typedChars);
+};
+
+const Cursor: React.FC<{
+	frame: number;
+	blinkFrames: number;
+	symbol?: string;
+}> = ({frame, blinkFrames, symbol = '\u258C'}) => {
+	const opacity = interpolate(
+		frame % blinkFrames,
+		[0, blinkFrames / 2, blinkFrames],
+		[1, 0, 1],
+		{extrapolateLeft: 'clamp', extrapolateRight: 'clamp'},
+	);
+
+	return <span style={{opacity}}>{symbol}</span>;
+};
+
+export const MyAnimation = () => {
+	const frame = useCurrentFrame();
+	const {fps} = useVideoConfig();
+
+	const pauseFrames = Math.round(fps * PAUSE_SECONDS);
+
+	const typedText = getTypedText({
+		frame,
+		fullText: FULL_TEXT,
+		pauseAfter: PAUSE_AFTER,
+		charFrames: CHAR_FRAMES,
+		pauseFrames,
+	});
+
+	return (
+		<AbsoluteFill
+			style={{
+				backgroundColor: COLOR_BG,
+			}}
+		>
+			<div
+				style={{
+					color: COLOR_TEXT,
+					fontSize: FONT_SIZE,
+					fontWeight: FONT_WEIGHT,
+					fontFamily: 'sans-serif',
+				}}
+			>
+				<span>{typedText}</span>
+				<Cursor frame={frame} blinkFrames={CURSOR_BLINK_FRAMES} />
+			</div>
+		</AbsoluteFill>
+	);
+};
diff --git a/.agents/skills/remotion-best-practices/rules/assets/text-animations-word-highlight.tsx b/.agents/skills/remotion-best-practices/rules/assets/text-animations-word-highlight.tsx
new file mode 100644
index 0000000..0aae3e2
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/assets/text-animations-word-highlight.tsx
@@ -0,0 +1,103 @@
+import {loadFont} from '@remotion/google-fonts/Inter';
+import React from 'react';
+import {AbsoluteFill, spring, useCurrentFrame, useVideoConfig} from 'remotion';
+
+/*
+ * Highlight a word in a sentence with a spring-animated wipe effect.
+ */
+
+// Ideal composition size: 1280x720
+
+const COLOR_BG = '#ffffff';
+const COLOR_TEXT = '#000000';
+const COLOR_HIGHLIGHT = '#A7C7E7';
+const FULL_TEXT = 'This is Remotion.';
+const HIGHLIGHT_WORD = 'Remotion';
+const FONT_SIZE = 72;
+const FONT_WEIGHT = 700;
+const HIGHLIGHT_START_FRAME = 30;
+const HIGHLIGHT_WIPE_DURATION = 18;
+
+const {fontFamily} = loadFont();
+
+const Highlight: React.FC<{
+	word: string;
+	color: string;
+	delay: number;
+	durationInFrames: number;
+}> = ({word, color, delay, durationInFrames}) => {
+	const frame = useCurrentFrame();
+	const {fps} = useVideoConfig();
+
+	const highlightProgress = spring({
+		fps,
+		frame,
+		config: {damping: 200},
+		delay,
+		durationInFrames,
+	});
+	const scaleX = Math.max(0, Math.min(1, highlightProgress));
+
+	return (
+		<span style={{position: 'relative', display: 'inline-block'}}>
+			<span
+				style={{
+					position: 'absolute',
+					left: 0,
+					right: 0,
+					top: '50%',
+					height: '1.05em',
+					transform: `translateY(-50%) scaleX(${scaleX})`,
+					transformOrigin: 'left center',
+					backgroundColor: color,
+					borderRadius: '0.18em',
+					zIndex: 0,
+				}}
+			/>
+			<span style={{position: 'relative', zIndex: 1}}>{word}</span>
+		</span>
+	);
+};
+
+export const MyAnimation = () => {
+	const highlightIndex = FULL_TEXT.indexOf(HIGHLIGHT_WORD);
+	const hasHighlight = highlightIndex >= 0;
+	const preText = hasHighlight ? FULL_TEXT.slice(0, highlightIndex) : FULL_TEXT;
+	const postText = hasHighlight
+		? FULL_TEXT.slice(highlightIndex + HIGHLIGHT_WORD.length)
+		: '';
+
+	return (
+		<AbsoluteFill
+			style={{
+				backgroundColor: COLOR_BG,
+				alignItems: 'center',
+				justifyContent: 'center',
+				fontFamily,
+			}}
+		>
+			<div
+				style={{
+					color: COLOR_TEXT,
+					fontSize: FONT_SIZE,
+					fontWeight: FONT_WEIGHT,
+				}}
+			>
+				{hasHighlight ? (
+					<>
+						<span>{preText}</span>
+						<Highlight
+							word={HIGHLIGHT_WORD}
+							color={COLOR_HIGHLIGHT}
+							delay={HIGHLIGHT_START_FRAME}
+							durationInFrames={HIGHLIGHT_WIPE_DURATION}
+						/>
+						<span>{postText}</span>
+					</>
+				) : (
+					<span>{FULL_TEXT}</span>
+				)}
+			</div>
+		</AbsoluteFill>
+	);
+};
diff --git a/.agents/skills/remotion-best-practices/rules/audio-visualization.md b/.agents/skills/remotion-best-practices/rules/audio-visualization.md
new file mode 100644
index 0000000..733b0d3
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/audio-visualization.md
@@ -0,0 +1,198 @@
+---
+name: audio-visualization
+description: Audio visualization patterns - spectrum bars, waveforms, bass-reactive effects
+metadata:
+  tags: audio, visualization, spectrum, waveform, bass, music, audiogram, frequency
+---
+
+# Audio Visualization in Remotion
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/media-utils
+```
+
+## Loading Audio Data
+
+Use `useWindowedAudioData()` (https://www.remotion.dev/docs/use-windowed-audio-data) to load audio data:
+
+```tsx
+import { useWindowedAudioData } from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+  src: staticFile("podcast.wav"),
+  frame,
+  fps,
+  windowInSeconds: 30,
+});
+```
+
+## Spectrum Bar Visualization
+
+Use `visualizeAudio()` (https://www.remotion.dev/docs/visualize-audio) to get frequency data for bar charts:
+
+```tsx
+import { useWindowedAudioData, visualizeAudio } from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+  src: staticFile("music.mp3"),
+  frame,
+  fps,
+  windowInSeconds: 30,
+});
+
+if (!audioData) {
+  return null;
+}
+
+const frequencies = visualizeAudio({
+  fps,
+  frame,
+  audioData,
+  numberOfSamples: 256,
+  optimizeFor: "speed",
+  dataOffsetInSeconds,
+});
+
+return (
+  <div style={{ display: "flex", alignItems: "flex-end", height: 200 }}>
+    {frequencies.map((v, i) => (
+      <div
+        key={i}
+        style={{
+          flex: 1,
+          height: `${v * 100}%`,
+          backgroundColor: "#0b84f3",
+          margin: "0 1px",
+        }}
+      />
+    ))}
+  </div>
+);
+```
+
+- `numberOfSamples` must be power of 2 (32, 64, 128, 256, 512, 1024)
+- Values range 0-1; left of array = bass, right = highs
+- Use `optimizeFor: "speed"` for Lambda or high sample counts
+
+**Important:** When passing `audioData` to child components, also pass the `frame` from the parent. Do not call `useCurrentFrame()` in each child - this causes discontinuous visualization when children are inside `<Sequence>` with offsets.
+
+## Waveform Visualization
+
+Use `visualizeAudioWaveform()` (https://www.remotion.dev/docs/media-utils/visualize-audio-waveform) with `createSmoothSvgPath()` (https://www.remotion.dev/docs/media-utils/create-smooth-svg-path) for oscilloscope-style displays:
+
+```tsx
+import {
+  createSmoothSvgPath,
+  useWindowedAudioData,
+  visualizeAudioWaveform,
+} from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { width, fps } = useVideoConfig();
+const HEIGHT = 200;
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+  src: staticFile("voice.wav"),
+  frame,
+  fps,
+  windowInSeconds: 30,
+});
+
+if (!audioData) {
+  return null;
+}
+
+const waveform = visualizeAudioWaveform({
+  fps,
+  frame,
+  audioData,
+  numberOfSamples: 256,
+  windowInSeconds: 0.5,
+  dataOffsetInSeconds,
+});
+
+const path = createSmoothSvgPath({
+  points: waveform.map((y, i) => ({
+    x: (i / (waveform.length - 1)) * width,
+    y: HEIGHT / 2 + (y * HEIGHT) / 2,
+  })),
+});
+
+return (
+  <svg width={width} height={HEIGHT}>
+    <path d={path} fill="none" stroke="#0b84f3" strokeWidth={2} />
+  </svg>
+);
+```
+
+## Bass-Reactive Effects
+
+Extract low frequencies for beat-reactive animations:
+
+```tsx
+const frequencies = visualizeAudio({
+  fps,
+  frame,
+  audioData,
+  numberOfSamples: 128,
+  optimizeFor: "speed",
+  dataOffsetInSeconds,
+});
+
+const lowFrequencies = frequencies.slice(0, 32);
+const bassIntensity =
+  lowFrequencies.reduce((sum, v) => sum + v, 0) / lowFrequencies.length;
+
+const scale = 1 + bassIntensity * 0.5;
+const opacity = Math.min(0.6, bassIntensity * 0.8);
+```
+
+## Volume-Based Waveform
+
+Use `getWaveformPortion()` (https://www.remotion.dev/docs/get-waveform-portion) when you need simplified volume data instead of frequency spectrum:
+
+```tsx
+import { getWaveformPortion } from "@remotion/media-utils";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+const currentTimeInSeconds = frame / fps;
+
+const waveform = getWaveformPortion({
+  audioData,
+  startTimeInSeconds: currentTimeInSeconds,
+  durationInSeconds: 5,
+  numberOfSamples: 50,
+});
+
+// Returns array of { index, amplitude } objects (amplitude: 0-1)
+waveform.map((bar) => (
+  <div key={bar.index} style={{ height: bar.amplitude * 100 }} />
+));
+```
+
+## Postprocessing
+
+Low frequencies naturally dominate. Apply logarithmic scaling for visual balance:
+
+```tsx
+const minDb = -100;
+const maxDb = -30;
+
+const scaled = frequencies.map((value) => {
+  const db = 20 * Math.log10(value);
+  return (db - minDb) / (maxDb - minDb);
+});
+```
diff --git a/.agents/skills/remotion-best-practices/rules/audio.md b/.agents/skills/remotion-best-practices/rules/audio.md
new file mode 100644
index 0000000..1097c70
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/audio.md
@@ -0,0 +1,169 @@
+---
+name: audio
+description: Using audio and sound in Remotion - importing, trimming, volume, speed, pitch
+metadata:
+  tags: audio, media, trim, volume, speed, loop, pitch, mute, sound, sfx
+---
+
+# Using audio in Remotion
+
+## Prerequisites
+
+First, the @remotion/media package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/media
+```
+
+## Importing Audio
+
+Use `<Audio>` from `@remotion/media` to add audio to your composition.
+
+```tsx
+import { Audio } from "@remotion/media";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Audio src={staticFile("audio.mp3")} />;
+};
+```
+
+Remote URLs are also supported:
+
+```tsx
+<Audio src="https://remotion.media/audio.mp3" />
+```
+
+By default, audio plays from the start, at full volume and full length.
+Multiple audio tracks can be layered by adding multiple `<Audio>` components.
+
+## Trimming
+
+Use `trimBefore` and `trimAfter` to remove portions of the audio. Values are in frames.
+
+```tsx
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    trimBefore={2 * fps} // Skip the first 2 seconds
+    trimAfter={10 * fps} // End at the 10 second mark
+  />
+);
+```
+
+The audio still starts playing at the beginning of the composition - only the specified portion is played.
+
+## Delaying
+
+Wrap the audio in a `<Sequence>` to delay when it starts:
+
+```tsx
+import { Sequence, staticFile } from "remotion";
+import { Audio } from "@remotion/media";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Sequence from={1 * fps}>
+    <Audio src={staticFile("audio.mp3")} />
+  </Sequence>
+);
+```
+
+The audio will start playing after 1 second.
+
+## Volume
+
+Set a static volume (0 to 1):
+
+```tsx
+<Audio src={staticFile("audio.mp3")} volume={0.5} />
+```
+
+Or use a callback for dynamic volume based on the current frame:
+
+```tsx
+import { interpolate } from "remotion";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    volume={(f) =>
+      interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
+    }
+  />
+);
+```
+
+The value of `f` starts at 0 when the audio begins to play, not the composition frame.
+
+## Muting
+
+Use `muted` to silence the audio. It can be set dynamically:
+
+```tsx
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    muted={frame >= 2 * fps && frame <= 4 * fps} // Mute between 2s and 4s
+  />
+);
+```
+
+## Speed
+
+Use `playbackRate` to change the playback speed:
+
+```tsx
+<Audio src={staticFile("audio.mp3")} playbackRate={2} /> {/* 2x speed */}
+<Audio src={staticFile("audio.mp3")} playbackRate={0.5} /> {/* Half speed */}
+```
+
+Reverse playback is not supported.
+
+## Looping
+
+Use `loop` to loop the audio indefinitely:
+
+```tsx
+<Audio src={staticFile("audio.mp3")} loop />
+```
+
+Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
+
+- `"repeat"`: Frame count resets to 0 each loop (default)
+- `"extend"`: Frame count continues incrementing
+
+```tsx
+<Audio
+  src={staticFile("audio.mp3")}
+  loop
+  loopVolumeCurveBehavior="extend"
+  volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
+/>
+```
+
+## Pitch
+
+Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
+
+```tsx
+<Audio
+  src={staticFile("audio.mp3")}
+  toneFrequency={1.5} // Higher pitch
+/>
+<Audio
+  src={staticFile("audio.mp3")}
+  toneFrequency={0.8} // Lower pitch
+/>
+```
+
+Pitch shifting only works during server-side rendering, not in the Remotion Studio preview or in the `<Player />`.
diff --git a/.agents/skills/remotion-best-practices/rules/calculate-metadata.md b/.agents/skills/remotion-best-practices/rules/calculate-metadata.md
new file mode 100644
index 0000000..eef564f
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/calculate-metadata.md
@@ -0,0 +1,134 @@
+---
+name: calculate-metadata
+description: Dynamically set composition duration, dimensions, and props
+metadata:
+  tags: calculateMetadata, duration, dimensions, props, dynamic
+---
+
+# Using calculateMetadata
+
+Use `calculateMetadata` on a `<Composition>` to dynamically set duration, dimensions, and transform props before rendering.
+
+```tsx
+<Composition
+  id="MyComp"
+  component={MyComponent}
+  durationInFrames={300}
+  fps={30}
+  width={1920}
+  height={1080}
+  defaultProps={{ videoSrc: "https://remotion.media/video.mp4" }}
+  calculateMetadata={calculateMetadata}
+/>
+```
+
+## Setting duration based on a video
+
+Use the [`getVideoDuration`](./get-video-duration.md) and [`getVideoDimensions`](./get-video-dimensions.md) skills to get the video duration and dimensions:
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+import { getVideoDuration } from "./get-video-duration";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const durationInSeconds = await getVideoDuration(props.videoSrc);
+
+  return {
+    durationInFrames: Math.ceil(durationInSeconds * 30),
+  };
+};
+```
+
+## Matching dimensions of a video
+
+Use the [`getVideoDimensions`](./get-video-dimensions.md) skill to get the video dimensions:
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+import { getVideoDuration } from "./get-video-duration";
+import { getVideoDimensions } from "./get-video-dimensions";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const dimensions = await getVideoDimensions(props.videoSrc);
+
+  return {
+    width: dimensions.width,
+    height: dimensions.height,
+  };
+};
+```
+
+## Setting duration based on multiple videos
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const metadataPromises = props.videos.map((video) =>
+    getVideoDuration(video.src),
+  );
+  const allMetadata = await Promise.all(metadataPromises);
+
+  const totalDuration = allMetadata.reduce(
+    (sum, durationInSeconds) => sum + durationInSeconds,
+    0,
+  );
+
+  return {
+    durationInFrames: Math.ceil(totalDuration * 30),
+  };
+};
+```
+
+## Setting a default outName
+
+Set the default output filename based on props:
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultOutName: `video-${props.id}.mp4`,
+  };
+};
+```
+
+## Transforming props
+
+Fetch data or transform props before rendering:
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+  abortSignal,
+}) => {
+  const response = await fetch(props.dataUrl, { signal: abortSignal });
+  const data = await response.json();
+
+  return {
+    props: {
+      ...props,
+      fetchedData: data,
+    },
+  };
+};
+```
+
+The `abortSignal` cancels stale requests when props change in the Studio.
+
+## Return value
+
+All fields are optional. Returned values override the `<Composition>` props:
+
+- `durationInFrames`: Number of frames
+- `width`: Composition width in pixels
+- `height`: Composition height in pixels
+- `fps`: Frames per second
+- `props`: Transformed props passed to the component
+- `defaultOutName`: Default output filename
+- `defaultCodec`: Default codec for rendering
diff --git a/.agents/skills/remotion-best-practices/rules/can-decode.md b/.agents/skills/remotion-best-practices/rules/can-decode.md
new file mode 100644
index 0000000..b7146c9
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/can-decode.md
@@ -0,0 +1,75 @@
+---
+name: can-decode
+description: Check if a video can be decoded by the browser using Mediabunny
+metadata:
+  tags: decode, validation, video, audio, compatibility, browser
+---
+
+# Checking if a video can be decoded
+
+Use Mediabunny to check if a video can be decoded by the browser before attempting to play it.
+
+## The `canDecode()` function
+
+This function can be copy-pasted into any project.
+
+```tsx
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const canDecode = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  try {
+    await input.getFormat();
+  } catch {
+    return false;
+  }
+
+  const videoTrack = await input.getPrimaryVideoTrack();
+  if (videoTrack && !(await videoTrack.canDecode())) {
+    return false;
+  }
+
+  const audioTrack = await input.getPrimaryAudioTrack();
+  if (audioTrack && !(await audioTrack.canDecode())) {
+    return false;
+  }
+
+  return true;
+};
+```
+
+## Usage
+
+```tsx
+const src = "https://remotion.media/video.mp4";
+const isDecodable = await canDecode(src);
+
+if (isDecodable) {
+  console.log("Video can be decoded");
+} else {
+  console.log("Video cannot be decoded by this browser");
+}
+```
+
+## Using with Blob
+
+For file uploads or drag-and-drop, use `BlobSource`:
+
+```tsx
+import { Input, ALL_FORMATS, BlobSource } from "mediabunny";
+
+export const canDecodeBlob = async (blob: Blob) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new BlobSource(blob),
+  });
+
+  // Same validation logic as above
+};
+```
diff --git a/.agents/skills/remotion-best-practices/rules/charts.md b/.agents/skills/remotion-best-practices/rules/charts.md
new file mode 100644
index 0000000..f036485
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/charts.md
@@ -0,0 +1,120 @@
+---
+name: charts
+description: Chart and data visualization patterns for Remotion. Use when creating bar charts, pie charts, line charts, stock graphs, or any data-driven animations.
+metadata:
+  tags: charts, data, visualization, bar-chart, pie-chart, line-chart, stock-chart, svg-paths, graphs
+---
+
+# Charts in Remotion
+
+Create charts using React code - HTML, SVG, and D3.js are all supported.
+
+Disable all animations from third party libraries - they cause flickering.  
+Drive all animations from `useCurrentFrame()`.
+
+## Bar Chart
+
+```tsx
+const STAGGER_DELAY = 5;
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const bars = data.map((item, i) => {
+  const height = spring({
+    frame,
+    fps,
+    delay: i * STAGGER_DELAY,
+    config: { damping: 200 },
+  });
+  return <div style={{ height: height * item.value }} />;
+});
+```
+
+## Pie Chart
+
+Animate segments using stroke-dashoffset, starting from 12 o'clock:
+
+```tsx
+const progress = interpolate(frame, [0, 100], [0, 1]);
+const circumference = 2 * Math.PI * radius;
+const segmentLength = (value / total) * circumference;
+const offset = interpolate(progress, [0, 1], [segmentLength, 0]);
+
+<circle
+  r={radius}
+  cx={center}
+  cy={center}
+  fill="none"
+  stroke={color}
+  strokeWidth={strokeWidth}
+  strokeDasharray={`${segmentLength} ${circumference}`}
+  strokeDashoffset={offset}
+  transform={`rotate(-90 ${center} ${center})`}
+/>;
+```
+
+## Line Chart / Path Animation
+
+Use `@remotion/paths` for animating SVG paths (line charts, stock graphs, signatures).
+
+Install: `npx remotion add @remotion/paths`  
+Docs: https://remotion.dev/docs/paths.md
+
+### Convert data points to SVG path
+
+```tsx
+type Point = { x: number; y: number };
+
+const generateLinePath = (points: Point[]): string => {
+  if (points.length < 2) return "";
+  return points.map((p, i) => `${i === 0 ? "M" : "L"} ${p.x} ${p.y}`).join(" ");
+};
+```
+
+### Draw path with animation
+
+```tsx
+import { evolvePath } from "@remotion/paths";
+
+const path = "M 100 200 L 200 150 L 300 180 L 400 100";
+const progress = interpolate(frame, [0, 2 * fps], [0, 1], {
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+  easing: Easing.out(Easing.quad),
+});
+
+const { strokeDasharray, strokeDashoffset } = evolvePath(progress, path);
+
+<path
+  d={path}
+  fill="none"
+  stroke="#FF3232"
+  strokeWidth={4}
+  strokeDasharray={strokeDasharray}
+  strokeDashoffset={strokeDashoffset}
+/>;
+```
+
+### Follow path with marker/arrow
+
+```tsx
+import {
+  getLength,
+  getPointAtLength,
+  getTangentAtLength,
+} from "@remotion/paths";
+
+const pathLength = getLength(path);
+const point = getPointAtLength(path, progress * pathLength);
+const tangent = getTangentAtLength(path, progress * pathLength);
+const angle = Math.atan2(tangent.y, tangent.x);
+
+<g
+  style={{
+    transform: `translate(${point.x}px, ${point.y}px) rotate(${angle}rad)`,
+    transformOrigin: "0 0",
+  }}
+>
+  <polygon points="0,0 -20,-10 -20,10" fill="#FF3232" />
+</g>;
+```
diff --git a/.agents/skills/remotion-best-practices/rules/compositions.md b/.agents/skills/remotion-best-practices/rules/compositions.md
new file mode 100644
index 0000000..0db5f60
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/compositions.md
@@ -0,0 +1,154 @@
+---
+name: compositions
+description: Defining compositions, stills, folders, default props and dynamic metadata
+metadata:
+  tags: composition, still, folder, props, metadata
+---
+
+A `<Composition>` defines the component, width, height, fps and duration of a renderable video.
+
+It normally is placed in the `src/Root.tsx` file.
+
+```tsx
+import { Composition } from "remotion";
+import { MyComposition } from "./MyComposition";
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComposition}
+      durationInFrames={100}
+      fps={30}
+      width={1080}
+      height={1080}
+    />
+  );
+};
+```
+
+## Default Props
+
+Pass `defaultProps` to provide initial values for your component.  
+Values must be JSON-serializable (`Date`, `Map`, `Set`, and `staticFile()` are supported).
+
+```tsx
+import { Composition } from "remotion";
+import { MyComposition, MyCompositionProps } from "./MyComposition";
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComposition}
+      durationInFrames={100}
+      fps={30}
+      width={1080}
+      height={1080}
+      defaultProps={
+        {
+          title: "Hello World",
+          color: "#ff0000",
+        } satisfies MyCompositionProps
+      }
+    />
+  );
+};
+```
+
+Use `type` declarations for props rather than `interface` to ensure `defaultProps` type safety.
+
+## Folders
+
+Use `<Folder>` to organize compositions in the sidebar.  
+Folder names can only contain letters, numbers, and hyphens.
+
+```tsx
+import { Composition, Folder } from "remotion";
+
+export const RemotionRoot = () => {
+  return (
+    <>
+      <Folder name="Marketing">
+        <Composition id="Promo" /* ... */ />
+        <Composition id="Ad" /* ... */ />
+      </Folder>
+      <Folder name="Social">
+        <Folder name="Instagram">
+          <Composition id="Story" /* ... */ />
+          <Composition id="Reel" /* ... */ />
+        </Folder>
+      </Folder>
+    </>
+  );
+};
+```
+
+## Stills
+
+Use `<Still>` for single-frame images. It does not require `durationInFrames` or `fps`.
+
+```tsx
+import { Still } from "remotion";
+import { Thumbnail } from "./Thumbnail";
+
+export const RemotionRoot = () => {
+  return (
+    <Still id="Thumbnail" component={Thumbnail} width={1280} height={720} />
+  );
+};
+```
+
+## Calculate Metadata
+
+Use `calculateMetadata` to make dimensions, duration, or props dynamic based on data.
+
+```tsx
+import { Composition, CalculateMetadataFunction } from "remotion";
+import { MyComposition, MyCompositionProps } from "./MyComposition";
+
+const calculateMetadata: CalculateMetadataFunction<
+  MyCompositionProps
+> = async ({ props, abortSignal }) => {
+  const data = await fetch(`https://api.example.com/video/${props.videoId}`, {
+    signal: abortSignal,
+  }).then((res) => res.json());
+
+  return {
+    durationInFrames: Math.ceil(data.duration * 30),
+    props: {
+      ...props,
+      videoUrl: data.url,
+    },
+  };
+};
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComposition}
+      durationInFrames={100} // Placeholder, will be overridden
+      fps={30}
+      width={1080}
+      height={1080}
+      defaultProps={{ videoId: "abc123" }}
+      calculateMetadata={calculateMetadata}
+    />
+  );
+};
+```
+
+The function can return `props`, `durationInFrames`, `width`, `height`, `fps`, and codec-related defaults. It runs once before rendering begins.
+
+## Nesting compositions within another
+
+To add a composition within another composition, you can use the `<Sequence>` component with a `width` and `height` prop to specify the size of the composition.
+
+```tsx
+<AbsoluteFill>
+  <Sequence width={COMPOSITION_WIDTH} height={COMPOSITION_HEIGHT}>
+    <CompositionComponent />
+  </Sequence>
+</AbsoluteFill>
+```
diff --git a/.agents/skills/remotion-best-practices/rules/display-captions.md b/.agents/skills/remotion-best-practices/rules/display-captions.md
new file mode 100644
index 0000000..f9cb0f0
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/display-captions.md
@@ -0,0 +1,184 @@
+---
+name: display-captions
+description: Displaying captions in Remotion with TikTok-style pages and word highlighting
+metadata:
+  tags: captions, subtitles, display, tiktok, highlight
+---
+
+# Displaying captions in Remotion
+
+This guide explains how to display captions in Remotion, assuming you already have captions in the [`Caption`](https://www.remotion.dev/docs/captions/caption) format.
+
+## Prerequisites
+
+Read [Transcribing audio](transcribe-captions.md) for how to generate captions.
+
+First, the [`@remotion/captions`](https://www.remotion.dev/docs/captions) package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/captions
+```
+
+## Fetching captions
+
+First, fetch your captions JSON file. Use [`useDelayRender()`](https://www.remotion.dev/docs/use-delay-render) to hold the render until the captions are loaded:
+
+```tsx
+import { useState, useEffect, useCallback } from "react";
+import { AbsoluteFill, staticFile, useDelayRender } from "remotion";
+import type { Caption } from "@remotion/captions";
+
+export const MyComponent: React.FC = () => {
+  const [captions, setCaptions] = useState<Caption[] | null>(null);
+  const { delayRender, continueRender, cancelRender } = useDelayRender();
+  const [handle] = useState(() => delayRender());
+
+  const fetchCaptions = useCallback(async () => {
+    try {
+      // Assuming captions.json is in the public/ folder.
+      const response = await fetch(staticFile("captions123.json"));
+      const data = await response.json();
+      setCaptions(data);
+      continueRender(handle);
+    } catch (e) {
+      cancelRender(e);
+    }
+  }, [continueRender, cancelRender, handle]);
+
+  useEffect(() => {
+    fetchCaptions();
+  }, [fetchCaptions]);
+
+  if (!captions) {
+    return null;
+  }
+
+  return <AbsoluteFill>{/* Render captions here */}</AbsoluteFill>;
+};
+```
+
+## Creating pages
+
+Use `createTikTokStyleCaptions()` to group captions into pages. The `combineTokensWithinMilliseconds` option controls how many words appear at once:
+
+```tsx
+import { useMemo } from "react";
+import { createTikTokStyleCaptions } from "@remotion/captions";
+import type { Caption } from "@remotion/captions";
+
+// How often captions should switch (in milliseconds)
+// Higher values = more words per page
+// Lower values = fewer words (more word-by-word)
+const SWITCH_CAPTIONS_EVERY_MS = 1200;
+
+const { pages } = useMemo(() => {
+  return createTikTokStyleCaptions({
+    captions,
+    combineTokensWithinMilliseconds: SWITCH_CAPTIONS_EVERY_MS,
+  });
+}, [captions]);
+```
+
+## Rendering with Sequences
+
+Map over the pages and render each one in a `<Sequence>`. Calculate the start frame and duration from the page timing:
+
+```tsx
+import { Sequence, useVideoConfig, AbsoluteFill } from "remotion";
+import type { TikTokPage } from "@remotion/captions";
+
+const CaptionedContent: React.FC = () => {
+  const { fps } = useVideoConfig();
+
+  return (
+    <AbsoluteFill>
+      {pages.map((page, index) => {
+        const nextPage = pages[index + 1] ?? null;
+        const startFrame = (page.startMs / 1000) * fps;
+        const endFrame = Math.min(
+          nextPage ? (nextPage.startMs / 1000) * fps : Infinity,
+          startFrame + (SWITCH_CAPTIONS_EVERY_MS / 1000) * fps,
+        );
+        const durationInFrames = endFrame - startFrame;
+
+        if (durationInFrames <= 0) {
+          return null;
+        }
+
+        return (
+          <Sequence
+            key={index}
+            from={startFrame}
+            durationInFrames={durationInFrames}
+          >
+            <CaptionPage page={page} />
+          </Sequence>
+        );
+      })}
+    </AbsoluteFill>
+  );
+};
+```
+
+## White-space preservation
+
+The captions are whitespace sensitive. You should include spaces in the `text` field before each word. Use `whiteSpace: "pre"` to preserve the whitespace in the captions.
+
+## Separate component for captions
+
+Put captioning logic in a separate component.  
+Make a new file for it.
+
+## Word highlighting
+
+A caption page contains `tokens` which you can use to highlight the currently spoken word:
+
+```tsx
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
+import type { TikTokPage } from "@remotion/captions";
+
+const HIGHLIGHT_COLOR = "#39E508";
+
+const CaptionPage: React.FC<{ page: TikTokPage }> = ({ page }) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  // Current time relative to the start of the sequence
+  const currentTimeMs = (frame / fps) * 1000;
+  // Convert to absolute time by adding the page start
+  const absoluteTimeMs = page.startMs + currentTimeMs;
+
+  return (
+    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
+      <div style={{ fontSize: 80, fontWeight: "bold", whiteSpace: "pre" }}>
+        {page.tokens.map((token) => {
+          const isActive =
+            token.fromMs <= absoluteTimeMs && token.toMs > absoluteTimeMs;
+
+          return (
+            <span
+              key={token.fromMs}
+              style={{ color: isActive ? HIGHLIGHT_COLOR : "white" }}
+            >
+              {token.text}
+            </span>
+          );
+        })}
+      </div>
+    </AbsoluteFill>
+  );
+};
+```
+
+## Display captions alongside video content
+
+By default, put the captions alongside the video content, so the captions are in sync.  
+For each video, make a new captions JSON file.
+
+```tsx
+<AbsoluteFill>
+  <Video src={staticFile("video.mp4")} />
+  <CaptionPage page={page} />
+</AbsoluteFill>
+```
diff --git a/.agents/skills/remotion-best-practices/rules/extract-frames.md b/.agents/skills/remotion-best-practices/rules/extract-frames.md
new file mode 100644
index 0000000..1a8a0c8
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/extract-frames.md
@@ -0,0 +1,229 @@
+---
+name: extract-frames
+description: Extract frames from videos at specific timestamps using Mediabunny
+metadata:
+  tags: frames, extract, video, thumbnail, filmstrip, canvas
+---
+
+# Extracting frames from videos
+
+Use Mediabunny to extract frames from videos at specific timestamps. This is useful for generating thumbnails, filmstrips, or processing individual frames.
+
+## The `extractFrames()` function
+
+This function can be copy-pasted into any project.
+
+```tsx
+import {
+  ALL_FORMATS,
+  Input,
+  UrlSource,
+  VideoSample,
+  VideoSampleSink,
+} from "mediabunny";
+
+type Options = {
+  track: { width: number; height: number };
+  container: string;
+  durationInSeconds: number | null;
+};
+
+export type ExtractFramesTimestampsInSecondsFn = (
+  options: Options,
+) => Promise<number[]> | number[];
+
+export type ExtractFramesProps = {
+  src: string;
+  timestampsInSeconds: number[] | ExtractFramesTimestampsInSecondsFn;
+  onVideoSample: (sample: VideoSample) => void;
+  signal?: AbortSignal;
+};
+
+export async function extractFrames({
+  src,
+  timestampsInSeconds,
+  onVideoSample,
+  signal,
+}: ExtractFramesProps): Promise<void> {
+  using input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src),
+  });
+
+  const [durationInSeconds, format, videoTrack] = await Promise.all([
+    input.computeDuration(),
+    input.getFormat(),
+    input.getPrimaryVideoTrack(),
+  ]);
+
+  if (!videoTrack) {
+    throw new Error("No video track found in the input");
+  }
+
+  if (signal?.aborted) {
+    throw new Error("Aborted");
+  }
+
+  const timestamps =
+    typeof timestampsInSeconds === "function"
+      ? await timestampsInSeconds({
+          track: {
+            width: videoTrack.displayWidth,
+            height: videoTrack.displayHeight,
+          },
+          container: format.name,
+          durationInSeconds,
+        })
+      : timestampsInSeconds;
+
+  if (timestamps.length === 0) {
+    return;
+  }
+
+  if (signal?.aborted) {
+    throw new Error("Aborted");
+  }
+
+  const sink = new VideoSampleSink(videoTrack);
+
+  for await (using videoSample of sink.samplesAtTimestamps(timestamps)) {
+    if (signal?.aborted) {
+      break;
+    }
+
+    if (!videoSample) {
+      continue;
+    }
+
+    onVideoSample(videoSample);
+  }
+}
+```
+
+## Basic usage
+
+Extract frames at specific timestamps:
+
+```tsx
+await extractFrames({
+  src: "https://remotion.media/video.mp4",
+  timestampsInSeconds: [0, 1, 2, 3, 4],
+  onVideoSample: (sample) => {
+    const canvas = document.createElement("canvas");
+    canvas.width = sample.displayWidth;
+    canvas.height = sample.displayHeight;
+    const ctx = canvas.getContext("2d");
+    sample.draw(ctx!, 0, 0);
+  },
+});
+```
+
+## Creating a filmstrip
+
+Use a callback function to dynamically calculate timestamps based on video metadata:
+
+```tsx
+const canvasWidth = 500;
+const canvasHeight = 80;
+const fromSeconds = 0;
+const toSeconds = 10;
+
+await extractFrames({
+  src: "https://remotion.media/video.mp4",
+  timestampsInSeconds: async ({ track, durationInSeconds }) => {
+    const aspectRatio = track.width / track.height;
+    const amountOfFramesFit = Math.ceil(
+      canvasWidth / (canvasHeight * aspectRatio),
+    );
+    const segmentDuration = toSeconds - fromSeconds;
+    const timestamps: number[] = [];
+
+    for (let i = 0; i < amountOfFramesFit; i++) {
+      timestamps.push(
+        fromSeconds + (segmentDuration / amountOfFramesFit) * (i + 0.5),
+      );
+    }
+
+    return timestamps;
+  },
+  onVideoSample: (sample) => {
+    console.log(`Frame at ${sample.timestamp}s`);
+
+    const canvas = document.createElement("canvas");
+    canvas.width = sample.displayWidth;
+    canvas.height = sample.displayHeight;
+    const ctx = canvas.getContext("2d");
+    sample.draw(ctx!, 0, 0);
+  },
+});
+```
+
+## Cancellation with AbortSignal
+
+Cancel frame extraction after a timeout:
+
+```tsx
+const controller = new AbortController();
+
+setTimeout(() => controller.abort(), 5000);
+
+try {
+  await extractFrames({
+    src: "https://remotion.media/video.mp4",
+    timestampsInSeconds: [0, 1, 2, 3, 4],
+    onVideoSample: (sample) => {
+      using frame = sample;
+      const canvas = document.createElement("canvas");
+      canvas.width = frame.displayWidth;
+      canvas.height = frame.displayHeight;
+      const ctx = canvas.getContext("2d");
+      frame.draw(ctx!, 0, 0);
+    },
+    signal: controller.signal,
+  });
+
+  console.log("Frame extraction complete!");
+} catch (error) {
+  console.error("Frame extraction was aborted or failed:", error);
+}
+```
+
+## Timeout with Promise.race
+
+```tsx
+const controller = new AbortController();
+
+const timeoutPromise = new Promise<never>((_, reject) => {
+  const timeoutId = setTimeout(() => {
+    controller.abort();
+    reject(new Error("Frame extraction timed out after 10 seconds"));
+  }, 10000);
+
+  controller.signal.addEventListener("abort", () => clearTimeout(timeoutId), {
+    once: true,
+  });
+});
+
+try {
+  await Promise.race([
+    extractFrames({
+      src: "https://remotion.media/video.mp4",
+      timestampsInSeconds: [0, 1, 2, 3, 4],
+      onVideoSample: (sample) => {
+        using frame = sample;
+        const canvas = document.createElement("canvas");
+        canvas.width = frame.displayWidth;
+        canvas.height = frame.displayHeight;
+        const ctx = canvas.getContext("2d");
+        frame.draw(ctx!, 0, 0);
+      },
+      signal: controller.signal,
+    }),
+    timeoutPromise,
+  ]);
+
+  console.log("Frame extraction complete!");
+} catch (error) {
+  console.error("Frame extraction was aborted or failed:", error);
+}
+```
diff --git a/.agents/skills/remotion-best-practices/rules/ffmpeg.md b/.agents/skills/remotion-best-practices/rules/ffmpeg.md
new file mode 100644
index 0000000..20c9a2d
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/ffmpeg.md
@@ -0,0 +1,38 @@
+---
+name: ffmpeg
+description: Using FFmpeg and FFprobe in Remotion
+metadata:
+  tags: ffmpeg, ffprobe, video, trimming
+---
+
+## FFmpeg in Remotion
+
+`ffmpeg` and `ffprobe` do not need to be installed. They are available via the `bunx remotion ffmpeg` and `bunx remotion ffprobe`:
+
+```bash
+bunx remotion ffmpeg -i input.mp4 output.mp3
+bunx remotion ffprobe input.mp4
+```
+
+### Trimming videos
+
+You have 2 options for trimming videos:
+
+1. Use the FFMpeg command line. You MUST re-encode the video to avoid frozen frames at the start of the video.
+
+```bash
+# Re-encodes from the exact frame
+bunx remotion ffmpeg -ss 00:00:05 -i public/input.mp4 -to 00:00:10 -c:v libx264 -c:a aac public/output.mp4
+```
+
+2. Use the `trimBefore` and `trimAfter` props of the `<Video>` component. The benefit is that this is non-destructive and you can change the trim at any time.
+
+```tsx
+import { Video } from "@remotion/media";
+
+<Video
+  src={staticFile("video.mp4")}
+  trimBefore={5 * fps}
+  trimAfter={10 * fps}
+/>;
+```
diff --git a/.agents/skills/remotion-best-practices/rules/fonts.md b/.agents/skills/remotion-best-practices/rules/fonts.md
new file mode 100644
index 0000000..c10cd83
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/fonts.md
@@ -0,0 +1,152 @@
+---
+name: fonts
+description: Loading Google Fonts and local fonts in Remotion
+metadata:
+  tags: fonts, google-fonts, typography, text
+---
+
+# Using fonts in Remotion
+
+## Google Fonts with @remotion/google-fonts
+
+The recommended way to use Google Fonts. It's type-safe and automatically blocks rendering until the font is ready.
+
+### Prerequisites
+
+First, the @remotion/google-fonts package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/google-fonts # If project uses npm
+bunx remotion add @remotion/google-fonts # If project uses bun
+yarn remotion add @remotion/google-fonts # If project uses yarn
+pnpm exec remotion add @remotion/google-fonts # If project uses pnpm
+```
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Lobster";
+
+const { fontFamily } = loadFont();
+
+export const MyComposition = () => {
+  return <div style={{ fontFamily }}>Hello World</div>;
+};
+```
+
+Preferrably, specify only needed weights and subsets to reduce file size:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Roboto";
+
+const { fontFamily } = loadFont("normal", {
+  weights: ["400", "700"],
+  subsets: ["latin"],
+});
+```
+
+### Waiting for font to load
+
+Use `waitUntilDone()` if you need to know when the font is ready:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Lobster";
+
+const { fontFamily, waitUntilDone } = loadFont();
+
+await waitUntilDone();
+```
+
+## Local fonts with @remotion/fonts
+
+For local font files, use the `@remotion/fonts` package.
+
+### Prerequisites
+
+First, install @remotion/fonts:
+
+```bash
+npx remotion add @remotion/fonts # If project uses npm
+bunx remotion add @remotion/fonts # If project uses bun
+yarn remotion add @remotion/fonts # If project uses yarn
+pnpm exec remotion add @remotion/fonts # If project uses pnpm
+```
+
+### Loading a local font
+
+Place your font file in the `public/` folder and use `loadFont()`:
+
+```tsx
+import { loadFont } from "@remotion/fonts";
+import { staticFile } from "remotion";
+
+await loadFont({
+  family: "MyFont",
+  url: staticFile("MyFont-Regular.woff2"),
+});
+
+export const MyComposition = () => {
+  return <div style={{ fontFamily: "MyFont" }}>Hello World</div>;
+};
+```
+
+### Loading multiple weights
+
+Load each weight separately with the same family name:
+
+```tsx
+import { loadFont } from "@remotion/fonts";
+import { staticFile } from "remotion";
+
+await Promise.all([
+  loadFont({
+    family: "Inter",
+    url: staticFile("Inter-Regular.woff2"),
+    weight: "400",
+  }),
+  loadFont({
+    family: "Inter",
+    url: staticFile("Inter-Bold.woff2"),
+    weight: "700",
+  }),
+]);
+```
+
+### Available options
+
+```tsx
+loadFont({
+  family: "MyFont", // Required: name to use in CSS
+  url: staticFile("font.woff2"), // Required: font file URL
+  format: "woff2", // Optional: auto-detected from extension
+  weight: "400", // Optional: font weight
+  style: "normal", // Optional: normal or italic
+  display: "block", // Optional: font-display behavior
+});
+```
+
+## Using in components
+
+Call `loadFont()` at the top level of your component or in a separate file that's imported early:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Montserrat";
+
+const { fontFamily } = loadFont("normal", {
+  weights: ["400", "700"],
+  subsets: ["latin"],
+});
+
+export const Title: React.FC<{ text: string }> = ({ text }) => {
+  return (
+    <h1
+      style={{
+        fontFamily,
+        fontSize: 80,
+        fontWeight: "bold",
+      }}
+    >
+      {text}
+    </h1>
+  );
+};
+```
diff --git a/.agents/skills/remotion-best-practices/rules/get-audio-duration.md b/.agents/skills/remotion-best-practices/rules/get-audio-duration.md
new file mode 100644
index 0000000..35ef747
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/get-audio-duration.md
@@ -0,0 +1,58 @@
+---
+name: get-audio-duration
+description: Getting the duration of an audio file in seconds with Mediabunny
+metadata:
+  tags: duration, audio, length, time, seconds, mp3, wav
+---
+
+# Getting audio duration with Mediabunny
+
+Mediabunny can extract the duration of an audio file. It works in browser, Node.js, and Bun environments.
+
+## Getting audio duration
+
+```tsx title="get-audio-duration.ts"
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getAudioDuration = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  const durationInSeconds = await input.computeDuration();
+  return durationInSeconds;
+};
+```
+
+## Usage
+
+```tsx
+const duration = await getAudioDuration("https://remotion.media/audio.mp3");
+console.log(duration); // e.g. 180.5 (seconds)
+```
+
+## Using with staticFile in Remotion
+
+Make sure to wrap the file path in `staticFile()`:
+
+```tsx
+import { staticFile } from "remotion";
+
+const duration = await getAudioDuration(staticFile("audio.mp3"));
+```
+
+## In Node.js and Bun
+
+Use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+  formats: ALL_FORMATS,
+  source: new FileSource(file), // File object from input or drag-drop
+});
+```
diff --git a/.agents/skills/remotion-best-practices/rules/get-video-dimensions.md b/.agents/skills/remotion-best-practices/rules/get-video-dimensions.md
new file mode 100644
index 0000000..746c09f
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/get-video-dimensions.md
@@ -0,0 +1,68 @@
+---
+name: get-video-dimensions
+description: Getting the width and height of a video file with Mediabunny
+metadata:
+  tags: dimensions, width, height, resolution, size, video
+---
+
+# Getting video dimensions with Mediabunny
+
+Mediabunny can extract the width and height of a video file. It works in browser, Node.js, and Bun environments.
+
+## Getting video dimensions
+
+```tsx
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getVideoDimensions = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  const videoTrack = await input.getPrimaryVideoTrack();
+  if (!videoTrack) {
+    throw new Error("No video track found");
+  }
+
+  return {
+    width: videoTrack.displayWidth,
+    height: videoTrack.displayHeight,
+  };
+};
+```
+
+## Usage
+
+```tsx
+const dimensions = await getVideoDimensions("https://remotion.media/video.mp4");
+console.log(dimensions.width); // e.g. 1920
+console.log(dimensions.height); // e.g. 1080
+```
+
+## Using with local files
+
+For local files, use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+  formats: ALL_FORMATS,
+  source: new FileSource(file), // File object from input or drag-drop
+});
+
+const videoTrack = await input.getPrimaryVideoTrack();
+const width = videoTrack.displayWidth;
+const height = videoTrack.displayHeight;
+```
+
+## Using with staticFile in Remotion
+
+```tsx
+import { staticFile } from "remotion";
+
+const dimensions = await getVideoDimensions(staticFile("video.mp4"));
+```
diff --git a/.agents/skills/remotion-best-practices/rules/get-video-duration.md b/.agents/skills/remotion-best-practices/rules/get-video-duration.md
new file mode 100644
index 0000000..10ab735
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/get-video-duration.md
@@ -0,0 +1,60 @@
+---
+name: get-video-duration
+description: Getting the duration of a video file in seconds with Mediabunny
+metadata:
+  tags: duration, video, length, time, seconds
+---
+
+# Getting video duration with Mediabunny
+
+Mediabunny can extract the duration of a video file. It works in browser, Node.js, and Bun environments.
+
+## Getting video duration
+
+```tsx
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getVideoDuration = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  const durationInSeconds = await input.computeDuration();
+  return durationInSeconds;
+};
+```
+
+## Usage
+
+```tsx
+const duration = await getVideoDuration("https://remotion.media/video.mp4");
+console.log(duration); // e.g. 10.5 (seconds)
+```
+
+## Video files from the public/ directory
+
+Make sure to wrap the file path in `staticFile()`:
+
+```tsx
+import { staticFile } from "remotion";
+
+const duration = await getVideoDuration(staticFile("video.mp4"));
+```
+
+## In Node.js and Bun
+
+Use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+  formats: ALL_FORMATS,
+  source: new FileSource(file), // File object from input or drag-drop
+});
+
+const durationInSeconds = await input.computeDuration();
+```
diff --git a/.agents/skills/remotion-best-practices/rules/gifs.md b/.agents/skills/remotion-best-practices/rules/gifs.md
new file mode 100644
index 0000000..042647f
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/gifs.md
@@ -0,0 +1,141 @@
+---
+name: gif
+description: Displaying GIFs, APNG, AVIF and WebP in Remotion
+metadata:
+  tags: gif, animation, images, animated, apng, avif, webp
+---
+
+# Using Animated images in Remotion
+
+## Basic usage
+
+Use `<AnimatedImage>` to display a GIF, APNG, AVIF or WebP image synchronized with Remotion's timeline:
+
+```tsx
+import { AnimatedImage, staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return (
+    <AnimatedImage src={staticFile("animation.gif")} width={500} height={500} />
+  );
+};
+```
+
+Remote URLs are also supported (must have CORS enabled):
+
+```tsx
+<AnimatedImage
+  src="https://example.com/animation.gif"
+  width={500}
+  height={500}
+/>
+```
+
+## Sizing and fit
+
+Control how the image fills its container with the `fit` prop:
+
+```tsx
+// Stretch to fill (default)
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="fill" />
+
+// Maintain aspect ratio, fit inside container
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="contain" />
+
+// Fill container, crop if needed
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="cover" />
+```
+
+## Playback speed
+
+Use `playbackRate` to control the animation speed:
+
+```tsx
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} playbackRate={2} /> {/* 2x speed */}
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} playbackRate={0.5} /> {/* Half speed */}
+```
+
+## Looping behavior
+
+Control what happens when the animation finishes:
+
+```tsx
+// Loop indefinitely (default)
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="loop" />
+
+// Play once, show final frame
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="pause-after-finish" />
+
+// Play once, then clear canvas
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="clear-after-finish" />
+```
+
+## Styling
+
+Use the `style` prop for additional CSS (use `width` and `height` props for sizing):
+
+```tsx
+<AnimatedImage
+  src={staticFile("animation.gif")}
+  width={500}
+  height={500}
+  style={{
+    borderRadius: 20,
+    position: "absolute",
+    top: 100,
+    left: 50,
+  }}
+/>
+```
+
+## Getting GIF duration
+
+Use `getGifDurationInSeconds()` from `@remotion/gif` to get the duration of a GIF.
+
+```bash
+npx remotion add @remotion/gif
+```
+
+```tsx
+import { getGifDurationInSeconds } from "@remotion/gif";
+import { staticFile } from "remotion";
+
+const duration = await getGifDurationInSeconds(staticFile("animation.gif"));
+console.log(duration); // e.g. 2.5
+```
+
+This is useful for setting the composition duration to match the GIF:
+
+```tsx
+import { getGifDurationInSeconds } from "@remotion/gif";
+import { staticFile, CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction = async () => {
+  const duration = await getGifDurationInSeconds(staticFile("animation.gif"));
+  return {
+    durationInFrames: Math.ceil(duration * 30),
+  };
+};
+```
+
+## Alternative
+
+If `<AnimatedImage>` does not work (only supported in Chrome and Firefox), you can use `<Gif>` from `@remotion/gif` instead.
+
+```bash
+npx remotion add @remotion/gif # If project uses npm
+bunx remotion add @remotion/gif # If project uses bun
+yarn remotion add @remotion/gif # If project uses yarn
+pnpm exec remotion add @remotion/gif # If project uses pnpm
+```
+
+```tsx
+import { Gif } from "@remotion/gif";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Gif src={staticFile("animation.gif")} width={500} height={500} />;
+};
+```
+
+The `<Gif>` component has the same props as `<AnimatedImage>` but only supports GIF files.
diff --git a/.agents/skills/remotion-best-practices/rules/images.md b/.agents/skills/remotion-best-practices/rules/images.md
new file mode 100644
index 0000000..3b03194
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/images.md
@@ -0,0 +1,134 @@
+---
+name: images
+description: Embedding images in Remotion using the <Img> component
+metadata:
+  tags: images, img, staticFile, png, jpg, svg, webp
+---
+
+# Using images in Remotion
+
+## The `<Img>` component
+
+Always use the `<Img>` component from `remotion` to display images:
+
+```tsx
+import { Img, staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Img src={staticFile("photo.png")} />;
+};
+```
+
+## Important restrictions
+
+**You MUST use the `<Img>` component from `remotion`.** Do not use:
+
+- Native HTML `<img>` elements
+- Next.js `<Image>` component
+- CSS `background-image`
+
+The `<Img>` component ensures images are fully loaded before rendering, preventing flickering and blank frames during video export.
+
+## Local images with staticFile()
+
+Place images in the `public/` folder and use `staticFile()` to reference them:
+
+```
+my-video/
+├─ public/
+│  ├─ logo.png
+│  ├─ avatar.jpg
+│  └─ icon.svg
+├─ src/
+├─ package.json
+```
+
+```tsx
+import { Img, staticFile } from "remotion";
+
+<Img src={staticFile("logo.png")} />;
+```
+
+## Remote images
+
+Remote URLs can be used directly without `staticFile()`:
+
+```tsx
+<Img src="https://example.com/image.png" />
+```
+
+Ensure remote images have CORS enabled.
+
+For animated GIFs, use the `<Gif>` component from `@remotion/gif` instead.
+
+## Sizing and positioning
+
+Use the `style` prop to control size and position:
+
+```tsx
+<Img
+  src={staticFile("photo.png")}
+  style={{
+    width: 500,
+    height: 300,
+    position: "absolute",
+    top: 100,
+    left: 50,
+    objectFit: "cover",
+  }}
+/>
+```
+
+## Dynamic image paths
+
+Use template literals for dynamic file references:
+
+```tsx
+import { Img, staticFile, useCurrentFrame } from "remotion";
+
+const frame = useCurrentFrame();
+
+// Image sequence
+<Img src={staticFile(`frames/frame${frame}.png`)} />
+
+// Selecting based on props
+<Img src={staticFile(`avatars/${props.userId}.png`)} />
+
+// Conditional images
+<Img src={staticFile(`icons/${isActive ? "active" : "inactive"}.svg`)} />
+```
+
+This pattern is useful for:
+
+- Image sequences (frame-by-frame animations)
+- User-specific avatars or profile images
+- Theme-based icons
+- State-dependent graphics
+
+## Getting image dimensions
+
+Use `getImageDimensions()` to get the dimensions of an image:
+
+```tsx
+import { getImageDimensions, staticFile } from "remotion";
+
+const { width, height } = await getImageDimensions(staticFile("photo.png"));
+```
+
+This is useful for calculating aspect ratios or sizing compositions:
+
+```tsx
+import {
+  getImageDimensions,
+  staticFile,
+  CalculateMetadataFunction,
+} from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction = async () => {
+  const { width, height } = await getImageDimensions(staticFile("photo.png"));
+  return {
+    width,
+    height,
+  };
+};
+```
diff --git a/.agents/skills/remotion-best-practices/rules/import-srt-captions.md b/.agents/skills/remotion-best-practices/rules/import-srt-captions.md
new file mode 100644
index 0000000..333c962
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/import-srt-captions.md
@@ -0,0 +1,69 @@
+---
+name: import-srt-captions
+description: Importing .srt subtitle files into Remotion using @remotion/captions
+metadata:
+  tags: captions, subtitles, srt, import, parse
+---
+
+# Importing .srt subtitles into Remotion
+
+If you have an existing `.srt` subtitle file, you can import it into Remotion using `parseSrt()` from `@remotion/captions`.
+
+If you don't have a .srt file, read [Transcribing audio](transcribe-captions.md) for how to generate captions instead.
+
+## Prerequisites
+
+First, the @remotion/captions package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/captions # If project uses npm
+bunx remotion add @remotion/captions # If project uses bun
+yarn remotion add @remotion/captions # If project uses yarn
+pnpm exec remotion add @remotion/captions # If project uses pnpm
+```
+
+## Reading an .srt file
+
+Use `staticFile()` to reference an `.srt` file in your `public` folder, then fetch and parse it:
+
+```tsx
+import { useState, useEffect, useCallback } from "react";
+import { AbsoluteFill, staticFile, useDelayRender } from "remotion";
+import { parseSrt } from "@remotion/captions";
+import type { Caption } from "@remotion/captions";
+
+export const MyComponent: React.FC = () => {
+  const [captions, setCaptions] = useState<Caption[] | null>(null);
+  const { delayRender, continueRender, cancelRender } = useDelayRender();
+  const [handle] = useState(() => delayRender());
+
+  const fetchCaptions = useCallback(async () => {
+    try {
+      const response = await fetch(staticFile("subtitles.srt"));
+      const text = await response.text();
+      const { captions: parsed } = parseSrt({ input: text });
+      setCaptions(parsed);
+      continueRender(handle);
+    } catch (e) {
+      cancelRender(e);
+    }
+  }, [continueRender, cancelRender, handle]);
+
+  useEffect(() => {
+    fetchCaptions();
+  }, [fetchCaptions]);
+
+  if (!captions) {
+    return null;
+  }
+
+  return <AbsoluteFill>{/* Use captions here */}</AbsoluteFill>;
+};
+```
+
+Remote URLs are also supported - you can `fetch()` a remote file via URL instead of using `staticFile()`.
+
+## Using imported captions
+
+Once parsed, the captions are in the `Caption` format and can be used with all `@remotion/captions` utilities.
diff --git a/.agents/skills/remotion-best-practices/rules/light-leaks.md b/.agents/skills/remotion-best-practices/rules/light-leaks.md
new file mode 100644
index 0000000..354b956
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/light-leaks.md
@@ -0,0 +1,73 @@
+---
+name: light-leaks
+description: Light leak overlay effects for Remotion using @remotion/light-leaks.
+metadata:
+  tags: light-leaks, overlays, effects, transitions
+---
+
+## Light Leaks
+
+This only works from Remotion 4.0.415 and up. Use `npx remotion versions` to check your Remotion version and `npx remotion upgrade` to upgrade your Remotion version.
+
+`<LightLeak>` from `@remotion/light-leaks` renders a WebGL-based light leak effect. It reveals during the first half of its duration and retracts during the second half.
+
+Typically used inside a `<TransitionSeries.Overlay>` to play over the cut point between two scenes. See the **transitions** rule for `<TransitionSeries>` and overlay usage.
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/light-leaks
+```
+
+## Basic usage with TransitionSeries
+
+```tsx
+import { TransitionSeries } from "@remotion/transitions";
+import { LightLeak } from "@remotion/light-leaks";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Overlay durationInFrames={30}>
+    <LightLeak />
+  </TransitionSeries.Overlay>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Props
+
+- `durationInFrames?` — defaults to the parent sequence/composition duration. The effect reveals during the first half and retracts during the second half.
+- `seed?` — determines the shape of the light leak pattern. Different seeds produce different patterns. Default: `0`.
+- `hueShift?` — rotates the hue in degrees (`0`–`360`). Default: `0` (yellow-to-orange). `120` = green, `240` = blue.
+
+## Customizing the look
+
+```tsx
+import { LightLeak } from "@remotion/light-leaks";
+
+// Blue-tinted light leak with a different pattern
+<LightLeak seed={5} hueShift={240} />;
+
+// Green-tinted light leak
+<LightLeak seed={2} hueShift={120} />;
+```
+
+## Standalone usage
+
+`<LightLeak>` can also be used outside of `<TransitionSeries>`, for example as a decorative overlay in any composition:
+
+```tsx
+import { AbsoluteFill } from "remotion";
+import { LightLeak } from "@remotion/light-leaks";
+
+const MyComp: React.FC = () => (
+  <AbsoluteFill>
+    <MyContent />
+    <LightLeak durationInFrames={60} seed={3} />
+  </AbsoluteFill>
+);
+```
diff --git a/.agents/skills/remotion-best-practices/rules/lottie.md b/.agents/skills/remotion-best-practices/rules/lottie.md
new file mode 100644
index 0000000..4b0c4ee
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/lottie.md
@@ -0,0 +1,70 @@
+---
+name: lottie
+description: Embedding Lottie animations in Remotion.
+metadata:
+  category: Animation
+---
+
+# Using Lottie Animations in Remotion
+
+## Prerequisites
+
+First, the @remotion/lottie package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/lottie # If project uses npm
+bunx remotion add @remotion/lottie # If project uses bun
+yarn remotion add @remotion/lottie # If project uses yarn
+pnpm exec remotion add @remotion/lottie # If project uses pnpm
+```
+
+## Displaying a Lottie file
+
+To import a Lottie animation:
+
+- Fetch the Lottie asset
+- Wrap the loading process in `delayRender()` and `continueRender()`
+- Save the animation data in a state
+- Render the Lottie animation using the `Lottie` component from the `@remotion/lottie` package
+
+```tsx
+import { Lottie, LottieAnimationData } from "@remotion/lottie";
+import { useEffect, useState } from "react";
+import { cancelRender, continueRender, delayRender } from "remotion";
+
+export const MyAnimation = () => {
+  const [handle] = useState(() => delayRender("Loading Lottie animation"));
+
+  const [animationData, setAnimationData] =
+    useState<LottieAnimationData | null>(null);
+
+  useEffect(() => {
+    fetch("https://assets4.lottiefiles.com/packages/lf20_zyquagfl.json")
+      .then((data) => data.json())
+      .then((json) => {
+        setAnimationData(json);
+        continueRender(handle);
+      })
+      .catch((err) => {
+        cancelRender(err);
+      });
+  }, [handle]);
+
+  if (!animationData) {
+    return null;
+  }
+
+  return <Lottie animationData={animationData} />;
+};
+```
+
+## Styling and animating
+
+Lottie supports the `style` prop to allow styles and animations:
+
+```tsx
+return (
+  <Lottie animationData={animationData} style={{ width: 400, height: 400 }} />
+);
+```
diff --git a/.agents/skills/remotion-best-practices/rules/maps.md b/.agents/skills/remotion-best-practices/rules/maps.md
new file mode 100644
index 0000000..1e4818c
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/maps.md
@@ -0,0 +1,412 @@
+---
+name: maps
+description: Make map animations with Mapbox
+metadata:
+  tags: map, map animation, mapbox
+---
+
+Maps can be added to a Remotion video with Mapbox.  
+The [Mapbox documentation](https://docs.mapbox.com/mapbox-gl-js/api/) has the API reference.
+
+## Prerequisites
+
+Mapbox and `@turf/turf` need to be installed.
+
+Search the project for lockfiles and run the correct command depending on the package manager:
+
+If `package-lock.json` is found, use the following command:
+
+```bash
+npm i mapbox-gl @turf/turf @types/mapbox-gl
+```
+
+If `bun.lock` is found, use the following command:
+
+```bash
+bun i mapbox-gl @turf/turf @types/mapbox-gl
+```
+
+If `yarn.lock` is found, use the following command:
+
+```bash
+yarn add mapbox-gl @turf/turf @types/mapbox-gl
+```
+
+If `pnpm-lock.yaml` is found, use the following command:
+
+```bash
+pnpm i mapbox-gl @turf/turf @types/mapbox-gl
+```
+
+The user needs to create a free Mapbox account and create an access token by visiting https://console.mapbox.com/account/access-tokens/.
+
+The mapbox token needs to be added to the `.env` file:
+
+```txt title=".env"
+REMOTION_MAPBOX_TOKEN==pk.your-mapbox-access-token
+```
+
+## Adding a map
+
+Here is a basic example of a map in Remotion.
+
+```tsx
+import { useEffect, useMemo, useRef, useState } from "react";
+import { AbsoluteFill, useDelayRender, useVideoConfig } from "remotion";
+import mapboxgl, { Map } from "mapbox-gl";
+
+export const lineCoordinates = [
+  [6.56158447265625, 46.059891147620725],
+  [6.5691375732421875, 46.05679376154153],
+  [6.5842437744140625, 46.05059898938315],
+  [6.594886779785156, 46.04702502069337],
+  [6.601066589355469, 46.0460718554722],
+  [6.6089630126953125, 46.0365370783104],
+  [6.6185760498046875, 46.018420689207964],
+];
+
+mapboxgl.accessToken = process.env.REMOTION_MAPBOX_TOKEN as string;
+
+export const MyComposition = () => {
+  const ref = useRef<HTMLDivElement>(null);
+  const { delayRender, continueRender } = useDelayRender();
+
+  const { width, height } = useVideoConfig();
+  const [handle] = useState(() => delayRender("Loading map..."));
+  const [map, setMap] = useState<Map | null>(null);
+
+  useEffect(() => {
+    const _map = new Map({
+      container: ref.current!,
+      zoom: 11.53,
+      center: [6.5615, 46.0598],
+      pitch: 65,
+      bearing: 0,
+      style: "⁠mapbox://styles/mapbox/standard",
+      interactive: false,
+      fadeDuration: 0,
+    });
+
+    _map.on("style.load", () => {
+      // Hide all features from the Mapbox Standard style
+      const hideFeatures = [
+        "showRoadsAndTransit",
+        "showRoads",
+        "showTransit",
+        "showPedestrianRoads",
+        "showRoadLabels",
+        "showTransitLabels",
+        "showPlaceLabels",
+        "showPointOfInterestLabels",
+        "showPointsOfInterest",
+        "showAdminBoundaries",
+        "showLandmarkIcons",
+        "showLandmarkIconLabels",
+        "show3dObjects",
+        "show3dBuildings",
+        "show3dTrees",
+        "show3dLandmarks",
+        "show3dFacades",
+      ];
+      for (const feature of hideFeatures) {
+        _map.setConfigProperty("basemap", feature, false);
+      }
+
+      _map.setConfigProperty("basemap", "colorTrunks", "rgba(0, 0, 0, 0)");
+
+      _map.addSource("trace", {
+        type: "geojson",
+        data: {
+          type: "Feature",
+          properties: {},
+          geometry: {
+            type: "LineString",
+            coordinates: lineCoordinates,
+          },
+        },
+      });
+      _map.addLayer({
+        type: "line",
+        source: "trace",
+        id: "line",
+        paint: {
+          "line-color": "black",
+          "line-width": 5,
+        },
+        layout: {
+          "line-cap": "round",
+          "line-join": "round",
+        },
+      });
+    });
+
+    _map.on("load", () => {
+      continueRender(handle);
+      setMap(_map);
+    });
+  }, [handle, lineCoordinates]);
+
+  const style: React.CSSProperties = useMemo(
+    () => ({ width, height, position: "absolute" }),
+    [width, height],
+  );
+
+  return <AbsoluteFill ref={ref} style={style} />;
+};
+```
+
+The following is important in Remotion:
+
+- Animations must be driven by `useCurrentFrame()` and animations that Mapbox brings itself should be disabled. For example, the `fadeDuration` prop should be set to `0`, `interactive` should be set to `false`, etc.
+- Loading the map should be delayed using `useDelayRender()` and the map should be set to `null` until it is loaded.
+- The element containing the ref MUST have an explicit width and height and `position: "absolute"`.
+- Do not add a `_map.remove();` cleanup function.
+
+## Drawing lines
+
+Unless I request it, do not add a glow effect to the lines.
+Unless I request it, do not add additional points to the lines.
+
+## Map style
+
+By default, use the `mapbox://styles/mapbox/standard` style.  
+Hide the labels from the base map style.
+
+Unless I request otherwise, remove all features from the Mapbox Standard style.
+
+```tsx
+// Hide all features from the Mapbox Standard style
+const hideFeatures = [
+  "showRoadsAndTransit",
+  "showRoads",
+  "showTransit",
+  "showPedestrianRoads",
+  "showRoadLabels",
+  "showTransitLabels",
+  "showPlaceLabels",
+  "showPointOfInterestLabels",
+  "showPointsOfInterest",
+  "showAdminBoundaries",
+  "showLandmarkIcons",
+  "showLandmarkIconLabels",
+  "show3dObjects",
+  "show3dBuildings",
+  "show3dTrees",
+  "show3dLandmarks",
+  "show3dFacades",
+];
+for (const feature of hideFeatures) {
+  _map.setConfigProperty("basemap", feature, false);
+}
+
+_map.setConfigProperty("basemap", "colorMotorways", "transparent");
+_map.setConfigProperty("basemap", "colorRoads", "transparent");
+_map.setConfigProperty("basemap", "colorTrunks", "transparent");
+```
+
+## Animating the camera
+
+You can animate the camera along the line by adding a `useEffect` hook that updates the camera position based on the current frame.
+
+Unless I ask for it, do not jump between camera angles.
+
+```tsx
+import * as turf from "@turf/turf";
+import { interpolate } from "remotion";
+import { Easing } from "remotion";
+import { useCurrentFrame, useVideoConfig, useDelayRender } from "remotion";
+
+const animationDuration = 20;
+const cameraAltitude = 4000;
+```
+
+```tsx
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+const { delayRender, continueRender } = useDelayRender();
+
+useEffect(() => {
+  if (!map) {
+    return;
+  }
+  const handle = delayRender("Moving point...");
+
+  const routeDistance = turf.length(turf.lineString(lineCoordinates));
+
+  const progress = interpolate(
+    frame / fps,
+    [0.00001, animationDuration],
+    [0, 1],
+    {
+      easing: Easing.inOut(Easing.sin),
+      extrapolateLeft: "clamp",
+      extrapolateRight: "clamp",
+    },
+  );
+
+  const camera = map.getFreeCameraOptions();
+
+  const alongRoute = turf.along(
+    turf.lineString(lineCoordinates),
+    routeDistance * progress,
+  ).geometry.coordinates;
+
+  camera.lookAtPoint({
+    lng: alongRoute[0],
+    lat: alongRoute[1],
+  });
+
+  map.setFreeCameraOptions(camera);
+  map.once("idle", () => continueRender(handle));
+}, [lineCoordinates, fps, frame, handle, map]);
+```
+
+Notes:
+
+IMPORTANT: Keep the camera by default so north is up.
+IMPORTANT: For multi-step animations, set all properties at all stages (zoom, position, line progress) to prevent jumps. Override initial values.
+
+- The progress is clamped to a minimum value to avoid the line being empty, which can lead to turf errors
+- See [Timing](./timing.md) for more options for timing.
+- Consider the dimensions of the composition and make the lines thick enough and the label font size large enough to be legible for when the composition is scaled down.
+
+## Animating lines
+
+### Straight lines (linear interpolation)
+
+To animate a line that appears straight on the map, use linear interpolation between coordinates. Do NOT use turf's `lineSliceAlong` or `along` functions, as they use geodesic (great circle) calculations which appear curved on a Mercator projection.
+
+```tsx
+const frame = useCurrentFrame();
+const { durationInFrames } = useVideoConfig();
+
+useEffect(() => {
+  if (!map) return;
+
+  const animationHandle = delayRender("Animating line...");
+
+  const progress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
+    extrapolateLeft: "clamp",
+    extrapolateRight: "clamp",
+    easing: Easing.inOut(Easing.cubic),
+  });
+
+  // Linear interpolation for a straight line on the map
+  const start = lineCoordinates[0];
+  const end = lineCoordinates[1];
+  const currentLng = start[0] + (end[0] - start[0]) * progress;
+  const currentLat = start[1] + (end[1] - start[1]) * progress;
+
+  const lineData: GeoJSON.Feature<GeoJSON.LineString> = {
+    type: "Feature",
+    properties: {},
+    geometry: {
+      type: "LineString",
+      coordinates: [start, [currentLng, currentLat]],
+    },
+  };
+
+  const source = map.getSource("trace") as mapboxgl.GeoJSONSource;
+  if (source) {
+    source.setData(lineData);
+  }
+
+  map.once("idle", () => continueRender(animationHandle));
+}, [frame, map, durationInFrames]);
+```
+
+### Curved lines (geodesic/great circle)
+
+To animate a line that follows the geodesic (great circle) path between two points, use turf's `lineSliceAlong`. This is useful for showing flight paths or the actual shortest distance on Earth.
+
+```tsx
+import * as turf from "@turf/turf";
+
+const routeLine = turf.lineString(lineCoordinates);
+const routeDistance = turf.length(routeLine);
+
+const currentDistance = Math.max(0.001, routeDistance * progress);
+const slicedLine = turf.lineSliceAlong(routeLine, 0, currentDistance);
+
+const source = map.getSource("route") as mapboxgl.GeoJSONSource;
+if (source) {
+  source.setData(slicedLine);
+}
+```
+
+## Markers
+
+Add labels, and markers where appropriate.
+
+```tsx
+_map.addSource("markers", {
+  type: "geojson",
+  data: {
+    type: "FeatureCollection",
+    features: [
+      {
+        type: "Feature",
+        properties: { name: "Point 1" },
+        geometry: { type: "Point", coordinates: [-118.2437, 34.0522] },
+      },
+    ],
+  },
+});
+
+_map.addLayer({
+  id: "city-markers",
+  type: "circle",
+  source: "markers",
+  paint: {
+    "circle-radius": 40,
+    "circle-color": "#FF4444",
+    "circle-stroke-width": 4,
+    "circle-stroke-color": "#FFFFFF",
+  },
+});
+
+_map.addLayer({
+  id: "labels",
+  type: "symbol",
+  source: "markers",
+  layout: {
+    "text-field": ["get", "name"],
+    "text-font": ["DIN Pro Bold", "Arial Unicode MS Bold"],
+    "text-size": 50,
+    "text-offset": [0, 0.5],
+    "text-anchor": "top",
+  },
+  paint: {
+    "text-color": "#FFFFFF",
+    "text-halo-color": "#000000",
+    "text-halo-width": 2,
+  },
+});
+```
+
+Make sure they are big enough. Check the composition dimensions and scale the labels accordingly.
+For a composition size of 1920x1080, the label font size should be at least 40px.
+
+IMPORTANT: Keep the `text-offset` small enough so it is close to the marker. Consider the marker circle radius. For a circle radius of 40, this is a good offset:
+
+```tsx
+"text-offset": [0, 0.5],
+```
+
+## 3D buildings
+
+To enable 3D buildings, use the following code:
+
+```tsx
+_map.setConfigProperty("basemap", "show3dObjects", true);
+_map.setConfigProperty("basemap", "show3dLandmarks", true);
+_map.setConfigProperty("basemap", "show3dBuildings", true);
+```
+
+## Rendering
+
+When rendering a map animation, make sure to render with the following flags:
+
+```
+npx remotion render --gl=angle --concurrency=1
+```
diff --git a/.agents/skills/remotion-best-practices/rules/measuring-dom-nodes.md b/.agents/skills/remotion-best-practices/rules/measuring-dom-nodes.md
new file mode 100644
index 0000000..4e63424
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/measuring-dom-nodes.md
@@ -0,0 +1,34 @@
+---
+name: measuring-dom-nodes
+description: Measuring DOM element dimensions in Remotion
+metadata:
+  tags: measure, layout, dimensions, getBoundingClientRect, scale
+---
+
+# Measuring DOM nodes in Remotion
+
+Remotion applies a `scale()` transform to the video container, which affects values from `getBoundingClientRect()`. Use `useCurrentScale()` to get correct measurements.
+
+## Measuring element dimensions
+
+```tsx
+import { useCurrentScale } from "remotion";
+import { useRef, useEffect, useState } from "react";
+
+export const MyComponent = () => {
+  const ref = useRef<HTMLDivElement>(null);
+  const scale = useCurrentScale();
+  const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
+
+  useEffect(() => {
+    if (!ref.current) return;
+    const rect = ref.current.getBoundingClientRect();
+    setDimensions({
+      width: rect.width / scale,
+      height: rect.height / scale,
+    });
+  }, [scale]);
+
+  return <div ref={ref}>Content to measure</div>;
+};
+```
diff --git a/.agents/skills/remotion-best-practices/rules/measuring-text.md b/.agents/skills/remotion-best-practices/rules/measuring-text.md
new file mode 100644
index 0000000..070a184
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/measuring-text.md
@@ -0,0 +1,140 @@
+---
+name: measuring-text
+description: Measuring text dimensions, fitting text to containers, and checking overflow
+metadata:
+  tags: measure, text, layout, dimensions, fitText, fillTextBox
+---
+
+# Measuring text in Remotion
+
+## Prerequisites
+
+Install @remotion/layout-utils if it is not already installed:
+
+```bash
+npx remotion add @remotion/layout-utils
+```
+
+## Measuring text dimensions
+
+Use `measureText()` to calculate the width and height of text:
+
+```tsx
+import { measureText } from "@remotion/layout-utils";
+
+const { width, height } = measureText({
+  text: "Hello World",
+  fontFamily: "Arial",
+  fontSize: 32,
+  fontWeight: "bold",
+});
+```
+
+Results are cached - duplicate calls return the cached result.
+
+## Fitting text to a width
+
+Use `fitText()` to find the optimal font size for a container:
+
+```tsx
+import { fitText } from "@remotion/layout-utils";
+
+const { fontSize } = fitText({
+  text: "Hello World",
+  withinWidth: 600,
+  fontFamily: "Inter",
+  fontWeight: "bold",
+});
+
+return (
+  <div
+    style={{
+      fontSize: Math.min(fontSize, 80), // Cap at 80px
+      fontFamily: "Inter",
+      fontWeight: "bold",
+    }}
+  >
+    Hello World
+  </div>
+);
+```
+
+## Checking text overflow
+
+Use `fillTextBox()` to check if text exceeds a box:
+
+```tsx
+import { fillTextBox } from "@remotion/layout-utils";
+
+const box = fillTextBox({ maxBoxWidth: 400, maxLines: 3 });
+
+const words = ["Hello", "World", "This", "is", "a", "test"];
+for (const word of words) {
+  const { exceedsBox } = box.add({
+    text: word + " ",
+    fontFamily: "Arial",
+    fontSize: 24,
+  });
+  if (exceedsBox) {
+    // Text would overflow, handle accordingly
+    break;
+  }
+}
+```
+
+## Best practices
+
+**Load fonts first:** Only call measurement functions after fonts are loaded.
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Inter";
+
+const { fontFamily, waitUntilDone } = loadFont("normal", {
+  weights: ["400"],
+  subsets: ["latin"],
+});
+
+waitUntilDone().then(() => {
+  // Now safe to measure
+  const { width } = measureText({
+    text: "Hello",
+    fontFamily,
+    fontSize: 32,
+  });
+});
+```
+
+**Use validateFontIsLoaded:** Catch font loading issues early:
+
+```tsx
+measureText({
+  text: "Hello",
+  fontFamily: "MyCustomFont",
+  fontSize: 32,
+  validateFontIsLoaded: true, // Throws if font not loaded
+});
+```
+
+**Match font properties:** Use the same properties for measurement and rendering:
+
+```tsx
+const fontStyle = {
+  fontFamily: "Inter",
+  fontSize: 32,
+  fontWeight: "bold" as const,
+  letterSpacing: "0.5px",
+};
+
+const { width } = measureText({
+  text: "Hello",
+  ...fontStyle,
+});
+
+return <div style={fontStyle}>Hello</div>;
+```
+
+**Avoid padding and border:** Use `outline` instead of `border` to prevent layout differences:
+
+```tsx
+<div style={{ outline: "2px solid red" }}>Text</div>
+```
diff --git a/.agents/skills/remotion-best-practices/rules/parameters.md b/.agents/skills/remotion-best-practices/rules/parameters.md
new file mode 100644
index 0000000..8860800
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/parameters.md
@@ -0,0 +1,109 @@
+---
+name: parameters
+description: Make a video parametrizable by adding a Zod schema
+metadata:
+  tags: parameters, zod, schema
+---
+
+To make a video parametrizable, a Zod schema can be added to a composition.
+
+First, `zod` must be installed .
+
+Search the project for lockfiles and run the correct command depending on the package manager:
+
+If `package-lock.json` is found, use the following command:
+
+```bash
+npm i zod
+```
+
+If `bun.lockb` is found, use the following command:
+
+```bash
+bun i zod
+```
+
+If `yarn.lock` is found, use the following command:
+
+```bash
+yarn add zod
+```
+
+If `pnpm-lock.yaml` is found, use the following command:
+
+```bash
+pnpm i zod
+```
+
+Then, a Zod schema can be defined alongside the component:
+
+```tsx title="src/MyComposition.tsx"
+import { z } from "zod";
+
+export const MyCompositionSchema = z.object({
+  title: z.string(),
+});
+
+const MyComponent: React.FC<z.infer<typeof MyCompositionSchema>> = () => {
+  return (
+    <div>
+      <h1>{props.title}</h1>
+    </div>
+  );
+};
+```
+
+In the root file, the schema can be passed to the composition:
+
+```tsx title="src/Root.tsx"
+import { Composition } from "remotion";
+import { MycComponent, MyCompositionSchema } from "./MyComposition";
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComponent}
+      durationInFrames={100}
+      fps={30}
+      width={1080}
+      height={1080}
+      defaultProps={{ title: "Hello World" }}
+      schema={MyCompositionSchema}
+    />
+  );
+};
+```
+
+Now, the user can edit the parameter visually in the sidebar.
+
+All schemas that are supported by Zod are supported by Remotion.
+
+Remotion requires that the top-level type is a z.object(), because the collection of props of a React component is always an object.
+
+## Color picker
+
+For adding a color picker, use `zColor()` from `@remotion/zod-types`.
+
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/zod-types # If project uses npm
+bunx remotion add @remotion/zod-types # If project uses bun
+yarn remotion add @remotion/zod-types # If project uses yarn
+pnpm exec remotion add @remotion/zod-types # If project uses pnpm
+```
+
+Then import `zColor` from `@remotion/zod-types`:
+
+```tsx
+import { zColor } from "@remotion/zod-types";
+```
+
+Then use it in the schema:
+
+```tsx
+export const MyCompositionSchema = z.object({
+  color: zColor(),
+});
+```
diff --git a/.agents/skills/remotion-best-practices/rules/sequencing.md b/.agents/skills/remotion-best-practices/rules/sequencing.md
new file mode 100644
index 0000000..46b86a8
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/sequencing.md
@@ -0,0 +1,118 @@
+---
+name: sequencing
+description: Sequencing patterns for Remotion - delay, trim, limit duration of items
+metadata:
+  tags: sequence, series, timing, delay, trim
+---
+
+Use `<Sequence>` to delay when an element appears in the timeline.
+
+```tsx
+import { Sequence } from "remotion";
+
+const {fps} = useVideoConfig();
+
+<Sequence from={1 * fps} durationInFrames={2 * fps} premountFor={1 * fps}>
+  <Title />
+</Sequence>
+<Sequence from={2 * fps} durationInFrames={2 * fps} premountFor={1 * fps}>
+  <Subtitle />
+</Sequence>
+```
+
+This will by default wrap the component in an absolute fill element.  
+If the items should not be wrapped, use the `layout` prop:
+
+```tsx
+<Sequence layout="none">
+  <Title />
+</Sequence>
+```
+
+## Premounting
+
+This loads the component in the timeline before it is actually played.  
+Always premount any `<Sequence>`!
+
+```tsx
+<Sequence premountFor={1 * fps}>
+  <Title />
+</Sequence>
+```
+
+## Series
+
+Use `<Series>` when elements should play one after another without overlap.
+
+```tsx
+import { Series } from "remotion";
+
+<Series>
+  <Series.Sequence durationInFrames={45}>
+    <Intro />
+  </Series.Sequence>
+  <Series.Sequence durationInFrames={60}>
+    <MainContent />
+  </Series.Sequence>
+  <Series.Sequence durationInFrames={30}>
+    <Outro />
+  </Series.Sequence>
+</Series>;
+```
+
+Same as with `<Sequence>`, the items will be wrapped in an absolute fill element by default when using `<Series.Sequence>`, unless the `layout` prop is set to `none`.
+
+### Series with overlaps
+
+Use negative offset for overlapping sequences:
+
+```tsx
+<Series>
+  <Series.Sequence durationInFrames={60}>
+    <SceneA />
+  </Series.Sequence>
+  <Series.Sequence offset={-15} durationInFrames={60}>
+    {/* Starts 15 frames before SceneA ends */}
+    <SceneB />
+  </Series.Sequence>
+</Series>
+```
+
+## Frame References Inside Sequences
+
+Inside a Sequence, `useCurrentFrame()` returns the local frame (starting from 0):
+
+```tsx
+<Sequence from={60} durationInFrames={30}>
+  <MyComponent />
+  {/* Inside MyComponent, useCurrentFrame() returns 0-29, not 60-89 */}
+</Sequence>
+```
+
+## Nested Sequences
+
+Sequences can be nested for complex timing:
+
+```tsx
+<Sequence from={0} durationInFrames={120}>
+  <Background />
+  <Sequence from={15} durationInFrames={90} layout="none">
+    <Title />
+  </Sequence>
+  <Sequence from={45} durationInFrames={60} layout="none">
+    <Subtitle />
+  </Sequence>
+</Sequence>
+```
+
+## Nesting compositions within another
+
+To add a composition within another composition, you can use the `<Sequence>` component with a `width` and `height` prop to specify the size of the composition.
+
+```tsx
+<AbsoluteFill>
+  <Sequence width={COMPOSITION_WIDTH} height={COMPOSITION_HEIGHT}>
+    <CompositionComponent />
+  </Sequence>
+</AbsoluteFill>
+```
diff --git a/.agents/skills/remotion-best-practices/rules/sfx.md b/.agents/skills/remotion-best-practices/rules/sfx.md
new file mode 100644
index 0000000..f03c6b7
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/sfx.md
@@ -0,0 +1,26 @@
+---
+name: sfx
+description: Including sound effects
+metadata:
+  tags: sfx, sound, effect, audio
+---
+
+To include a sound effect, use the `<Audio>` tag:
+
+```tsx
+import { Audio } from "@remotion/sfx";
+
+<Audio src={"https://remotion.media/whoosh.wav"} />;
+```
+
+The following sound effects are available:
+
+- `https://remotion.media/whoosh.wav`
+- `https://remotion.media/whip.wav`
+- `https://remotion.media/page-turn.wav`
+- `https://remotion.media/switch.wav`
+- `https://remotion.media/mouse-click.wav`
+- `https://remotion.media/shutter-modern.wav`
+- `https://remotion.media/shutter-old.wav`
+
+For more sound effects, search the internet. A good resource is https://github.com/kapishdima/soundcn/tree/main/assets.
diff --git a/.agents/skills/remotion-best-practices/rules/subtitles.md b/.agents/skills/remotion-best-practices/rules/subtitles.md
new file mode 100644
index 0000000..2291eef
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/subtitles.md
@@ -0,0 +1,36 @@
+---
+name: subtitles
+description: subtitles and caption rules
+metadata:
+  tags: subtitles, captions, remotion, json
+---
+
+All captions must be processed in JSON. The captions must use the `Caption` type which is the following:
+
+```ts
+import type { Caption } from "@remotion/captions";
+```
+
+This is the definition:
+
+```ts
+type Caption = {
+  text: string;
+  startMs: number;
+  endMs: number;
+  timestampMs: number | null;
+  confidence: number | null;
+};
+```
+
+## Generating captions
+
+To transcribe video and audio files to generate captions, load the [./transcribe-captions.md](./transcribe-captions.md) file for more instructions.
+
+## Displaying captions
+
+To display captions in your video, load the [./display-captions.md](./display-captions.md) file for more instructions.
+
+## Importing captions
+
+To import captions from a .srt file, load the [./import-srt-captions.md](./import-srt-captions.md) file for more instructions.
diff --git a/.agents/skills/remotion-best-practices/rules/tailwind.md b/.agents/skills/remotion-best-practices/rules/tailwind.md
new file mode 100644
index 0000000..928f633
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/tailwind.md
@@ -0,0 +1,11 @@
+---
+name: tailwind
+description: Using TailwindCSS in Remotion.
+metadata:
+---
+
+You can and should use TailwindCSS in Remotion, if TailwindCSS is installed in the project.
+
+Don't use `transition-*` or `animate-*` classes - always animate using the `useCurrentFrame()` hook.
+
+Tailwind must be installed and enabled first in a Remotion project - fetch https://www.remotion.dev/docs/tailwind using WebFetch for instructions.
diff --git a/.agents/skills/remotion-best-practices/rules/text-animations.md b/.agents/skills/remotion-best-practices/rules/text-animations.md
new file mode 100644
index 0000000..e38b1c5
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/text-animations.md
@@ -0,0 +1,20 @@
+---
+name: text-animations
+description: Typography and text animation patterns for Remotion.
+metadata:
+  tags: typography, text, typewriter, highlighter ken
+---
+
+## Text animations
+
+Based on `useCurrentFrame()`, reduce the string character by character to create a typewriter effect.
+
+## Typewriter Effect
+
+See [Typewriter](assets/text-animations-typewriter.tsx) for an advanced example with a blinking cursor and a pause after the first sentence.
+
+Always use string slicing for typewriter effects. Never use per-character opacity.
+
+## Word Highlighting
+
+See [Word Highlight](assets/text-animations-word-highlight.tsx) for an example for how a word highlight is animated, like with a highlighter pen.
diff --git a/.agents/skills/remotion-best-practices/rules/timing.md b/.agents/skills/remotion-best-practices/rules/timing.md
new file mode 100644
index 0000000..a7b4987
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/timing.md
@@ -0,0 +1,179 @@
+---
+name: timing
+description: Interpolation curves in Remotion - linear, easing, spring animations
+metadata:
+  tags: spring, bounce, easing, interpolation
+---
+
+A simple linear interpolation is done using the `interpolate` function.
+
+```ts title="Going from 0 to 1 over 100 frames"
+import { interpolate } from "remotion";
+
+const opacity = interpolate(frame, [0, 100], [0, 1]);
+```
+
+By default, the values are not clamped, so the value can go outside the range [0, 1].  
+Here is how they can be clamped:
+
+```ts title="Going from 0 to 1 over 100 frames with extrapolation"
+const opacity = interpolate(frame, [0, 100], [0, 1], {
+  extrapolateRight: "clamp",
+  extrapolateLeft: "clamp",
+});
+```
+
+## Spring animations
+
+Spring animations have a more natural motion.  
+They go from 0 to 1 over time.
+
+```ts title="Spring animation from 0 to 1 over 100 frames"
+import { spring, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const scale = spring({
+  frame,
+  fps,
+});
+```
+
+### Physical properties
+
+The default configuration is: `mass: 1, damping: 10, stiffness: 100`.  
+This leads to the animation having a bit of bounce before it settles.
+
+The config can be overwritten like this:
+
+```ts
+const scale = spring({
+  frame,
+  fps,
+  config: { damping: 200 },
+});
+```
+
+The recommended configuration for a natural motion without a bounce is: `{ damping: 200 }`.
+
+Here are some common configurations:
+
+```tsx
+const smooth = { damping: 200 }; // Smooth, no bounce (subtle reveals)
+const snappy = { damping: 20, stiffness: 200 }; // Snappy, minimal bounce (UI elements)
+const bouncy = { damping: 8 }; // Bouncy entrance (playful animations)
+const heavy = { damping: 15, stiffness: 80, mass: 2 }; // Heavy, slow, small bounce
+```
+
+### Delay
+
+The animation starts immediately by default.  
+Use the `delay` parameter to delay the animation by a number of frames.
+
+```tsx
+const entrance = spring({
+  frame: frame - ENTRANCE_DELAY,
+  fps,
+  delay: 20,
+});
+```
+
+### Duration
+
+A `spring()` has a natural duration based on the physical properties.  
+To stretch the animation to a specific duration, use the `durationInFrames` parameter.
+
+```tsx
+const spring = spring({
+  frame,
+  fps,
+  durationInFrames: 40,
+});
+```
+
+### Combining spring() with interpolate()
+
+Map spring output (0-1) to custom ranges:
+
+```tsx
+const springProgress = spring({
+  frame,
+  fps,
+});
+
+// Map to rotation
+const rotation = interpolate(springProgress, [0, 1], [0, 360]);
+
+<div style={{ rotate: rotation + "deg" }} />;
+```
+
+### Adding springs
+
+Springs return just numbers, so math can be performed:
+
+```tsx
+const frame = useCurrentFrame();
+const { fps, durationInFrames } = useVideoConfig();
+
+const inAnimation = spring({
+  frame,
+  fps,
+});
+const outAnimation = spring({
+  frame,
+  fps,
+  durationInFrames: 1 * fps,
+  delay: durationInFrames - 1 * fps,
+});
+
+const scale = inAnimation - outAnimation;
+```
+
+## Easing
+
+Easing can be added to the `interpolate` function:
+
+```ts
+import { interpolate, Easing } from "remotion";
+
+const value1 = interpolate(frame, [0, 100], [0, 1], {
+  easing: Easing.inOut(Easing.quad),
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+```
+
+The default easing is `Easing.linear`.  
+There are various other convexities:
+
+- `Easing.in` for starting slow and accelerating
+- `Easing.out` for starting fast and slowing down
+- `Easing.inOut`
+
+and curves (sorted from most linear to most curved):
+
+- `Easing.quad`
+- `Easing.sin`
+- `Easing.exp`
+- `Easing.circle`
+
+Convexities and curves need be combined for an easing function:
+
+```ts
+const value1 = interpolate(frame, [0, 100], [0, 1], {
+  easing: Easing.inOut(Easing.quad),
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+```
+
+Cubic bezier curves are also supported:
+
+```ts
+const value1 = interpolate(frame, [0, 100], [0, 1], {
+  easing: Easing.bezier(0.8, 0.22, 0.96, 0.65),
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+```
diff --git a/.agents/skills/remotion-best-practices/rules/transcribe-captions.md b/.agents/skills/remotion-best-practices/rules/transcribe-captions.md
new file mode 100644
index 0000000..ba649d5
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/transcribe-captions.md
@@ -0,0 +1,70 @@
+---
+name: transcribe-captions
+description: Transcribing audio to generate captions in Remotion
+metadata:
+  tags: captions, transcribe, whisper, audio, speech-to-text
+---
+
+# Transcribing audio
+
+To transcribe audio to generate captions in Remotion, you can use the [`transcribe()`](https://www.remotion.dev/docs/install-whisper-cpp/transcribe) function from the [`@remotion/install-whisper-cpp`](https://www.remotion.dev/docs/install-whisper-cpp) package.
+
+## Prerequisites
+
+First, the @remotion/install-whisper-cpp package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/install-whisper-cpp
+```
+
+## Transcribing
+
+Make a Node.js script to download Whisper.cpp and a model, and transcribe the audio.
+
+```ts
+import path from "path";
+import {
+  downloadWhisperModel,
+  installWhisperCpp,
+  transcribe,
+  toCaptions,
+} from "@remotion/install-whisper-cpp";
+import fs from "fs";
+
+const to = path.join(process.cwd(), "whisper.cpp");
+
+await installWhisperCpp({
+  to,
+  version: "1.5.5",
+});
+
+await downloadWhisperModel({
+  model: "medium.en",
+  folder: to,
+});
+
+// Convert the audio to a 16KHz wav file first if needed:
+// import {execSync} from 'child_process';
+// execSync('ffmpeg -i /path/to/audio.mp4 -ar 16000 /path/to/audio.wav -y');
+
+const whisperCppOutput = await transcribe({
+  model: "medium.en",
+  whisperPath: to,
+  whisperCppVersion: "1.5.5",
+  inputPath: "/path/to/audio123.wav",
+  tokenLevelTimestamps: true,
+});
+
+// Optional: Apply our recommended postprocessing
+const { captions } = toCaptions({
+  whisperCppOutput,
+});
+
+// Write it to the public/ folder so it can be fetched from Remotion
+fs.writeFileSync("captions123.json", JSON.stringify(captions, null, 2));
+```
+
+Transcribe each clip individually and create multiple JSON files.
+
+See [Displaying captions](display-captions.md) for how to display the captions in Remotion.
diff --git a/.agents/skills/remotion-best-practices/rules/transitions.md b/.agents/skills/remotion-best-practices/rules/transitions.md
new file mode 100644
index 0000000..91ef8bd
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/transitions.md
@@ -0,0 +1,197 @@
+---
+name: transitions
+description: Scene transitions and overlays for Remotion using TransitionSeries.
+metadata:
+  tags: transitions, overlays, fade, slide, wipe, scenes
+---
+
+## TransitionSeries
+
+`<TransitionSeries>` arranges scenes and supports two ways to enhance the cut point between them:
+
+- **Transitions** (`<TransitionSeries.Transition>`) — crossfade, slide, wipe, etc. between two scenes. Shortens the timeline because both scenes play simultaneously during the transition.
+- **Overlays** (`<TransitionSeries.Overlay>`) — render an effect (e.g. a light leak) on top of the cut point without shortening the timeline.
+
+Children are absolutely positioned.
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/transitions
+```
+
+## Transition example
+
+```tsx
+import { TransitionSeries, linearTiming } from "@remotion/transitions";
+import { fade } from "@remotion/transitions/fade";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={fade()}
+    timing={linearTiming({ durationInFrames: 15 })}
+  />
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Overlay example
+
+Any React component can be used as an overlay. For a ready-made effect, see the **light-leaks** rule.
+
+```tsx
+import { TransitionSeries } from "@remotion/transitions";
+import { LightLeak } from "@remotion/light-leaks";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Overlay durationInFrames={20}>
+    <LightLeak />
+  </TransitionSeries.Overlay>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Mixing transitions and overlays
+
+Transitions and overlays can coexist in the same `<TransitionSeries>`, but an overlay cannot be adjacent to a transition or another overlay.
+
+```tsx
+import { TransitionSeries, linearTiming } from "@remotion/transitions";
+import { fade } from "@remotion/transitions/fade";
+import { LightLeak } from "@remotion/light-leaks";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Overlay durationInFrames={30}>
+    <LightLeak />
+  </TransitionSeries.Overlay>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={fade()}
+    timing={linearTiming({ durationInFrames: 15 })}
+  />
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneC />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Transition props
+
+`<TransitionSeries.Transition>` requires:
+
+- `presentation` — the visual effect (e.g. `fade()`, `slide()`, `wipe()`).
+- `timing` — controls speed and easing (e.g. `linearTiming()`, `springTiming()`).
+
+## Overlay props
+
+`<TransitionSeries.Overlay>` accepts:
+
+- `durationInFrames` — how long the overlay is visible (positive integer).
+- `offset?` — shifts the overlay relative to the cut point center. Positive = later, negative = earlier. Default: `0`.
+
+## Available transition types
+
+Import transitions from their respective modules:
+
+```tsx
+import { fade } from "@remotion/transitions/fade";
+import { slide } from "@remotion/transitions/slide";
+import { wipe } from "@remotion/transitions/wipe";
+import { flip } from "@remotion/transitions/flip";
+import { clockWipe } from "@remotion/transitions/clock-wipe";
+```
+
+## Slide transition with direction
+
+```tsx
+import { slide } from "@remotion/transitions/slide";
+
+<TransitionSeries.Transition
+  presentation={slide({ direction: "from-left" })}
+  timing={linearTiming({ durationInFrames: 20 })}
+/>;
+```
+
+Directions: `"from-left"`, `"from-right"`, `"from-top"`, `"from-bottom"`
+
+## Timing options
+
+```tsx
+import { linearTiming, springTiming } from "@remotion/transitions";
+
+// Linear timing - constant speed
+linearTiming({ durationInFrames: 20 });
+
+// Spring timing - organic motion
+springTiming({ config: { damping: 200 }, durationInFrames: 25 });
+```
+
+## Duration calculation
+
+Transitions overlap adjacent scenes, so the total composition length is **shorter** than the sum of all sequence durations. Overlays do **not** affect the total duration.
+
+For example, with two 60-frame sequences and a 15-frame transition:
+
+- Without transitions: `60 + 60 = 120` frames
+- With transition: `60 + 60 - 15 = 105` frames
+
+Adding an overlay between two other sequences does not change the total.
+
+### Getting the duration of a transition
+
+Use the `getDurationInFrames()` method on the timing object:
+
+```tsx
+import { linearTiming, springTiming } from "@remotion/transitions";
+
+const linearDuration = linearTiming({
+  durationInFrames: 20,
+}).getDurationInFrames({ fps: 30 });
+// Returns 20
+
+const springDuration = springTiming({
+  config: { damping: 200 },
+}).getDurationInFrames({ fps: 30 });
+// Returns calculated duration based on spring physics
+```
+
+For `springTiming` without an explicit `durationInFrames`, the duration depends on `fps` because it calculates when the spring animation settles.
+
+### Calculating total composition duration
+
+```tsx
+import { linearTiming } from "@remotion/transitions";
+
+const scene1Duration = 60;
+const scene2Duration = 60;
+const scene3Duration = 60;
+
+const timing1 = linearTiming({ durationInFrames: 15 });
+const timing2 = linearTiming({ durationInFrames: 20 });
+
+const transition1Duration = timing1.getDurationInFrames({ fps: 30 });
+const transition2Duration = timing2.getDurationInFrames({ fps: 30 });
+
+const totalDuration =
+  scene1Duration +
+  scene2Duration +
+  scene3Duration -
+  transition1Duration -
+  transition2Duration;
+// 60 + 60 + 60 - 15 - 20 = 145 frames
+```
diff --git a/.agents/skills/remotion-best-practices/rules/transparent-videos.md b/.agents/skills/remotion-best-practices/rules/transparent-videos.md
new file mode 100644
index 0000000..dce5de5
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/transparent-videos.md
@@ -0,0 +1,106 @@
+---
+name: transparent-videos
+description: Rendering transparent videos in Remotion
+metadata:
+  tags: transparent, alpha, codec, vp9, prores, webm
+---
+
+# Rendering Transparent Videos
+
+Remotion can render transparent videos in two ways: as a ProRes video or as a WebM video.
+
+## Transparent ProRes
+
+Ideal for when importing into video editing software.
+
+**CLI:**
+
+```bash
+npx remotion render --image-format=png --pixel-format=yuva444p10le --codec=prores --prores-profile=4444 MyComp out.mov
+```
+
+**Default in Studio** (restart Studio after changing):
+
+```ts
+// remotion.config.ts
+import { Config } from "@remotion/cli/config";
+
+Config.setVideoImageFormat("png");
+Config.setPixelFormat("yuva444p10le");
+Config.setCodec("prores");
+Config.setProResProfile("4444");
+```
+
+**Setting it as the default export settings for a composition** (using `calculateMetadata`):
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultCodec: "prores",
+    defaultVideoImageFormat: "png",
+    defaultPixelFormat: "yuva444p10le",
+    defaultProResProfile: "4444",
+  };
+};
+
+<Composition
+  id="my-video"
+  component={MyVideo}
+  durationInFrames={150}
+  fps={30}
+  width={1920}
+  height={1080}
+  calculateMetadata={calculateMetadata}
+/>;
+```
+
+## Transparent WebM (VP9)
+
+Ideal for when playing in a browser.
+
+**CLI:**
+
+```bash
+npx remotion render --image-format=png --pixel-format=yuva420p --codec=vp9 MyComp out.webm
+```
+
+**Default in Studio** (restart Studio after changing):
+
+```ts
+// remotion.config.ts
+import { Config } from "@remotion/cli/config";
+
+Config.setVideoImageFormat("png");
+Config.setPixelFormat("yuva420p");
+Config.setCodec("vp9");
+```
+
+**Setting it as the default export settings for a composition** (using `calculateMetadata`):
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultCodec: "vp8",
+    defaultVideoImageFormat: "png",
+    defaultPixelFormat: "yuva420p",
+  };
+};
+
+<Composition
+  id="my-video"
+  component={MyVideo}
+  durationInFrames={150}
+  fps={30}
+  width={1920}
+  height={1080}
+  calculateMetadata={calculateMetadata}
+/>;
+```
diff --git a/.agents/skills/remotion-best-practices/rules/trimming.md b/.agents/skills/remotion-best-practices/rules/trimming.md
new file mode 100644
index 0000000..e7534d1
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/trimming.md
@@ -0,0 +1,51 @@
+---
+name: trimming
+description: Trimming patterns for Remotion - cut the beginning or end of animations
+metadata:
+  tags: sequence, trim, clip, cut, offset
+---
+
+Use `<Sequence>` with a negative `from` value to trim the start of an animation.
+
+## Trim the Beginning
+
+A negative `from` value shifts time backwards, making the animation start partway through:
+
+```tsx
+import { Sequence, useVideoConfig } from "remotion";
+
+const fps = useVideoConfig();
+
+<Sequence from={-0.5 * fps}>
+  <MyAnimation />
+</Sequence>;
+```
+
+The animation appears 15 frames into its progress - the first 15 frames are trimmed off.
+Inside `<MyAnimation>`, `useCurrentFrame()` starts at 15 instead of 0.
+
+## Trim the End
+
+Use `durationInFrames` to unmount content after a specified duration:
+
+```tsx
+<Sequence durationInFrames={1.5 * fps}>
+  <MyAnimation />
+</Sequence>
+```
+
+The animation plays for 45 frames, then the component unmounts.
+
+## Trim and Delay
+
+Nest sequences to both trim the beginning and delay when it appears:
+
+```tsx
+<Sequence from={30}>
+  <Sequence from={-15}>
+    <MyAnimation />
+  </Sequence>
+</Sequence>
+```
+
+The inner sequence trims 15 frames from the start, and the outer sequence delays the result by 30 frames.
diff --git a/.agents/skills/remotion-best-practices/rules/videos.md b/.agents/skills/remotion-best-practices/rules/videos.md
new file mode 100644
index 0000000..4d99b31
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/videos.md
@@ -0,0 +1,171 @@
+---
+name: videos
+description: Embedding videos in Remotion - trimming, volume, speed, looping, pitch
+metadata:
+  tags: video, media, trim, volume, speed, loop, pitch
+---
+
+# Using videos in Remotion
+
+## Prerequisites
+
+First, the @remotion/media package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/media # If project uses npm
+bunx remotion add @remotion/media # If project uses bun
+yarn remotion add @remotion/media # If project uses yarn
+pnpm exec remotion add @remotion/media # If project uses pnpm
+```
+
+Use `<Video>` from `@remotion/media` to embed videos into your composition.
+
+```tsx
+import { Video } from "@remotion/media";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Video src={staticFile("video.mp4")} />;
+};
+```
+
+Remote URLs are also supported:
+
+```tsx
+<Video src="https://remotion.media/video.mp4" />
+```
+
+## Trimming
+
+Use `trimBefore` and `trimAfter` to remove portions of the video. Values are in seconds.
+
+```tsx
+const { fps } = useVideoConfig();
+
+return (
+  <Video
+    src={staticFile("video.mp4")}
+    trimBefore={2 * fps} // Skip the first 2 seconds
+    trimAfter={10 * fps} // End at the 10 second mark
+  />
+);
+```
+
+## Delaying
+
+Wrap the video in a `<Sequence>` to delay when it appears:
+
+```tsx
+import { Sequence, staticFile } from "remotion";
+import { Video } from "@remotion/media";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Sequence from={1 * fps}>
+    <Video src={staticFile("video.mp4")} />
+  </Sequence>
+);
+```
+
+The video will appear after 1 second.
+
+## Sizing and Position
+
+Use the `style` prop to control size and position:
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  style={{
+    width: 500,
+    height: 300,
+    position: "absolute",
+    top: 100,
+    left: 50,
+    objectFit: "cover",
+  }}
+/>
+```
+
+## Volume
+
+Set a static volume (0 to 1):
+
+```tsx
+<Video src={staticFile("video.mp4")} volume={0.5} />
+```
+
+Or use a callback for dynamic volume based on the current frame:
+
+```tsx
+import { interpolate } from "remotion";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Video
+    src={staticFile("video.mp4")}
+    volume={(f) =>
+      interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
+    }
+  />
+);
+```
+
+Use `muted` to silence the video entirely:
+
+```tsx
+<Video src={staticFile("video.mp4")} muted />
+```
+
+## Speed
+
+Use `playbackRate` to change the playback speed:
+
+```tsx
+<Video src={staticFile("video.mp4")} playbackRate={2} /> {/* 2x speed */}
+<Video src={staticFile("video.mp4")} playbackRate={0.5} /> {/* Half speed */}
+```
+
+Reverse playback is not supported.
+
+## Looping
+
+Use `loop` to loop the video indefinitely:
+
+```tsx
+<Video src={staticFile("video.mp4")} loop />
+```
+
+Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
+
+- `"repeat"`: Frame count resets to 0 each loop (for `volume` callback)
+- `"extend"`: Frame count continues incrementing
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  loop
+  loopVolumeCurveBehavior="extend"
+  volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
+/>
+```
+
+## Pitch
+
+Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  toneFrequency={1.5} // Higher pitch
+/>
+<Video
+  src={staticFile("video.mp4")}
+  toneFrequency={0.8} // Lower pitch
+/>
+```
+
+Pitch shifting only works during server-side rendering, not in the Remotion Studio preview or in the `<Player />`.
diff --git a/.agents/skills/remotion-best-practices/rules/voiceover.md b/.agents/skills/remotion-best-practices/rules/voiceover.md
new file mode 100644
index 0000000..0d3b546
--- /dev/null
+++ b/.agents/skills/remotion-best-practices/rules/voiceover.md
@@ -0,0 +1,99 @@
+---
+name: voiceover
+description: Adding AI-generated voiceover to Remotion compositions using ElevenLabs TTS
+metadata:
+  tags: voiceover, audio, elevenlabs, tts, speech, calculateMetadata, dynamic duration
+---
+
+# Adding AI voiceover to a Remotion composition
+
+Use ElevenLabs TTS to generate speech audio per scene, then use [`calculateMetadata`](./calculate-metadata) to dynamically size the composition to match the audio.
+
+## Prerequisites
+
+An **ElevenLabs API key** is required (`ELEVENLABS_API_KEY` environment variable).
+
+**MUST** ask the user for their ElevenLabs API key if `ELEVENLABS_API_KEY` is not set. **MUST NOT** fall back to other TTS tools.
+
+Ensure the environment variable is available when running the generation script:
+
+```bash
+node --strip-types generate-voiceover.ts
+```
+
+## Generating audio with ElevenLabs
+
+Create a script that reads the config, calls the ElevenLabs API for each scene, and writes MP3 files to the `public/` directory so Remotion can access them via `staticFile()`.
+
+The core API call for a single scene:
+
+```ts title="generate-voiceover.ts"
+const response = await fetch(
+  `https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`,
+  {
+    method: "POST",
+    headers: {
+      "xi-api-key": process.env.ELEVENLABS_API_KEY!,
+      "Content-Type": "application/json",
+      Accept: "audio/mpeg",
+    },
+    body: JSON.stringify({
+      text: "Welcome to the show.",
+      model_id: "eleven_multilingual_v2",
+      voice_settings: {
+        stability: 0.5,
+        similarity_boost: 0.75,
+        style: 0.3,
+      },
+    }),
+  },
+);
+
+const audioBuffer = Buffer.from(await response.arrayBuffer());
+writeFileSync(`public/voiceover/${compositionId}/${scene.id}.mp3`, audioBuffer);
+```
+
+## Dynamic composition duration with calculateMetadata
+
+Use [`calculateMetadata`](./calculate-metadata.md) to measure the [audio durations](./get-audio-duration.md) and set the composition length accordingly.
+
+```tsx
+import { CalculateMetadataFunction, staticFile } from "remotion";
+import { getAudioDuration } from "./get-audio-duration";
+
+const FPS = 30;
+
+const SCENE_AUDIO_FILES = [
+  "voiceover/my-comp/scene-01-intro.mp3",
+  "voiceover/my-comp/scene-02-main.mp3",
+  "voiceover/my-comp/scene-03-outro.mp3",
+];
+
+export const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const durations = await Promise.all(
+    SCENE_AUDIO_FILES.map((file) => getAudioDuration(staticFile(file))),
+  );
+
+  const sceneDurations = durations.map((durationInSeconds) => {
+    return durationInSeconds * FPS;
+  });
+
+  return {
+    durationInFrames: Math.ceil(sceneDurations.reduce((sum, d) => sum + d, 0)),
+  };
+};
+```
+
+The computed `sceneDurations` are passed into the component via a `voiceover` prop so the component knows how long each scene should be.
+
+If the composition uses [`<TransitionSeries>`](./transitions.md), subtract the overlap from total duration: [./transitions.md#calculating-total-composition-duration](./transitions.md#calculating-total-composition-duration)
+
+## Rendering audio in the component
+
+See [audio.md](./audio.md) for more information on how to render audio in the component.
+
+## Delaying audio start
+
+See [audio.md#delaying](./audio.md#delaying) for more information on how to delay the audio start.
diff --git a/CLAUDE.md b/CLAUDE.md
index 17c7b22..8b79b8b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -125,6 +125,14 @@ Scaffold(
 
 ---
 
+## Agent Skills (`.agents/skills/`)
+
+UI/UX 디자인 또는 프론트엔드 구현 작업 시 자동으로 참조할 것:
+- `.agents/skills/frontend-design/SKILL.md` — 프론트엔드 디자인 가이드 (UI 구현 전 Read로 로드)
+- `.agents/skills/find-skills/SKILL.md` — 새로운 스킬 검색/설치 (`npx skills find <query>`)
+
+---
+
 ## Key References
 
 - [docs/05_WIDGETS_GUIDE.md](docs/05_WIDGETS_GUIDE.md) — 위젯 카탈로그 (위젯 생성 전 필독)
diff --git a/skills-lock.json b/skills-lock.json
new file mode 100644
index 0000000..c9c2325
--- /dev/null
+++ b/skills-lock.json
@@ -0,0 +1,20 @@
+{
+  "version": 1,
+  "skills": {
+    "find-skills": {
+      "source": "vercel-labs/skills",
+      "sourceType": "github",
+      "computedHash": "6412eb4eb3b91595ebab937f0c69501240e7ba761b3d82510b5cf506ec5c7adc"
+    },
+    "frontend-design": {
+      "source": "anthropics/skills",
+      "sourceType": "github",
+      "computedHash": "063a0e6448123cd359ad0044cc46b0e490cc7964d45ef4bb9fd842bd2ffbca67"
+    },
+    "remotion-best-practices": {
+      "source": "remotion-dev/skills",
+      "sourceType": "github",
+      "computedHash": "9851afb52e1b892c43b2af973bda1776ce01fedfdfe704e0cfd70069a3a9c300"
+    }
+  }
+}

From a39b95f45a0e5c381bfb5363db9b1480331fdaea Mon Sep 17 00:00:00 2001
From: GitHub Action <action@github.com>
Date: Mon, 9 Mar 2026 04:37:13 +0000
Subject: [PATCH 09/20] =?UTF-8?q?SpaceStudyShip-FE=20=EB=B2=84=EC=A0=84=20?=
 =?UTF-8?q?=EC=A0=95=EB=B3=B4=20=EA=B4=80=EB=A6=AC:=20chore:=20=EB=B2=84?=
 =?UTF-8?q?=EC=A0=84=201.1.35=20[skip=20ci]?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pubspec.yaml | 2 +-
 version.yml  | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/pubspec.yaml b/pubspec.yaml
index f2f3115..4442385 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,7 +1,7 @@
 name: space_study_ship
 description: "Space Study Ship - 우주 테마 게이미피케이션 학습 관리 앱"
 publish_to: "none"
-version: 1.1.34+78
+version: 1.1.35+79
 environment:
   sdk: ^3.9.2
 dependencies:
diff --git a/version.yml b/version.yml
index 4760fbf..b5bfaa0 100644
--- a/version.yml
+++ b/version.yml
@@ -34,12 +34,12 @@
 # - 버전은 항상 높은 버전으로 자동 동기화됩니다
 # ===================================================================
 
-version: "1.1.34" # 사용자에게 표시되는 버전
-version_code: 79 # app build number
+version: "1.1.35" # 사용자에게 표시되는 버전
+version_code: 80 # app build number
 project_type: "flutter" # spring, flutter, react, react-native, react-native-expo, node, python, basic
 metadata:
-  last_updated: "2026-03-05 06:06:06"
-  last_updated_by: "Cassiiopeia"
+  last_updated: "2026-03-09 04:37:13"
+  last_updated_by: "EM-H20"
   default_branch: "main"
   integrated_from: "SUH-DEVOPS-TEMPLATE"
   integration_date: "2026-02-06"

From c4995f24907db5266c80cbd8380df01ff72cd586 Mon Sep 17 00:00:00 2001
From: EM-H20 <ghd0106@gmail.com>
Date: Mon, 9 Mar 2026 23:18:55 +0900
Subject: [PATCH 10/20] =?UTF-8?q?feat=20:=20Dismissible=EC=9D=84=20flutter?=
 =?UTF-8?q?=5Fslidable=EB=A1=9C=20=EA=B5=90=EC=B2=B4=ED=95=98=EC=97=AC=20?=
 =?UTF-8?q?=EC=8A=A4=EC=99=80=EC=9D=B4=ED=94=84=20=EC=95=A1=EC=85=98=20UI?=
 =?UTF-8?q?=20=EA=B0=9C=EC=84=A0=20#51?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- flutter_slidable 패키지 추가
- 좌→우: 카테고리 이동, 우→좌: 날짜 제거 + 삭제
- CustomSlidableAction으로 반투명 배경 + 아이콘/텍스트 스타일 적용
---
 .../widgets/dismissible_todo_item.dart        | 318 +++++++-----------
 pubspec.lock                                  |   8 +
 pubspec.yaml                                  |   1 +
 3 files changed, 131 insertions(+), 196 deletions(-)

diff --git a/lib/features/todo/presentation/widgets/dismissible_todo_item.dart b/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
index 3900776..6d67c3c 100644
--- a/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
+++ b/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
@@ -1,12 +1,10 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:flutter_screenutil/flutter_screenutil.dart';
-import 'package:intl/intl.dart';
+import 'package:flutter_slidable/flutter_slidable.dart';
 
 import '../../../../core/constants/app_colors.dart';
-import '../../../../core/constants/spacing_and_radius.dart';
 import '../../../../core/constants/text_styles.dart';
-import '../../../../core/widgets/atoms/drag_handle.dart';
 import '../../../../core/widgets/dialogs/app_dialog.dart';
 import '../../../../core/widgets/feedback/app_snackbar.dart';
 import '../../../../core/widgets/space/todo_item.dart';
@@ -17,11 +15,11 @@ import '../providers/todo_provider.dart';
 import 'category_select_bottom_sheet.dart';
 import 'todo_add_bottom_sheet.dart';
 
-/// 양방향 스와이프 Dismissible + TodoItem 통합 위젯
+/// Slidable + TodoItem 통합 위젯
 ///
-/// - 좌→우: 카테고리 선택 바텀시트
-/// - 우→좌: 삭제 확인 (다중 날짜면 3가지 선택)
-/// - 탭: 완료 토글 (onTap 미지정 시)
+/// - 좌→우 (startActionPane): 카테고리 이동
+/// - 우→좌 (endActionPane): 날짜에서 제거 + 삭제
+/// - 탭: 할일 수정 바텀시트 (onTap 미지정 시)
 ///
 /// [contextDate] 캘린더에서 선택된 날짜. null이면 글로벌(isFullyCompleted) 사용.
 class DismissibleTodoItem extends ConsumerWidget {
@@ -42,84 +40,54 @@ class DismissibleTodoItem extends ConsumerWidget {
         ? todo.isCompletedForDate(contextDate!)
         : todo.isFullyCompleted;
 
-    return Dismissible(
+    return Slidable(
       key: Key('${todo.id}_${contextDate?.toIso8601String() ?? "global"}'),
-      direction: DismissDirection.horizontal,
-      confirmDismiss: (direction) async {
-        if (direction == DismissDirection.startToEnd) {
-          final newCategoryIds = await showCategorySelectBottomSheet(
-            context: context,
-            currentCategoryIds: todo.categoryIds,
-          );
-          if (newCategoryIds != null && context.mounted) {
-            ref
-                .read(todoListNotifierProvider.notifier)
-                .updateTodo(todo.copyWith(categoryIds: newCategoryIds));
-          }
-          return false;
-        }
-        // 타이머에 연동된 할 일이면 삭제 차단
-        final timerState = ref.read(timerNotifierProvider);
-        if (timerState.status != TimerStatus.idle &&
-            timerState.linkedTodoId == todo.id) {
-          AppSnackBar.warning(context, '타이머에 연동된 할 일은 삭제할 수 없어요');
-          return false;
-        }
-        // 삭제 방향: 다중 날짜 할일이면 선택지 표시
-        if (todo.scheduledDates.length > 1 && contextDate != null) {
-          final action = await _showMultiDateDeleteSheet(context);
-          if (action == null) return false;
-          if (!context.mounted) return false;
-          final notifier = ref.read(todoListNotifierProvider.notifier);
-          switch (action) {
-            case _DeleteAction.thisDateOnly:
-              await notifier.removeDateFromTodo(todo, contextDate!);
-              return false; // 직접 처리함
-            case _DeleteAction.thisAndAfter:
-              await notifier.removeDateAndAfterFromTodo(todo, contextDate!);
-              return false;
-            case _DeleteAction.all:
-              return true; // onDismissed에서 삭제
-          }
-        }
-        // 단일 날짜 또는 글로벌 뷰: 기존 삭제 확인
-        if (!context.mounted) return false;
-        final confirmed = await AppDialog.confirm(
-          context: context,
-          title: '할일 삭제',
-          message: "'${todo.title}'을(를) 삭제하시겠습니까?\n삭제된 항목은 복구할 수 없습니다.",
-          emotion: AppDialogEmotion.warning,
-          confirmText: '삭제',
-          cancelText: '취소',
-          isDestructive: true,
-        );
-        return confirmed == true;
-      },
-      onDismissed: (_) {
-        ref.read(todoListNotifierProvider.notifier).deleteTodo(todo.id);
-      },
-      background: Container(
-        alignment: Alignment.centerLeft,
-        padding: AppPadding.horizontal20,
-        decoration: BoxDecoration(
-          color: AppColors.primary.withValues(alpha: 0.2),
-          borderRadius: AppRadius.large,
-        ),
-        child: Icon(
-          Icons.drive_file_move_outline,
-          color: AppColors.primary,
-          size: 24.w,
-        ),
+      groupTag: 'todos',
+
+      // ── 좌→우: 카테고리 이동 ──
+      startActionPane: ActionPane(
+        motion: const DrawerMotion(),
+        extentRatio: 0.25,
+        children: [
+          CustomSlidableAction(
+            onPressed: (_) => _moveCategory(context, ref),
+            backgroundColor: Colors.transparent,
+            child: _buildActionContent(
+              icon: Icons.drive_file_move_outline,
+              label: '이동',
+              color: AppColors.primaryLight,
+            ),
+          ),
+        ],
       ),
-      secondaryBackground: Container(
-        alignment: Alignment.centerRight,
-        padding: AppPadding.horizontal20,
-        decoration: BoxDecoration(
-          color: AppColors.error.withValues(alpha: 0.2),
-          borderRadius: AppRadius.large,
-        ),
-        child: Icon(Icons.delete_outline, color: AppColors.error, size: 24.w),
+
+      // ── 우→좌: 날짜에서 제거 + 삭제 ──
+      endActionPane: ActionPane(
+        motion: const DrawerMotion(),
+        extentRatio: contextDate != null ? 0.5 : 0.25,
+        children: [
+          if (contextDate != null)
+            CustomSlidableAction(
+              onPressed: (_) => _removeFromDate(context, ref),
+              backgroundColor: Colors.transparent,
+              child: _buildActionContent(
+                icon: Icons.event_busy_rounded,
+                label: '제거',
+                color: AppColors.accentGoldLight,
+              ),
+            ),
+          CustomSlidableAction(
+            onPressed: (_) => _deleteTodo(context, ref),
+            backgroundColor: Colors.transparent,
+            child: _buildActionContent(
+              icon: Icons.delete_outline,
+              label: '삭제',
+              color: AppColors.error,
+            ),
+          ),
+        ],
       ),
+
       child: TodoItem(
         title: todo.title,
         subtitle: todo.actualMinutes != null && todo.actualMinutes! > 0
@@ -137,7 +105,73 @@ class DismissibleTodoItem extends ConsumerWidget {
     );
   }
 
-  void _openEditSheet(BuildContext context, WidgetRef ref) async {
+  Widget _buildActionContent({
+    required IconData icon,
+    required String label,
+    required Color color,
+  }) {
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        Icon(icon, color: color, size: 22.w),
+        SizedBox(height: 4.h),
+        Text(label, style: AppTextStyles.tag_12.copyWith(color: color)),
+      ],
+    );
+  }
+
+  /// 카테고리 이동
+  Future<void> _moveCategory(BuildContext context, WidgetRef ref) async {
+    Slidable.of(context)?.close();
+    final newCategoryIds = await showCategorySelectBottomSheet(
+      context: context,
+      currentCategoryIds: todo.categoryIds,
+    );
+    if (newCategoryIds != null && context.mounted) {
+      ref
+          .read(todoListNotifierProvider.notifier)
+          .updateTodo(todo.copyWith(categoryIds: newCategoryIds));
+    }
+  }
+
+  /// 선택된 날짜에서 제거 (bank로 복귀)
+  Future<void> _removeFromDate(BuildContext context, WidgetRef ref) async {
+    Slidable.of(context)?.close();
+    if (contextDate == null) return;
+    // 타이머 연동 체크
+    if (_isLinkedToTimer(ref)) {
+      AppSnackBar.warning(context, '타이머에 연동된 할 일은 제거할 수 없어요');
+      return;
+    }
+    await ref
+        .read(todoListNotifierProvider.notifier)
+        .removeDateFromTodo(todo, contextDate!);
+  }
+
+  /// 할일 완전 삭제
+  Future<void> _deleteTodo(BuildContext context, WidgetRef ref) async {
+    Slidable.of(context)?.close();
+    // 타이머 연동 체크
+    if (_isLinkedToTimer(ref)) {
+      AppSnackBar.warning(context, '타이머에 연동된 할 일은 삭제할 수 없어요');
+      return;
+    }
+    final confirmed = await AppDialog.confirm(
+      context: context,
+      title: '할일 삭제',
+      message: "'${todo.title}'을(를) 삭제하시겠습니까?\n삭제된 항목은 복구할 수 없습니다.",
+      emotion: AppDialogEmotion.warning,
+      confirmText: '삭제',
+      cancelText: '취소',
+      isDestructive: true,
+    );
+    if (confirmed == true && context.mounted) {
+      ref.read(todoListNotifierProvider.notifier).deleteTodo(todo.id);
+    }
+  }
+
+  /// 할일 수정 바텀시트
+  Future<void> _openEditSheet(BuildContext context, WidgetRef ref) async {
     final result = await showTodoAddBottomSheet(
       context: context,
       initialTodo: todo,
@@ -156,118 +190,10 @@ class DismissibleTodoItem extends ConsumerWidget {
     }
   }
 
-  Future<_DeleteAction?> _showMultiDateDeleteSheet(BuildContext context) {
-    return showModalBottomSheet<_DeleteAction>(
-      context: context,
-      backgroundColor: Colors.transparent,
-      builder: (context) => _MultiDateDeleteSheet(contextDate: contextDate!),
-    );
-  }
-}
-
-enum _DeleteAction { thisDateOnly, thisAndAfter, all }
-
-class _MultiDateDeleteSheet extends StatelessWidget {
-  const _MultiDateDeleteSheet({required this.contextDate});
-
-  final DateTime contextDate;
-
-  @override
-  Widget build(BuildContext context) {
-    final dateLabel = DateFormat('M/d (E)', 'ko_KR').format(contextDate);
-
-    return Container(
-      decoration: BoxDecoration(
-        color: AppColors.spaceSurface,
-        borderRadius: AppRadius.modal,
-      ),
-      child: Column(
-        mainAxisSize: MainAxisSize.min,
-        children: [
-          // 드래그 핸들
-          const DragHandle(),
-          Padding(
-            padding: AppPadding.bottomSheetTitlePadding,
-            child: Text(
-              '반복 할일 삭제',
-              style: AppTextStyles.subHeading_18.copyWith(color: Colors.white),
-            ),
-          ),
-          _buildOption(
-            context,
-            icon: Icons.today,
-            label: '$dateLabel만 삭제',
-            action: _DeleteAction.thisDateOnly,
-          ),
-          _buildOption(
-            context,
-            icon: Icons.event,
-            label: '$dateLabel 이후 모두 삭제',
-            action: _DeleteAction.thisAndAfter,
-          ),
-          _buildOption(
-            context,
-            icon: Icons.delete_forever,
-            label: '전체 삭제',
-            action: _DeleteAction.all,
-            isDestructive: true,
-          ),
-          SizedBox(height: AppSpacing.s8),
-          // 취소 버튼
-          Padding(
-            padding: AppPadding.horizontal20,
-            child: SizedBox(
-              width: double.infinity,
-              child: TextButton(
-                onPressed: () => Navigator.of(context).pop(),
-                child: Text(
-                  '취소',
-                  style: AppTextStyles.label_16.copyWith(
-                    color: AppColors.textSecondary,
-                  ),
-                ),
-              ),
-            ),
-          ),
-          SizedBox(height: MediaQuery.of(context).padding.bottom + 12.h),
-        ],
-      ),
-    );
-  }
-
-  Widget _buildOption(
-    BuildContext context, {
-    required IconData icon,
-    required String label,
-    required _DeleteAction action,
-    bool isDestructive = false,
-  }) {
-    return Material(
-      color: Colors.transparent,
-      child: InkWell(
-        onTap: () => Navigator.of(context).pop(action),
-        child: Padding(
-          padding: EdgeInsets.symmetric(horizontal: 20.w, vertical: 14.h),
-          child: Row(
-            children: [
-              Icon(
-                icon,
-                color: isDestructive
-                    ? AppColors.error
-                    : AppColors.textSecondary,
-                size: 20.w,
-              ),
-              SizedBox(width: AppSpacing.s12),
-              Text(
-                label,
-                style: AppTextStyles.label_16.copyWith(
-                  color: isDestructive ? AppColors.error : Colors.white,
-                ),
-              ),
-            ],
-          ),
-        ),
-      ),
-    );
+  /// 타이머에 연동된 할일인지 확인
+  bool _isLinkedToTimer(WidgetRef ref) {
+    final timerState = ref.read(timerNotifierProvider);
+    return timerState.status != TimerStatus.idle &&
+        timerState.linkedTodoId == todo.id;
   }
 }
diff --git a/pubspec.lock b/pubspec.lock
index 5ba7096..40ae911 100644
--- a/pubspec.lock
+++ b/pubspec.lock
@@ -590,6 +590,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "3.1.2"
+  flutter_slidable:
+    dependency: "direct main"
+    description:
+      name: flutter_slidable
+      sha256: ea369262929d3cc6ebf9d8a00c196127966f117fe433a5e5cb47fb08008ca203
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.0.3"
   flutter_staggered_grid_view:
     dependency: transitive
     description:
diff --git a/pubspec.yaml b/pubspec.yaml
index 4442385..a82fff0 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -36,6 +36,7 @@ dependencies:
   flutter_expandable_fab: ^2.5.2 # 확장 가능한 FAB (Floating Action Button)
   showcaseview: ^5.0.1 # 튜토리얼
   table_calendar: ^3.2.0 # 캘린더 위젯 (월간/주간 뷰)
+  flutter_slidable: ^4.0.3 # 슬라이드 가능한 리스트 아이템
   # 리스트 & 데이터 표시
   infinite_scroll_pagination: ^5.1.1 # 무한 스크롤 페이징 처리
   # 알림 & 실시간 통신

From c116c3be16728122bff0b6c35e751f9bfca4af03 Mon Sep 17 00:00:00 2001
From: EM-H20 <ghd0106@gmail.com>
Date: Mon, 9 Mar 2026 23:19:01 +0900
Subject: [PATCH 11/20] =?UTF-8?q?feat=20:=20=ED=99=88=20=ED=99=94=EB=A9=B4?=
 =?UTF-8?q?=20=EB=B0=94=ED=85=80=EC=8B=9C=ED=8A=B8=EC=97=90=20todo=20bank?=
 =?UTF-8?q?=20=EC=84=B9=EC=85=98=20=EC=B6=94=EA=B0=80=20#51?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- todosNotForDate provider 추가 (선택 날짜에 미배정 할일 필터)
- 홈 화면에 '할 일 추가' 섹션으로 todo bank 표시
- 탭하면 해당 날짜에 즉시 배정
---
 .../presentation/screens/home_screen.dart     |  55 ++++++++
 .../presentation/providers/todo_provider.dart |  15 +++
 .../providers/todo_provider.g.dart            | 120 ++++++++++++++++++
 3 files changed, 190 insertions(+)

diff --git a/lib/features/home/presentation/screens/home_screen.dart b/lib/features/home/presentation/screens/home_screen.dart
index ceef287..56686a8 100644
--- a/lib/features/home/presentation/screens/home_screen.dart
+++ b/lib/features/home/presentation/screens/home_screen.dart
@@ -19,6 +19,7 @@ import '../../../../routes/route_paths.dart';
 import '../../../timer/presentation/providers/study_stats_provider.dart';
 import '../../../todo/domain/entities/todo_entity.dart';
 import '../../../todo/presentation/providers/todo_provider.dart';
+import '../../../../core/widgets/space/todo_item.dart';
 import '../../../todo/presentation/widgets/dismissible_todo_item.dart';
 import '../../../todo/presentation/widgets/todo_add_bottom_sheet.dart';
 import '../widgets/space_calendar.dart';
@@ -431,6 +432,9 @@ class _HomeScreenState extends ConsumerState<HomeScreen> {
             (todo) => _buildTodoRow(todo, contextDate: _selectedDay),
           ),
 
+        // ── 할 일 추가 (todo bank) ──
+        _buildTodoBankSection(selectedKey),
+
         // ── 카테고리 관리 버튼 ──
         Padding(
           padding: AppPadding.horizontal20,
@@ -485,6 +489,57 @@ class _HomeScreenState extends ConsumerState<HomeScreen> {
     );
   }
 
+  /// 할 일 추가 (todo bank): 선택된 날짜에 배정되지 않은 할일 목록
+  ///
+  /// 탭하면 해당 날짜에 즉시 추가된다.
+  Widget _buildTodoBankSection(DateTime selectedDate) {
+    return Consumer(
+      builder: (context, ref, _) {
+        final todosNotForDate = ref.watch(todosNotForDateProvider(selectedDate));
+        if (todosNotForDate.isEmpty) return const SizedBox.shrink();
+
+        return Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            SizedBox(height: AppSpacing.s16),
+            Padding(
+              padding: AppPadding.horizontal20,
+              child: _buildSectionTitle('할 일 추가'),
+            ),
+            SizedBox(height: AppSpacing.s8),
+            ...todosNotForDate.map(
+              (todo) => Padding(
+                padding: EdgeInsets.fromLTRB(20.w, 0, 20.w, AppSpacing.s8),
+                child: TodoItem(
+                  title: todo.title,
+                  subtitle: todo.actualMinutes != null && todo.actualMinutes! > 0
+                      ? '${todo.actualMinutes}분 공부'
+                      : null,
+                  isCompleted: false,
+                  leading: Icon(
+                    Icons.add_circle_outline_rounded,
+                    color: AppColors.primary,
+                    size: 24.w,
+                  ),
+                  onToggle: () => _addTodoToDate(ref, todo, selectedDate),
+                  onTap: () => _addTodoToDate(ref, todo, selectedDate),
+                ),
+              ),
+            ),
+          ],
+        );
+      },
+    );
+  }
+
+  void _addTodoToDate(WidgetRef ref, TodoEntity todo, DateTime date) {
+    final normalized = DateTime(date.year, date.month, date.day);
+    final updated = todo.copyWith(
+      scheduledDates: [...todo.scheduledDates, normalized],
+    );
+    ref.read(todoListNotifierProvider.notifier).updateTodo(updated);
+  }
+
   Widget _buildEmptyTodoCard() {
     return AppCard(
       style: AppCardStyle.outlined,
diff --git a/lib/features/todo/presentation/providers/todo_provider.dart b/lib/features/todo/presentation/providers/todo_provider.dart
index 8c31b1a..60f59c3 100644
--- a/lib/features/todo/presentation/providers/todo_provider.dart
+++ b/lib/features/todo/presentation/providers/todo_provider.dart
@@ -300,6 +300,21 @@ List<TodoEntity> todosForDate(Ref ref, DateTime date) {
   }).toList();
 }
 
+// === 해당 날짜에 배정되지 않은 할일 (todo bank용) ===
+
+@riverpod
+List<TodoEntity> todosNotForDate(Ref ref, DateTime date) {
+  final todos = ref.watch(todoListNotifierProvider).valueOrNull ?? [];
+  final normalizedDate = DateTime(date.year, date.month, date.day);
+  return todos.where((t) {
+    if (t.scheduledDates.isEmpty) return false;
+    return !t.scheduledDates.any((d) {
+      final scheduled = DateTime(d.year, d.month, d.day);
+      return scheduled == normalizedDate;
+    });
+  }).toList();
+}
+
 // === 미지정 할일 필터 ===
 
 @riverpod
diff --git a/lib/features/todo/presentation/providers/todo_provider.g.dart b/lib/features/todo/presentation/providers/todo_provider.g.dart
index 605bbf9..cdbdbcf 100644
--- a/lib/features/todo/presentation/providers/todo_provider.g.dart
+++ b/lib/features/todo/presentation/providers/todo_provider.g.dart
@@ -335,6 +335,126 @@ class _TodosForDateProviderElement
   DateTime get date => (origin as TodosForDateProvider).date;
 }
 
+String _$todosNotForDateHash() => r'd9a7cfb7df5ca2c2c0a6f31c40dd8fbcda127400';
+
+/// See also [todosNotForDate].
+@ProviderFor(todosNotForDate)
+const todosNotForDateProvider = TodosNotForDateFamily();
+
+/// See also [todosNotForDate].
+class TodosNotForDateFamily extends Family<List<TodoEntity>> {
+  /// See also [todosNotForDate].
+  const TodosNotForDateFamily();
+
+  /// See also [todosNotForDate].
+  TodosNotForDateProvider call(DateTime date) {
+    return TodosNotForDateProvider(date);
+  }
+
+  @override
+  TodosNotForDateProvider getProviderOverride(
+    covariant TodosNotForDateProvider provider,
+  ) {
+    return call(provider.date);
+  }
+
+  static const Iterable<ProviderOrFamily>? _dependencies = null;
+
+  @override
+  Iterable<ProviderOrFamily>? get dependencies => _dependencies;
+
+  static const Iterable<ProviderOrFamily>? _allTransitiveDependencies = null;
+
+  @override
+  Iterable<ProviderOrFamily>? get allTransitiveDependencies =>
+      _allTransitiveDependencies;
+
+  @override
+  String? get name => r'todosNotForDateProvider';
+}
+
+/// See also [todosNotForDate].
+class TodosNotForDateProvider extends AutoDisposeProvider<List<TodoEntity>> {
+  /// See also [todosNotForDate].
+  TodosNotForDateProvider(DateTime date)
+    : this._internal(
+        (ref) => todosNotForDate(ref as TodosNotForDateRef, date),
+        from: todosNotForDateProvider,
+        name: r'todosNotForDateProvider',
+        debugGetCreateSourceHash: const bool.fromEnvironment('dart.vm.product')
+            ? null
+            : _$todosNotForDateHash,
+        dependencies: TodosNotForDateFamily._dependencies,
+        allTransitiveDependencies:
+            TodosNotForDateFamily._allTransitiveDependencies,
+        date: date,
+      );
+
+  TodosNotForDateProvider._internal(
+    super._createNotifier, {
+    required super.name,
+    required super.dependencies,
+    required super.allTransitiveDependencies,
+    required super.debugGetCreateSourceHash,
+    required super.from,
+    required this.date,
+  }) : super.internal();
+
+  final DateTime date;
+
+  @override
+  Override overrideWith(
+    List<TodoEntity> Function(TodosNotForDateRef provider) create,
+  ) {
+    return ProviderOverride(
+      origin: this,
+      override: TodosNotForDateProvider._internal(
+        (ref) => create(ref as TodosNotForDateRef),
+        from: from,
+        name: null,
+        dependencies: null,
+        allTransitiveDependencies: null,
+        debugGetCreateSourceHash: null,
+        date: date,
+      ),
+    );
+  }
+
+  @override
+  AutoDisposeProviderElement<List<TodoEntity>> createElement() {
+    return _TodosNotForDateProviderElement(this);
+  }
+
+  @override
+  bool operator ==(Object other) {
+    return other is TodosNotForDateProvider && other.date == date;
+  }
+
+  @override
+  int get hashCode {
+    var hash = _SystemHash.combine(0, runtimeType.hashCode);
+    hash = _SystemHash.combine(hash, date.hashCode);
+
+    return _SystemHash.finish(hash);
+  }
+}
+
+@Deprecated('Will be removed in 3.0. Use Ref instead')
+// ignore: unused_element
+mixin TodosNotForDateRef on AutoDisposeProviderRef<List<TodoEntity>> {
+  /// The parameter `date` of this provider.
+  DateTime get date;
+}
+
+class _TodosNotForDateProviderElement
+    extends AutoDisposeProviderElement<List<TodoEntity>>
+    with TodosNotForDateRef {
+  _TodosNotForDateProviderElement(super.provider);
+
+  @override
+  DateTime get date => (origin as TodosNotForDateProvider).date;
+}
+
 String _$unscheduledTodosHash() => r'6392feb486da0deccf3be9ca35e32a2eba1a66e1';
 
 /// See also [unscheduledTodos].

From c0d6c0654d27cde748d3e359f9eb2aa035ad661b Mon Sep 17 00:00:00 2001
From: EM-H20 <ghd0106@gmail.com>
Date: Mon, 9 Mar 2026 23:19:05 +0900
Subject: [PATCH 12/20] =?UTF-8?q?chore=20:=20build=5Frunner=20=EC=BD=94?=
 =?UTF-8?q?=EB=93=9C=20=EC=83=9D=EC=84=B1=20=ED=8C=8C=EC=9D=BC=20=EC=97=85?=
 =?UTF-8?q?=EB=8D=B0=EC=9D=B4=ED=8A=B8=20#51?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 lib/features/auth/presentation/providers/auth_provider.g.dart   | 2 +-
 .../settings/presentation/providers/settings_provider.g.dart    | 2 +-
 lib/features/timer/presentation/providers/timer_provider.g.dart | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/lib/features/auth/presentation/providers/auth_provider.g.dart b/lib/features/auth/presentation/providers/auth_provider.g.dart
index ebbc020..288f127 100644
--- a/lib/features/auth/presentation/providers/auth_provider.g.dart
+++ b/lib/features/auth/presentation/providers/auth_provider.g.dart
@@ -244,7 +244,7 @@ final activeLoginNotifierProvider =
     );
 
 typedef _$ActiveLoginNotifier = AutoDisposeNotifier<SocialLoginProvider?>;
-String _$authNotifierHash() => r'fc03859db1dd948d709fdb96f0edf483be7998a0';
+String _$authNotifierHash() => r'ac2268510acb44e219020f7de48858e9a85cc68d';
 
 /// 인증 상태를 관리하는 Notifier
 ///
diff --git a/lib/features/settings/presentation/providers/settings_provider.g.dart b/lib/features/settings/presentation/providers/settings_provider.g.dart
index 7f928f7..658356d 100644
--- a/lib/features/settings/presentation/providers/settings_provider.g.dart
+++ b/lib/features/settings/presentation/providers/settings_provider.g.dart
@@ -63,7 +63,7 @@ final starTwinkleEnabledProvider = AutoDisposeProvider<bool>.internal(
 @Deprecated('Will be removed in 3.0. Use Ref instead')
 // ignore: unused_element
 typedef StarTwinkleEnabledRef = AutoDisposeProviderRef<bool>;
-String _$settingsNotifierHash() => r'e5590548d61a207a0e84fc69ef25dea67626ca2f';
+String _$settingsNotifierHash() => r'09dd0a8d82513eb4a2b24203f0048bf9fb748fea';
 
 /// See also [SettingsNotifier].
 @ProviderFor(SettingsNotifier)
diff --git a/lib/features/timer/presentation/providers/timer_provider.g.dart b/lib/features/timer/presentation/providers/timer_provider.g.dart
index 2921af7..0ebc2d9 100644
--- a/lib/features/timer/presentation/providers/timer_provider.g.dart
+++ b/lib/features/timer/presentation/providers/timer_provider.g.dart
@@ -6,7 +6,7 @@ part of 'timer_provider.dart';
 // RiverpodGenerator
 // **************************************************************************
 
-String _$timerNotifierHash() => r'3aff7b6060abf1214b4dd19e8384010bbec83a8a';
+String _$timerNotifierHash() => r'0aac0c38f3140e893027e6775032b82c0f09df64';
 
 /// See also [TimerNotifier].
 @ProviderFor(TimerNotifier)

From 617cf430f5d8f7ae6589f8d689f44256275fb778 Mon Sep 17 00:00:00 2001
From: EM-H20 <ghd0106@gmail.com>
Date: Mon, 9 Mar 2026 23:20:07 +0900
Subject: [PATCH 13/20] =?UTF-8?q?docs=20:=20=EA=B5=AC=ED=98=84=20=EB=82=B4?=
 =?UTF-8?q?=EC=9A=A9=EC=97=90=20=EB=A7=9E=EA=B2=8C=20=EC=84=A4=EA=B3=84=20?=
 =?UTF-8?q?=EB=AC=B8=EC=84=9C=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8=20#51?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../2026-03-09-todo-list-calendar-redesign.md | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 docs/plans/2026-03-09-todo-list-calendar-redesign.md

diff --git a/docs/plans/2026-03-09-todo-list-calendar-redesign.md b/docs/plans/2026-03-09-todo-list-calendar-redesign.md
new file mode 100644
index 0000000..67f229c
--- /dev/null
+++ b/docs/plans/2026-03-09-todo-list-calendar-redesign.md
@@ -0,0 +1,46 @@
+# 홈 화면 Todo Bank + Slidable 스와이프 액션 구현
+
+**Goal:** 홈 화면 바텀시트에 todo bank 섹션을 추가하고, 할일 스와이프 액션을 flutter_slidable로 개선하여 날짜별 할일 관리 UX를 향상시킨다.
+
+**Architecture:** 기존 HomeScreen 바텀시트에 todo bank 섹션 추가. TodoListScreen은 변경 없음. DismissibleTodoItem을 Dismissible에서 flutter_slidable의 Slidable로 교체.
+
+**Tech Stack:** Flutter · Riverpod · flutter_slidable · table_calendar
+
+**관련 이슈:** #51
+
+---
+
+## 구현 내용
+
+### 1. Todo Bank (홈 화면 바텀시트)
+
+**변경 파일:**
+- `lib/features/todo/presentation/providers/todo_provider.dart` — `todosNotForDate` provider 추가
+- `lib/features/todo/presentation/providers/todo_provider.g.dart` — 코드 생성
+- `lib/features/home/presentation/screens/home_screen.dart` — `_buildTodoBankSection`, `_addTodoToDate` 추가
+
+**동작:**
+- 홈 화면 캘린더에서 날짜 선택 후, 해당 날짜에 배정되지 않은 할일 목록을 "할 일 추가" 섹션으로 표시
+- 할일을 탭하면 선택된 날짜의 scheduledDates에 추가되어 즉시 해당 날짜 할일 목록에 나타남
+- 다른 날짜를 선택하면 해당 날짜에 미배정된 할일이 다시 bank에 표시됨
+- scheduledDates가 비어있는 할일(미지정)은 bank에 표시하지 않음
+
+### 2. Slidable 스와이프 액션
+
+**변경 파일:**
+- `lib/features/todo/presentation/widgets/dismissible_todo_item.dart` — Dismissible → Slidable 교체
+- `pubspec.yaml` / `pubspec.lock` — flutter_slidable 패키지 추가
+
+**동작:**
+- **좌→우 (startActionPane):** 카테고리 이동 — `primaryLight` 색상
+- **우→좌 (endActionPane):**
+  - 날짜에서 제거 (contextDate가 있을 때만) — `accentGoldLight` 색상
+  - 삭제 — `error` 색상
+- CustomSlidableAction + 투명 배경 + 아이콘/텍스트만 표시 (다크 우주 테마에 어울리는 미니멀 스타일)
+- 타이머 연동 중인 할일은 제거/삭제 차단
+
+### 3. 변경하지 않은 것
+
+- TodoListScreen (카테고리 그리드 중심 레이아웃 유지)
+- CategoryTodoScreen 및 라우팅
+- 기존 할일 CRUD 로직

From 068db7547631e54e58f301dc57fd6e157d37d164 Mon Sep 17 00:00:00 2001
From: EM-H20 <ghd0106@gmail.com>
Date: Mon, 9 Mar 2026 23:36:56 +0900
Subject: [PATCH 14/20] =?UTF-8?q?fix=20:=20=EC=BD=94=EB=93=9C=20=EB=A6=AC?=
 =?UTF-8?q?=EB=B7=B0=20=ED=94=BC=EB=93=9C=EB=B0=B1=20=EB=B0=98=EC=98=81=20?=
 =?UTF-8?q?=E2=80=94=20=EC=95=88=EC=A0=84=EC=84=B1=20=EB=B0=8F=20=EA=B5=AC?=
 =?UTF-8?q?=EC=A1=B0=20=EA=B0=9C=EC=84=A0=20#51?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Slidable context 분리 (slidableContext vs buildContext)
- deleteTodo에 await 추가하여 에러 시 rollback 정상 작동
- 마지막 배정 날짜 제거 시 확인 다이얼로그 추가
- addDateToTodo를 TodoListNotifier로 이동 + 중복 날짜 체크
- 날짜 정규화를 TodoEntity.normalizeDate()로 통일
- TodoEntity.studyTimeLabel getter로 subtitle 중복 제거
- SizedBox(height: 4.h) → AppSpacing.s4
---
 .../presentation/screens/home_screen.dart     | 14 ++---
 .../todo/domain/entities/todo_entity.dart     |  3 +
 .../presentation/providers/todo_provider.dart | 34 +++++++----
 .../providers/todo_provider.g.dart            |  8 +--
 .../widgets/dismissible_todo_item.dart        | 58 ++++++++++++++-----
 5 files changed, 77 insertions(+), 40 deletions(-)

diff --git a/lib/features/home/presentation/screens/home_screen.dart b/lib/features/home/presentation/screens/home_screen.dart
index 56686a8..6025b10 100644
--- a/lib/features/home/presentation/screens/home_screen.dart
+++ b/lib/features/home/presentation/screens/home_screen.dart
@@ -495,7 +495,9 @@ class _HomeScreenState extends ConsumerState<HomeScreen> {
   Widget _buildTodoBankSection(DateTime selectedDate) {
     return Consumer(
       builder: (context, ref, _) {
-        final todosNotForDate = ref.watch(todosNotForDateProvider(selectedDate));
+        final todosNotForDate = ref.watch(
+          todosNotForDateProvider(selectedDate),
+        );
         if (todosNotForDate.isEmpty) return const SizedBox.shrink();
 
         return Column(
@@ -512,9 +514,7 @@ class _HomeScreenState extends ConsumerState<HomeScreen> {
                 padding: EdgeInsets.fromLTRB(20.w, 0, 20.w, AppSpacing.s8),
                 child: TodoItem(
                   title: todo.title,
-                  subtitle: todo.actualMinutes != null && todo.actualMinutes! > 0
-                      ? '${todo.actualMinutes}분 공부'
-                      : null,
+                  subtitle: todo.studyTimeLabel,
                   isCompleted: false,
                   leading: Icon(
                     Icons.add_circle_outline_rounded,
@@ -533,11 +533,7 @@ class _HomeScreenState extends ConsumerState<HomeScreen> {
   }
 
   void _addTodoToDate(WidgetRef ref, TodoEntity todo, DateTime date) {
-    final normalized = DateTime(date.year, date.month, date.day);
-    final updated = todo.copyWith(
-      scheduledDates: [...todo.scheduledDates, normalized],
-    );
-    ref.read(todoListNotifierProvider.notifier).updateTodo(updated);
+    ref.read(todoListNotifierProvider.notifier).addDateToTodo(todo, date);
   }
 
   Widget _buildEmptyTodoCard() {
diff --git a/lib/features/todo/domain/entities/todo_entity.dart b/lib/features/todo/domain/entities/todo_entity.dart
index b9edcd9..82b68d6 100644
--- a/lib/features/todo/domain/entities/todo_entity.dart
+++ b/lib/features/todo/domain/entities/todo_entity.dart
@@ -30,4 +30,7 @@ class TodoEntity with _$TodoEntity {
     if (scheduledDates.isEmpty) return completedDates.isNotEmpty;
     return scheduledDates.every((d) => isCompletedForDate(d));
   }
+
+  String? get studyTimeLabel =>
+      actualMinutes != null && actualMinutes! > 0 ? '$actualMinutes분 공부' : null;
 }
diff --git a/lib/features/todo/presentation/providers/todo_provider.dart b/lib/features/todo/presentation/providers/todo_provider.dart
index 60f59c3..17ec941 100644
--- a/lib/features/todo/presentation/providers/todo_provider.dart
+++ b/lib/features/todo/presentation/providers/todo_provider.dart
@@ -128,6 +128,20 @@ class TodoListNotifier extends _$TodoListNotifier {
     }
   }
 
+  /// 특정 날짜를 할일에 추가 (todo bank → 날짜 배정)
+  Future<void> addDateToTodo(TodoEntity todo, DateTime date) async {
+    final normalized = TodoEntity.normalizeDate(date);
+    if (todo.scheduledDates.any(
+      (d) => TodoEntity.normalizeDate(d) == normalized,
+    )) {
+      return;
+    }
+    final updated = todo.copyWith(
+      scheduledDates: [...todo.scheduledDates, normalized],
+    );
+    await updateTodo(updated);
+  }
+
   Future<void> updateTodo(TodoEntity todo) async {
     final previousState = state;
     state = AsyncData(
@@ -291,12 +305,11 @@ class CategoryListNotifier extends _$CategoryListNotifier {
 @riverpod
 List<TodoEntity> todosForDate(Ref ref, DateTime date) {
   final todos = ref.watch(todoListNotifierProvider).valueOrNull ?? [];
-  final normalizedDate = DateTime(date.year, date.month, date.day);
+  final normalizedDate = TodoEntity.normalizeDate(date);
   return todos.where((t) {
-    return t.scheduledDates.any((d) {
-      final scheduled = DateTime(d.year, d.month, d.day);
-      return scheduled == normalizedDate;
-    });
+    return t.scheduledDates.any(
+      (d) => TodoEntity.normalizeDate(d) == normalizedDate,
+    );
   }).toList();
 }
 
@@ -305,13 +318,12 @@ List<TodoEntity> todosForDate(Ref ref, DateTime date) {
 @riverpod
 List<TodoEntity> todosNotForDate(Ref ref, DateTime date) {
   final todos = ref.watch(todoListNotifierProvider).valueOrNull ?? [];
-  final normalizedDate = DateTime(date.year, date.month, date.day);
+  final normalizedDate = TodoEntity.normalizeDate(date);
   return todos.where((t) {
     if (t.scheduledDates.isEmpty) return false;
-    return !t.scheduledDates.any((d) {
-      final scheduled = DateTime(d.year, d.month, d.day);
-      return scheduled == normalizedDate;
-    });
+    return !t.scheduledDates.any(
+      (d) => TodoEntity.normalizeDate(d) == normalizedDate,
+    );
   }).toList();
 }
 
@@ -331,7 +343,7 @@ Map<DateTime, List<TodoEntity>> todosByDateMap(Ref ref) {
   final map = <DateTime, List<TodoEntity>>{};
   for (final todo in todos) {
     for (final date in todo.scheduledDates) {
-      final key = DateTime(date.year, date.month, date.day);
+      final key = TodoEntity.normalizeDate(date);
       map.putIfAbsent(key, () => []).add(todo);
     }
   }
diff --git a/lib/features/todo/presentation/providers/todo_provider.g.dart b/lib/features/todo/presentation/providers/todo_provider.g.dart
index cdbdbcf..f56012d 100644
--- a/lib/features/todo/presentation/providers/todo_provider.g.dart
+++ b/lib/features/todo/presentation/providers/todo_provider.g.dart
@@ -194,7 +194,7 @@ final deleteCategoryUseCaseProvider =
 // ignore: unused_element
 typedef DeleteCategoryUseCaseRef =
     AutoDisposeProviderRef<DeleteCategoryUseCase>;
-String _$todosForDateHash() => r'9af8ac0f2a2d3d7d8d191238f0d4f23c52da6ddf';
+String _$todosForDateHash() => r'5b3fdfd35342374991d2a3254a2b58755b3c3048';
 
 /// Copied from Dart SDK
 class _SystemHash {
@@ -335,7 +335,7 @@ class _TodosForDateProviderElement
   DateTime get date => (origin as TodosForDateProvider).date;
 }
 
-String _$todosNotForDateHash() => r'd9a7cfb7df5ca2c2c0a6f31c40dd8fbcda127400';
+String _$todosNotForDateHash() => r'eea5324e8b8ac04c8d396fa8837c97a56dba259f';
 
 /// See also [todosNotForDate].
 @ProviderFor(todosNotForDate)
@@ -472,7 +472,7 @@ final unscheduledTodosProvider = AutoDisposeProvider<List<TodoEntity>>.internal(
 @Deprecated('Will be removed in 3.0. Use Ref instead')
 // ignore: unused_element
 typedef UnscheduledTodosRef = AutoDisposeProviderRef<List<TodoEntity>>;
-String _$todosByDateMapHash() => r'63550762dadad72a407562f09198045aafdb1ece';
+String _$todosByDateMapHash() => r'6dc1d0fabc90511db8196e00c2d42897b473afc8';
 
 /// See also [todosByDateMap].
 @ProviderFor(todosByDateMap)
@@ -738,7 +738,7 @@ class _CategoryTodoStatsProviderElement
   String? get categoryId => (origin as CategoryTodoStatsProvider).categoryId;
 }
 
-String _$todoListNotifierHash() => r'7a2600651b82a5cf90efe6d25e37eefaadbed87e';
+String _$todoListNotifierHash() => r'157130d482c19d25a2c1adeaa51e4824b408e79f';
 
 /// See also [TodoListNotifier].
 @ProviderFor(TodoListNotifier)
diff --git a/lib/features/todo/presentation/widgets/dismissible_todo_item.dart b/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
index 6d67c3c..4f615dd 100644
--- a/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
+++ b/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
@@ -4,6 +4,7 @@ import 'package:flutter_screenutil/flutter_screenutil.dart';
 import 'package:flutter_slidable/flutter_slidable.dart';
 
 import '../../../../core/constants/app_colors.dart';
+import '../../../../core/constants/spacing_and_radius.dart';
 import '../../../../core/constants/text_styles.dart';
 import '../../../../core/widgets/dialogs/app_dialog.dart';
 import '../../../../core/widgets/feedback/app_snackbar.dart';
@@ -50,7 +51,8 @@ class DismissibleTodoItem extends ConsumerWidget {
         extentRatio: 0.25,
         children: [
           CustomSlidableAction(
-            onPressed: (_) => _moveCategory(context, ref),
+            onPressed: (slidableContext) =>
+                _moveCategory(slidableContext, context, ref),
             backgroundColor: Colors.transparent,
             child: _buildActionContent(
               icon: Icons.drive_file_move_outline,
@@ -68,7 +70,8 @@ class DismissibleTodoItem extends ConsumerWidget {
         children: [
           if (contextDate != null)
             CustomSlidableAction(
-              onPressed: (_) => _removeFromDate(context, ref),
+              onPressed: (slidableContext) =>
+                  _removeFromDate(slidableContext, context, ref),
               backgroundColor: Colors.transparent,
               child: _buildActionContent(
                 icon: Icons.event_busy_rounded,
@@ -77,7 +80,8 @@ class DismissibleTodoItem extends ConsumerWidget {
               ),
             ),
           CustomSlidableAction(
-            onPressed: (_) => _deleteTodo(context, ref),
+            onPressed: (slidableContext) =>
+                _deleteTodo(slidableContext, context, ref),
             backgroundColor: Colors.transparent,
             child: _buildActionContent(
               icon: Icons.delete_outline,
@@ -90,9 +94,7 @@ class DismissibleTodoItem extends ConsumerWidget {
 
       child: TodoItem(
         title: todo.title,
-        subtitle: todo.actualMinutes != null && todo.actualMinutes! > 0
-            ? '${todo.actualMinutes}분 공부'
-            : null,
+        subtitle: todo.studyTimeLabel,
         isCompleted: isCompleted,
         onToggle: () {
           final date = contextDate ?? DateTime.now();
@@ -114,15 +116,20 @@ class DismissibleTodoItem extends ConsumerWidget {
       mainAxisSize: MainAxisSize.min,
       children: [
         Icon(icon, color: color, size: 22.w),
-        SizedBox(height: 4.h),
+        SizedBox(height: AppSpacing.s4),
         Text(label, style: AppTextStyles.tag_12.copyWith(color: color)),
       ],
     );
   }
 
   /// 카테고리 이동
-  Future<void> _moveCategory(BuildContext context, WidgetRef ref) async {
-    Slidable.of(context)?.close();
+  Future<void> _moveCategory(
+    BuildContext slidableContext,
+    BuildContext context,
+    WidgetRef ref,
+  ) async {
+    Slidable.of(slidableContext)?.close();
+    if (!context.mounted) return;
     final newCategoryIds = await showCategorySelectBottomSheet(
       context: context,
       currentCategoryIds: todo.categoryIds,
@@ -135,23 +142,42 @@ class DismissibleTodoItem extends ConsumerWidget {
   }
 
   /// 선택된 날짜에서 제거 (bank로 복귀)
-  Future<void> _removeFromDate(BuildContext context, WidgetRef ref) async {
-    Slidable.of(context)?.close();
+  Future<void> _removeFromDate(
+    BuildContext slidableContext,
+    BuildContext context,
+    WidgetRef ref,
+  ) async {
+    Slidable.of(slidableContext)?.close();
     if (contextDate == null) return;
-    // 타이머 연동 체크
     if (_isLinkedToTimer(ref)) {
       AppSnackBar.warning(context, '타이머에 연동된 할 일은 제거할 수 없어요');
       return;
     }
+    // 마지막 날짜인 경우 확인 다이얼로그
+    if (todo.scheduledDates.length == 1) {
+      final confirmed = await AppDialog.confirm(
+        context: context,
+        title: '할일 제거',
+        message: "'${todo.title}'의 마지막 배정 날짜입니다.\n제거하면 할일이 삭제됩니다.",
+        emotion: AppDialogEmotion.warning,
+        confirmText: '제거',
+        cancelText: '취소',
+        isDestructive: true,
+      );
+      if (confirmed != true || !context.mounted) return;
+    }
     await ref
         .read(todoListNotifierProvider.notifier)
         .removeDateFromTodo(todo, contextDate!);
   }
 
   /// 할일 완전 삭제
-  Future<void> _deleteTodo(BuildContext context, WidgetRef ref) async {
-    Slidable.of(context)?.close();
-    // 타이머 연동 체크
+  Future<void> _deleteTodo(
+    BuildContext slidableContext,
+    BuildContext context,
+    WidgetRef ref,
+  ) async {
+    Slidable.of(slidableContext)?.close();
     if (_isLinkedToTimer(ref)) {
       AppSnackBar.warning(context, '타이머에 연동된 할 일은 삭제할 수 없어요');
       return;
@@ -166,7 +192,7 @@ class DismissibleTodoItem extends ConsumerWidget {
       isDestructive: true,
     );
     if (confirmed == true && context.mounted) {
-      ref.read(todoListNotifierProvider.notifier).deleteTodo(todo.id);
+      await ref.read(todoListNotifierProvider.notifier).deleteTodo(todo.id);
     }
   }
 

From 6acc20be4e144742d283c6396c0d257bbec14e5e Mon Sep 17 00:00:00 2001
From: EM-H20 <ghd0106@gmail.com>
Date: Mon, 9 Mar 2026 23:36:59 +0900
Subject: [PATCH 15/20] =?UTF-8?q?chore=20:=20build=5Frunner=20=EC=BD=94?=
 =?UTF-8?q?=EB=93=9C=20=EC=83=9D=EC=84=B1=20=ED=8C=8C=EC=9D=BC=20=EC=97=85?=
 =?UTF-8?q?=EB=8D=B0=EC=9D=B4=ED=8A=B8=20#51?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../badge/presentation/providers/badge_provider.g.dart        | 2 +-
 .../presentation/providers/exploration_provider.g.dart        | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/lib/features/badge/presentation/providers/badge_provider.g.dart b/lib/features/badge/presentation/providers/badge_provider.g.dart
index df21d0a..c98bc2d 100644
--- a/lib/features/badge/presentation/providers/badge_provider.g.dart
+++ b/lib/features/badge/presentation/providers/badge_provider.g.dart
@@ -61,7 +61,7 @@ final unlockedBadgeCountProvider = AutoDisposeProvider<int>.internal(
 @Deprecated('Will be removed in 3.0. Use Ref instead')
 // ignore: unused_element
 typedef UnlockedBadgeCountRef = AutoDisposeProviderRef<int>;
-String _$badgeNotifierHash() => r'ad13e70d5d21f2d41098e468f25fdacdcca38080';
+String _$badgeNotifierHash() => r'121f7003985d1c63cac4dc17728c23c75a31529b';
 
 /// See also [BadgeNotifier].
 @ProviderFor(BadgeNotifier)
diff --git a/lib/features/exploration/presentation/providers/exploration_provider.g.dart b/lib/features/exploration/presentation/providers/exploration_provider.g.dart
index 97bfeb8..6e870b6 100644
--- a/lib/features/exploration/presentation/providers/exploration_provider.g.dart
+++ b/lib/features/exploration/presentation/providers/exploration_provider.g.dart
@@ -208,7 +208,7 @@ class _ExplorationProgressProviderElement
 }
 
 String _$explorationNotifierHash() =>
-    r'c774ca8225cc050cb9e6f247f36e9e0493e4874c';
+    r'0934da4a60377bef28a4a744d9c5fce5acd4cb32';
 
 /// 행성 목록 상태
 ///
@@ -230,7 +230,7 @@ final explorationNotifierProvider =
 
 typedef _$ExplorationNotifier = Notifier<List<ExplorationNodeEntity>>;
 String _$regionListNotifierHash() =>
-    r'24380eb73e0ae93bc2cce7228fa4097bb211ba24';
+    r'aee531fb3209715c68491f42d65e86bdfc8adee6';
 
 abstract class _$RegionListNotifier
     extends BuildlessAutoDisposeNotifier<List<ExplorationNodeEntity>> {

From 5187582e451561e80f5e7eb8654b67d9325790ab Mon Sep 17 00:00:00 2001
From: EM-H20 <ghd0106@gmail.com>
Date: Tue, 10 Mar 2026 00:00:47 +0900
Subject: [PATCH 16/20] =?UTF-8?q?fix=20:=20Slidable=20=EC=97=B4=EB=A6=B0?=
 =?UTF-8?q?=20=EC=83=81=ED=83=9C=EC=97=90=EC=84=9C=20=ED=83=AD=20=EC=8B=9C?=
 =?UTF-8?q?=20=EC=8A=AC=EB=9D=BC=EC=9D=B4=EB=93=9C=20=EB=8B=AB=EA=B8=B0=20?=
 =?UTF-8?q?=EC=B2=98=EB=A6=AC=20#51?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../widgets/dismissible_todo_item.dart        | 35 +++++++++++++------
 1 file changed, 24 insertions(+), 11 deletions(-)

diff --git a/lib/features/todo/presentation/widgets/dismissible_todo_item.dart b/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
index 4f615dd..fc15485 100644
--- a/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
+++ b/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
@@ -92,17 +92,30 @@ class DismissibleTodoItem extends ConsumerWidget {
         ],
       ),
 
-      child: TodoItem(
-        title: todo.title,
-        subtitle: todo.studyTimeLabel,
-        isCompleted: isCompleted,
-        onToggle: () {
-          final date = contextDate ?? DateTime.now();
-          ref
-              .read(todoListNotifierProvider.notifier)
-              .toggleTodoForDate(todo, date);
-        },
-        onTap: onTap ?? () => _openEditSheet(context, ref),
+      child: Builder(
+        builder: (slidableChildContext) => TodoItem(
+          title: todo.title,
+          subtitle: todo.studyTimeLabel,
+          isCompleted: isCompleted,
+          onToggle: () {
+            final date = contextDate ?? DateTime.now();
+            ref
+                .read(todoListNotifierProvider.notifier)
+                .toggleTodoForDate(todo, date);
+          },
+          onTap:
+              onTap ??
+              () {
+                final slidable = Slidable.of(slidableChildContext);
+                if (slidable != null &&
+                    (slidable.animation.value > 0 ||
+                        slidable.animation.isAnimating)) {
+                  slidable.close();
+                  return;
+                }
+                _openEditSheet(context, ref);
+              },
+        ),
       ),
     );
   }

From 60de94e7704b93bc524af3be0cffdce670c55467 Mon Sep 17 00:00:00 2001
From: EM-H20 <ghd0106@gmail.com>
Date: Tue, 10 Mar 2026 01:42:39 +0900
Subject: [PATCH 17/20] =?UTF-8?q?fix=20:=20CodeRabbit=20=EB=A6=AC=EB=B7=B0?=
 =?UTF-8?q?=20=ED=94=BC=EB=93=9C=EB=B0=B1=20=EB=B0=98=EC=98=81=20#51?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- bank에 할일이 있으면 빈 상태 카드 숨기고 bank만 표시
- 불필요한 Consumer 래핑 제거 (상위에서 watch한 데이터 전달)
- contextDate null일 때 토글 no-op 처리하여 표시/저장 기준 불일치 해결
---
 .../presentation/screens/home_screen.dart     | 73 +++++++++----------
 .../widgets/dismissible_todo_item.dart        |  4 +-
 2 files changed, 37 insertions(+), 40 deletions(-)

diff --git a/lib/features/home/presentation/screens/home_screen.dart b/lib/features/home/presentation/screens/home_screen.dart
index 6025b10..a0790c3 100644
--- a/lib/features/home/presentation/screens/home_screen.dart
+++ b/lib/features/home/presentation/screens/home_screen.dart
@@ -347,6 +347,7 @@ class _HomeScreenState extends ConsumerState<HomeScreen> {
       _selectedDay.day,
     );
     final todosForSelected = ref.watch(todosForDateProvider(selectedKey));
+    final bankTodos = ref.watch(todosNotForDateProvider(selectedKey));
     final unscheduled = ref.watch(unscheduledTodosProvider);
     final todosByDate = ref.watch(todosByDateMapProvider);
     final dateLabel = DateFormat('M/d', 'ko_KR').format(_selectedDay);
@@ -422,18 +423,18 @@ class _HomeScreenState extends ConsumerState<HomeScreen> {
         ),
         SizedBox(height: AppSpacing.s8),
 
-        if (todosForSelected.isEmpty)
+        if (todosForSelected.isEmpty && bankTodos.isEmpty)
           Padding(
             padding: AppPadding.horizontal20,
             child: _buildEmptyTodoCard(),
           )
-        else
+        else if (todosForSelected.isNotEmpty)
           ...todosForSelected.map(
             (todo) => _buildTodoRow(todo, contextDate: _selectedDay),
           ),
 
         // ── 할 일 추가 (todo bank) ──
-        _buildTodoBankSection(selectedKey),
+        _buildTodoBankSection(selectedKey, bankTodos),
 
         // ── 카테고리 관리 버튼 ──
         Padding(
@@ -492,43 +493,39 @@ class _HomeScreenState extends ConsumerState<HomeScreen> {
   /// 할 일 추가 (todo bank): 선택된 날짜에 배정되지 않은 할일 목록
   ///
   /// 탭하면 해당 날짜에 즉시 추가된다.
-  Widget _buildTodoBankSection(DateTime selectedDate) {
-    return Consumer(
-      builder: (context, ref, _) {
-        final todosNotForDate = ref.watch(
-          todosNotForDateProvider(selectedDate),
-        );
-        if (todosNotForDate.isEmpty) return const SizedBox.shrink();
-
-        return Column(
-          crossAxisAlignment: CrossAxisAlignment.start,
-          children: [
-            SizedBox(height: AppSpacing.s16),
-            Padding(
-              padding: AppPadding.horizontal20,
-              child: _buildSectionTitle('할 일 추가'),
-            ),
-            SizedBox(height: AppSpacing.s8),
-            ...todosNotForDate.map(
-              (todo) => Padding(
-                padding: EdgeInsets.fromLTRB(20.w, 0, 20.w, AppSpacing.s8),
-                child: TodoItem(
-                  title: todo.title,
-                  subtitle: todo.studyTimeLabel,
-                  isCompleted: false,
-                  leading: Icon(
-                    Icons.add_circle_outline_rounded,
-                    color: AppColors.primary,
-                    size: 24.w,
-                  ),
-                  onToggle: () => _addTodoToDate(ref, todo, selectedDate),
-                  onTap: () => _addTodoToDate(ref, todo, selectedDate),
-                ),
+  Widget _buildTodoBankSection(
+    DateTime selectedDate,
+    List<TodoEntity> bankTodos,
+  ) {
+    if (bankTodos.isEmpty) return const SizedBox.shrink();
+
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.start,
+      children: [
+        SizedBox(height: AppSpacing.s16),
+        Padding(
+          padding: AppPadding.horizontal20,
+          child: _buildSectionTitle('할 일 추가'),
+        ),
+        SizedBox(height: AppSpacing.s8),
+        ...bankTodos.map(
+          (todo) => Padding(
+            padding: EdgeInsets.fromLTRB(20.w, 0, 20.w, AppSpacing.s8),
+            child: TodoItem(
+              title: todo.title,
+              subtitle: todo.studyTimeLabel,
+              isCompleted: false,
+              leading: Icon(
+                Icons.add_circle_outline_rounded,
+                color: AppColors.primary,
+                size: 24.w,
               ),
+              onToggle: () => _addTodoToDate(ref, todo, selectedDate),
+              onTap: () => _addTodoToDate(ref, todo, selectedDate),
             ),
-          ],
-        );
-      },
+          ),
+        ),
+      ],
     );
   }
 
diff --git a/lib/features/todo/presentation/widgets/dismissible_todo_item.dart b/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
index fc15485..3ade227 100644
--- a/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
+++ b/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
@@ -98,10 +98,10 @@ class DismissibleTodoItem extends ConsumerWidget {
           subtitle: todo.studyTimeLabel,
           isCompleted: isCompleted,
           onToggle: () {
-            final date = contextDate ?? DateTime.now();
+            if (contextDate == null) return;
             ref
                 .read(todoListNotifierProvider.notifier)
-                .toggleTodoForDate(todo, date);
+                .toggleTodoForDate(todo, contextDate!);
           },
           onTap:
               onTap ??

From 0e2d138067145beb7f1c023e8b006899a8d9d270 Mon Sep 17 00:00:00 2001
From: EM-H20 <ghd0106@gmail.com>
Date: Tue, 10 Mar 2026 09:45:41 +0900
Subject: [PATCH 18/20] =?UTF-8?q?fix=20:=20=EB=B9=84=EB=8F=99=EA=B8=B0=20m?=
 =?UTF-8?q?utation=20=ED=98=B8=EC=B6=9C=EC=97=90=20await=20=EC=B6=94?=
 =?UTF-8?q?=EA=B0=80=20#51?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 lib/features/home/presentation/screens/home_screen.dart   | 8 ++++++--
 .../todo/presentation/widgets/dismissible_todo_item.dart  | 4 ++--
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/lib/features/home/presentation/screens/home_screen.dart b/lib/features/home/presentation/screens/home_screen.dart
index a0790c3..5a75c2e 100644
--- a/lib/features/home/presentation/screens/home_screen.dart
+++ b/lib/features/home/presentation/screens/home_screen.dart
@@ -529,8 +529,12 @@ class _HomeScreenState extends ConsumerState<HomeScreen> {
     );
   }
 
-  void _addTodoToDate(WidgetRef ref, TodoEntity todo, DateTime date) {
-    ref.read(todoListNotifierProvider.notifier).addDateToTodo(todo, date);
+  Future<void> _addTodoToDate(
+    WidgetRef ref,
+    TodoEntity todo,
+    DateTime date,
+  ) async {
+    await ref.read(todoListNotifierProvider.notifier).addDateToTodo(todo, date);
   }
 
   Widget _buildEmptyTodoCard() {
diff --git a/lib/features/todo/presentation/widgets/dismissible_todo_item.dart b/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
index 3ade227..2d31d5d 100644
--- a/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
+++ b/lib/features/todo/presentation/widgets/dismissible_todo_item.dart
@@ -148,7 +148,7 @@ class DismissibleTodoItem extends ConsumerWidget {
       currentCategoryIds: todo.categoryIds,
     );
     if (newCategoryIds != null && context.mounted) {
-      ref
+      await ref
           .read(todoListNotifierProvider.notifier)
           .updateTodo(todo.copyWith(categoryIds: newCategoryIds));
     }
@@ -216,7 +216,7 @@ class DismissibleTodoItem extends ConsumerWidget {
       initialTodo: todo,
     );
     if (result != null && context.mounted) {
-      ref
+      await ref
           .read(todoListNotifierProvider.notifier)
           .updateTodo(
             todo.copyWith(

From d512ae996ddf3e58ca47bc503ac4030871461c1b Mon Sep 17 00:00:00 2001
From: GitHub Action <action@github.com>
Date: Tue, 10 Mar 2026 01:07:48 +0000
Subject: [PATCH 19/20] =?UTF-8?q?SpaceStudyShip-FE=20=EB=B2=84=EC=A0=84=20?=
 =?UTF-8?q?=EC=A0=95=EB=B3=B4=20=EA=B4=80=EB=A6=AC:=20chore:=20=EB=B2=84?=
 =?UTF-8?q?=EC=A0=84=201.1.36=20[skip=20ci]?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pubspec.yaml | 2 +-
 version.yml  | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/pubspec.yaml b/pubspec.yaml
index a82fff0..d71887f 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,7 +1,7 @@
 name: space_study_ship
 description: "Space Study Ship - 우주 테마 게이미피케이션 학습 관리 앱"
 publish_to: "none"
-version: 1.1.35+79
+version: 1.1.36+80
 environment:
   sdk: ^3.9.2
 dependencies:
diff --git a/version.yml b/version.yml
index b5bfaa0..589cf10 100644
--- a/version.yml
+++ b/version.yml
@@ -34,11 +34,11 @@
 # - 버전은 항상 높은 버전으로 자동 동기화됩니다
 # ===================================================================
 
-version: "1.1.35" # 사용자에게 표시되는 버전
-version_code: 80 # app build number
+version: "1.1.36" # 사용자에게 표시되는 버전
+version_code: 81 # app build number
 project_type: "flutter" # spring, flutter, react, react-native, react-native-expo, node, python, basic
 metadata:
-  last_updated: "2026-03-09 04:37:13"
+  last_updated: "2026-03-10 01:07:48"
   last_updated_by: "EM-H20"
   default_branch: "main"
   integrated_from: "SUH-DEVOPS-TEMPLATE"

From 187ed3923eac54e84594560acca2e779c7f22c23 Mon Sep 17 00:00:00 2001
From: GitHub Action <action@github.com>
Date: Tue, 10 Mar 2026 01:12:00 +0000
Subject: [PATCH 20/20] =?UTF-8?q?SpaceStudyShip-FE=20=EB=B2=84=EC=A0=84=20?=
 =?UTF-8?q?=EA=B4=80=EB=A6=AC=20:=20docs=20:=20v1.1.36=20=EB=A6=B4?=
 =?UTF-8?q?=EB=A6=AC=EC=A6=88=20=EB=AC=B8=EC=84=9C=20=EC=97=85=EB=8D=B0?=
 =?UTF-8?q?=EC=9D=B4=ED=8A=B8=20(PR=20#53)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CHANGELOG.json | 30 +++++++++++++++++++++++++++---
 CHANGELOG.md   | 18 ++++++++++++++++--
 2 files changed, 43 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.json b/CHANGELOG.json
index 6229cd1..91648ab 100644
--- a/CHANGELOG.json
+++ b/CHANGELOG.json
@@ -1,11 +1,35 @@
 {
   "metadata": {
-    "lastUpdated": "2026-03-05T00:22:10Z",
-    "currentVersion": "1.1.31",
+    "lastUpdated": "2026-03-10T01:11:59Z",
+    "currentVersion": "1.1.36",
     "projectType": "flutter",
-    "totalReleases": 26
+    "totalReleases": 27
   },
   "releases": [
+    {
+      "version": "1.1.36",
+      "project_type": "flutter",
+      "date": "2026-03-10",
+      "pr_number": 53,
+      "raw_summary": "## Summary by CodeRabbit\n\n## 릴리스 노트\n\n* **새로운 기능**\n  * 할 일 뱅크 기능 추가 - 선택한 날짜에 할당되지 않은 할 일을 관리 가능\n  * 향상된 할 일 항목 스와이프 액션 인터페이스 적용\n  * 새로운 에이전트 스킬 추가: 스킬 찾기, 프론트엔드 디자인\n\n* **개선 사항**\n  * 의존성 업데이트 및 버전 1.1.36으로 업그레이드",
+      "parsed_changes": {
+        "새로운_기능": {
+          "title": "새로운 기능",
+          "items": [
+            "할 일 뱅크 기능 추가 - 선택한 날짜에 할당되지 않은 할 일을 관리 가능",
+            "향상된 할 일 항목 스와이프 액션 인터페이스 적용",
+            "새로운 에이전트 스킬 추가: 스킬 찾기, 프론트엔드 디자인"
+          ]
+        },
+        "개선_사항": {
+          "title": "개선 사항",
+          "items": [
+            "의존성 업데이트 및 버전 1.1.36으로 업그레이드"
+          ]
+        }
+      },
+      "parse_method": "markdown"
+    },
     {
       "version": "1.1.31",
       "project_type": "flutter",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 20f9c8e..826ebb2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,7 +1,21 @@
 # Changelog
 
-**현재 버전:** 1.1.31  
-**마지막 업데이트:** 2026-03-05T00:22:10Z  
+**현재 버전:** 1.1.36  
+**마지막 업데이트:** 2026-03-10T01:11:59Z  
+
+---
+
+## [1.1.36] - 2026-03-10
+
+**PR:** #53  
+
+**새로운 기능**
+- 할 일 뱅크 기능 추가 - 선택한 날짜에 할당되지 않은 할 일을 관리 가능
+- 향상된 할 일 항목 스와이프 액션 인터페이스 적용
+- 새로운 에이전트 스킬 추가: 스킬 찾기, 프론트엔드 디자인
+
+**개선 사항**
+- 의존성 업데이트 및 버전 1.1.36으로 업그레이드
 
 ---