update readme

README.md

@@ -109,6 +109,10 @@ RELEASE_DATE_PRIORITY=digital,physical,theatrical
 PREFER_RELEASE_DATES_OVER_FILE_DATES=true
 ALLOW_FILE_DATE_FALLBACK=false
 
+# Smart date validation: prefer theatrical over unreasonably late dates
+ENABLE_SMART_DATE_VALIDATION=true
+MAX_RELEASE_DATE_GAP_YEARS=10
+
 # Database connection
 RADARR_DB_HOST=radarr-postgres
 RADARR_DB_PORT=5432
@@ -251,6 +255,36 @@ NFOGuard uses a **smart fallback system** when Radarr has no valid import histor
 - **TMDB Source**: Release type 3
 - **Most Authoritative**: Always used when no digital/physical exists
 
+## 🧠 Smart Date Validation
+
+**NEW**: Automatically detects unreasonable date gaps and chooses the most logical release date.
+
+### How It Works
+- **Compares release dates**: Checks if digital/physical releases are unreasonably far from theatrical
+- **Automatic fallback**: If gap exceeds threshold, prefers theatrical date instead
+- **Configurable threshold**: `MAX_RELEASE_DATE_GAP_YEARS=10` (default: 10 years)
+
+### Real Example: "The Craft (1996)"
+```bash
+# Without smart validation:
+Physical Release: 2022-05-17 (26 years after theatrical!)
+Selected: 2022 ❌
+
+# With smart validation:
+Theatrical: 1996-05-03
+Physical: 2022-05-17 (26 year gap > 10 year limit)
+Selected: 1996 theatrical ✅ (smart fallback)
+```
+
+**Configuration**:
+```bash
+# Enable/disable smart validation
+ENABLE_SMART_DATE_VALIDATION=true
+
+# Maximum reasonable gap in years
+MAX_RELEASE_DATE_GAP_YEARS=10
+```
+
 ### Configuration Examples
 
 **For "The Craft (1996)"** (predates digital):