docs: mimari ve operasyon dokümantasyonlarını ekle

- `ARCHITECTURE_AND_FLOW.md`: Mimari, servis sorumlulukları, kuyruklar ve iş akışı.
- `HANDOVER_2026-02-16.md`: Tamamlanan kapsam, düzeltmeler ve sonraki adımlar.
- `OPERATIONS_RUNBOOK.md`: Dev/prod çalıştırma, test ve sık karşılaşılan sorunlar.
- `TURKCEALTYAZI_REAL_STATUS.md`: Gerçek provider entegrasyon durumu ve yapılacaklar.
- `README.md`: Dokümantasyon dizini için giriş ve indeks.

doc/TURKCEALTYAZI_REAL_STATUS.md

@@ -0,0 +1,82 @@
+# TurkceAltyazi Gercek Entegrasyon Durum Raporu
+
+Guncel durum tarihi: **16 Subat 2026**
+
+## Hedef
+
+Mock yerine TurkceAltyazi kaynagindan gercek aday bulma ve indirme akisini aktif etmek.
+
+## Tamamlananlar
+
+1. Feature flags tanimli:
+- `ENABLE_TURKCEALTYAZI_REAL`
+- `TURKCEALTYAZI_ALLOW_MOCK_FALLBACK`
+- `TURKCEALTYAZI_BASE_URL`
+- `TURKCEALTYAZI_TIMEOUT_MS`
+- `TURKCEALTYAZI_MIN_DELAY_MS`
+
+2. Real helper dosyasi var:
+- `services/api/src/lib/turkcealtyaziReal.ts`
+  - Arama URL denemeleri
+  - HTML parse ile aday cikarimi
+  - Detail sayfasinda download link cikarimi
+  - Binary indirme
+
+3. Provider real/mok gecisi var:
+- `services/api/src/providers/TurkceAltyaziProvider.ts`
+  - Real aciksa once real dener
+  - Basarisiz olursa fallback policy'e gore mock'a duser
+
+4. Trace log adimlari var:
+- `TA_SEARCH_REQUEST`
+- `TA_SEARCH_PARSED`
+- `TA_DETAIL_FETCHED`
+- `TA_DOWNLOAD_URL_RESOLVED`
+
+## Su an nerede kaldik?
+
+- KOD seviyesinde real TA akisi entegre edildi.
+- Servisler ayaga kalkiyor.
+- Runtime'da real TA davranisinin stabilitesi daha test edilmedi (site response/DOM degiskenligi nedeniyle).
+- Yani entegrasyon **ilk calisir prototip** seviyesinde.
+
+## Kalan kritik isler
+
+1. HTML parseri fixture testlerle sabitle
+- Ornek TA arama/detay HTML snapshotlari ile unit test yaz.
+- DOM degisikliklerine karsi fallback selector stratejisi ekle.
+
+2. Dayaniklilik katmani
+- 403/429/Cloudflare benzeri durumlari ayri hata kodlariyla logla.
+- Retry/backoff politikasi daha netlestir.
+
+3. Download tipi dogrulama
+- Content-Type + dosya signature kontrolu ekle.
+- Yanlis mime/redirect durumlarini net hata ile ele al.
+
+4. Yasal/etik uyum notu
+- Robots/ToS uyumunu projede dokumante et.
+
+## Devam ederken kontrol listesi
+
+1. `.env`:
+```env
+ENABLE_TURKCEALTYAZI_REAL=true
+TURKCEALTYAZI_ALLOW_MOCK_FALLBACK=true
+```
+2. Servisleri yeniden baslat:
+```bash
+docker compose -f compose.dev.yml up -d --build api core
+```
+3. Yeni bir movie job tetikle.
+4. Job logda TA adimlarini dogrula.
+5. Mock'a dustuyse sebebi logla ve parseri iyilestir.
+
+## Onemli dosyalar
+
+- `services/api/src/lib/turkcealtyaziReal.ts`
+- `services/api/src/providers/TurkceAltyaziProvider.ts`
+- `services/api/src/lib/subtitleEngine.ts`
+- `.env`
+- `.env.example`
+