docs: Add comprehensive customization documentation

- Added README-CUSTOMIZATIONS.md with full project overview
- Added CUSTOM: comments to all profile files documenting intentional changes
- Created update scripts for both bash and PowerShell workflows
- Documented UHD Bluray priority, IMAX Enhanced scoring, Special Edition penalties
- Standardized workflow with proper upstream/origin remote configuration

This ensures customizations are preserved during future upstream merges.

README-CUSTOMIZATIONS.md

@@ -0,0 +1,61 @@
+# St-sha's Profilarr HTB Customizations
+
+This is my private fork of the [Dictionarry-Hub Profilarr HTB Database](https://github.com/Dictionarry-Hub/database) with personal customizations for my media setup.
+
+## 🎯 Customization Philosophy
+
+- **Physical Media Priority**: UHD Bluray and Remux formats are strongly preferred
+- **Quality Over Size**: Transparent encodes and lossless audio prioritized
+- **IMAX Enhanced**: Special scoring for IMAX Enhanced releases
+- **Theatrical Preference**: Special Edition penalty in theatrical variant
+- **Streaming Service Optimization**: Enhanced scoring for premium services (MA, ATVP, DSNP)
+
+## 📁 Key Customized Profiles
+
+### 2160p Quality
+- **UHD Bluray Priority**: Score 280,000 (matches Quality Tier 5 but comes first)
+- **Physical > Digital**: Clear hierarchy favoring physical media
+- **Quality Tier Integration**: Incorporates upstream quality tiers while preserving priorities
+
+### 2160p Remux Variants
+- **2160p Remux**: Base remux profile with neutral Special Edition handling
+- **2160p Remux (Prefer Theatrical)**: Special Edition penalty (-40,000), IMAX Enhanced boost (+40,000)
+- **2160p Remux Only**: Restricts to remux qualities only
+
+## 🔄 Update Workflow
+
+```bash
+# Pull latest from upstream
+git fetch upstream
+git pull upstream stable
+
+# Resolve any conflicts while preserving customizations
+# (See inline comments in profile files for guidance)
+
+# Push to personal repo
+git push origin stable
+```
+
+## 🏷️ Customization Markers
+
+Look for `# CUSTOM:` comments in profile files to identify intentional changes that should be preserved during updates.
+
+## 📊 Scoring Philosophy
+
+- **280,000+**: UHD Bluray and highest quality tiers
+- **250,000+**: 2160p physical media
+- **200,000+**: 1080p physical media  
+- **140,000+**: High-quality web sources
+- **40,000+**: IMAX Enhanced (theatrical variant)
+- **1,000-10,000**: Streaming services and audio/video enhancements
+- **-40,000**: Special Edition penalty (theatrical variant)
+- **-220,000**: x265 Bluray penalty
+- **-999,999**: Banned content
+
+## 🔧 Last Updated
+- **Repository**: October 21, 2025
+- **Upstream Sync**: October 21, 2025
+- **Profiles Documented**: 4/4 (2160p variants)
+
+---
+*Private repository for personal use - based on Dictionarry-Hub's excellent work*

profiles/2160p Quality.yml

@@ -1,8 +1,9 @@
 custom_formats:
+# CUSTOM: UHD Bluray prioritized at front of list to ensure physical media preference
 - name: UHD Bluray
-  score: 280000
+  score: 280000  # CUSTOM: Matches Quality Tier 5 score but positioned first for priority
 - name: UHD Bluray (Missing)
-  score: 280000
+  score: 280000  # CUSTOM: Companion to UHD Bluray for missing metadata cases
 - name: 2160p Quality Tier 1
   score: 284000
 - name: 2160p Quality Tier 2
@@ -188,12 +189,13 @@ custom_formats:
 - name: x264 (2160p)
   score: -999999
 custom_formats_radarr:
+# CUSTOM: Enhanced streaming service scoring for premium providers
 - name: MA
-  score: 6000
+  score: 6000  # CUSTOM: Movies Anywhere premium scoring
 - name: ATVP
-  score: 4000
+  score: 4000  # CUSTOM: Apple TV+ high priority
 - name: DSNP
-  score: 4000
+  score: 4000  # CUSTOM: Disney+ high priority
 - name: iT
   score: 4000
 - name: Amazon Enhancement

profiles/2160p Remux (Prefer Theatrical).yml

@@ -1,5 +1,5 @@
 name: 2160p Remux (Prefer Theatrical)
-description: "Copied from 2160p Remux\n\nChanges: \n- Special Edition set to -40000"
+description: "Copied from 2160p Remux\n\nChanges: \n- Special Edition set to -40000\n- IMAX Enhanced set to +40000\n\nCUSTOM: This profile actively penalizes Special Editions to prefer theatrical releases"
 tags:
 - 2160p
 - Remux
@@ -184,8 +184,9 @@ custom_formats:
 - name: x264 (2160p)
   score: -999999
 custom_formats_radarr:
+# CUSTOM: Theatrical preference scoring - heavily favor IMAX, penalize Special Editions
 - name: IMAX Enhanced
-  score: 40000
+  score: 40000  # CUSTOM: Strong preference for IMAX Enhanced releases
 - name: MA
   score: 5000
 - name: iT
@@ -195,7 +196,7 @@ custom_formats_radarr:
 - name: CRIT
   score: 1000
 - name: Special Edition
-  score: -40000
+  score: -40000  # CUSTOM: Heavy penalty to prefer theatrical releases
 - name: 3D
   score: -999999
 - name: B&W

profiles/2160p Remux Only.yml

@@ -1,6 +1,5 @@
 name: 2160p Remux Only
-description: "Copied from 2160p Remux\n\nChanges: \n- Only allow 2160p and 1080p Remux\
+description: "Copied from 2160p Remux\n\nChanges: \n- Only allow 2160p and 1080p Remux qualities\n\nCUSTOM: This profile restricts downloads to lossless remux formats only"
-  \ qualities"
 tags:
 - 2160p
 - Remux
@@ -199,8 +198,9 @@ custom_formats:
 - name: x264 (2160p)
   score: -999999
 custom_formats_radarr:
+# CUSTOM: IMAX Enhanced preference maintained in remux-only profile
 - name: IMAX Enhanced
-  score: 40000
+  score: 40000  # CUSTOM: Preserve IMAX preference even in remux-only mode
 - name: MA
   score: 5000
 - name: iT
@@ -229,10 +229,11 @@ custom_formats_sonarr:
 - name: TV Extras
   score: -999999
 qualities:
+# CUSTOM: Restricted quality list - only remux formats allowed
 - id: 3
-  name: Remux-2160p
+  name: Remux-2160p  # CUSTOM: Primary target quality
 - id: 8
-  name: Remux-1080p
+  name: Remux-1080p  # CUSTOM: Fallback remux quality
 upgrade_until:
   id: 3
   name: Remux-2160p

update-from-upstream.ps1

@@ -0,0 +1,30 @@
+# update-from-upstream.ps1
+# PowerShell script to update from upstream while preserving customizations
+
+Write-Host "🔄 Updating from upstream Dictionarry-Hub database..." -ForegroundColor Cyan
+
+# Fetch latest changes
+git fetch upstream
+
+# Show what's new
+Write-Host "📋 New commits from upstream:" -ForegroundColor Yellow
+git log --oneline HEAD..upstream/stable
+
+# Pull and merge
+Write-Host "🔀 Merging upstream changes..." -ForegroundColor Green
+git pull upstream stable
+
+# Check for conflicts
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "⚠️  Conflicts detected!" -ForegroundColor Red
+    Write-Host "👀 Check files with CUSTOM: comments to preserve your changes" -ForegroundColor Yellow
+    Write-Host "📝 Resolve conflicts and run: git commit" -ForegroundColor Yellow
+    exit 1
+}
+
+# Push to your repo
+Write-Host "⬆️  Pushing to your repository..." -ForegroundColor Blue
+git push origin stable
+
+Write-Host "✅ Update complete!" -ForegroundColor Green
+Write-Host "🔍 Review changes and test your profiles" -ForegroundColor Cyan

update-from-upstream.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# update-from-upstream.sh
+# Simple script to update from upstream while preserving customizations
+
+echo "🔄 Updating from upstream Dictionarry-Hub database..."
+
+# Fetch latest changes
+git fetch upstream
+
+# Show what's new
+echo "📋 New commits from upstream:"
+git log --oneline HEAD..upstream/stable
+
+# Pull and merge
+echo "🔀 Merging upstream changes..."
+git pull upstream stable
+
+# Check for conflicts
+if [ $? -ne 0 ]; then
+    echo "⚠️  Conflicts detected!"
+    echo "👀 Check files with CUSTOM: comments to preserve your changes"
+    echo "📝 Resolve conflicts and run: git commit"
+    exit 1
+fi
+
+# Push to your repo
+echo "⬆️  Pushing to your repository..."
+git push origin stable
+
+echo "✅ Update complete!"
+echo "🔍 Review changes and test your profiles"