docs: consolidate env var documentation into unified reference table (#66)

Replaces 8+ scattered subsections in README with a single comprehensive
environment variables table grouped by category (Telegram Credentials,
Backup, Chat Filtering, Real-time Listener, Database, Viewer, Security,
Notifications). Each variable shows its default, scope (B/V/B+V), and
description.

Key improvements:
- Document previously undocumented CORS_ORIGINS, SECURE_COOKIES, and
  MASS_OPERATION_BUFFER_DELAY environment variables
- Explain that ENABLE_LISTENER is a master switch controlling all
  LISTEN_* and MASS_OPERATION_* variables
- Add Scope column (B=backup, V=viewer, B/V=both) to clarify which
  service each variable applies to
- Update docker-compose.yml with all missing env vars for both backup
  (listener sub-settings, mass operation, deduplicate) and viewer
  (AUTH_SESSION_DAYS, SHOW_STATS, CORS_ORIGINS, SECURE_COOKIES,
  notifications) services
- Rewrite .env.example with complete variable coverage including viewer,
  security, listener, and notification sections
- Fix duplicate BATCH_SIZE comment in .env.example
- Keep explanatory prose for chat filtering, listener, mass operation
  protection, and database config without duplicating the env var tables

Author: GeiserX

.env.example

@@ -1,14 +1,27 @@
-# Required Telegram API credentials
+# ==============================================================================
+# Telegram Archive — Environment Variables
+# ==============================================================================
+# Copy this file to .env and fill in your values:
+#   cp .env.example .env
+#
+# For the full reference table, see the README:
+#   https://github.com/GeiserX/Telegram-Archive#environment-variables
+# ==============================================================================
+
+# ==============================================================================
+# TELEGRAM CREDENTIALS (required for backup)
+# ==============================================================================
 # Get these from https://my.telegram.org/apps
 TELEGRAM_API_ID=your_api_id_here
 TELEGRAM_API_HASH=your_api_hash_here
 TELEGRAM_PHONE=+1234567890
 
-# Backup schedule (cron format: minute hour day month weekday)
-# Examples:
-#   0 */6 * * *    = Every 6 hours
-#   0 0 * * *      = Daily at midnight
-#   0 */1 * * *    = Every hour
+# ==============================================================================
+# BACKUP SCHEDULE & STORAGE
+# ==============================================================================
+
+# Cron schedule (minute hour day month weekday)
+# Examples: 0 */6 * * * (every 6h), 0 0 * * * (daily), 0 */1 * * * (hourly)
 SCHEDULE=0 */6 * * *
 
 # Backup destination path (inside container)
@@ -22,116 +35,94 @@ DOWNLOAD_MEDIA=true
 # Files larger than this will be skipped
 MAX_MEDIA_SIZE_MB=4096
 
-# Batch size for database insertions and progress logging
-# Higher values = faster but more memory usage
-# Default: 100
-# Batch size for database insertions and progress logging
+# Messages processed per database batch
 # Higher values = faster but more memory usage
-# Default: 100
 BATCH_SIZE=100
 
-# Sync deletions and edits (Optional)
-# Set to true to mirror deletions and edits from Telegram
-# WARNING: This is expensive and slow as it checks every message
-# Default: false
-SYNC_DELETIONS_EDITS=false
+# Use symlinks to deduplicate identical media files across chats
+# DEDUPLICATE_MEDIA=true
 
-# Media verification mode (Optional)
-# When enabled, checks all media files on disk after each backup
-# Re-downloads any missing or corrupted files from Telegram
-# Useful for recovering from interrupted backups or accidentally deleted media
-# Default: false
-VERIFY_MEDIA=false
+# Comma-separated chat IDs to process FIRST in all operations
+# PRIORITY_CHAT_IDS=
+
+# Hour (0-23) to recalculate backup statistics daily
+# STATS_CALCULATION_HOUR=3
+
+# Logging level: DEBUG, INFO, WARNING, ERROR
+LOG_LEVEL=INFO
+
+# Session name (use different names for multiple accounts)
+SESSION_NAME=telegram_backup
+
+# Session directory (defaults to /data/session)
+# SESSION_DIR=/data/session
 
 # ==============================================================================
-# CHAT FILTERING - Choose ONE mode
+# CHAT FILTERING — Choose ONE mode
 # ==============================================================================
 
-# -----------------------------------------------------------------------------
-# MODE 1: WHITELIST (Simple) - Set CHAT_IDS to backup ONLY specific chats
-# -----------------------------------------------------------------------------
-# When set, ONLY these chats are backed up. All other settings are ignored.
+# MODE 1: WHITELIST (Simple) — Set CHAT_IDS to backup ONLY specific chats
+# When set, ONLY these chats are backed up. All other filtering is ignored.
 # Example: CHAT_IDS=-1001234567890,-1009876543210
 CHAT_IDS=
 
-# -----------------------------------------------------------------------------
-# MODE 2: TYPE-BASED (Default) - Use CHAT_TYPES to backup by type
-# -----------------------------------------------------------------------------
+# MODE 2: TYPE-BASED (Default) — Use CHAT_TYPES to backup by type
 # Options: private, groups, channels (comma-separated)
-# Example: CHAT_TYPES=private,groups (everything except channels)
 CHAT_TYPES=private,groups,channels
 
-# EXCLUDE specific chats (blacklist - takes priority)
+# EXCLUDE specific chats (blacklist — takes priority)
 GLOBAL_EXCLUDE_CHAT_IDS=
 PRIVATE_EXCLUDE_CHAT_IDS=
 GROUPS_EXCLUDE_CHAT_IDS=
 CHANNELS_EXCLUDE_CHAT_IDS=
 
-# INCLUDE additional chats (additive - adds to what CHAT_TYPES already includes)
+# INCLUDE additional chats (additive — adds to what CHAT_TYPES selects)
 # Note: These ADD to the selection, they don't restrict it.
 # For exclusive selection, use CHAT_IDS mode instead.
 GLOBAL_INCLUDE_CHAT_IDS=
 PRIVATE_INCLUDE_CHAT_IDS=
 GROUPS_INCLUDE_CHAT_IDS=
 CHANNELS_INCLUDE_CHAT_IDS=
 
-# Examples:
-# 1. Backup ONLY these 2 channels (nothing else):
-#    CHAT_IDS=-1001234567890,-1009876543210
-#
-# 2. Backup all groups except one:
-#    CHAT_TYPES=groups
-#    GROUPS_EXCLUDE_CHAT_IDS=-123456789
-#
-# 3. Backup all groups PLUS one specific channel:
-#    CHAT_TYPES=groups
-#    CHANNELS_INCLUDE_CHAT_IDS=-1001234567890
+# ==============================================================================
+# REAL-TIME LISTENER
+# ==============================================================================
+# ENABLE_LISTENER is the master switch. When false (default), all LISTEN_*
+# and MASS_OPERATION_* variables below have no effect.
 
+ENABLE_LISTENER=false
 
-# Logging level
-# Options: DEBUG, INFO, WARNING, ERROR
-LOG_LEVEL=INFO
+# Granular listener controls (only apply when ENABLE_LISTENER=true):
+# LISTEN_EDITS=true
+# LISTEN_DELETIONS=true
+# LISTEN_NEW_MESSAGES=true
+# LISTEN_NEW_MESSAGES_MEDIA=false
+# LISTEN_CHAT_ACTIONS=true
 
-# Session name (for multiple accounts, use different names)
-SESSION_NAME=telegram_backup
+# Mass operation protection (only applies when ENABLE_LISTENER=true)
+# MASS_OPERATION_THRESHOLD=10
+# MASS_OPERATION_WINDOW_SECONDS=30
+# MASS_OPERATION_BUFFER_DELAY=2.0
 
-# Session directory (defaults to /data/session)
-# The session file is stored separately from backup data for better organization
-# SESSION_DIR=/data/session
+# Batch sync alternative (expensive — prefer ENABLE_LISTENER instead)
+SYNC_DELETIONS_EDITS=false
 
-# Database directory (optional)
-# Store the SQLite database in a separate location (e.g., on SSD)
-# Default: same as BACKUP_PATH
-# DATABASE_DIR=/data/database
+# Re-download missing or corrupted media files
+VERIFY_MEDIA=false
 
-# ================================
-# Display Chat IDs (Viewer Restriction)
-# ================================
-# Restrict the web viewer to show only specific chats
-# Useful for sharing public channel viewers without exposing other chats
-# Comma-separated list of chat IDs (e.g., 224091347,-100123456789)
-# DISPLAY_CHAT_IDS=
+# ==============================================================================
+# DATABASE CONFIGURATION (v3.0+)
+# ==============================================================================
+# Supports SQLite (default) and PostgreSQL.
+# Both backup and viewer containers MUST use the same database settings.
 
-# ================================
-# Database Configuration (v3.0+)
-# ================================
-# Telegram Archive supports multiple database backends:
-# - SQLite (default): Simple, no setup required
-# - PostgreSQL: Better for high-traffic deployments
-
-# Option 1: Use DATABASE_URL (takes priority)
-# SQLite example:
-# DATABASE_URL=sqlite:///data/telegram_backup.db
-# PostgreSQL example:
-# DATABASE_URL=postgresql://user:password@localhost:5432/telegram_backup
-
-# Option 2: Use individual settings (v2 DATABASE_PATH/DATABASE_DIR also supported)
-# DB_TYPE: sqlite (default) or postgresql
-DB_TYPE=sqlite
+# Option 1: Full DATABASE_URL (takes priority over all below)
+# SQLite:     DATABASE_URL=sqlite:///data/telegram_backup.db
+# PostgreSQL: DATABASE_URL=postgresql://user:password@localhost:5432/telegram_backup
 
-# SQLite settings (when DB_TYPE=sqlite)
-# DB_PATH: Path to SQLite database file
-DB_PATH=data/telegram_backup.db
+# Option 2: Individual settings
+DB_TYPE=sqlite
+DB_PATH=/data/backups/telegram_backup.db
 
 # PostgreSQL settings (when DB_TYPE=postgresql)
 # POSTGRES_HOST=localhost
@@ -140,5 +131,48 @@ DB_PATH=data/telegram_backup.db
 # POSTGRES_PASSWORD=your_secure_password
 # POSTGRES_DB=telegram_backup
 
-# Enable SQL query logging (for debugging)
-# DB_ECHO=false
+# ==============================================================================
+# VIEWER & AUTHENTICATION
+# ==============================================================================
+# These apply to the telegram-archive-viewer container.
+
+# Basic auth — set BOTH to enable authentication (recommended)
+# VIEWER_USERNAME=admin
+# VIEWER_PASSWORD=your_secure_password
+# AUTH_SESSION_DAYS=30
+
+# Timezone for displayed timestamps (tz database name)
+# VIEWER_TIMEZONE=Europe/Madrid
+
+# Show backup statistics dropdown in viewer header
+# SHOW_STATS=true
+
+# Restrict viewer to specific chats (comma-separated IDs)
+# Useful for sharing public channel viewers without exposing other chats
+# DISPLAY_CHAT_IDS=
+
+# ==============================================================================
+# SECURITY
+# ==============================================================================
+
+# Allowed CORS origins (comma-separated)
+# Default: * (allow all origins, credentials auto-disabled)
+# Example: CORS_ORIGINS=https://my.domain.com,https://other.domain.com
+# CORS_ORIGINS=*
+
+# Set Secure flag on auth cookies
+# Disable (false) only when developing locally over HTTP
+# SECURE_COOKIES=true
+
+# ==============================================================================
+# NOTIFICATIONS
+# ==============================================================================
+
+# Push notification mode: off, basic (in-browser only), full (Web Push)
+# PUSH_NOTIFICATIONS=basic
+
+# Custom VAPID keys for Web Push (auto-generated if empty)
+# Generate with: npx web-push generate-vapid-keys
+# VAPID_PRIVATE_KEY=
+# VAPID_PUBLIC_KEY=
+# VAPID_CONTACT=mailto:admin@example.com