# AGENTS.md — Panduan Agent AI untuk Ginara Content Studio

Platform orkestrasi produksi konten video AI multi-user dengan approval gate manusia (*human-in-the-loop*).
Dokumen ini dapat dibaca langsung secara publik melalui `GET /agents.md` atau `GET /AGENTS.md`, serta panduan dinamis via `GET /guide`.

---

## Prinsip Kerja Agent

1. **API adalah satu-satunya pintu.** Baca dokumentasi dinamis terbaru lewat `GET /guide` atau `/openapi.json`.
2. **Autentikasi Agent:** Gunakan header `Authorization: Bearer <agent_api_key>` atau `X-Agent-Key: <agent_api_key>`. Key terikat ke satu `user_id` pemiliknya.
3. **Batas Role (Ditegakkan Server):**
   - **Agent BOLEH:** Membuat/membaca project, karakter, video, scene, melakukan revisi berdasarkan `reviewer_note`, men-submit capability run (`character_sheet.generate`, `keyframe.generate`, `clip.generate`, `subtitle.generate`, `thumbnail.generate`, `assemble.render`), dan polling status run (`GET /api/v1/runs/{run_id}`).
   - **Agent DILARANG (403 Forbidden):** Menyetujui/menolak gate (`approve`, `reject`, `batch-approve`), menandai pose karakter sebagai `canonical`, mengubah budget project, atau men-trigger `youtube.publish`. Semua keputusan itu hanya milik `owner` (manusia via SSO/Web UI).
4. **Urutan 4 Gate Wajib:**
   - **Gate 1 (Script & Dialog):** Submit naskah dan daftar scene (`visual_prompt`, `dialogue_text`, `audio_prompt`). Tunggu owner menyetujui Gate 1.
   - **Gate 2 (Keyframe Visual):** Jalankan `keyframe.generate` (server otomatis menyuntikkan pose `canonical` karakter ke `reference_images[]`). Tunggu owner menyetujui keyframe per scene.
   - **Gate 3 (Video + Audio/Speech Clip):** Jalankan `clip.generate` untuk scene yang keyframe-nya sudah `approved`. Jangan memicu untuk keyframe `pending`/`rejected`/`stale`. Tunggu owner mengaudit video + audio + trim.
   - **Gate 4 (Render Final & Publish):** Jalankan `subtitle.generate` dan `assemble.render` setelah seluruh scene `approved` (dan tidak `stale`). Publikasi YouTube dilakukan oleh owner.
5. **Cascade Invalidation & Feedback Loop:**
   - Jika scene berstatus `needs_revision`, baca `reviewer_note`, perbaiki field terkait via `PATCH /api/v1/scenes/{scene_id}`, lalu jalankan ulang capability tahap tersebut.
   - Mengubah hulu (misal merevisi keyframe) otomatis menandai hilir (`clip`, `final_render`) menjadi `stale`.
6. **Gunakan `Idempotency-Key`:** Sertakan header `Idempotency-Key` pada endpoint pembuatan job/run agar retry jaringan tidak menggandakan eksekusi GPU.

---

<!-- SYSTEM_PROMPT_START -->
## SOP Brainstorming Kreatif & 4-Gate Pipeline (Wajib Dijalankan Agent)

User cukup memberi topik kasar (misal: *"taubatnya penjudi online"*). **Jangan minta user menentukan jumlah scene.** AI memandu ide ke cerita final, karakter konsisten, lalu memecahnya otomatis menjadi Part & Scene:

1. **Rekomendasi Format & Sinopsis:** Analisis cerita dan ajukan **1 Video Short** (~5–8 scene) atau **Series Ber-Part** (hook pembuka + cliffhanger). Berikan **Judul**, **Logline**, **Sinopsis**, **Style Bible**, dan **Rasio (`9:16` / `16:9`)**.
2. **Diskusi & Finalisasi:** Revisi alur, konflik, dan ending hingga user menyetujui cerita final.
3. **Karakter Konsisten Lintas Part:** Ekstrak tokoh beserta `description` visual spesifik & `voice_description`. Buat 1 Project + Character + 3 pose sheet; owner menandai pose **Canonical**.
4. **Breakdown Part & Scene (Gate 1):** Tiap Part jadi 1 Video (`scenes[]`, 5–8 dtk/scene): `order_index`, `character_ids`, `visual_prompt`, `dialogue_text`, `audio_prompt`. Tunggu approve **Gate 1**.
5. **Gate 2–4 & Revisi:** Gate 2 (`keyframe`) -> Gate 3 (`clip` `i2v`/`r2v` 5–10 dtk) -> Gate 4 (`subtitle` + `render`). Scene `needs_revision` diperbaiki berdasar `reviewer_note`.
<!-- SYSTEM_PROMPT_END -->

---

## Referensi Cepat Endpoint API

| Tahap | Method & Endpoint | Pelaku | Fungsi |
| :--- | :--- | :--- | :--- |
| Guide | `GET /agents.md` / `GET /guide` | Agent / Tim | Membaca SOP & daftar capability |
| Worker | `GET /api/v1/workers/models-status` | Agent / Owner | Cek kesiapan model MiniMax H3 di GPU `.77` |
| Project | `POST /api/v1/projects` | Agent / Owner | Buat project series/cerita |
| Karakter | `POST /api/v1/characters` | Agent / Owner | Daftarkan tokoh + deskripsi visual & suara |
| Sheet | `POST /api/v1/characters/{char_id}/generate-sheet` | Agent / Owner | Generate 3 pose turnaround karakter |
| Canonical | `POST /api/v1/characters/{char_id}/canonical` | **Owner Only** | Kunci pose canonical (Agent ditolak `403`) |
| Video/Part | `POST /api/v1/videos` | Agent / Owner | Buat Video/Part sekaligus breakdown `scenes[]` |
| Gate 1 | `POST /api/v1/videos/{video_id}/gate1/approve` | **Owner Only** | Setujui naskah & breakdown scene |
| Keyframe | `POST /api/v1/scenes/{scene_id}/generate-keyframe` | Agent / Owner | Generate keyframe scene (Gate 2) |
| Revisi | `PATCH /api/v1/scenes/{scene_id}` | Agent / Owner | Perbaiki prompt/dialog berdasar `reviewer_note` |
| Clip | `POST /api/v1/scenes/{scene_id}/generate-clip` | Agent / Owner | Generate video + suara (`i2v` / `r2v`, Gate 3) |
| Status | `GET /api/v1/runs/{run_id}` | Agent / Owner | Polling status antrean GPU |
| Final | `POST /api/v1/videos/{video_id}/generate-subtitles` & `/render` | Agent / Owner | Buat `.srt` & render video final (Gate 4) |
| Gate 4 | `POST /api/v1/videos/{video_id}/gate4/approve` | **Owner Only** | Setujui video final (Gate 4) tanpa wajib YouTube |
| Publish | `POST /api/v1/videos/{video_id}/gate4/approve-publish` | **Owner Only** | Upload final ke channel YouTube milik owner |