feat: write all required NFO tags on creation

docs/ARCHITECTURE.md

@@ -204,6 +204,15 @@ src/core/
 +-- entities/               # Domain entities
 |   +-- series.py           # Serie class with sanitized_folder property
 |   +-- SerieList.py        # SerieList collection with sanitized folder support
+|   +-- nfo_models.py       # Pydantic models for tvshow.nfo (TVShowNFO, ActorInfo…)
++-- services/               # Domain services
+|   +-- nfo_service.py      # NFO lifecycle: create / update tvshow.nfo
+|   +-- tmdb_client.py      # Async TMDB API client
++-- utils/                  # Utility helpers (no side-effects)
+|   +-- nfo_generator.py    # TVShowNFO → XML serialiser
+|   +-- nfo_mapper.py       # TMDB API dict → TVShowNFO (tmdb_to_nfo_model,
+|   |                       #   _extract_rating_by_country, _extract_fsk_rating)
+|   +-- image_downloader.py # TMDB image downloader
 +-- providers/              # External provider adapters
 |   +-- base_provider.py    # Loader interface
 |   +-- provider_factory.py # Provider registry

docs/CHANGELOG.md

@@ -37,6 +37,30 @@ This changelog follows [Keep a Changelog](https://keepachangelog.com/) principle
 
 ---
 
+## [Unreleased] - 2026-02-22
+
+### Added
+
+- **NFO tag completeness (`nfo_mapper.py`)**: All 17 required NFO tags are now
+  explicitly populated during creation: `originaltitle`, `sorttitle`, `year`,
+  `plot`, `outline`, `tagline`, `runtime`, `premiered`, `status`, `imdbid`,
+  `genre`, `studio`, `country`, `actor`, `watched`, `dateadded`, `mpaa`.
+- **`src/core/utils/nfo_mapper.py`**: New module containing
+  `tmdb_to_nfo_model()`, `_extract_rating_by_country()`, and
+  `_extract_fsk_rating()`. Extracted from `NFOService` to keep files under
+  500 lines and isolate pure mapping logic.
+- **US MPAA rating**: `_extract_rating_by_country(ratings, "US")` now maps the
+  US TMDB content rating to the `<mpaa>` NFO tag.
+
+### Changed
+
+- `NFOService._tmdb_to_nfo_model()` and `NFOService._extract_fsk_rating()` moved
+  to `src/core/utils/nfo_mapper.py` as module-level functions
+  `tmdb_to_nfo_model()` and `_extract_fsk_rating()`.
+- `src/core/services/nfo_service.py` reduced from 640 → 471 lines.
+
+---
+
 ## [Unreleased] - 2026-01-18
 
 ### Added

docs/NFO_GUIDE.md

@@ -636,7 +636,44 @@ curl -X POST "http://127.0.0.1:8000/api/scheduler/config" \
 
 ---
 
-## 10. Support
+## 10. Tag Reference
+
+The table below lists every XML tag written to `tvshow.nfo` and its source in
+the TMDB API response.  All tags are written whenever the NFO is created or
+updated via `create_tvshow_nfo()` / `update_tvshow_nfo()`.
+
+| NFO tag         | TMDB source field                              | Required |
+| --------------- | ---------------------------------------------- | -------- |
+| `title`         | `name`                                         | ✅        |
+| `originaltitle` | `original_name`                                | ✅        |
+| `showtitle`     | `name` (same as `title`)                       | ✅        |
+| `sorttitle`     | `name` (same as `title`)                       | ✅        |
+| `year`          | First 4 chars of `first_air_date`              | ✅        |
+| `plot`          | `overview`                                     | ✅        |
+| `outline`       | `overview` (same as `plot`)                    | ✅        |
+| `tagline`       | `tagline`                                      | optional |
+| `runtime`       | `episode_run_time[0]`                          | ✅        |
+| `premiered`     | `first_air_date`                               | ✅        |
+| `status`        | `status`                                       | ✅        |
+| `mpaa`          | US content rating from `content_ratings.results`| optional |
+| `fsk`           | DE content rating (written as `mpaa` when preferred) | optional |
+| `imdbid`        | `external_ids.imdb_id`                         | ✅        |
+| `tmdbid`        | `id`                                           | ✅        |
+| `tvdbid`        | `external_ids.tvdb_id`                         | optional |
+| `genre`         | `genres[].name` (one element per genre)        | ✅        |
+| `studio`        | `networks[].name` (one element per network)    | ✅        |
+| `country`       | `origin_country[]` or `production_countries[].name` | ✅  |
+| `actor`         | `credits.cast[]` (top 10, with name/role/thumb)| ✅        |
+| `watched`       | Always `false` on creation                     | ✅        |
+| `dateadded`     | System clock at creation time (`YYYY-MM-DD HH:MM:SS`) | ✅  |
+
+The mapping logic lives in `src/core/utils/nfo_mapper.py` (`tmdb_to_nfo_model`).
+The XML serialisation lives in `src/core/utils/nfo_generator.py`
+(`generate_tvshow_nfo`).
+
+---
+
+## 11. Support
 
 ### Getting Help