# YouTube Automation

현재는 Kling API 기반 v1 파이프라인 설계와 SQLite 기반 초기 코드 골격이 있으며, **Phase 1 문서화(현 scope 기준)는 완료**되었다. 또한 **Phase 2는 현재 repo의 production-facing model/input/payload policy 범위에서는 closeout 가능한 상태**다. 다만 이것은 전체 플랫폼 의미의 영구 확정이나 모든 endpoint 세부 검증 완료를 뜻하지 않는다. repo가 지금 보수적으로 주장할 수 있는 범위는 다음과 같다: **production model pair는 `kling-v3` + `kling-v3-omni`, 이미지 입력 기본전략은 우리 쪽 base64 attachment, 그리고 endpoint-specific shape는 분리 유지 (`image2video`=`image`/`image_tail`, Omni=`image_list[].image_url`)**. 현재 verified outcome으로 문서에 남겨둘 수 있는 최소 사실은: **`text2video` with `kling-v3` = verified, `image2video` with `kling-v3` = verified, `omni` with `kling-v3-omni` = verified**.

## Closeout snapshot
- **Completed**
  - Phase 1: field-level documentation-first scope closeout
  - Phase 2: current production-facing model/input/payload policy sync closeout
- **Not completed**
  - full platform-wide certainty beyond the repo's conservative production pair
  - full repo-wide helper cleanup / provenance tagging
  - callback-reachable production validation
- **Next phase meaning**
  - Phase 3 is now the **expanded verification phase**
  - it includes both deeper Omni verification **and** explicit non-Omni verification
  - it does **not** start automatically; any billable create still requires explicit user approval first

## 현재 상태
- AK/SK -> JWT 인증 골격 반영
- callback-first + permissive/shared-secret receiver modes
- endpoint-specific payload builders / validators 추가
- task schema metadata 확장
- 3.0 detailed spec 문서 분리 완료
- field-level documentation-first closeout 완료
  - Tier 1: video create/query 핵심 필드 정리
  - Tier 2: element create/query/list/delete top-level 필드 정리
  - Tier 3: image generation create/query 핵심 필드 정리
- production-facing code sync 핵심 반영
  - validators/builders/configs가 current repo production pair를 `kling-v3` + `kling-v3-omni`로 맞춤
  - image input 기본전략을 remote-url 의존이 아니라 local/base64 attachment 중심으로 읽도록 정리
  - endpoint-specific image shape를 분리 유지 (`image2video`=`image`/`image_tail`, Omni=`image_list[].image_url`)
  - live-confirmed multi-shot `multi_prompt[].index + duration` 검사 반영

## 문서 closeout 판단
- `docs/current/` 기준으로 현재 Phase 1은 **field-level documentation-first scope에서는 완료**로 본다.
- Omni-first narrow sync 기준으로는 Phase 2도 **과장 없이 closeout 가능**으로 본다.
- 다만 이것이 모든 세부사항의 영구 종료를 의미하진 않는다.
- 다음으로 남아 있는 것은 주로:
  - nested child-row 정밀화
  - capability-map 기반 지원 범위 해석
  - broadened Phase 3 verification (Omni + non-Omni)
  - broader non-Omni endpoint cleanup / stronger helper retirement

## Expanded Phase 3 definition
Phase 3는 더 이상 "Omni 몇 가지 추가 확인"만을 뜻하지 않는다. 이제는 아래 범위를 포함하는 **확장 검증 단계**다.

- Omni verification refinement
  - `pro` quality 비교
  - stronger `video_list(remote url)` continuation validation
  - element-backed generation validation
  - audio / voice workflow validation
- non-Omni verification
  - `text2video` current payload/model policy re-check
  - `image2video` current payload/model policy re-check
  - `reference2video` current payload/model policy re-check
  - 각 endpoint에서 historical pass와 current scaffold policy를 분리해서 재판정
- approval gate
  - billable create가 하나라도 포함되면 시작 전 사용자 승인 필요
  - hypothesis-only payload는 승인 없이 금지
  - 같은 immediate purpose로 2건 이상 create가 필요하면 예상 create 수와 노출 단위를 먼저 고지해야 함

## 초기 코드 위치
- `configs/kling.py`
- `scripts/kling_auth.py`
- `scripts/builders.py`
- `scripts/db.py`
- `scripts/repository.py`
- `scripts/kling_client.py`
- `scripts/kling_tasks.py`
- `scripts/query_paths.py`
- `server/callback_receiver.py`
- `scripts/scene_router.py`

## 주요 운영 문서
- `docs/current/kling-current-state-summary.md`
- `docs/current/kling-priority-todo.md`
- `docs/current/kling-docs-to-implementation-workboard.md`
- `docs/current/kling-billable-create-guardrails.md`
- `docs/current/kling-api-status.md`

## 주의
- 일부 endpoint/query path는 아직 provisional
- real Kling smoke test 전까지는 working scaffold로 간주
- non-Omni endpoint는 "historical pass가 있었음"과 "현재 기본 지원으로 동기화됨"을 같은 뜻으로 취급하지 말 것
- preserved artifacts에 없는 필드는 문서에 추가로 invent하지 말 것
- **first billable Phase 3 run 전에는 반드시 explicit approval를 받아야 한다**