From 192f59e80cfb46fa7c049157d75576e89a41c8f0 Mon Sep 17 00:00:00 2001
From: SBCrumb <sbcrumb@kickthetree.com>
Date: Wed, 10 Sep 2025 10:07:23 -0400
Subject: [PATCH] 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 | 41 +++++++++++++++++++++++++++--------------
 VERSION   |  2 +-
 2 files changed, 28 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 0aef521..7ccb929 100644
--- a/README.md
+++ b/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
 
diff --git a/VERSION b/VERSION
index 3bfb9a4..599028f 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.2.20
+0.2.21