docs: rewrite README and docs to concise ASCII style

docs/PLUGIN_DEVELOPMENT.md

@@ -1,118 +1,85 @@
-# ViewIT – Entwicklerdoku Plugins (`addon/plugins/*_plugin.py`)
+# ViewIT Plugin Entwicklung (`addon/plugins/*_plugin.py`)
 
-Diese Doku beschreibt, wie Plugins im ViewIT‑Addon aufgebaut sind und wie neue Provider‑Integrationen entwickelt werden.
+Diese Datei beschreibt den Vertrag zwischen Router und Plugins.
 
 ## Grundlagen
-- Jedes Plugin ist eine einzelne Datei unter `addon/plugins/`.
-- Dateinamen **ohne** `_`‑Prefix werden automatisch geladen.
-- Jede Datei enthält eine Klasse, die von `BasisPlugin` erbt.
-- Optional: `Plugin = <Klasse>` als expliziter Einstiegspunkt (bevorzugt vom Loader).
+- Ein Plugin ist eine Python Datei in `addon/plugins/`.
+- Dateien mit `_` Prefix werden nicht geladen.
+- Plugin Klasse erbt von `BasisPlugin`.
+- Optional: `Plugin = <Klasse>` als klarer Einstiegspunkt.
 
-## Pflicht‑Methoden (BasisPlugin)
-Jedes Plugin muss diese Methoden implementieren:
+## Pflichtmethoden
+Jedes Plugin implementiert:
 - `async search_titles(query: str) -> list[str]`
 - `seasons_for(title: str) -> list[str]`
 - `episodes_for(title: str, season: str) -> list[str]`
 
-## Vertrag Plugin ↔ Hauptlogik (`default.py`)
-Die Hauptlogik ruft Plugin-Methoden auf und verarbeitet ausschließlich deren Rückgaben.
+## Wichtige optionale Methoden
+- `stream_link_for(...)`
+- `resolve_stream_link(...)`
+- `metadata_for(...)`
+- `available_hosters_for(...)`
+- `series_url_for_title(...)`
+- `remember_series_url(...)`
+- `episode_url_for(...)`
+- `available_hosters_for_url(...)`
+- `stream_link_for_url(...)`
 
-Wesentliche Rückgaben an die Hauptlogik:
-- `search_titles(...)` → Liste von Titel-Strings für die Trefferliste
-- `seasons_for(...)` → Liste von Staffel-Labels
-- `episodes_for(...)` → Liste von Episoden-Labels
-- `stream_link_for(...)` → Hoster-/Player-Link (nicht zwingend finale Media-URL)
-- `resolve_stream_link(...)` → finale/spielbare URL nach Redirect/Resolver
-- `metadata_for(...)` → Info-Labels/Art (Plot/Poster) aus der Quelle
-- Optional `available_hosters_for(...)` → auswählbare Hoster-Namen im Dialog
-- Optional `series_url_for_title(...)` → stabile Detail-URL pro Titel für Folgeaufrufe
-- Optional `remember_series_url(...)` → Übernahme einer bereits bekannten Detail-URL
+## Film Provider Standard
+Wenn keine echten Staffeln existieren:
+- `seasons_for(title)` gibt `['Film']`
+- `episodes_for(title, 'Film')` gibt `['Stream']`
 
-Standard für Film-Provider (ohne echte Staffeln):
-- `seasons_for(title)` gibt `["Film"]` zurück
-- `episodes_for(title, "Film")` gibt `["Stream"]` zurück
+## Capabilities
+Ein Plugin kann Features melden ueber `capabilities()`.
+Bekannte Werte:
+- `popular_series`
+- `genres`
+- `latest_episodes`
+- `new_titles`
+- `alpha`
+- `series_catalog`
 
-## Optionale Features (Capabilities)
-Über `capabilities()` kann das Plugin zusätzliche Funktionen anbieten:
-- `popular_series` → `popular_series()`
-- `genres` → `genres()` + `titles_for_genre(genre)`
-- `latest_episodes` → `latest_episodes(page=1)`
-- `new_titles` → `new_titles_page(page=1)`
-- `alpha` → `alpha_index()` + `titles_for_alpha_page(letter, page)`
-- `series_catalog` → `series_catalog_page(page=1)`
+## Suche
+Aktuelle Regeln fuer Suchtreffer:
+- Match auf Titel
+- Wortbasiert
+- Keine Teilwort Treffer im selben Wort
+- Beschreibungen nicht fuer Match nutzen
 
-## Empfohlene Struktur
-- Konstanten für URLs/Endpoints (BASE_URL, Pfade, Templates)
-- `requests` + `bs4` optional (fehlt beides, Plugin sollte sauber deaktivieren)
-- Helper‑Funktionen für Parsing und Normalisierung
-- Caches für Such‑, Staffel‑ und Episoden‑Daten
+## Settings
+Pro Plugin meist `*_base_url`.
+Beispiele:
+- `serienstream_base_url`
+- `aniworld_base_url`
+- `einschalten_base_url`
+- `topstream_base_url`
+- `filmpalast_base_url`
+- `doku_streams_base_url`
 
