feat(youtube): InnerTube-first search, transcripts and watch-next related (Steps 15-18)

- InnerTube layer via pinned youtubei.js 18.1.0 (no quota, no key):
  search with merged continuations (unlimited pages), watch-next
  related with LockupView mapping, caption-track discovery
- 3-layer dispatcher (YT_SEARCH_MODE, default innertube-first):
  innertube -> yt-dlp scrape -> official API, graceful errors.yt
- Robust yt-dlp binary resolution (YT_DLP_PATH > PATH > bundled)
  with systematic API fallback (fixes spawn ENOENT in UI)
- Transcript: InnerTube caption discovery (YT_TRANSCRIPT_SOURCE),
  reusing pickTrack/orderedTracks/parseTrackText; yt-dlp fallback kept
- Watch: sidebar uses real watch-next related[] (/api/details),
  title-search fallback for other providers
- Cache: memory LRU + SQLite (youtube_search_cache, youtube_metrics),
  never persist empty pages; /healthz observability; /api/trending
- Includes pending Step 15/16 leftovers in same files (suggest,
  test scripts); unrelated provider adapters left uncommitted

.env.example

@@ -1,8 +1,28 @@
 # Configuration des clés API pour les adaptateurs de recherche
 # Copiez ce fichier en .env et remplissez les valeurs
 
-# YouTube API Key (obligatoire pour la recherche YouTube)
+# --- YouTube hybride Step 17-18 : InnerTube (sans clé) > scrape yt-dlp > API officielle ---
+# Mode : innertube-first (défaut, 0 quota, pagination illimitée) | innertube-only
+#      | scrape-first | api-first | scrape-only | api-only
+YT_SEARCH_MODE=innertube-first
+# Localisation InnerTube (gl=region, hl=langue)
+YT_INNERTUBE_GL=FR
+YT_INNERTUBE_HL=fr
+# Découverte des pistes de sous-titres YouTube : innertube-first (défaut,
+# sans spawn yt-dlp) | ytdlp-only | innertube-only
+YT_TRANSCRIPT_SOURCE=innertube-first
+# Cache scrape (30 min) + binaire yt-dlp (frais requis contre le bot-check)
+YT_SCRAPE_TTL_MS=1800000
+YT_DLP_TIMEOUT_MS=20000
+# YT_DLP_PATH=/usr/local/bin/yt-dlp
+# Anti-ban : cookies exportés (volume :ro en Docker) + PO-Token + proxy sortant
+# YT_COOKIES_FILE=/cookies/youtube.txt
+# YT_PO_TOKEN=
+# YT_EGRESS_PROXY=http://proxy:8080
+
+# YouTube API Key (fallback uniquement en scrape-first, obligatoire en api-only)
 # Obtenez une clé ici : https://console.developers.google.com/
+# Accepte YOUTUBE_API_KEYS en CSV ('k1,k2') ou JSON ('["k1","k2"]') avec rotation auto.
 YOUTUBE_API_KEY=your_youtube_api_key_here
 
 # Twitch Client ID (optionnel, pour une recherche Twitch plus complète)