videonut 1.0.1 → 1.1.0

package/docs/LIFECYCLE.md

@@ -0,0 +1,651 @@
+# VideoNut Complete Lifecycle Documentation
+
+## 📊 SYSTEM OVERVIEW
+
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                           VIDEONUT AGENT PIPELINE                             ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                                                                               ║
+║   USER ──────────────────────────────────────────────────────────────────►   ║
+║          │                                                                    ║
+║          ▼                                                                    ║
+║   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐║
+║   │ 📡 SCOUT    │────►│ 🎯 PROMPT   │────►│ 🕵️ INVEST  │────►│ ✍️ SCRIPT   │║
+║   │ (1st Agent) │     │   AGENT     │     │  IGATOR     │     │  WRITER     │║
+║   └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘║
+║          │                   │                   │                   │        ║
+║          │ WRITES            │ READS             │ READS             │ READS  ║
+║          ▼                   ▼                   ▼                   ▼        ║
+║   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐║
+║   │config.yaml  │     │topic_brief  │     │  prompt.md  │     │truth_dossier│║
+║   │             │     │    .md      │     │             │     │    .md      │║
+║   └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘║
+║                                                                               ║
+║   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐║
+║   │ 🎬 DIRECTOR │────►│ 🦅 SCAVENGE │────►│ 💾 ARCHIVIST│────►│ 🧐 EIC      │║
+║   │             │     │     R       │     │             │     │             │║
+║   └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘║
+║          │                   │                   │                   │        ║
+║          │ READS             │ READS             │ READS             │ READS  ║
+║          ▼                   ▼                   ▼                   ▼        ║
+║   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐║
+║   │voice_script │     │master_script│     │asset_manifest│    │ALL PREVIOUS │║
+║   │narrative_   │     │    .md      │     │    .md      │     │   FILES     │║
+║   │script.md    │     │             │     │             │     │             │║
+║   └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘║
+║                                                                               ║
+║                    ┌─────────────┐     ┌─────────────┐                        ║
+║                    │ 🎨 THUMBNAIL│     │ 🔍 SEO      │                        ║
+║                    │             │     │             │                        ║
+║                    └─────────────┘     └─────────────┘                        ║
+║                           │                   │                               ║
+║                           └───────┬───────────┘                               ║
+║                                   ▼                                           ║
+║                          ┌─────────────────┐                                  ║
+║                          │youtube_         │                                  ║
+║                          │optimization.md  │                                  ║
+║                          └─────────────────┘                                  ║
+║                                                                               ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## 🔐 CONFIG.YAML ACCESS CONTROL
+
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                           WHO CAN MODIFY CONFIG.YAML?                         ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                                                                               ║
+║   ┌──────────────────────────────────────────────────────────────────────┐   ║
+║   │                    📡 TOPIC SCOUT (ONLY AGENT)                        │   ║
+║   │                                                                       │   ║
+║   │   ✅ CAN WRITE TO config.yaml:                                        │   ║
+║   │      • projects_folder                                                │   ║
+║   │      • current_project                                                │   ║
+║   │      • video_format                                                   │   ║
+║   │      • target_duration                                                │   ║
+║   │      • target_line_count                                              │   ║
+║   │      • audio_language                                                 │   ║
+║   │      • scope (international/national/regional)                        │   ║
+║   │      • country                                                        │   ║
+║   │      • region                                                         │   ║
+║   │      • industry_tag                                                   │   ║
+║   │                                                                       │   ║
+║   └──────────────────────────────────────────────────────────────────────┘   ║
+║                                      │                                        ║
+║                                      │ WRITES                                 ║
+║                                      ▼                                        ║
+║   ┌──────────────────────────────────────────────────────────────────────┐   ║
+║   │                         config.yaml                                   │   ║
+║   └──────────────────────────────────────────────────────────────────────┘   ║
+║                                      │                                        ║
+║                                      │ READ ONLY                              ║
+║                                      ▼                                        ║
+║   ┌──────────────────────────────────────────────────────────────────────┐   ║
+║   │  🎯 Prompt  │ 🕵️ Investigator │ ✍️ Scriptwriter │ 🎬 Director        │   ║
+║   │  🦅 Scavenger │ 💾 Archivist │ 🧐 EIC │ 🎨 Thumbnail │ 🔍 SEO         │   ║
+║   │                                                                       │   ║
+║   │  ❌ CANNOT MODIFY config.yaml                                         │   ║
+║   │  ✅ CAN READ all values                                               │   ║
+║   │  ✅ CAN CREATE files in {projects_folder}/{current_project}/          │   ║
+║   └──────────────────────────────────────────────────────────────────────┘   ║
+║                                                                               ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## 🛠️ AGENT TOOLS MATRIX
+
+```
+╔════════════════════════════════════════════════════════════════════════════════════════╗
+║                              WHICH AGENT USES WHICH TOOLS?                              ║
+╠════════════════════════════════════════════════════════════════════════════════════════╣
+║                                                                                          ║
+║  TOOL                    │ SCOUT │ PROMPT │ INVEST │ SCRIPT │ DIREC │ SCAV │ ARCH │ EIC ║
+║  ────────────────────────┼───────┼────────┼────────┼────────┼───────┼──────┼──────┼─────║
+║  google_web_search       │  ✅   │   ✅   │   ✅   │   ❌   │  ✅   │  ✅  │  ❌  │  ❌ ║
+║  youtube_search.py       │  ✅   │   ✅   │   ✅   │   ❌   │  ✅   │  ✅  │  ❌  │  ❌ ║
+║  caption_reader.py       │  ✅   │   ✅   │   ✅   │   ❌   │  ✅   │  ✅  │  ✅  │  ❌ ║
+║  web_reader.py           │  ✅   │   ✅   │   ✅   │   ❌   │  ✅   │  ✅  │  ❌  │  ❌ ║
+║  link_checker.py         │  ✅   │   ✅   │   ✅   │   ❌   │  ✅   │  ✅  │  ✅  │  ✅ ║
+║  clip_grabber.py         │  ❌   │   ❌   │   ❌   │   ❌   │  ❌   │  ❌  │  ✅  │  ❌ ║
+║  image_grabber.py        │  ❌   │   ❌   │   ❌   │   ❌   │  ❌   │  ❌  │  ✅  │  ❌ ║
+║  article_screenshotter   │  ❌   │   ❌   │   ❌   │   ❌   │  ❌   │  ❌  │  ✅  │  ❌ ║
+║  screenshotter.py        │  ❌   │   ❌   │   ❌   │   ❌   │  ❌   │  ❌  │  ✅  │  ❌ ║
+║  pdf_reader.py           │  ❌   │   ❌   │   ✅   │   ❌   │  ❌   │  ❌  │  ❌  │  ❌ ║
+║  archive_url.py          │  ❌   │   ❌   │   ✅   │   ❌   │  ❌   │  ✅  │  ❌  │  ❌ ║
+║  search_logger.py        │  ✅   │   ✅   │   ✅   │   ❌   │  ❌   │  ❌  │  ❌  │  ❌ ║
+║                                                                                          ║
+╚════════════════════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## 📁 FILE CREATION & READING FLOW
+
+```
+╔══════════════════════════════════════════════════════════════════════════════════════════╗
+║                              FILE FLOW: WHO CREATES, WHO READS                            ║
+╠══════════════════════════════════════════════════════════════════════════════════════════╣
+║                                                                                           ║
+║  📡 TOPIC SCOUT ─────────────────────────────────────────────────────────────────────►   ║
+║      │                                                                                    ║
+║      ├──► CREATES: Project folder (gemini_2026-01-04_Topic_001/)                         ║
+║      ├──► UPDATES: config.yaml (ALL settings)                                            ║
+║      └──► CREATES: topic_brief.md (200 words)                                            ║
+║                    │                                                                      ║
+║                    ▼ READS topic_brief.md                                                 ║
+║  🎯 PROMPT AGENT ────────────────────────────────────────────────────────────────────►   ║
+║      │                                                                                    ║
+║      └──► CREATES: prompt.md (Full investigation prompt with 21 questions)               ║
+║                    │                                                                      ║
+║                    ▼ READS prompt.md                                                      ║
+║  🕵️ INVESTIGATOR ────────────────────────────────────────────────────────────────────►   ║
+║      │                                                                                    ║
+║      └──► CREATES: truth_dossier.md (Research findings, answers to 21 questions)         ║
+║                    │                                                                      ║
+║                    ▼ READS truth_dossier.md                                               ║
+║  ✍️ SCRIPTWRITER ─────────────────────────────────────────────────────────────────────►   ║
+║      │                                                                                    ║
+║      ├──► CREATES: voice_script.md (Script for TTS with voice cues)                      ║
+║      └──► CREATES: narrative_script.md (Clean script for Director)                       ║
+║                    │                                                                      ║
+║                    ▼ READS narrative_script.md                                            ║
+║  🎬 DIRECTOR ──────────────────────────────────────────────────────────────────────────►  ║
+║      │                                                                                    ║
+║      ├──► CREATES: master_script.md (Scene-by-scene with visual directions)              ║
+║      └──► CREATES: video_direction.md (Summary of visual needs)                          ║
+║                    │                                                                      ║
+║                    ▼ READS master_script.md                                               ║
+║  🦅 SCAVENGER ───────────────────────────────────────────────────────────────────────►   ║
+║      │                                                                                    ║
+║      └──► CREATES: asset_manifest.md (All URLs + timestamps verified)                    ║
+║                    │                                                                      ║
+║                    ▼ READS asset_manifest.md                                              ║
+║  💾 ARCHIVIST ───────────────────────────────────────────────────────────────────────►   ║
+║      │                                                                                    ║
+║      ├──► DOWNLOADS: assets/ folder (images, videos, screenshots)                        ║
+║      └──► CREATES: MANUAL_REQUIRED.txt (If some downloads failed)                        ║
+║                    │                                                                      ║
+║                    ▼ READS ALL previous files                                             ║
+║  🧐 EIC (Editor-in-Chief) ────────────────────────────────────────────────────────────►  ║
+║      │                                                                                    ║
+║      └──► CREATES: review_report.md (Quality review, approval/rejection)                 ║
+║                    │                                                                      ║
+║                    ▼ READS voice_script.md, truth_dossier.md                              ║
+║  🎨 THUMBNAIL + 🔍 SEO ─────────────────────────────────────────────────────────────────► ║
+║      │                                                                                    ║
+║      └──► CREATES: youtube_optimization.md (Thumbnail prompts + SEO)                     ║
+║                                                                                           ║
+╚══════════════════════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## 💬 WHAT EACH AGENT ASKS THE USER
+
+```
+╔══════════════════════════════════════════════════════════════════════════════════════════╗
+║                              USER INTERACTION PER AGENT                                   ║
+╠══════════════════════════════════════════════════════════════════════════════════════════╣
+║                                                                                           ║
+║  📡 TOPIC SCOUT (MOST USER INTERACTION)                                                   ║
+║  ├── [NP] What's the topic? ─────────────────────►  User enters topic                    ║
+║  ├── [NP] Scope? (1=International, 2=National, 3=Regional) ───► User picks 1/2/3         ║
+║  ├── [NP] Which country? ─────────────────────────►  User enters "India"                 ║
+║  ├── [NP] Which region? ──────────────────────────►  User enters "Telangana"             ║
+║  ├── [NP] Audio language? ────────────────────────►  User picks Telugu                   ║
+║  ├── [NP] Video format? ──────────────────────────►  User picks Investigative            ║
+║  ├── [NP] Duration? ──────────────────────────────►  User enters 25 (minutes)            ║
+║  ├── [NP] Industry tag? ──────────────────────────►  User picks Political                ║
+║  ├── [ST] Pick topic (1-5)? ──────────────────────►  User picks 2                        ║
+║  └── Proceed to Prompt Agent? ────────────────────►  User says Y                         ║
+║                                                                                           ║
+║  🎯 PROMPT AGENT (MINIMAL INTERACTION)                                                    ║
+║  ├── Topic already from topic_brief.md? Use it? ──►  User says Y                         ║
+║  └── Proceed to Investigator? ────────────────────►  User says Y                         ║
+║                                                                                           ║
+║  🕵️ INVESTIGATOR (ONE CONFIRMATION)                                                       ║
+║  └── [SI] Start Investigation? ───────────────────►  User says Y                         ║
+║                                                                                           ║
+║  ✍️ SCRIPTWRITER (ONE CONFIRMATION)                                                       ║
+║  └── [GS] Generate Script? ───────────────────────►  User says Y                         ║
+║                                                                                           ║
+║  🎬 DIRECTOR (ONE CONFIRMATION)                                                           ║
+║  └── [GM] Generate Master Script? ────────────────►  User says Y                         ║
+║                                                                                           ║
+║  🦅 SCAVENGER (ONE CONFIRMATION)                                                          ║
+║  └── [FA] Find Assets? ───────────────────────────►  User says Y                         ║
+║                                                                                           ║
+║  💾 ARCHIVIST (ONE CONFIRMATION)                                                          ║
+║  └── [DA] Download Assets? ───────────────────────►  User says Y                         ║
+║                                                                                           ║
+║  🧐 EIC (Automatic, may ask for revisions)                                                ║
+║  └── [SR] Start Review? ──────────────────────────►  User says Y                         ║
+║                                                                                           ║
+║  🎨 THUMBNAIL + 🔍 SEO (ONE CONFIRMATION)                                                  ║
+║  └── [GO] Generate Optimization? ─────────────────►  User says Y                         ║
+║                                                                                           ║
+╚══════════════════════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## 📋 COMPLETE EXAMPLE: Electoral Bonds Scam
+
+```
+╔══════════════════════════════════════════════════════════════════════════════════════════╗
+║              COMPLETE WALKTHROUGH: "Electoral Bonds Scam" (Political, India)              ║
+╠══════════════════════════════════════════════════════════════════════════════════════════╣
+
+STEP 1: USER RUNS /topic_scout
+═══════════════════════════════════════════════════════════════════════════════════════════
+
+User: /topic_scout
+
+📡 Scout: "Ready to configure. What do you want to do?"
+
+User: [NP] New Project
+
+📡 Scout: "What's the topic?"
+User: "Electoral Bonds Scam"
+
+📡 Scout: "What's the scope?"
+   [1] International
+   [2] National
+   [3] Regional
+User: 2
+
+📡 Scout: "Which country?"
+User: "India"
+
+📡 Scout: "Audio language?"
+   [1] English  [2] Telugu  [3] Hindi...
+User: 2 (Telugu)
+
+📡 Scout: "Video format?"
+   [1] Investigative Case Study (30-45 min)
+   [2] News Explainer (15-20 min)
+   ...
+User: 1
+
+📡 Scout: "Target duration in minutes?"
+User: 30
+
+📡 Scout: "Industry tag?"
+   [1] Finance  [2] Stock Market  [3] Political...
+User: 3 (Political)
+
+📡 Scout: "✅ PROJECT CREATED"
+   📁 Folder: gemini_2026-01-04_Electoral_Bonds_Scam_001
+   📊 Settings:
+      • Scope: national | India
+      • Language: Telugu
+      • Format: Investigative Case Study
+      • Duration: 30 min (4050 words)
+      • Industry: Political
+      
+   config.yaml UPDATED ✅
+   
+📡 Scout: "Search for topic context or enter manually?"
+User: [ST] Search
+
+📡 Scout: *searches using google_web_search, youtube_search.py*
+   
+   TOP 5 ANGLES:
+   #1 🔥 "Supreme Court reveals full donor list"
+   #2 📈 "Congress demands JPC probe"
+   #3 💡 "How companies bought politicians"
+   ...
+
+User: 1
+
+📡 Scout: *researches deeply, finds YouTube videos*
+   *uses caption_reader.py to get timestamps*
+   *writes 200-word brief*
+   *saves to topic_brief.md*
+
+📡 Scout: "✅ Brief saved. Proceed to /prompt? [Y/N]"
+User: Y
+
+═══════════════════════════════════════════════════════════════════════════════════════════
+STEP 2: USER RUNS /prompt
+═══════════════════════════════════════════════════════════════════════════════════════════
+
+User: /prompt
+
+🎯 Prompt Agent: "📁 Found topic_brief.md from Topic Scout!"
+   Topic: Electoral Bonds Scam - Supreme Court revelation
+   
+🎯 Prompt Agent: "Use this topic? [Y/N]"
+User: Y
+
+🎯 Prompt Agent: *reads brief*
+   *searches for more details using google_web_search*
+   *generates 21 investigation questions*
+   *saves to prompt.md*
+
+🎯 Prompt Agent: "✅ Prompt created. Proceed to /investigator? [Y/N]"
+User: Y
+
+═══════════════════════════════════════════════════════════════════════════════════════════
+STEP 3: USER RUNS /investigator
+═══════════════════════════════════════════════════════════════════════════════════════════
+
+User: /investigator
+
+🕵️ Investigator: "Active Project: gemini_2026-01-04_Electoral_Bonds_Scam_001"
+   "📍 Scope: national | India"
+   "🏷️ Industry: Political"
+   
+🕵️ Investigator: "[SI] Start Investigation? [Y/N]"
+User: Y
+
+🕵️ Investigator: *reads prompt.md*
+   *uses google_web_search for each question*
+   *uses youtube_search.py to find interviews*
+   *uses caption_reader.py to extract quotes with timestamps*
+   *uses web_reader.py to read news articles*
+   *uses archive_url.py to preserve key sources*
+   
+   Industry: Political → Prioritizes:
+      • myneta.info (donation data)
+      • Election Commission website
+      • Supreme Court judgments
+      • Parliament proceedings
+
+🕵️ Investigator: *writes truth_dossier.md with all findings*
+
+🕵️ Investigator: "✅ Dossier created. Proceed to /scriptwriter? [Y/N]"
+User: Y
+
+═══════════════════════════════════════════════════════════════════════════════════════════
+STEP 4: USER RUNS /scriptwriter
+═══════════════════════════════════════════════════════════════════════════════════════════
+
+User: /scriptwriter
+
+✍️ Scriptwriter: "Active Project: gemini_2026-01-04_Electoral_Bonds_Scam_001"
+   Target: 30 min = 4050 words (Telugu audio)
+
+✍️ Scriptwriter: "[GS] Generate Script?"
+User: Y
+
+✍️ Scriptwriter: *reads truth_dossier.md*
+   *reads config for audio_language: Telugu*
+   *writes voice_script.md (with voice cues like (pause 2s), (angry tone))*
+   *writes narrative_script.md (clean version for Director)*
+   
+   Word count check: 4050 words ✅
+
+✍️ Scriptwriter: "✅ Scripts created: voice_script.md, narrative_script.md"
+
+═══════════════════════════════════════════════════════════════════════════════════════════
+STEP 5: USER RUNS /director
+═══════════════════════════════════════════════════════════════════════════════════════════
+
+User: /director
+
+🎬 Director: "[GM] Generate Master Script?"
+User: Y
+
+🎬 Director: *reads narrative_script.md*
+   *reads config for video_format: Investigative Case Study*
+   *designs visual shots for each narration line*
+   *uses youtube_search.py to find clips*
+   *uses caption_reader.py to get exact timestamps*
+   
+   Scene count: 50 scenes (30 min video) ✅
+
+🎬 Director: *writes master_script.md*
+   *writes video_direction.md*
+   
+   Assets sourced:
+   - 15 YouTube clips with timestamps
+   - 10 news article screenshots [MANUAL]
+   - 8 stock footage [STOCK-MANUAL]
+   - 12 graphics/charts [MANUAL]
+
+═══════════════════════════════════════════════════════════════════════════════════════════
+STEP 6: USER RUNS /scavenger
+═══════════════════════════════════════════════════════════════════════════════════════════
+
+User: /scavenger
+
+🦅 Scavenger: "[FA] Find Assets?"
+User: Y
+
+🦅 Scavenger: *reads master_script.md*
+   *uses link_checker.py to validate ALL URLs*
+   *uses youtube_search.py to find better alternatives*
+   *uses caption_reader.py to verify timestamps*
+   *uses archive_url.py to preserve news links*
+   
+   URL Validation:
+   - 15 YouTube URLs: ✅ All valid
+   - 8 News URLs: ✅ 7 valid, 1 archived
+   - 5 Image URLs: ✅ All valid
+
+🦅 Scavenger: *writes asset_manifest.md*
+   
+   Ready to Download: 28 assets
+   Manual Required: 10 assets
+
+═══════════════════════════════════════════════════════════════════════════════════════════
+STEP 7: USER RUNS /archivist
+═══════════════════════════════════════════════════════════════════════════════════════════
+
+User: /archivist
+
+💾 Archivist: "[DA] Download Assets?"
+User: Y
+
+💾 Archivist: *reads asset_manifest.md*
+   *uses link_checker.py before each download*
+   *uses clip_grabber.py for YouTube clips*
+   *uses image_grabber.py for images*
+   *uses article_screenshotter.py for news quotes*
+   *uses caption_reader.py for transcript files*
+
+   Downloads:
+   ├── assets/
+   │   ├── 001_supreme_court_judgment_clip.mp4 ✅
+   │   ├── 002_rahul_gandhi_speech_0215-0342.mp4 ✅
+   │   ├── 003_bjp_press_conference.mp4 ✅
+   │   ├── 004_economist_article_quote.png ✅
+   │   ...
+   └── MANUAL_REQUIRED.txt (10 items)
+
+═══════════════════════════════════════════════════════════════════════════════════════════
+STEP 8: USER RUNS /eic
+═══════════════════════════════════════════════════════════════════════════════════════════
+
+User: /eic
+
+🧐 EIC: "[SR] Start Review?"
+User: Y
+
+🧐 EIC: *reads ALL files*
+   *uses link_checker.py to verify URLs still work*
+   
+   CHECKLIST:
+   ✅ Dossier has 21 questions answered
+   ✅ Script is 4050 words (30 min target)
+   ✅ All 21 questions referenced in script
+   ✅ Scene count: 50 (within limit)
+   ✅ 28/38 assets downloaded (10 manual)
+   ✅ Human story present (victims identified)
+   ✅ Hook in first 30 seconds
+   
+🧐 EIC: *writes review_report.md*
+   Status: APPROVED ✅
+
+═══════════════════════════════════════════════════════════════════════════════════════════
+STEP 9: USER RUNS /thumbnail and /seo
+═══════════════════════════════════════════════════════════════════════════════════════════
+
+User: /thumbnail
+
+🎨 Thumbnail: *reads voice_script.md, truth_dossier.md*
+   *generates 3 AI image prompts*
+   *saves to youtube_optimization.md*
+
+User: /seo
+
+🔍 SEO: *reads voice_script.md*
+   *uses google_web_search for keyword research*
+   *generates title, description, tags*
+   *appends to youtube_optimization.md*
+
+═══════════════════════════════════════════════════════════════════════════════════════════
+FINAL PROJECT FOLDER STRUCTURE
+═══════════════════════════════════════════════════════════════════════════════════════════
+
+./Projects/gemini_2026-01-04_Electoral_Bonds_Scam_001/
+├── topic_brief.md           (200 words - from Scout)
+├── prompt.md                (21 questions - from Prompt Agent)
+├── truth_dossier.md         (Research - from Investigator)
+├── voice_script.md          (TTS ready - from Scriptwriter)
+├── narrative_script.md      (Clean script - from Scriptwriter)
+├── master_script.md         (Scene-by-scene - from Director)
+├── video_direction.md       (Summary - from Director)
+├── asset_manifest.md        (URLs + timestamps - from Scavenger)
+├── review_report.md         (Quality check - from EIC)
+├── youtube_optimization.md  (Thumbnail + SEO - from both)
+├── MANUAL_REQUIRED.txt      (Failed downloads - from Archivist)
+└── assets/
+    ├── 001_supreme_court_judgment_clip.mp4
+    ├── 002_rahul_gandhi_speech.mp4
+    ├── 003_bjp_press_conference.mp4
+    ├── ...
+    └── (28 downloaded files)
+
+╚══════════════════════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## 🔗 AGENT CONNECTION DIAGRAM
+
+```
+                                    USER
+                                      │
+                                      │ /topic_scout
+                                      ▼
+                    ┌─────────────────────────────────────┐
+                    │           📡 TOPIC SCOUT            │
+                    │  • Creates project folder           │
+                    │  • WRITES config.yaml (ALL fields)  │
+                    │  • Creates topic_brief.md           │
+                    └─────────────────┬───────────────────┘
+                                      │
+                            config.yaml updated
+                            topic_brief.md created
+                                      │
+                                      ▼
+                    ┌─────────────────────────────────────┐
+                    │           🎯 PROMPT AGENT           │
+                    │  • READS config.yaml                │
+                    │  • READS topic_brief.md             │
+                    │  • Creates prompt.md                │
+                    └─────────────────┬───────────────────┘
+                                      │
+                                      ▼
+                    ┌─────────────────────────────────────┐
+                    │          🕵️ INVESTIGATOR           │
+                    │  • READS config.yaml (industry_tag) │
+                    │  • READS prompt.md                  │
+                    │  • Creates truth_dossier.md         │
+                    └─────────────────┬───────────────────┘
+                                      │
+                                      ▼
+                    ┌─────────────────────────────────────┐
+                    │          ✍️ SCRIPTWRITER            │
+                    │  • READS config.yaml (language)     │
+                    │  • READS truth_dossier.md           │
+                    │  • Creates voice_script.md          │
+                    │  • Creates narrative_script.md      │
+                    └─────────────────┬───────────────────┘
+                                      │
+                                      ▼
+                    ┌─────────────────────────────────────┐
+                    │           🎬 DIRECTOR               │
+                    │  • READS config.yaml (format)       │
+                    │  • READS narrative_script.md        │
+                    │  • Creates master_script.md         │
+                    │  • Creates video_direction.md       │
+                    └─────────────────┬───────────────────┘
+                                      │
+                                      ▼
+                    ┌─────────────────────────────────────┐
+                    │           🦅 SCAVENGER              │
+                    │  • READS config.yaml                │
+                    │  • READS master_script.md           │
+                    │  • Creates asset_manifest.md        │
+                    └─────────────────┬───────────────────┘
+                                      │
+                                      ▼
+                    ┌─────────────────────────────────────┐
+                    │           💾 ARCHIVIST              │
+                    │  • READS config.yaml                │
+                    │  • READS asset_manifest.md          │
+                    │  • Downloads to assets/             │
+                    │  • Creates MANUAL_REQUIRED.txt      │
+                    └─────────────────┬───────────────────┘
+                                      │
+                                      ▼
+                    ┌─────────────────────────────────────┐
+                    │             🧐 EIC                  │
+                    │  • READS config.yaml                │
+                    │  • READS ALL previous files         │
+                    │  • Creates review_report.md         │
+                    └─────────────────┬───────────────────┘
+                                      │
+                        ┌─────────────┴─────────────┐
+                        ▼                           ▼
+          ┌──────────────────────┐    ┌──────────────────────┐
+          │     🎨 THUMBNAIL     │    │       🔍 SEO         │
+          │  • Creates prompts   │    │  • Title/Desc/Tags   │
+          └──────────┬───────────┘    └──────────┬───────────┘
+                     │                           │
+                     └───────────┬───────────────┘
+                                 ▼
+                    ┌─────────────────────────────────────┐
+                    │       youtube_optimization.md       │
+                    └─────────────────────────────────────┘
+                                 │
+                                 ▼
+                           VIDEO READY!
+```
+
+---
+
+## 📌 KEY RULES SUMMARY
+
+```
+╔══════════════════════════════════════════════════════════════════════════════════════════╗
+║                                    KEY RULES                                              ║
+╠══════════════════════════════════════════════════════════════════════════════════════════╣
+║                                                                                           ║
+║  1️⃣  ONLY Topic Scout creates projects and modifies config.yaml                           ║
+║                                                                                           ║
+║  2️⃣  ALL other agents READ config.yaml but NEVER modify it                                ║
+║                                                                                           ║
+║  3️⃣  ALL files are created in: {projects_folder}/{current_project}/                       ║
+║                                                                                           ║
+║  4️⃣  Region is USER SELECTED, not auto-derived from language                              ║
+║                                                                                           ║
+║  5️⃣  Each agent READS the previous agent's output file                                    ║
+║                                                                                           ║
+║  6️⃣  Industry Tag helps agents prioritize relevant sources                                ║
+║                                                                                           ║
+║  7️⃣  Word count = Duration × 135 (avg 135 words per minute)                               ║
+║                                                                                           ║
+║  8️⃣  Minimum video duration = 15 minutes (2025 words)                                     ║
+║                                                                                           ║
+╚══════════════════════════════════════════════════════════════════════════════════════════╝
+```