docs: document NFO repair feature

docs/NFO_GUIDE.md

@@ -673,7 +673,73 @@ The XML serialisation lives in `src/core/utils/nfo_generator.py`
 
 ---
 
-## 11. Support
+## 11. Automatic NFO Repair
+
+Every time the server starts, Aniworld scans all existing `tvshow.nfo` files and
+automatically repairs any that are missing required tags.
+
+### How It Works
+
+1. **Scan** — `perform_nfo_repair_scan()` in
+   `src/server/services/initialization_service.py` is called from the FastAPI
+   lifespan after `perform_media_scan_if_needed()`.
+2. **Detect** — `nfo_needs_repair(nfo_path)` from
+   `src/core/services/nfo_repair_service.py` parses each `tvshow.nfo` with
+   `lxml` and checks for the 13 required tags listed below.
+3. **Repair** — Series whose NFO is incomplete are queued for background reload
+   via `BackgroundLoaderService.add_series_loading_task()`.  The background
+   loader re-fetches metadata from TMDB and rewrites the NFO with all tags
+   populated.
+
+### Tags Checked (13 required)
+
+| XPath          | Tag name        |
+| -------------- | --------------- |
+| `./title`      | `title`         |
+| `./originaltitle` | `originaltitle` |
+| `./year`       | `year`          |
+| `./plot`       | `plot`          |
+| `./runtime`    | `runtime`       |
+| `./premiered`  | `premiered`     |
+| `./status`     | `status`        |
+| `./imdbid`     | `imdbid`        |
+| `./genre`      | `genre`         |
+| `./studio`     | `studio`        |
+| `./country`    | `country`       |
+| `./actor/name` | `actor/name`    |
+| `./watched`    | `watched`       |
+
+### Log Messages
+
+| Message | Meaning |
+| --- | --- |
+| `NFO repair scan complete: 0 of N series queued for repair` | All NFOs are complete — no action needed |
+| `NFO repair scan complete: X of N series queued for repair` | X series had incomplete NFOs and have been queued |
+| `NFO repair scan skipped: TMDB API key not configured` | Set `tmdb_api_key` in `data/config.json` |
+| `NFO repair scan skipped: anime directory not configured` | Set `anime_directory` in `data/config.json` |
+
+### Triggering a Manual Repair
+
+You can also repair a single series on demand via the API:
+
+```http
+POST /api/nfo/update/{series_key}
+```
+
+This calls `NFOService.update_tvshow_nfo()` directly and overwrites the existing
+`tvshow.nfo` with fresh data from TMDB.
+
+### Source Files
+
+| File | Purpose |
+| ---- | ------- |
+| `src/core/services/nfo_repair_service.py` | `REQUIRED_TAGS`, `parse_nfo_tags`, `find_missing_tags`, `nfo_needs_repair`, `NfoRepairService` |
+| `src/server/services/initialization_service.py` | `perform_nfo_repair_scan` startup hook |
+| `src/server/fastapi_app.py` | Wires `perform_nfo_repair_scan` into the lifespan |
+
+---
+
+## 12. Support
 
 ### Getting Help