-## Suche (aktuelle Policy)
-- **Nur Titel‑Matches**
-- **Wortbasierter Match** nach Normalisierung (Lowercase + Nicht‑Alnum → Leerzeichen)
-- Keine Teilwort-Treffer innerhalb eines Wortes (Beispiel: `hund` matcht nicht `thunder`)
-- Keine Beschreibung/Plot/Meta für Matches
+## Playback Flow
+1. Episode oder Film auswaehlen.
+2. Optional Hosterliste anzeigen.
+3. `stream_link_for` oder `stream_link_for_url` aufrufen.
+4. `resolve_stream_link` aufrufen.
+5. Finale URL an Kodi geben.
 
-## Namensgebung
-- Plugin‑Klassenname: `XxxPlugin`
-- Anzeigename (Property `name`): **mit Großbuchstaben beginnen** (z. B. `Serienstream`, `Einschalten`)
-
-## Settings pro Plugin
-Standard: `*_base_url` (Domain / BASE_URL)
-- Beispiele:
-  - `serienstream_base_url`
-  - `aniworld_base_url`
-  - `einschalten_base_url`
-  - `topstream_base_url`
-  - `filmpalast_base_url`
-  - `doku_streams_base_url`
-
-## Playback
-- `stream_link_for(...)` implementieren (liefert bevorzugten Hoster-Link).
-- `available_hosters_for(...)` bereitstellen, wenn die Seite mehrere Hoster anbietet.
-- `resolve_stream_link(...)` nach einheitlichem Flow umsetzen:
-  1. Redirects auflösen (falls vorhanden)
-  2. ResolveURL (`resolveurl_backend.resolve`) versuchen
-  3. Bei Fehlschlag auf den besten verfügbaren Link zurückfallen
-- Optional `set_preferred_hosters(...)` unterstützen, damit die Hoster-Auswahl aus der Hauptlogik direkt greift.
-
-## Standard‑Flow (empfohlen)
-1. **Suche**: nur Titel liefern und Titel→Detail-URL mappen.
-2. **Navigation**: `series_url_for_title`/`remember_series_url` unterstützen, damit URLs zwischen Aufrufen stabil bleiben.
-3. **Auswahl Hoster**: Hoster-Namen aus der Detailseite extrahieren und anbieten.
-4. **Playback**: Hoster-Link liefern, danach konsistent über `resolve_stream_link` finalisieren.
-5. **Metadaten**: `metadata_for` nutzen, Plot/Poster aus der Quelle zurückgeben.
-6. **Fallbacks**: bei Layout-Unterschieden defensiv parsen und Logging aktivierbar halten.
-
-## Debugging
-Global gesteuert über Settings:
-- `debug_log_urls`
-- `debug_dump_html`
-- `debug_show_url_info`
-
-Plugins sollten die Helper aus `addon/plugin_helpers.py` nutzen:
+## Logging
+Nutze Helper aus `addon/plugin_helpers.py`:
 - `log_url(...)`
 - `dump_response_html(...)`
 - `notify_url(...)`
 
-## Template
-`addon/plugins/_template_plugin.py` dient als Startpunkt für neue Provider.
+## Build und Checks
+- ZIP: `./scripts/build_kodi_zip.sh`
+- Addon Ordner: `./scripts/build_install_addon.sh`
+- Manifest: `python3 scripts/generate_plugin_manifest.py`
+- Snapshot Checks: `python3 qa/run_plugin_snapshots.py`
 
-## Build & Test
-- ZIP bauen: `./scripts/build_kodi_zip.sh`
-- Addon‑Ordner: `./scripts/build_install_addon.sh`
-- Plugin‑Manifest aktualisieren: `python3 scripts/generate_plugin_manifest.py`
-- Live-Snapshot-Checks: `python3 qa/run_plugin_snapshots.py` (aktualisieren mit `--update`)
-
-## Beispiel‑Checkliste
-- [ ] `name` korrekt gesetzt
-- [ ] `*_base_url` in Settings vorhanden
-- [ ] Suche matcht nur Titel und wortbasiert
-- [ ] `stream_link_for` + `resolve_stream_link` folgen dem Standard-Flow
-- [ ] Optional: `available_hosters_for` + `set_preferred_hosters` vorhanden
-- [ ] Optional: `series_url_for_title` + `remember_series_url` vorhanden
-- [ ] Fehlerbehandlung und Timeouts vorhanden
-- [ ] Optional: Caches für Performance
-
-## Hinweis zur Erstellung
-Teile dieser Dokumentation wurden KI‑gestützt erstellt und bei Bedarf manuell angepasst.
+## Kurze Checkliste
+- `name` gesetzt und korrekt
+- `*_base_url` in Settings vorhanden
+- Suche liefert nur passende Titel
+- Playback Methoden vorhanden
+- Fehler und Timeouts behandelt
+- Cache nur da, wo er Zeit spart