Document comprehensive date selection priority system in README

- Added detailed explanation of 4-tier fallback hierarchy
- Documents all TMDB release types (1-6) with clear descriptions
- Explains rename-first detection and Radarr NFO fallback logic
- Shows difference between import_then_digital vs digital_then_import priorities
- Version bumped to 0.2.21

README.md

@@ -236,24 +236,37 @@ curl "http://localhost:8080/debug/tmdb/tt1674782"
 }
 ```
 
-## 🎯 Release Date Priority System
+## 🎯 Date Selection Priority System
 
-NFOGuard uses a **smart fallback system** when Radarr has no valid import history:
+NFOGuard uses a **comprehensive fallback hierarchy** to find the best possible date for each movie:
 
-### 1. **Digital Release** (streaming/VOD)
-- Netflix, Amazon Prime, iTunes, etc.
-- **TMDB Source**: Release type 4
-- **Typical**: 45-90 days after theatrical
+### Movie Priority: `import_then_digital` (Default)
 
-### 2. **Physical Release** (DVD/Blu-ray) 
-- Physical media release dates
-- **TMDB Source**: Release type 5  
-- **Typical**: 90-120 days after theatrical
+**1. Radarr Import History** *(Highest Priority)*
+- `radarr:db.history.import` - Real download/import events from Radarr database
+- `radarr:db.history.grab` - Fallback to grab events if no import events exist
+- **Skip if**: First event is rename (indicates upgrades, not original import)
 
-### 3. **Theatrical Release** (cinema)
-- Original movie theater release
-- **TMDB Source**: Release type 3
-- **Most Authoritative**: Always used when no digital/physical exists
+**2. TMDB Release Dates** *(When import unavailable/unreliable)*
+- `tmdb:premiere` - Type 1: World premieres, film festivals  
+- `tmdb:limited` - Type 2: Limited theatrical releases
+- `tmdb:theatrical` - Type 3: Wide theatrical releases
+- `tmdb:digital` - Type 4: Digital/streaming releases (Netflix, iTunes, etc.)
+- `tmdb:physical` - Type 5: Physical media (DVD, Blu-ray)
+- `tmdb:tv` - Type 6: TV broadcasts, TV movie premieres
+- **Priority Order**: Uses `RELEASE_DATE_PRIORITY=digital,physical,theatrical`
+
+**3. Radarr NFO Premiered Date** *(Radarr's own research)*
+- `radarr:nfo.premiered` - Extracts `<premiered>YYYY-MM-DD</premiered>` from existing movie.nfo
+- **Source**: Radarr's metadata providers (TMDB, IMDb, etc.)
+
+**4. File Modification Time** *(Last Resort)*
+- `file:mtime` - Earliest video file modification time in directory
+- **Only if**: `ALLOW_FILE_DATE_FALLBACK=true`
+
+### Movie Priority: `digital_then_import`
+
+Same hierarchy, but **TMDB Release Dates** are tried **before** Radarr Import History.
 
 ## 🧠 Smart Date Validation
 

VERSION

@@ -1 +1 @@
-0.2.20
+0.2.21