docs: 컷별 댓글 추천 기능을 ARCHITECTURE/SETUP에 반영

recommend.py 모듈, 카드 배치가 자동 탭(card_cuts→_cards_by_cut)과
나머지 탭(_load_comment_cards 전체 균등)으로 갈린 이유, 그리고 서버가
카드 시간을 미리 확정하지 않는 이유(무음 제거 시 자막만 재매핑되고
카드가 혼자 어긋나는 것을 방지)를 문서에 남겨 나중에 이 설계를
실수로 되돌리는 것을 막는다. SETUP.md 문제 해결표에도 추천 실패
폴백 증상 두 건을 추가.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

ARCHITECTURE.md

@@ -37,6 +37,7 @@ capcut2/
    ├─ silence.py                 ffmpeg silencedetect → 발화 구간
    ├─ transcribe.py              faster-whisper(medium/int8/cpu) 단어 타임스탬프
    ├─ correct.py                 Gemini 자막 글자 교정(시간 불변) — gemini-2.5-flash
+   ├─ recommend.py               컷별 댓글 추천(자동 탭) — 타임스탬프 우선 + Gemini 텍스트 추천
    ├─ highlight.py               자막 청킹(cut_plan) 유틸
    ├─ scene.py                   ffmpeg scene 필터 장면전환 감지·분할
    ├─ media.py                   프레임 PNG 생성, 흰밴드 감지, 오디오 추출
@@ -129,6 +130,8 @@ LLM이 만든 편집안 JSON을 **그대로** 사용. 무음컷·ASR **기본
    JSON bottom 폴백. effect/제목/채널은 JSON 유지.
    ⚠ "remove_silence 후에 돌리면 remap 불필요"는 틀림 — 파일은 압축 안 되므로 cut_plan 매핑 필수.
 6. **scene / 댓글카드 / draft**: 4-A와 동일(좌표도 공통 — §9).
+   자동 탭에서 넘어온 경우 `process_paste(card_cuts=[...])`로 카드별 소속 컷을
+   받는다(§6 참고) — 붙여넣기 탭 직접 사용 시엔 생략(기존 전체 균등 배치).
 
 #### 붙여넣기 JSON 스키마 (LLM에게 시킬 형식)
 
@@ -223,6 +226,16 @@ title_top 서브제목 / title_main 메인제목 / channel 출처 / effect 효
 - `_load_comment_cards(folder, dur, interval=3.0)`:
   - 모든 파일명이 숫자로 시작 → 숫자순(1,2,10). 아니면 → **파일 생성시각(저장 순서)**.
   - png/jpg/jpeg/webp. 카드당 3초, 영상 길이 초과분은 생략.
+- **배치 방식이 두 갈래**(정렬 자체는 `_card_paths()`로 공통): 자동 탭은 검토 화면에서
+  카드별 소속 컷 인덱스(`card_cuts`)를 보내고, `_cards_by_cut(paths, card_cuts, placements, dur)`가
+  **그 컷 구간 안에서** 균등 배치한다(한 컷이 덜 차도 다음 컷 카드가 앞으로 밀리지 않음).
+  파일/유튜브 탭·붙여넣기 탭 직접 사용은 컷 소속을 몰라 기존 `_load_comment_cards` 전체 균등
+  배치 그대로 쓴다.
+  - ⚠ **카드 시간은 서버가 미리 확정하지 않는다.** `/auto/build`는 "몇 번 컷 소속"만 넘기고,
+    파이프라인이 컷 누적 위치(`placements`)로 시간을 계산한다. 무음 제거를 켜면 타임라인이
+    압축되는데(`timeline_dur = sum(keep)`), 서버가 시간을 미리 박아두면 자막만 재매핑되고
+    카드는 혼자 어긋나기 때문이다 — 카드도 자막과 **같은 `_remap_caps()`**로 재매핑된다
+    (튜플 모양이 `(start, end, path)`로 같아서 가능). 이 순서를 뒤집지 말 것.
 - 렌더: comment 트랙에 **scale 0.89 / X 0**, 세로는 **윗변이 영상 바로 아래**에 오도록 카드마다 계산(§9).
 - 출처: 사용자가 h-lab(https://h-lab.tolag.shop/comment-cards)에서 실제 유튜브 댓글을
   카드 PNG로 저장해 폴더에 넣음. (향후: h-lab API 연동해 완전 자동화 아이디어 있음)

SETUP.md

@@ -280,6 +280,8 @@ yt-dlp --version
 | 드래프트 열면 영상이 흰띠·댓글 위로 삐짐 | CapCut 편집 중 render_index 꼬임 | 최신 `draft.py`는 오버레이/제목 트랙 자동 잠금으로 예방 |
 | **클립을 옮긴 뒤 확대하면 그 클립만 템플릿 밖으로 삐짐** | CapCut이 옮긴 클립에 렌더순서를 새로(맨 위로) 매김 — 잠금으로 못 막음 | **캡컷에서 그 프로젝트를 닫고** → 웹 UI 하단 **"🩹 레이어 수리"** → 드래프트 선택 → 실행 → 캡컷에서 다시 열기 |
 | **영상 중간에 초록 화면이 몇 초 나옴** | yt-dlp가 키프레임 아닌 위치에서 잘라 참조 프레임이 없음 | 최신 `youtube.py`가 컷마다 자동 검증→재다운로드→정밀 재컷. 로그에 `🩹` 표시. 예전에 받은 영상은 다시 만들어야 함 |
+| 댓글이 엉뚱한 장면에 뜬다 | 컷별 추천이 실패해 기존 전체 균등 배치로 폴백 | 검토 화면 상단 경고 확인. Gemini 한도 초과면 잠시 뒤 재시도 |
+| 컷 섹션이 안 보이고 ⭐ 하나만 뜬다 | 추천 실패 폴백 | 위와 동일. `프롬프트/댓글_추천.md`를 고쳤다면 `{cuts}` `{comments}` `{k}` 가 남아 있는지 확인 |
 | 콘솔에 한글 깨짐 | Windows cp949 | 표시만 깨짐. 로직·결과와 무관 |
 
 ---