chore: bump version

- test_add_anime_nfo_content.py: verify required NFO tags after anime add
- test_sacrificial_princess_nfo.py: test full NFO generation and repair path

.gitignore

@@ -4,6 +4,7 @@
 /src/__pycache__/*
 /src/__pycache__/
 /.vs/*
+/.venv/*
 /src/Temp/*
 /src/Loaders/__pycache__/*
 /src/Loaders/provider/__pycache__/*
@@ -81,4 +82,5 @@ Temp/
 temp/
 tmp/
 *.tmp
-.coverage
+.coverage
+.venv/bin/dotenv

.vscode/settings.json

@@ -1,8 +1,11 @@
 {
-    "python.defaultInterpreterPath": "C:\\Users\\lukas\\anaconda3\\envs\\AniWorld\\python.exe",
+    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
     "python.terminal.activateEnvironment": true,
-    "python.condaPath": "C:\\Users\\lukas\\anaconda3\\Scripts\\conda.exe",
     "python.terminal.activateEnvInCurrentTerminal": true,
+    "terminal.integrated.env.linux": {
+        "VIRTUAL_ENV": "${workspaceFolder}/.venv",
+        "PATH": "${workspaceFolder}/.venv/bin:${env:PATH}"
+    },
     "python.linting.enabled": true,
     "python.linting.flake8Enabled": true,
     "python.linting.pylintEnabled": true,

Docker/Containerfile

@@ -13,7 +13,8 @@ RUN apk add --no-cache \
 # Create wireguard config directory (config is mounted at runtime)
 RUN mkdir -p /etc/wireguard
 
-# Copy entrypoint
+# Copy version file and entrypoint
+COPY VERSION /etc/wireguard/VERSION
 COPY entrypoint.sh /entrypoint.sh
 RUN chmod +x /entrypoint.sh
 

Docker/VERSION

@@ -0,0 +1 @@
+v1.1.7

Docker/entrypoint.sh

@@ -1,6 +1,14 @@
 #!/bin/bash
 set -e
 
+VERSION_FILE="/etc/wireguard/VERSION"
+if [ -f "$VERSION_FILE" ]; then
+    VERSION=$(cat "$VERSION_FILE")
+else
+    VERSION="unknown"
+fi
+echo "[init] VPN Container Entrypoint ${VERSION}"
+
 INTERFACE="wg0"
 MOUNT_CONFIG="/etc/wireguard/${INTERFACE}.conf"
 CONFIG_DIR="/run/wireguard"
@@ -64,9 +72,11 @@ setup_killswitch() {
     iptables -A INPUT  -i "$INTERFACE" -j ACCEPT
     iptables -A OUTPUT -o "$INTERFACE" -j ACCEPT
 
-    # Allow DNS to the VPN DNS server (through wg0)
-    iptables -A OUTPUT -o "$INTERFACE" -p udp --dport 53 -j ACCEPT
-    iptables -A OUTPUT -o "$INTERFACE" -p tcp --dport 53 -j ACCEPT
+    # Allow DNS (VPN DNS servers are routed through wg0; allow before routing decision)
+    iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
+    iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT
+    iptables -A INPUT  -p udp --sport 53 -j ACCEPT
+    iptables -A INPUT  -p tcp --sport 53 -j ACCEPT
 
     # Allow DHCP (for container networking)
     iptables -A OUTPUT -p udp --dport 67:68 -j ACCEPT
@@ -120,27 +130,46 @@ start_vpn() {
     ip link add "$INTERFACE" type wireguard
 
     # Apply the WireGuard config (keys, peer, endpoint)
+    # Filter out wg-quick directives that wg setconf doesn't understand
     wg setconf "$INTERFACE" <(grep -v -i '^\(Address\|DNS\|MTU\|Table\|PreUp\|PostUp\|PreDown\|PostDown\|SaveConfig\)' "$CONFIG_FILE")
 
+    # Log public key so it can be verified against the server's peer list
+    local PUBKEY
+    PUBKEY=$(wg show "$INTERFACE" public-key 2>/dev/null || echo "unknown")
+    echo "[vpn] Public key: ${PUBKEY}"
+
     # Assign the address
     ip -4 address add "$VPN_ADDRESS" dev "$INTERFACE"
 
-    # Set MTU
+    # Set MTU and bring up
     ip link set mtu 1420 up dev "$INTERFACE"
 
-    # Find default gateway/interface for the endpoint route
+    # ── fwmark-based routing (mirrors wg-quick behavior) ──
+    # WireGuard marks its own encapsulated UDP packets with this fwmark.
+    # Policy rules then ensure:
+    #   - Normal packets (no mark) → VPN routing table → wg0
+    #   - WireGuard-encapsulated packets (marked) → main table → eth0
+    local FW_MARK=51820
+    local FW_TABLE=51820
+    wg set "$INTERFACE" fwmark "$FW_MARK"
+
+    # Remove any auto-created default route on wg0
+    ip route del default dev "$INTERFACE" 2>/dev/null || true
+
+    # VPN routing table: send everything through the tunnel
+    ip -4 route add default dev "$INTERFACE" table "$FW_TABLE"
+
+    # Policy rules:
+    # 1. Packets NOT marked by WireGuard use the VPN table (→ wg0)
+    # 2. suppress_prefixlength 0: ignore bare default routes in main table,
+    #    but keep more-specific routes (e.g. LAN, endpoint) working
+    ip -4 rule add not fwmark "$FW_MARK" table "$FW_TABLE"
+    ip -4 rule add table main suppress_prefixlength 0
+
+    # Find default gateway/interface
     DEFAULT_GW=$(ip route | grep '^default' | head -1 | awk '{print $3}')
     DEFAULT_IF=$(ip route | grep '^default' | head -1 | awk '{print $5}')
 
-    # Route VPN endpoint through the container's default gateway
-    if [ -n "$DEFAULT_GW" ] && [ -n "$DEFAULT_IF" ]; then
-        ip route add "$VPN_ENDPOINT/32" via "$DEFAULT_GW" dev "$DEFAULT_IF" 2>/dev/null || true
-    fi
-
-    # Route all traffic through the WireGuard tunnel
-    ip route add 0.0.0.0/1 dev "$INTERFACE"
-    ip route add 128.0.0.0/1 dev "$INTERFACE"
-
     # ── Policy routing: ensure responses to incoming LAN traffic go back via eth0 ──
     if [ -n "$DEFAULT_GW" ] && [ -n "$DEFAULT_IF" ]; then
         # Get the container's eth0 IP address (BusyBox-compatible, no grep -P)
@@ -155,14 +184,26 @@ start_vpn() {
         fi
     fi
 
-    # Set up DNS
+    # Set up DNS (handle comma-separated DNS servers)
     VPN_DNS=$(grep -i '^DNS' "$CONFIG_FILE" | head -1 | sed 's/.*= *//;s/ //g')
     if [ -n "$VPN_DNS" ]; then
-        echo "nameserver $VPN_DNS" > /etc/resolv.conf
-        echo "[vpn] DNS set to ${VPN_DNS}"
+        # Clear resolv.conf and add each DNS server on its own line
+        > /etc/resolv.conf
+        for dns in $(echo "$VPN_DNS" | tr ',' ' '); do
+            echo "nameserver $dns" >> /etc/resolv.conf
+        done
+        echo "[vpn] DNS set to: ${VPN_DNS}"
     fi
 
     echo "[vpn] WireGuard interface ${INTERFACE} is up."
+    echo "[vpn] Main routes:"
+    ip route show | sed 's/^/[vpn]   /'
+    echo "[vpn] VPN table ($FW_TABLE):"
+    ip route show table "$FW_TABLE" 2>/dev/null | sed 's/^/[vpn]   /'
+    echo "[vpn] Policy rules:"
+    ip rule show | sed 's/^/[vpn]   /'
+    echo "[vpn] WireGuard status:"
+    wg show "$INTERFACE" 2>/dev/null | sed 's/^/[vpn]   /'
 }
 
 # ──────────────────────────────────────────────
@@ -170,6 +211,21 @@ start_vpn() {
 # ──────────────────────────────────────────────
 stop_vpn() {
     echo "[vpn] Stopping WireGuard interface ${INTERFACE}..."
+
+    local FW_MARK=51820
+    local FW_TABLE=51820
+
+    # Remove fwmark-based policy rules
+    ip -4 rule del not fwmark "$FW_MARK" table "$FW_TABLE" 2>/dev/null || true
+    ip -4 rule del table main suppress_prefixlength 0 2>/dev/null || true
+
+    # Flush VPN routing table
+    ip -4 route flush table "$FW_TABLE" 2>/dev/null || true
+
+    # Remove LAN policy routing
+    ip -4 rule del table 100 2>/dev/null || true
+    ip -4 route flush table 100 2>/dev/null || true
+
     ip link del "$INTERFACE" 2>/dev/null || true
 }
 
@@ -185,14 +241,19 @@ health_loop() {
     while true; do
         sleep "$CHECK_INTERVAL"
 
-        if curl -sf --max-time 5 "http://$CHECK_HOST" > /dev/null 2>&1; then
+        if ping -c 1 -W 5 "$CHECK_HOST" > /dev/null 2>&1; then
             if [ "$failures" -gt 0 ]; then
                 echo "[health] VPN recovered."
                 failures=0
             fi
         else
             failures=$((failures + 1))
-            echo "[health] Ping failed ($failures/$max_failures)"
+            echo "[health] Check failed ($failures/$max_failures) — ping ${CHECK_HOST} failed"
+            # Dump WireGuard stats to show if handshake is stale and how much data flows
+            echo "[health] wg stats:"
+            wg show "$INTERFACE" 2>/dev/null | grep -E 'latest handshake|transfer|endpoint' | sed 's/^/[health]   /' || echo "[health]   wg0 not found"
+            echo "[health] routes:"
+            ip route show | grep -E 'wg0|default' | sed 's/^/[health]   /'
 
             if [ "$failures" -ge "$max_failures" ]; then
                 echo "[health] VPN appears down. Restarting WireGuard..."
@@ -221,8 +282,81 @@ cleanup() {
 
 trap cleanup SIGTERM SIGINT
 
+# ──────────────────────────────────────────────
+# Startup connectivity checks — diagnose issues early
+# ──────────────────────────────────────────────
+check_vpn_connectivity() {
+    echo "[check] ── Startup connectivity checks ──"
+
+    # 1. Wait for WireGuard handshake (up to 15s)
+    local elapsed=0
+    local handshake_ts=0
+    echo "[check] Waiting for WireGuard handshake (up to 15s)..."
+    while [ "$elapsed" -lt 15 ]; do
+        handshake_ts=$(wg show "$INTERFACE" latest-handshakes 2>/dev/null | awk '{print $2}' | head -1)
+        if [ -n "$handshake_ts" ] && [ "$handshake_ts" != "0" ]; then
+            local age=$(( $(date +%s) - handshake_ts ))
+            echo "[check] OK   Handshake established ${age}s ago"
+            break
+        fi
+        sleep 1
+        elapsed=$((elapsed + 1))
+    done
+    if [ "$elapsed" -ge 15 ]; then
+        echo "[check] FAIL No WireGuard handshake after 15s — tunnel is not up"
+        echo "[check]      This container's public key (must be on the server):"
+        echo "[check]        PublicKey  = $(wg show "$INTERFACE" public-key 2>/dev/null || echo 'unknown')"
+        echo "[check]        AllowedIPs = ${VPN_ADDRESS}"
+        echo "[check]      Verify on server: wg show"
+    fi
+
+    # 2. Check whether traffic actually flows through the tunnel
+    echo "[check] Testing traffic through tunnel (ping ${CHECK_HOST})..."
+    local rx_before
+    rx_before=$(wg show "$INTERFACE" transfer 2>/dev/null | awk '{print $2}' | head -1)
+
+    if ping -c 1 -W 8 "${CHECK_HOST}" > /dev/null 2>&1; then
+        echo "[check] OK   Traffic flows — tunnel is fully working"
+    else
+        local rx_after
+        rx_after=$(wg show "$INTERFACE" transfer 2>/dev/null | awk '{print $2}' | head -1)
+        echo "[check] FAIL ping ${CHECK_HOST} unreachable through tunnel"
+
+        if [ -n "$rx_before" ] && [ -n "$rx_after" ]; then
+            if [ "$rx_after" -le "$rx_before" ]; then
+                echo "[check]      RX bytes unchanged (${rx_before} → ${rx_after})"
+                echo "[check]      Server receives packets but does NOT route them back"
+                echo "[check]      Fix on VPN server (${VPN_ENDPOINT}):"
+                echo "[check]        sysctl net.ipv4.ip_forward              # must output 1"
+                echo "[check]        iptables -t nat -L POSTROUTING -v -n    # must have MASQUERADE"
+                echo "[check]        wg show                                  # check peer + AllowedIPs"
+            else
+                echo "[check]      RX increased (${rx_before} → ${rx_after}) — tunnel passes data"
+                echo "[check]      Issue may be specific to ${CHECK_HOST} or DNS"
+            fi
+        fi
+
+        local transfer
+        transfer=$(wg show "$INTERFACE" transfer 2>/dev/null | awk '{printf "rx=%s tx=%s", $2, $3}')
+        echo "[check]      wg transfer: ${transfer}"
+    fi
+
+    # 3. DNS check
+    echo "[check] Testing DNS resolution..."
+    if nslookup 1.1.1.1 > /dev/null 2>&1 || nslookup google.com > /dev/null 2>&1; then
+        echo "[check] OK   DNS resolves"
+    else
+        echo "[check] FAIL DNS resolution failed"
+        echo "[check]      resolv.conf: $(tr '\n' ' ' < /etc/resolv.conf)"
+        echo "[check]      Check that DNS servers are reachable through wg0"
+    fi
+
+    echo "[check] ── End of checks ──"
+}
+
 # ── Main ──
 enable_forwarding
 setup_killswitch
 start_vpn
+check_vpn_connectivity
 health_loop

Docker/nl.conf

@@ -1,17 +1,16 @@
 [Interface]
-PrivateKey = iO5spIue/6ciwUoR95hYtuxdtQxV/Q9EOoQ/jHe18kM=
-Address = 10.2.0.2/32
-DNS = 10.2.0.1
+PrivateKey = EPRa2f/v72LvIXAY4yqIRJifsSb+nCcYHqC2rwA94UI=
+Address = 100.64.244.78/32
+DNS = 198.18.0.1,198.18.0.2
 
 # Route zum VPN-Server direkt über dein lokales Netz
-PostUp = ip route add 185.183.34.149 via 192.168.178.1 dev wlp4s0f0
+PostUp = ip route add 91.148.236.64 via 192.168.178.1 dev wlp4s0f0
 PostUp = ip route add 192.168.178.0/24 via 192.168.178.1 dev wlp4s0f0
-PostDown = ip route del 185.183.34.149 via 192.168.178.1 dev wlp4s0f0
+PostDown = ip route del 91.148.236.64 via 192.168.178.1 dev wlp4s0f0
 PostDown = ip route del 192.168.178.0/24 via 192.168.178.1 dev wlp4s0f0
 
 [Peer]
-PublicKey = J4XVdtoBVc/EoI2Yk673Oes97WMnQSH5KfamZNjtM2s=
-AllowedIPs = 0.0.0.0/1, 128.0.0.0/1
-Endpoint = 185.183.34.149:51820
-
+PublicKey = KgTUh3KLijVluDvNpzDCJJfrJ7EyLzYLmdHCksG4sRg=
+AllowedIPs = 0.0.0.0/0
+Endpoint = 91.148.236.64:51820
 

Docker/podman-compose.yml

@@ -7,6 +7,7 @@ services:
     cap_add:
       - NET_ADMIN
       - SYS_MODULE
+      - NET_RAW
     sysctls:
       - net.ipv4.ip_forward=1
       - net.ipv4.conf.all.src_valid_mark=1

Docker/push.sh

@@ -1,15 +1,19 @@
 #!/usr/bin/env bash
-# filepath: /home/lukas/Volume/repo/Aniworld/Docker/push.sh
 #
-# Build and push Aniworld container images to the Gitea registry.
+# Build and push AniWorld container images to the Gitea registry.
 #
 # Usage:
-#   ./push.sh              # builds & pushes with tag "latest"
-#   ./push.sh v1.2.3       # builds & pushes with tag "v1.2.3"
-#   ./push.sh v1.2.3 --no-build   # pushes existing images only
+#   ./push.sh              # builds & pushes app with tag "latest"
+#   ./push.sh app          # builds & pushes app image
+#   ./push.sh vpn          # builds & pushes vpn image
+#   ./push.sh all          # builds & pushes both images
+#   ./push.sh app v1.2.3   # builds & pushes app with tag "v1.2.3"
+#   ./push.sh vpn v1.2.3   # builds & pushes vpn with tag "v1.2.3"
+#   ./push.sh all v1.2.3   # builds & pushes both images
+#   ./push.sh app v1.2.3 --no-build   # pushes existing image only
 #
 # Prerequisites:
-#   podman login git.lpl-mind.de
+#   podman login git.lpl-mind.de   (or: docker login git.lpl-mind.de)
 
 set -euo pipefail
 
@@ -23,12 +27,20 @@ PROJECT="aniworld"
 APP_IMAGE="${REGISTRY}/${NAMESPACE}/${PROJECT}/app"
 VPN_IMAGE="${REGISTRY}/${NAMESPACE}/${PROJECT}/vpn"
 
-TAG="${1:-latest}"
+# Parse arguments
+TARGET="${1:-app}"
+TAG="${2:-latest}"
 SKIP_BUILD=false
-if [[ "${2:-}" == "--no-build" ]]; then
+if [[ "${3:-}" == "--no-build" ]]; then
     SKIP_BUILD=true
 fi
 
+# Validate target
+if [[ "${TARGET}" != "app" && "${TARGET}" != "vpn" && "${TARGET}" != "all" ]]; then
+    echo "ERROR: Invalid target '${TARGET}'. Must be one of: app, vpn, all" >&2
+    exit 1
+fi
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 
@@ -36,62 +48,93 @@ PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 # Helpers
 # ---------------------------------------------------------------------------
 log() { echo -e "\n>>> $*"; }
-err() { echo -e "\n❌ ERROR: $*" >&2; exit 1; }
+err() { echo -e "\nERROR: $*" >&2; exit 1; }
+
+# Detect container engine (podman preferred, docker fallback)
+if command -v podman &>/dev/null; then
+    ENGINE="podman"
+elif command -v docker &>/dev/null; then
+    ENGINE="docker"
+else
+    err "Neither podman nor docker is installed."
+fi
 
 # ---------------------------------------------------------------------------
 # Pre-flight checks
 # ---------------------------------------------------------------------------
 echo "============================================"
-echo " Aniworld — Build & Push"
+echo " AniWorld — Build & Push"
+echo " Engine   : ${ENGINE}"
 echo " Registry : ${REGISTRY}"
+echo " Target   : ${TARGET}"
 echo " Tag      : ${TAG}"
 echo "============================================"
 
-command -v podman &>/dev/null || err "podman is not installed."
-
-if ! podman login --get-login "${REGISTRY}" &>/dev/null; then
-    err "Not logged in. Run:\n  podman login ${REGISTRY}"
-fi
+log "Logging in to ${REGISTRY}"
+"${ENGINE}" login "${REGISTRY}"
 
 # ---------------------------------------------------------------------------
 # Build
 # ---------------------------------------------------------------------------
-if [[ "${SKIP_BUILD}" == false ]]; then
+build_app() {
     log "Building app image  →  ${APP_IMAGE}:${TAG}"
-    podman build \
+    "${ENGINE}" build \
         -t "${APP_IMAGE}:${TAG}" \
         -f "${SCRIPT_DIR}/Dockerfile.app" \
         "${PROJECT_ROOT}"
+}
 
-    log "Building VPN image  →  ${VPN_IMAGE}:${TAG}"
-    podman build \
+build_vpn() {
+    log "Building vpn image  →  ${VPN_IMAGE}:${TAG}"
+    "${ENGINE}" build \
         -t "${VPN_IMAGE}:${TAG}" \
         -f "${SCRIPT_DIR}/Containerfile" \
         "${SCRIPT_DIR}"
+}
+
+if [[ "${SKIP_BUILD}" == false ]]; then
+    case "${TARGET}" in
+        app)  build_app ;;
+        vpn)  build_vpn ;;
+        all)  build_app; build_vpn ;;
+    esac
 fi
 
 # ---------------------------------------------------------------------------
 # Push
 # ---------------------------------------------------------------------------
-log "Pushing ${APP_IMAGE}:${TAG}"
-podman push "${APP_IMAGE}:${TAG}"
+push_app() {
+    log "Pushing ${APP_IMAGE}:${TAG}"
+    "${ENGINE}" push "${APP_IMAGE}:${TAG}"
+}
 
-log "Pushing ${VPN_IMAGE}:${TAG}"
-podman push "${VPN_IMAGE}:${TAG}"
+push_vpn() {
+    log "Pushing ${VPN_IMAGE}:${TAG}"
+    "${ENGINE}" push "${VPN_IMAGE}:${TAG}"
+}
+
+case "${TARGET}" in
+    app)  push_app ;;
+    vpn)  push_vpn ;;
+    all)  push_app; push_vpn ;;
+esac
 
 # ---------------------------------------------------------------------------
 # Summary
 # ---------------------------------------------------------------------------
 echo ""
 echo "============================================"
-echo " ✅  Push complete!"
+echo "  Push complete!"
 echo ""
 echo " Images:"
-echo "   ${APP_IMAGE}:${TAG}"
-echo "   ${VPN_IMAGE}:${TAG}"
+case "${TARGET}" in
+    app)  echo "   ${APP_IMAGE}:${TAG}" ;;
+    vpn)  echo "   ${VPN_IMAGE}:${TAG}" ;;
+    all)  echo "   ${APP_IMAGE}:${TAG}"; echo "   ${VPN_IMAGE}:${TAG}" ;;
+esac
 echo ""
 echo " Deploy on server:"
-echo "   podman login ${REGISTRY}"
-echo "   podman-compose -f podman-compose.prod.yml pull"
-echo "   podman-compose -f podman-compose.prod.yml up -d"
+echo "   ${ENGINE} login ${REGISTRY}"
+echo "   ${ENGINE} compose -f Docker/podman-compose.prod.yml pull"
+echo "   ${ENGINE} compose -f Docker/podman-compose.prod.yml up -d"
 echo "============================================"

Docker/release.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+#
+# Bump the project version and push images to the registry.
+#
+# Usage:
+#   ./release.sh
+#
+# The current version is stored in VERSION (next to this script).
+# You will be asked whether to bump major, minor, or patch.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VERSION_FILE="${SCRIPT_DIR}/VERSION"
+
+# ---------------------------------------------------------------------------
+# Read current version
+# ---------------------------------------------------------------------------
+if [[ ! -f "${VERSION_FILE}" ]]; then
+    echo "0.0.0" > "${VERSION_FILE}"
+fi
+
+CURRENT="$(cat "${VERSION_FILE}")"
+# Strip leading 'v' for arithmetic
+VERSION="${CURRENT#v}"
+
+IFS='.' read -r MAJOR MINOR PATCH <<< "${VERSION}"
+
+echo "============================================"
+echo " AniWorld — Release"
+echo " Current version: v${MAJOR}.${MINOR}.${PATCH}"
+echo "============================================"
+echo ""
+echo "Which image(s) would you like to release?"
+echo "  1) app  (Dockerfile.app)"
+echo "  2) vpn  (Containerfile)"
+echo "  3) all  (both images)"
+echo ""
+read -rp "Enter choice [1/2/3]: " TARGET_CHOICE
+
+case "${TARGET_CHOICE}" in
+    1) TARGET="app" ;;
+    2) TARGET="vpn" ;;
+    3) TARGET="all" ;;
+    *)
+        echo "Invalid choice. Aborting." >&2
+        exit 1
+        ;;
+esac
+
+echo ""
+echo "How would you like to bump the version?"
+echo "  1) patch  (v${MAJOR}.${MINOR}.${PATCH} → v${MAJOR}.${MINOR}.$((PATCH + 1)))"
+echo "  2) minor  (v${MAJOR}.${MINOR}.${PATCH} → v${MAJOR}.$((MINOR + 1)).0)"
+echo "  3) major  (v${MAJOR}.${MINOR}.${PATCH} → v$((MAJOR + 1)).0.0)"
+echo ""
+read -rp "Enter choice [1/2/3]: " CHOICE
+
+case "${CHOICE}" in
+    1) NEW_TAG="v${MAJOR}.${MINOR}.$((PATCH + 1))" ;;
+    2) NEW_TAG="v${MAJOR}.$((MINOR + 1)).0" ;;
+    3) NEW_TAG="v$((MAJOR + 1)).0.0" ;;
+    *)
+        echo "Invalid choice. Aborting." >&2
+        exit 1
+        ;;
+esac
+
+echo ""
+echo "New version: ${NEW_TAG}"
+echo "Target: ${TARGET}"
+read -rp "Confirm? [y/N]: " CONFIRM
+if [[ ! "${CONFIRM}" =~ ^[yY]$ ]]; then
+    echo "Aborted."
+    exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Write new version
+# ---------------------------------------------------------------------------
+echo "${NEW_TAG}" > "${VERSION_FILE}"
+echo "Version file updated → ${VERSION_FILE}"
+
+# Keep root package.json in sync.
+FRONT_VERSION="${NEW_TAG#v}"
+FRONT_PKG="${SCRIPT_DIR}/../package.json"
+if [[ -f "${FRONT_PKG}" ]]; then
+    sed -i "s/\"version\": \"[^\"]*\"/\"version\": \"${FRONT_VERSION}\"/" "${FRONT_PKG}"
+    echo "package.json version updated → ${FRONT_VERSION}"
+else
+    echo "Warning: package.json not found, skipping package.json version sync" >&2
+fi
+
+# Keep root pyproject.toml in sync.
+BACKEND_PYPROJECT="${SCRIPT_DIR}/../pyproject.toml"
+if [[ -f "${BACKEND_PYPROJECT}" ]]; then
+    # Update version under [project] section if present
+    if grep -q '^\[project\]' "${BACKEND_PYPROJECT}"; then
+        sed -i "/^\[project\]/,/^\[/ s/^version = \".*\"/version = \"${FRONT_VERSION}\"/" "${BACKEND_PYPROJECT}"
+    else
+        sed -i "s/^version = \".*\"/version = \"${FRONT_VERSION}\"/" "${BACKEND_PYPROJECT}"
+    fi
+    echo "pyproject.toml version updated → ${FRONT_VERSION}"
+else
+    echo "Warning: pyproject.toml not found, skipping pyproject.toml version sync" >&2
+fi
+
+# ---------------------------------------------------------------------------
+# Push containers
+# ---------------------------------------------------------------------------
+bash "${SCRIPT_DIR}/push.sh" "${TARGET}" "${NEW_TAG}"
+bash "${SCRIPT_DIR}/push.sh" "${TARGET}"
+
+
+# ---------------------------------------------------------------------------
+# Git tag (local only; push after container build)
+# ---------------------------------------------------------------------------
+cd "${SCRIPT_DIR}/.."
+git add Docker/VERSION package.json pyproject.toml
+git commit -m "chore: bump version"
+git tag -a "${NEW_TAG}" -m "Release ${NEW_TAG}"
+echo "Local git commit + tag ${NEW_TAG} created."
+
+# ---------------------------------------------------------------------------
+# Push git commits & tag
+# ---------------------------------------------------------------------------
+git push origin HEAD
+git push origin "${NEW_TAG}"
+echo "Git commit and tag ${NEW_TAG} pushed."

Docker/test_vpn.py

@@ -6,22 +6,31 @@ Verifies:
 2. The container starts and becomes healthy.
 3. The public IP inside the VPN differs from the host IP.
 4. Kill switch blocks traffic when WireGuard is down.
+5. AllowedIPs routes are set dynamically from the config.
 
 Requirements:
     - podman installed
-    - Root/sudo (NET_ADMIN capability)
+    - Root/sudo (NET_ADMIN capability) for container runtime tests
     - A valid WireGuard config at ./wg0.conf (or ./nl.conf)
 
 Usage:
+    # Build-only test (no sudo needed):
+    python3 -m pytest test_vpn.py::TestVPNImage::test_00_build_image -v
+
+    # Full integration test (requires sudo):
     sudo python3 -m pytest test_vpn.py -v
     # or
     sudo python3 test_vpn.py
 """
 
+import logging
+import os
 import subprocess
+import sys
 import time
 import unittest
-import os
+
+logger = logging.getLogger(__name__)
 
 IMAGE_NAME = "vpn-wireguard-test"
 CONTAINER_NAME = "vpn-test-container"
@@ -32,6 +41,11 @@ STARTUP_TIMEOUT = 30  # seconds to wait for VPN to come up
 HEALTH_POLL_INTERVAL = 2  # seconds between health checks
 
 
+def is_root() -> bool:
+    """Check if running as root."""
+    return os.geteuid() == 0
+
+
 def run(cmd: list[str], timeout: int = 30, check: bool = True) -> subprocess.CompletedProcess:
     """Run a command and return the result."""
     return subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, check=check)
@@ -52,6 +66,7 @@ class TestVPNImage(unittest.TestCase):
     """Test suite for the WireGuard VPN container."""
 
     host_ip: str = ""
+    container_id: str = ""
 
     @classmethod
     def setUpClass(cls):
@@ -63,23 +78,32 @@ class TestVPNImage(unittest.TestCase):
         )
 
         # ── 1. Get host public IP before VPN ──
-        print("\n[setup] Fetching host public IP...")
+        logger.info("Fetching host public IP...")
         cls.host_ip = get_host_ip()
-        print(f"[setup] Host public IP: {cls.host_ip}")
+        logger.info("Host public IP: %s", cls.host_ip)
         assert cls.host_ip, "Could not determine host public IP"
 
         # ── 2. Build the image ──
-        print(f"[setup] Building image '{IMAGE_NAME}'...")
+        logger.info("Building image '%s'...", IMAGE_NAME)
         result = run(
             ["podman", "build", "-t", IMAGE_NAME, BUILD_DIR],
             timeout=180,
         )
-        print(result.stdout[-500:] if len(result.stdout) > 500 else result.stdout)
+        logger.debug(
+            "Build output: %s",
+            result.stdout[-500:] if len(result.stdout) > 500 else result.stdout,
+        )
         assert result.returncode == 0, f"Build failed:\n{result.stderr}"
-        print("[setup] Image built successfully.")
+        logger.info("Image built successfully.")
+
+        # Skip container runtime tests if not root
+        if not is_root():
+            logger.warning("Not running as root — skipping container runtime tests.")
+            cls.container_id = ""
+            return
 
         # ── 3. Start the container ──
-        print(f"[setup] Starting container '{CONTAINER_NAME}'...")
+        logger.info("Starting container '%s'...", CONTAINER_NAME)
         result = run(
             [
                 "podman", "run", "-d",
@@ -96,7 +120,7 @@ class TestVPNImage(unittest.TestCase):
         )
         assert result.returncode == 0, f"Container failed to start:\n{result.stderr}"
         cls.container_id = result.stdout.strip()
-        print(f"[setup] Container started: {cls.container_id[:12]}")
+        logger.info("Container started: %s", cls.container_id[:12])
 
         # Verify it's running
         inspect = run(
@@ -106,17 +130,19 @@ class TestVPNImage(unittest.TestCase):
         assert inspect.stdout.strip() == "true", "Container is not running"
 
         # ── 4. Wait for VPN to come up ──
-        print(f"[setup] Waiting up to {STARTUP_TIMEOUT}s for VPN tunnel...")
+        logger.info("Waiting up to %d seconds for VPN tunnel...", STARTUP_TIMEOUT)
         vpn_up = cls._wait_for_vpn_cls(STARTUP_TIMEOUT)
         assert vpn_up, f"VPN did not come up within {STARTUP_TIMEOUT}s"
-        print("[setup] VPN tunnel is up. Running tests.\n")
+        logger.info("VPN tunnel is up. Running tests.")
 
     @classmethod
     def tearDownClass(cls):
         """Stop and remove the container."""
-        print("\n[teardown] Cleaning up...")
+        if not is_root():
+            return
+        logger.info("Cleaning up test container...")
         subprocess.run(["podman", "rm", "-f", CONTAINER_NAME], capture_output=True, check=False)
-        print("[teardown] Done.")
+        logger.info("Cleanup complete.")
 
     @classmethod
     def _wait_for_vpn_cls(cls, timeout: int = STARTUP_TIMEOUT) -> bool:
@@ -138,13 +164,25 @@ class TestVPNImage(unittest.TestCase):
         )
         return result.stdout.strip()
 
+    def _skip_if_not_root(self):
+        """Skip test if not running as root."""
+        if not is_root():
+            self.skipTest("This test requires root/sudo privileges")
+
     # ── Tests ────────────────────────────────────────────────
 
+    def test_00_build_image(self):
+        """The image builds successfully."""
+        # This is already verified in setUpClass, just confirm here
+        result = run(["podman", "images", "--format", "{{.Repository}}:{{.Tag}}"])
+        self.assertIn(IMAGE_NAME, result.stdout, "Image was not built")
+
     def test_01_ip_differs_from_host(self):
         """Public IP inside VPN is different from host IP."""
+        self._skip_if_not_root()
         vpn_ip = self._get_vpn_ip()
-        print(f"\n[test] VPN public IP:  {vpn_ip}")
-        print(f"[test] Host public IP: {self.host_ip}")
+        logger.info("VPN public IP: %s", vpn_ip)
+        logger.info("Host public IP: %s", self.host_ip)
 
         self.assertTrue(vpn_ip, "Could not fetch IP from inside the container")
         self.assertNotEqual(
@@ -155,12 +193,42 @@ class TestVPNImage(unittest.TestCase):
 
     def test_02_wireguard_interface_exists(self):
         """The wg0 interface is present in the container."""
+        self._skip_if_not_root()
         result = podman_exec(CONTAINER_NAME, ["wg", "show", "wg0"])
         self.assertEqual(result.returncode, 0, f"wg show failed:\n{result.stderr}")
         self.assertIn("peer", result.stdout.lower(), "No peer information in wg show output")
+        # AllowedIPs should be present in wg show output
+        self.assertIn("allowed ips", result.stdout.lower(), "AllowedIPs not found in wg show output")
 
-    def test_03_kill_switch_blocks_traffic(self):
+    def test_03_allowedips_routes_set(self):
+        """Routes are set dynamically based on AllowedIPs from config."""
+        self._skip_if_not_root()
+        # Check that routes exist for the AllowedIPs
+        result = podman_exec(CONTAINER_NAME, ["ip", "route", "show", "dev", "wg0"])
+        self.assertEqual(result.returncode, 0, f"ip route show failed:\n{result.stderr}")
+        # The config has AllowedIPs = 0.0.0.0/0, which should result in:
+        # 0.0.0.0/1 dev wg0 and 128.0.0.0/1 dev wg0
+        self.assertIn("0.0.0.0/1", result.stdout, "Route 0.0.0.0/1 not found")
+        self.assertIn("128.0.0.0/1", result.stdout, "Route 128.0.0.0/1 not found")
+        # Make sure there is NO default route through wg0 (Table = off should prevent this)
+        self.assertNotIn("default dev wg0", result.stdout, "Default route through wg0 found — Table = off not working!")
+        logger.info("AllowedIPs routes verified: %s", result.stdout.strip())
+
+    def test_03b_dns_configured(self):
+        """DNS is configured correctly with multiple nameserver lines."""
+        self._skip_if_not_root()
+        result = podman_exec(CONTAINER_NAME, ["cat", "/etc/resolv.conf"])
+        self.assertEqual(result.returncode, 0, f"cat /etc/resolv.conf failed:\n{result.stderr}")
+        # Should have two separate nameserver lines, not one with commas
+        self.assertIn("nameserver 198.18.0.1", result.stdout, "DNS 198.18.0.1 not found")
+        self.assertIn("nameserver 198.18.0.2", result.stdout, "DNS 198.18.0.2 not found")
+        # Make sure there are no commas in nameserver lines
+        self.assertNotIn("nameserver 198.18.0.1,198.18.0.2", result.stdout, "DNS servers written on one line with comma!")
+        logger.info("DNS config verified: %s", result.stdout.strip())
+
+    def test_04_kill_switch_blocks_traffic(self):
         """When WireGuard is down, traffic is blocked (kill switch)."""
+        self._skip_if_not_root()
         # Bring down the WireGuard interface by deleting it
         down_result = podman_exec(CONTAINER_NAME, ["ip", "link", "del", "wg0"], timeout=10)
         self.assertEqual(down_result.returncode, 0, f"ip link del wg0 failed:\n{down_result.stderr}")
@@ -178,7 +246,7 @@ class TestVPNImage(unittest.TestCase):
             result.returncode, 0,
             "Traffic went through even with WireGuard down — kill switch is NOT working!",
         )
-        print("\n[test] Kill switch confirmed: traffic blocked with VPN down")
+        logger.info("Kill switch confirmed: traffic blocked with VPN down")
 
 
 if __name__ == "__main__":

Docker/wg0.conf

@@ -1,10 +1,17 @@
 [Interface]
-PrivateKey = iO5spIue/6ciwUoR95hYtuxdtQxV/Q9EOoQ/jHe18kM=
-Address = 10.2.0.2/32
-DNS = 10.2.0.1
+PrivateKey = EPRa2f/v72LvIXAY4yqIRJifsSb+nCcYHqC2rwA94UI=
+Address = 100.64.244.78/32
+DNS = 198.18.0.1,198.18.0.2
+
+# Route zum VPN-Server direkt über dein lokales Netz
+PostUp = ip route add 91.148.236.64 via 192.168.178.1 dev wlp4s0f0
+PostUp = ip route add 192.168.178.0/24 via 192.168.178.1 dev wlp4s0f0
+PostDown = ip route del 91.148.236.64 via 192.168.178.1 dev wlp4s0f0
+PostDown = ip route del 192.168.178.0/24 via 192.168.178.1 dev wlp4s0f0
 
 [Peer]
-PublicKey = J4XVdtoBVc/EoI2Yk673Oes97WMnQSH5KfamZNjtM2s=
+PublicKey = KgTUh3KLijVluDvNpzDCJJfrJ7EyLzYLmdHCksG4sRg=
 AllowedIPs = 0.0.0.0/0
-Endpoint = 185.183.34.149:51820
+Endpoint = 91.148.236.64:51820
 PersistentKeepalive = 25
+

docs/API.md

@@ -203,14 +203,14 @@ List library series that have missing episodes.
 | `page` | int | 1 | Page number (must be positive) |
 | `per_page` | int | 20 | Items per page (max 1000) |
 | `sort_by` | string | null | Sort field: `title`, `id`, `name`, `missing_episodes` |
-| `filter` | string | null | Filter: `no_episodes` (shows only series with missing episodes - episodes in DB that haven't been downloaded yet) |
+| `filter` | string | null | Filter: `missing_episodes` (shows series with any missing episodes), `no_episodes` (shows series with zero downloaded episodes) |
 
 **Filter Details:**
 
-- `no_episodes`: Returns series that have at least one episode in the database with `is_downloaded=False`
+- `missing_episodes`: Returns series that have at least one missing episode recorded in the database (`is_downloaded=False`)
+- `no_episodes`: Returns series that have missing episodes and no downloaded episodes (i.e., only missing episodes exist in the database)
 - Episodes in the database represent MISSING episodes (from episodeDict during scanning)
 - `is_downloaded=False` means the episode file was not found in the folder
-- This effectively shows series where no video files were found for missing episodes
 
 **Response (200 OK):**
 
@@ -1285,7 +1285,7 @@ Basic health check endpoint.
 {
     "status": "healthy",
     "timestamp": "2025-12-13T10:30:00.000Z",
-    "version": "1.0.0"
+    "version": "1.0.1"
 }
 ```
 
@@ -1303,7 +1303,7 @@ Comprehensive health check with database, filesystem, and system metrics.
 {
     "status": "healthy",
     "timestamp": "2025-12-13T10:30:00.000Z",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "dependencies": {
         "database": {
             "status": "healthy",

docs/ARCHITECTURE.md

@@ -81,6 +81,7 @@ src/server/
 |   +-- websocket_service.py# WebSocket broadcasting
 |   +-- queue_repository.py # Database persistence
 |   +-- nfo_service.py      # NFO metadata management
+|   +-- folder_scan_service.py # Daily folder maintenance scan
 +-- models/                 # Pydantic models
 |   +-- auth.py             # Auth request/response models
 |   +-- config.py           # Configuration models
@@ -290,8 +291,9 @@ The FastAPI lifespan function (`src/server/fastapi_app.py`) runs the following s
 8. Background loader service started
 
 9. Scheduler service started
-
-10. NFO repair scan (queue incomplete tvshow.nfo files for background reload)
+   +-- Cron-based library rescans configured
+   +-- Optional: auto-download missing episodes after rescan
+   +-- Optional: folder maintenance (NFO repair, renaming, poster checks) during scheduled runs
 ```
 
 ### 12.2 Temp Folder Guarantee

docs/CHANGELOG.md

@@ -73,17 +73,16 @@ This changelog follows [Keep a Changelog](https://keepachangelog.com/) principle
   that detects incomplete `tvshow.nfo` files and triggers TMDB re-fetch.
   Provides `parse_nfo_tags()`, `find_missing_tags()`, `nfo_needs_repair()`, and
   `NfoRepairService.repair_series()`. 13 required tags are checked.
-- **`perform_nfo_repair_scan()` startup hook
-  (`src/server/services/initialization_service.py`)**: New async function
-  called during application startup. Iterates every series directory, checks
-  whether `tvshow.nfo` is missing required tags using `nfo_needs_repair()`, and
-  either queues the series for background reload (when a `background_loader` is
-  provided) or calls `NfoRepairService.repair_series()` directly. Skips
-  gracefully when `tmdb_api_key` or `anime_directory` is not configured.
-- **NFO repair wired into startup lifespan (`src/server/fastapi_app.py`)**:
-  `perform_nfo_repair_scan(background_loader)` is called at the end of the
-  FastAPI lifespan startup, after `perform_media_scan_if_needed`, ensuring
-  every existing series NFO is checked and repaired on each server start.
+- **`perform_nfo_repair_scan()`
+  (`src/server/services/folder_scan_service.py`)**: New async function
+  that iterates every series directory, checks whether `tvshow.nfo` is missing
+  required tags using `nfo_needs_repair()`, and queues the series for background
+  reload via `asyncio.create_task`. Skips gracefully when `tmdb_api_key` or
+  `anime_directory` is not configured.
+- **NFO repair wired into scheduled folder scan (`src/server/services/folder_scan_service.py`)**:
+  `perform_nfo_repair_scan(background_loader=None)` is called during the
+  scheduled daily folder scan, keeping startup fast while ensuring regular
+  maintenance.
 
 ### Changed
 

docs/CONFIGURATION.md

@@ -117,7 +117,8 @@ Location: `data/config.json`
         "interval_minutes": 60,
         "schedule_time": "03:00",
         "schedule_days": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"],
-        "auto_download_after_rescan": false
+        "auto_download_after_rescan": false,
+        "folder_scan_enabled": false
     },
     "logging": {
         "level": "INFO",
@@ -143,7 +144,7 @@ Location: `data/config.json`
         "master_password_hash": "$pbkdf2-sha256$...",
         "anime_directory": "/path/to/anime"
     },
-    "version": "1.0.0"
+    "version": "1.0.1"
 }
 ```
 
@@ -173,6 +174,7 @@ Controls automatic cron-based library rescanning (powered by APScheduler).
 | `scheduler.schedule_time`              | string       | `"03:00"`                                     | Daily run time in 24-h `HH:MM` format.                               |
 | `scheduler.schedule_days`              | list[string] | `["mon","tue","wed","thu","fri","sat","sun"]` | Days of the week to run the scan. Empty list disables the cron job.  |
 | `scheduler.auto_download_after_rescan` | bool         | `false`                                       | Automatically queue missing episodes for download after each rescan. |
+| `scheduler.folder_scan_enabled`        | bool         | `false`                                       | Run folder maintenance (NFO repair, folder renaming, poster checks) during scheduled runs. **When enabled, series folders are automatically renamed to match the `<title> (<year>)` convention derived from their `tvshow.nfo` files.** |
 
 Valid day abbreviations: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`.
 
@@ -216,7 +218,9 @@ Source: [src/server/models/config.py](../src/server/models/config.py#L15-L24)
 - Obtain a TMDB API key from https://www.themoviedb.org/settings/api
 - `auto_create` creates NFO files during the download process
 - `update_on_scan` refreshes metadata when scanning existing anime
+- `download_poster` also controls whether the scheduled folder scan checks for and re-downloads missing or corrupted `poster.jpg` files (see [NFO_GUIDE.md](NFO_GUIDE.md#6-poster-check))
 - Image downloads require valid `tmdb_api_key`
+- `TMDB_API_KEY` environment variable is optional when `nfo.tmdb_api_key` is configured in `data/config.json`
 - Larger image sizes (`w780`, `original`) consume more storage space
 
 Source: [src/server/models/config.py](../src/server/models/config.py#L109-L132)

docs/InstructionsLogging.md

@@ -0,0 +1,94 @@
+# Logging Instructions
+
+This document describes how to write and refactor logging across the AniWorld codebase to make logs **human-readable**, **debug-friendly**, and **noise-free**.
+
+> ✅ Goal: Logs should help a developer understand what happened, why it happened, and what to inspect next — without overwhelming them with duplicates or irrelevant details.
+
+---
+
+## 1. Principles for Great Logs
+
+### 1.1 Use the Right Log Level
+
+- `DEBUG`: Detailed internal state useful when debugging a specific issue (e.g., decision points, returned values, request/response payloads). Not for normal operation.
+- `INFO`: High-level events that represent what the system is doing (e.g., "Import started", "New series added", "Config reloaded"). Use sparingly.
+- `WARNING`: Something unexpected happened, but the system can continue (e.g., missing optional file, fallback behavior).
+- `ERROR`: An operation failed and needs attention (e.g., exception caught, failed database write).
+- `CRITICAL`: The system is in an unusable state (e.g., config corruption, failed startup).
+
+### 1.2 Keep Logs Human-Readable
+
+- Write messages in a clear, descriptive sentence-style format.
+- Avoid cryptic codes or single-word log messages.
+- Prefer `logger.debug("... %s", value)`-style formatting over f-strings to avoid unnecessary work when the log level is disabled.
+
+### 1.3 Avoid Log Spam
+
+- Don’t log inside hot loops unless you explicitly aggregate and log a summary (e.g., "Processed 124 files, 3 failures").
+- Avoid repeated/logging the same event at the same level (e.g., do not log "Retrying" 10 times at INFO; log once at INFO and then use DEBUG for each retry).
+- Use rate limiting or debounce patterns for logs that can fire rapidly (e.g., external service health checks).
+- Prefer a single higher-level log with context rather than many low-level logs that clutter output.
+
+### 1.4 Log Objects Usefully
+
+- When logging objects, log the minimal useful representation (e.g., ID, name, status) rather than the full object or its memory address.
+- If an object has a `.dict()`, `.to_dict()`, or `.as_dict()` helper (common in Pydantic models), log that rather than relying on `repr()`.
+- Add a `__repr__` or `__str__` implementation to domain models that returns a helpful, concise string with key identifiers.
+- Use structured logging (e.g., `logger.info("Series added", extra={"series_id": series.id, "title": series.title})`) where supported.
+- For exceptions, prefer `logger.exception("Failed to ...")` to capture stack traces.
+
+---
+
+## 2. Refactoring Existing Logs
+
+When improving or refactoring existing log statements, aim to make them:
+
+- **Actionable**: A developer reading the log should know what happened and what to check next.
+- **Non-redundant**: Remove duplicates and ensure only one log records the same high-level event at a given level.
+- **Context-rich**: Include identifiers (e.g., `series_id`, `file_path`, `user_id`) and key state that explains why a decision was made.
+- **Level-appropriate**: Downgrade noisy INFO logs to DEBUG, and elevate critical failures to ERROR/CRITICAL.
+
+### 2.1 Refactor Checklist
+
+1. **Locate noisy logs**: Search for repeated messages (e.g., "Start", "Done") and determine whether they should be DEBUG or removed.
+2. **Replace ad-hoc prints**: Remove `print()` statements or `print(obj)` and replace with `logger.*` calls.
+3. **Use structured context**: If a function logs multiple related messages, include the same context in each (e.g., `extra={"series_id": series.id}`) or use a context manager that attaches it.
+4. **Validate object output**: Ensure any logged object produces a useful representation (add methods or translate to dict). If not, log the key fields explicitly.
+5. **Batch repetitive events**: If a loop logs per item, consider collecting stats and logging a summary at the end.
+
+## 3. Adding New Logs
+
+When adding logs to new code paths:
+
+- Log **important state transitions** (e.g., "Queue started", "Download completed", "Config reloaded").
+- For error paths, include what failed and why (e.g., "Could not load config from X: {exc}").
+- Prefer logging at the boundaries of operations, not deep inside utility functions unless it aids debugging.
+- Write logs in full sentences, with a clear subject, verb, and object.
+
+---
+
+## 4. Example Patterns
+
+```python
+logger.info("Import completed", extra={"series_id": series.id, "count": len(imported)})
+
+logger.debug(
+    "Fetched feed items",
+    extra={"feed_url": feed.url, "item_count": len(items)},
+)
+
+try:
+    result = download_episode(episode)
+except Exception:
+    logger.exception("Failed to download episode %s", episode.id)
+```
+
+> 💡 When in doubt, favor **fewer, richer logs** over many noisy logs.
+
+---
+
+## 5. Logging Audit Task List
+
+For a guided checklist of files and logging improvements, see **`docs/tasks.md`**. This is where we track which files have been reviewed and which logging items still need attention.
+
+> ✅ After applying the guidelines above, update `docs/tasks.md` to indicate which tasks are complete.

docs/NFO_GUIDE.md

@@ -246,7 +246,84 @@ NFO files are created in the anime directory:
 
 ---
 
-## 5. API Reference
+## 5. Folder Naming Convention
+
+### 5.1 Expected Format
+
+After the daily folder scan (when **Update on library scan** is enabled), Aniworld validates every series folder against its `tvshow.nfo` metadata. If the folder name does not match the expected convention, it is automatically renamed.
+
+**Format:**
+
+```
+{title} ({year})
+```
+
+**Examples:**
+
+| NFO `<title>` | NFO `<year>` | Expected Folder Name |
+|---------------|--------------|----------------------|
+| `Attack on Titan` | `2013` | `Attack on Titan (2013)` |
+| `One Piece` | `1999` | `One Piece (1999)` |
+| `Demon Slayer: Kimetsu no Yaiba` | `2019` | `Demon Slayer Kimetsu no Yaiba (2019)` |
+
+### 5.2 Sanitization Rules
+
+Illegal filesystem characters are removed or replaced to ensure cross-platform compatibility:
+
+- Removed: `< > : " / \ | ? *` and null bytes
+- Control characters stripped
+- Multiple spaces collapsed to one
+- Leading/trailing dots and whitespace trimmed
+- Maximum length: 200 characters (truncated at word boundary if possible)
+
+### 5.3 Skip Conditions
+
+A folder is **not** renamed when any of the following apply:
+
+- `tvshow.nfo` is missing `<title>` or `<year>` (or they are empty)
+- The series has an **active or pending download**
+- The target folder name already exists (duplicate)
+- The resulting path would exceed the OS path-length limit
+- The app lacks write permission to the anime directory
+
+All skipped and renamed actions are logged.
+
+---
+
+## 6. Poster Check
+
+### 6.1 Overview
+
+During the daily folder scan, Aniworld checks every series folder for a valid `poster.jpg`. If the file is missing or smaller than 1 KB, the application attempts to re-download it from the URL stored in the series' `tvshow.nfo` file.
+
+### 6.2 How It Works
+
+1. **Scan** — After folder renaming, the scan iterates over all series folders that contain a `tvshow.nfo`.
+2. **Validate** — For each folder, it checks whether `poster.jpg` exists and is at least 1 KB.
+3. **Parse NFO** — If the poster is missing or too small, the scan reads `tvshow.nfo` and looks for a `<thumb aspect="poster">` (or any `<thumb>`) URL.
+4. **Download** — If a URL is found, the poster is downloaded using `ImageDownloader` with a concurrency limit of 3 simultaneous downloads.
+5. **Validate Download** — The downloaded image is validated with PIL to ensure it is not corrupted.
+
+### 6.3 Skip Conditions
+
+A folder is **not** processed for poster download when any of the following apply:
+
+- `tvshow.nfo` does not exist in the folder.
+- `poster.jpg` already exists and is ≥ 1 KB.
+- No `<thumb>` URL is found in the NFO (the NFO may have been created before thumb tags were added).
+- The `nfo.download_poster` setting is `false` (poster checks are still performed, but downloads are skipped if the setting is disabled; see [CONFIGURATION.md](CONFIGURATION.md)).
+
+### 6.4 Logging
+
+Every poster check action is logged:
+
+- **INFO** — When a poster is successfully downloaded.
+- **WARNING** — When a download fails or no URL is found.
+- **ERROR** — When an unexpected exception occurs during download.
+
+---
+
+## 7. API Reference
 
 ### 5.1 Check NFO Status
 
@@ -675,21 +752,25 @@ The XML serialisation lives in `src/core/utils/nfo_generator.py`
 
 ## 11. Automatic NFO Repair
 
-Every time the server starts, Aniworld scans all existing `tvshow.nfo` files and
-automatically repairs any that are missing required tags.
+NFO repair now runs as part of the scheduled daily folder scan rather than on every
+startup.  When the scheduler triggers `FolderScanService.run_folder_scan()`, the first
+step is `perform_nfo_repair_scan(background_loader=None)`.  Each incomplete NFO is
+queued as a background `asyncio` task, so the scan returns quickly while repairs
+continue asynchronously.
 
 ### How It Works
 
 1. **Scan** — `perform_nfo_repair_scan()` in
-   `src/server/services/initialization_service.py` is called from the FastAPI
-   lifespan after `perform_media_scan_if_needed()`.
+   `src/server/services/initialization_service.py` is called from
+   `FolderScanService.run_folder_scan()` (`src/server/services/folder_scan_service.py`).
 2. **Detect** — `nfo_needs_repair(nfo_path)` from
    `src/core/services/nfo_repair_service.py` parses each `tvshow.nfo` with
    `lxml` and checks for the 13 required tags listed below.
 3. **Repair** — Series whose NFO is incomplete are queued for background reload
-   via `BackgroundLoaderService.add_series_loading_task()`. The background
-   loader re-fetches metadata from TMDB and rewrites the NFO with all tags
-   populated.
+   via `asyncio.create_task`. Each task creates its own isolated
+   :class:`NFOService` / :class:`TMDBClient` so concurrent tasks never share an
+   ``aiohttp`` session — this prevents "Connector is closed" errors when many repairs
+   run in parallel.  A semaphore caps TMDB concurrency at 3 to stay within rate limits.
 
 ### Tags Checked (13 required)
 
@@ -734,8 +815,7 @@ This calls `NFOService.update_tvshow_nfo()` directly and overwrites the existing
 | File                                            | Purpose                                                                                        |
 | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
 | `src/core/services/nfo_repair_service.py`       | `REQUIRED_TAGS`, `parse_nfo_tags`, `find_missing_tags`, `nfo_needs_repair`, `NfoRepairService` |
-| `src/server/services/initialization_service.py` | `perform_nfo_repair_scan` startup hook                                                         |
-| `src/server/fastapi_app.py`                     | Wires `perform_nfo_repair_scan` into the lifespan                                              |
+| `src/server/services/folder_scan_service.py`    | `perform_nfo_repair_scan` — invoked during the scheduled daily folder scan                     |
 
 ---
 

docs/features.md

@@ -59,6 +59,10 @@ The application now features a comprehensive configuration system that allows us
 ## Anime Management
 
 - **Anime Library Page**: Display list of anime series with missing episodes
+- **Library Filters**:
+    - "Missing Episodes Only" (shows only series with missing episodes, including series that currently have no downloaded episodes)
+    - "No Episodes" (shows series that are present in the library but have zero downloaded episodes)
+    - "Show All Series" (overrides other filters to show every series)
 - **Database-Backed Series Storage**: All series metadata and missing episodes stored in SQLite database
 - **Automatic Database Synchronization**: Series loaded from database on startup, stays in sync with filesystem
 - **Series Selection**: Select individual anime series and add episodes to download queue

docs/instructions.md

@@ -117,100 +117,3 @@ For each task completed:
 
 ---
 
-## TODO List:
-
----
-
-fix: download not working:
-
-elf.\_progress_service.update_progress(
-
-File "/app/src/server/services/progress_service.py", line 369, in update_progress
-
-    raise ProgressServiceError(
-
-src.server.services.progress_service.ProgressServiceError: Progress with id 'download_queue' not found
-
-2026-03-11 15:15:42 [info ] Processing next item from queue item_id=108 remaining=2 serie=I Was Reincarnated as the 7th Prince So I Can Take My Time Perfecting My Magical Ability
-
-2026-03-11 15:15:42 [error ] Error in queue processing loop error=Progress with id 'download_queue' not found
-
-Traceback (most recent call last):
-
-File "/app/src/server/services/download_service.py", line 716, in \_process_queue
-
-    await self._progress_service.update_progress(
-
-File "/app/src/server/services/progress_service.py", line 369, in update_progress
-
-    raise ProgressServiceError(
-
-src.server.services.progress_service.ProgressServiceError: Progress with id 'download_queue' not found
-
-2026-03-11 15:15:43 [info ] Processing next item from queue item_id=109 remaining=1 serie=I Was Reincarnated as the 7th Prince So I Can Take My Time Perfecting My Magical Ability
-
-2026-03-11 15:15:43 [error ] Error in queue processing loop error=Progress with id 'download_queue' not found
-
-Traceback (most recent call last):
-
-File "/app/src/server/services/download_service.py", line 716, in \_process_queue
-
-    await self._progress_service.update_progress(
-
-File "/app/src/server/services/progress_service.py", line 369, in update_progress
-
-    raise ProgressServiceError(
-
-src.server.services.progress_service.ProgressServiceError: Progress with id 'download_queue' not found
-
-2026-03-11 15:15:44 [info ] Processing next item from queue item_id=110 remaining=0 serie=I Was Reincarnated as the 7th Prince So I Can Take My Time Perfecting My Magical Ability
-
-2026-03-11 15:15:44 [error ] Error in queue processing loop error=Progress with id 'download_queue' not found
-
-Traceback (most recent call last):
-
-File "/app/src/server/services/download_service.py", line 716, in \_process_queue
-
-    await self._progress_service.update_progress(
-
-File "/app/src/server/services/progress_service.py", line 369, in update_progress
-
-    raise ProgressServiceError(
-
-src.server.services.progress_service.ProgressServiceError: Progress with id 'download_queue' not found
-
-2026-03-11 15:15:45 [info ] Queue processing completed - all items processed
-
-ERROR: Task exception was never retrieved
-
-future: <Task finished name='Task-16373' coro=<DownloadService.\_process_queue() done, defined at /app/src/server/services/download_service.py:688> exception=ProgressServiceError("Progress with id 'download_queue' not found")>
-
-Traceback (most recent call last):
-
-File "/app/src/server/services/download_service.py", line 755, in \_process_queue
-
-    await self._progress_service.complete_progress(
-
-File "/app/src/server/services/progress_service.py", line 446, in complete_progress
-
-    raise ProgressServiceError(
-
-src.server.services.progress_service.ProgressServiceError: Progress with id 'download_queue' not found
-
-2026-03-11 15:15:46 [info ] Queue processing completed - all items processed
-
-ERROR: Task exception was never retrieved
-
-future: <Task finished name='Task-16313' coro=<DownloadService.\_process_queue() done, defined at /app/src/server/services/download_service.py:688> exception=ProgressServiceError("Progress with id 'download_queue' not found")>
-
-Traceback (most recent call last):
-
-File "/app/src/server/services/download_service.py", line 755, in \_process_queue
-
-    await self._progress_service.complete_progress(
-
-File "/app/src/server/services/progress_service.py", line 446, in complete_progress
-
-    raise ProgressServiceError(
-
-src.server.services.progress_service.ProgressServiceError: Progress with id 'download_queue' not found

docs/key

@@ -2,3 +2,50 @@ API key : 299ae8f630a31bda814263c551361448
 
 /mnt/server/serien/Serien/
 
+{
+  "name": "Aniworld",
+  "data_dir": "data",
+  "scheduler": {
+    "enabled": true,
+    "interval_minutes": 60,
+    "schedule_time": "03:00",
+    "schedule_days": [
+      "mon",
+      "tue",
+      "wed",
+      "thu",
+      "fri",
+      "sat",
+      "sun"
+    ],
+    "auto_download_after_rescan": true,
+    "folder_scan_enabled": true
+  },
+  "logging": {
+    "level": "INFO",
+    "file": null,
+    "max_bytes": null,
+    "backup_count": 3
+  },
+  "backup": {
+    "enabled": false,
+    "path": "data/backups",
+    "keep_days": 30
+  },
+  "nfo": {
+    "tmdb_api_key": "9bc3e547caff878615cbdba2cc421d37",
+    "auto_create": true,
+    "update_on_scan": true,
+    "download_poster": true,
+    "download_logo": true,
+    "download_fanart": true,
+    "image_size": "original"
+  },
+  "other": {
+    "master_password_hash": "$pbkdf2-sha256$29000$HQNASKk1xpgTAgAgJGRMaQ$73TOCCM0UEZONyNXQEPa3SmIoXeG6C1l5mMFDNgYfMQ",
+    "anime_directory": "/data"
+  },
+  "version": "1.0.0"
+}
+
+

docs/tasks.md

@@ -0,0 +1,178 @@
+# Tasks
+
+## 1. Scheduled Folder Scan
+
+### Task 1.1: Add folder scan scheduler configuration
+
+**Where is that found**
+- `src/server/models/config.py` (`SchedulerConfig`)
+- `data/config.json` (example/default config)
+- `src/server/web/templates/setup.html` (setup UI)
+- `src/server/api/auth.py` (config save endpoint, if it validates scheduler fields)
+
+**Goal. How it should be**
+Add a new boolean field `folder_scan_enabled` (default `false`) to `SchedulerConfig`. When `true`, the scheduler will execute the folder maintenance routine during its scheduled run. Add the field to the setup page as a checkbox. Ensure existing configs without this field load successfully (Pydantic default handles this).
+
+**Possible traps and issues**
+- Backward compatibility: old `data/config.json` files must load without errors. Pydantic defaults solve this, but verify by loading an old config.
+- The setup page JavaScript must include the new field in the payload sent to `/api/config`.
+- Do not confuse this with `auto_download_after_rescan` — this is a separate toggle.
+
+**Docs changes needed**
+- `docs/CONFIGURATION.md`: Document the new `scheduler.folder_scan_enabled` option.
+- `docs/ARCHITECTURE.md`: Mention folder scan in the scheduler section.
+
+**Why this is needed**
+Users need an opt-in toggle to enable automatic daily folder maintenance (NFO repair, folder renaming, poster checks) without forcing it on everyone.
+
+---
+
+### Task 1.2: Create FolderScanService skeleton
+
+**Where is that found**
+- New file: `src/server/services/folder_scan_service.py`
+- `src/server/services/scheduler_service.py` (to call it)
+
+**Goal. How it should be**
+Create a new `FolderScanService` class with a single async entry point `async def run_folder_scan(self) -> None`. The method should:
+1. Log start/completion with structlog.
+2. Check prerequisites (`settings.anime_directory` exists, `settings.tmdb_api_key` is set).
+3. Skip gracefully with a warning log if prerequisites are missing.
+4. Use a module-level semaphore (similar to `_NFO_REPAIR_SEMAPHORE`) to limit concurrent TMDB operations to 3.
+
+Keep the implementation empty for the sub-tasks (1.3–1.5) to fill in. Just add the skeleton and the semaphore.
+
+**Possible traps and issues**
+- Circular imports: `folder_scan_service.py` will import from `initialization_service`, `config.settings`, etc. Keep imports inside methods or at the bottom if circular issues arise.
+- The service should follow the singleton pattern like `SchedulerService` and `DownloadService` if it holds state, or be stateless. For simplicity, make it a plain class instantiated per call or a module-level function set.
+- Exception handling: any unhandled exception in the scheduled task should be caught and logged so it doesn't crash the scheduler.
+
+**Docs changes needed**
+- `docs/ARCHITECTURE.md`: Add `folder_scan_service.py` to the services list.
+
+**Why this is needed**
+Encapsulates the new daily maintenance logic in its own module, keeping `scheduler_service.py` clean and allowing the folder scan to be tested independently.
+
+---
+
+### Task 1.3: Integrate NFO repair into folder scan
+
+**Where is that found**
+- `src/server/services/folder_scan_service.py`
+- `src/server/services/initialization_service.py` (`perform_nfo_repair_scan`)
+
+**Goal. How it should be**
+Inside `FolderScanService.run_folder_scan()`, call `perform_nfo_repair_scan(background_loader=None)` as the first step. Reuse the existing function exactly — do not copy its logic. Log a message before and after the call.
+
+**Possible traps and issues**
+- `perform_nfo_repair_scan` spawns `asyncio.create_task` for each repair. When called from the scheduler, these background tasks will still run after `run_folder_scan` returns. This is fine, but log that repairs are queued.
+- The function already handles missing `tmdb_api_key` and `anime_directory`, so the caller doesn't need to double-check, but the skeleton from Task 1.2 already checks prerequisites.
+- `perform_nfo_repair_scan` imports `nfo_needs_repair` and `NfoRepairService` inside the function, so no heavy import-time dependencies.
+
+**Docs changes needed**
+- `docs/NFO_GUIDE.md`: Update the "Automatic NFO Repair" section to state that repair now runs as part of the scheduled folder scan instead of every startup.
+
+**Why this is needed**
+Reuses the existing, tested NFO repair logic. Moves NFO repair from startup blocking to scheduled background maintenance.
+
+---
+
+### Task 1.4: Validate and rename series folders
+
+**Where is that found**
+- `src/server/services/folder_scan_service.py`
+- `src/core/services/nfo_repair_service.py` (for `parse_nfo_tags` or similar NFO parsing)
+- `src/server/database/models.py` / `src/server/database/system_settings_service.py` (if folder paths are stored in DB)
+
+**Goal. How it should be**
+After NFO repair, iterate over every subfolder in `settings.anime_directory` that contains a `tvshow.nfo`. For each folder:
+1. Parse the NFO to extract `<title>` and `<year>` text values.
+2. Compute the expected folder name: `f"{title} ({year})"`.
+3. Sanitize the expected name for filesystem safety (remove/replace illegal characters like `/`, `\`, `:`, etc.).
+4. Compare with the current folder name (`series_dir.name`).
+5. If different, rename the folder using `series_dir.rename(expected_path)`.
+6. If the series path is stored in the database (check `anime_service` or DB models), update the database record to point to the new path.
+
+Skip folders where title or year is missing/empty. Log every rename action.
+
+**Possible traps and issues**
+- **Database path consistency**: If `Series` or `Episode` models store absolute or relative paths, renaming the folder on disk without updating the DB will break downloads, NFO updates, and the web UI. Must verify whether paths are stored in the DB and update them.
+- **Active downloads**: A series currently being downloaded should not be renamed. Check the download queue or lock status before renaming. If no lock mechanism exists, this is a major trap — document it.
+- **Filesystem permissions**: The app may not have write permission to the anime directory. Catch `PermissionError` and `OSError` and log gracefully.
+- **Special characters**: Titles like `"A / B"` or `"Show: Subtitle"` contain characters illegal in folder names. Define a sanitization function (e.g., replace `/` with `-`, remove trailing dots on Windows, etc.).
+- **Duplicate names**: Two different series could sanitize to the same name. Check if target path already exists before renaming.
+- **Path length limits**: Very long titles might exceed OS path limits.
+
+**Docs changes needed**
+- `docs/NFO_GUIDE.md`: Add a section "Folder Naming Convention" explaining the `<title> (<year>)` format.
+- `docs/CONFIGURATION.md`: Mention that enabling folder scan will rename folders.
+
+**Why this is needed**
+Enforces a consistent, predictable folder naming scheme across the library, making it easier for media center apps (Kodi, Jellyfin, Plex) to match metadata.
+
+---
+
+### Task 1.5: Check and download missing poster.jpg
+
+**Where is that found**
+- `src/server/services/folder_scan_service.py`
+- `src/core/utils/image_downloader.py` (`ImageDownloader`)
+- `src/core/services/nfo_service.py` or `src/core/services/nfo_repair_service.py` (to get poster URL from NFO or TMDB)
+
+**Goal. How it should be**
+After folder renaming, iterate over series folders again (or combine with Task 1.4 loop). For each folder:
+1. Check if `poster.jpg` exists and has a size ≥ `ImageDownloader.min_file_size` (1 KB by default).
+2. If missing or too small:
+   a. Parse `tvshow.nfo` for `<thumb aspect="poster">` or `<thumb>` URL.
+   b. If no URL in NFO, skip (do not query TMDB again to keep tasks small; the NFO should already have it after repair).
+   c. Use `ImageDownloader` (with context manager) to download the image to `series_dir / "poster.jpg"`.
+   d. Validate the downloaded image with `ImageDownloader._validate_image` (or similar existing validation).
+3. Use the existing `_NFO_REPAIR_SEMAPHORE` or a new `POSTER_DOWNLOAD_SEMAPHORE` to limit concurrent downloads to 3.
+
+**Possible traps and issues**
+- **TMDB rate limiting**: Even downloading images hits TMDB CDN. The semaphore limits concurrency.
+- **Invalid images**: A download might produce a 0-byte or corrupted file. `ImageDownloader` already validates with PIL; reuse that.
+- **NFO without thumb URL**: If the NFO was created before thumb tags were added, there may be no URL. In that case, skip and log. A future task could query TMDB directly.
+- **Write permissions**: Same as Task 1.4.
+- **Async session sharing**: `ImageDownloader` manages its own `aiohttp` session. Use `async with ImageDownloader() as downloader:` to ensure cleanup.
+
+**Docs changes needed**
+- `docs/NFO_GUIDE.md`: Add "Poster Check" subsection under folder scan.
+- `docs/CONFIGURATION.md`: Mention that `nfo.download_poster` setting also affects scheduled poster checks.
+
+**Why this is needed**
+Ensures every series has artwork, which is required by most media center front-ends for a polished library view.
+
+---
+
+## 2. Remove startup NFO repair
+
+### Task 2.1: Remove perform_nfo_repair_scan from startup lifespan
+
+**Where is that found**
+- `src/server/fastapi_app.py` (lifespan startup block, lines ~245 and ~319)
+- `src/server/services/initialization_service.py` (keep the function, just remove the call site)
+- `tests/integration/test_nfo_repair_startup.py`
+- `tests/unit/test_initialization_service.py` (tests that call `perform_nfo_repair_scan` directly can stay, but integration tests verifying startup wiring must change)
+
+**Goal. How it should be**
+1. In `src/server/fastapi_app.py`, remove the import of `perform_nfo_repair_scan` from the `initialization_service` import block.
+2. Remove the line `await perform_nfo_repair_scan(background_loader)` from the lifespan startup sequence.
+3. Update `tests/integration/test_nfo_repair_startup.py`:
+   - Remove or modify `test_perform_nfo_repair_scan_imported_in_lifespan` and `test_perform_nfo_repair_scan_called_after_media_scan` since the startup wiring is gone.
+   - Replace with a test that verifies `perform_nfo_repair_scan` is NOT called during startup (or simply delete the file if it has no other purpose).
+4. `tests/unit/test_initialization_service.py` tests for `perform_nfo_repair_scan` can remain because they test the function itself, not the startup wiring.
+
+**Possible traps and issues**
+- **Test failures**: `test_nfo_repair_startup.py` will fail immediately after the code change. It must be updated in the same PR.
+- **Documentation drift**: `docs/NFO_GUIDE.md`, `docs/CHANGELOG.md`, and `docs/ARCHITECTURE.md` all describe the startup NFO repair behavior. If docs are not updated, users will expect repair on every start.
+- **Background loader parameter**: The `background_loader` variable was created partly for `perform_nfo_repair_scan`. After removal, check if `background_loader` is still needed for other startup steps (yes — `perform_media_scan_if_needed` uses it). Do not remove `background_loader` entirely.
+- **Import cleanup**: Ensure no unused imports remain in `fastapi_app.py` after removal.
+
+**Docs changes needed**
+- `docs/NFO_GUIDE.md`: Update section 11 "Automatic NFO Repair" to remove startup references and state it runs via scheduler.
+- `docs/CHANGELOG.md`: Add an entry under "Changed" or "Removed" noting that startup NFO repair is replaced by scheduled folder scan.
+- `docs/ARCHITECTURE.md`: Update the startup sequence description.
+
+**Why this is needed**
+Running `perform_nfo_repair_scan` on every startup slows down server restarts, especially for large libraries. Moving it to a scheduled task keeps startup fast while still ensuring regular maintenance.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aniworld-web",
-  "version": "1.0.0",
+  "version": "1.1.7",
   "description": "Aniworld Anime Download Manager - Web Frontend",
   "type": "module",
   "scripts": {

src/cli/nfo_cli.py

@@ -5,6 +5,7 @@ and checking NFO metadata files.
 """
 
 import asyncio
+import logging
 import sys
 from pathlib import Path
 
@@ -14,48 +15,50 @@ sys.path.insert(0, str(Path(__file__).parent.parent.parent))
 from src.config.settings import settings
 from src.core.services.series_manager_service import SeriesManagerService
 
+logger = logging.getLogger(__name__)
+
 
 async def scan_and_create_nfo():
     """Scan all series and create missing NFO files."""
-    print("=" * 70)
-    print("NFO Auto-Creation Tool")
-    print("=" * 70)
-    
+    logger.info("%s", "=" * 70)
+    logger.info("NFO Auto-Creation Tool")
+    logger.info("%s", "=" * 70)
+
     if not settings.tmdb_api_key:
-        print("\n❌ Error: TMDB_API_KEY not configured")
-        print("   Set TMDB_API_KEY in .env file or environment")
-        print("   Get API key from: https://www.themoviedb.org/settings/api")
+        logger.error("TMDB_API_KEY not configured")
+        logger.error("Set TMDB_API_KEY in .env file or environment")
+        logger.error("Get API key from: https://www.themoviedb.org/settings/api")
         return 1
     
     if not settings.anime_directory:
-        print("\n❌ Error: ANIME_DIRECTORY not configured")
+        logger.error("ANIME_DIRECTORY not configured")
         return 1
-    
-    print(f"\nAnime Directory: {settings.anime_directory}")
-    print(f"Auto-create NFO: {settings.nfo_auto_create}")
-    print(f"Update on scan: {settings.nfo_update_on_scan}")
-    print(f"Download poster: {settings.nfo_download_poster}")
-    print(f"Download logo: {settings.nfo_download_logo}")
-    print(f"Download fanart: {settings.nfo_download_fanart}")
-    
+
+    logger.info("Anime Directory: %s", settings.anime_directory)
+    logger.info("Auto-create NFO: %s", settings.nfo_auto_create)
+    logger.info("Update on scan: %s", settings.nfo_update_on_scan)
+    logger.info("Download poster: %s", settings.nfo_download_poster)
+    logger.info("Download logo: %s", settings.nfo_download_logo)
+    logger.info("Download fanart: %s", settings.nfo_download_fanart)
+
     if not settings.nfo_auto_create:
-        print("\n⚠️  Warning: NFO_AUTO_CREATE is set to False")
-        print("   Enable it in .env to auto-create NFO files")
-        print("\n   Continuing anyway to demonstrate functionality...")
+        logger.warning("NFO_AUTO_CREATE is set to False")
+        logger.warning("Enable it in .env to auto-create NFO files")
+        logger.info("Continuing anyway to demonstrate functionality...")
         # Override for demonstration
         settings.nfo_auto_create = True
     
-    print("\nInitializing series manager...")
+    logger.info("Initializing series manager...")
     manager = SeriesManagerService.from_settings()
-    
+
     # Get series list first
     serie_list = manager.get_serie_list()
     all_series = serie_list.get_all()
-    
-    print(f"Found {len(all_series)} series in directory")
-    
+
+    logger.info("Found %d series in directory", len(all_series))
+
     if not all_series:
-        print("\n⚠️  No series found. Add some anime series first.")
+        logger.warning("No series found. Add some anime series first.")
         return 0
     
     # Show series without NFO
@@ -65,25 +68,25 @@ async def scan_and_create_nfo():
             series_without_nfo.append(serie)
     
     if series_without_nfo:
-        print(f"\nSeries without NFO: {len(series_without_nfo)}")
+        logger.info("Series without NFO: %d", len(series_without_nfo))
         for serie in series_without_nfo[:5]:  # Show first 5
-            print(f"  - {serie.name} ({serie.folder})")
+            logger.debug("Missing NFO: %s (%s)", serie.name, serie.folder)
         if len(series_without_nfo) > 5:
-            print(f"  ... and {len(series_without_nfo) - 5} more")
+            logger.info("... and %d more", len(series_without_nfo) - 5)
     else:
-        print("\n✅ All series already have NFO files!")
-        
+        logger.info("All series already have NFO files")
+
         if not settings.nfo_update_on_scan:
-            print("\nNothing to do. Enable NFO_UPDATE_ON_SCAN to update existing NFOs.")
+            logger.info("Nothing to do. Enable NFO_UPDATE_ON_SCAN to update existing NFOs.")
             return 0
     
-    print("\nProcessing NFO files...")
-    print("(This may take a while depending on the number of series)")
-    
+    logger.info("Processing NFO files...")
+    logger.info("This may take a while depending on the number of series")
+
     try:
         await manager.scan_and_process_nfo()
-        print("\n✅ NFO processing complete!")
-        
+        logger.info("NFO processing complete")
+
         # Show updated stats
         serie_list.load_series()  # Reload to get updated stats
         all_series = serie_list.get_all()
@@ -91,17 +94,17 @@ async def scan_and_create_nfo():
         series_with_poster = [s for s in all_series if s.has_poster()]
         series_with_logo = [s for s in all_series if s.has_logo()]
         series_with_fanart = [s for s in all_series if s.has_fanart()]
-        
-        print("\nFinal Statistics:")
-        print(f"  Series with NFO:    {len(series_with_nfo)}/{len(all_series)}")
-        print(f"  Series with poster: {len(series_with_poster)}/{len(all_series)}")
-        print(f"  Series with logo:   {len(series_with_logo)}/{len(all_series)}")
-        print(f"  Series with fanart: {len(series_with_fanart)}/{len(all_series)}")
-        
-    except Exception as e:
-        print(f"\n❌ Error: {e}")
-        import traceback
-        traceback.print_exc()
+
+        logger.info("Final statistics", extra={
+            "total_series": len(all_series),
+            "with_nfo": len(series_with_nfo),
+            "with_poster": len(series_with_poster),
+            "with_logo": len(series_with_logo),
+            "with_fanart": len(series_with_fanart),
+        })
+
+    except Exception:
+        logger.exception("Failed to process NFO files")
         return 1
     finally:
         await manager.close()
@@ -111,78 +114,92 @@ async def scan_and_create_nfo():
 
 async def check_nfo_status():
     """Check NFO status for all series."""
-    print("=" * 70)
-    print("NFO Status Check")
-    print("=" * 70)
-    
+    logger.info("%s", "=" * 70)
+    logger.info("NFO Status Check")
+    logger.info("%s", "=" * 70)
+
     if not settings.anime_directory:
-        print("\n❌ Error: ANIME_DIRECTORY not configured")
+        logger.error("ANIME_DIRECTORY not configured")
         return 1
-    
-    print(f"\nAnime Directory: {settings.anime_directory}")
-    
+
+    logger.info("Anime Directory: %s", settings.anime_directory)
+
     # Create series list (no NFO service needed for status check)
     from src.core.entities.SerieList import SerieList
     serie_list = SerieList(settings.anime_directory)
     all_series = serie_list.get_all()
-    
+
     if not all_series:
-        print("\n⚠️  No series found")
+        logger.warning("No series found")
         return 0
-    
-    print(f"\nTotal series: {len(all_series)}")
-    
+
+    logger.info("Total series: %d", len(all_series))
+
     # Categorize series
     with_nfo = []
     without_nfo = []
-    
+
     for serie in all_series:
         if serie.has_nfo():
             with_nfo.append(serie)
         else:
             without_nfo.append(serie)
-    
-    print(f"\nWith NFO:    {len(with_nfo)} ({len(with_nfo) * 100 // len(all_series)}%)")
-    print(f"Without NFO: {len(without_nfo)} ({len(without_nfo) * 100 // len(all_series)}%)")
-    
+
+    logger.info(
+        "Series NFO coverage",
+        extra={
+            "with_nfo": len(with_nfo),
+            "without_nfo": len(without_nfo),
+            "total": len(all_series),
+        },
+    )
+
     if without_nfo:
-        print("\nSeries missing NFO:")
+        logger.info("Series missing NFO: %d", len(without_nfo))
         for serie in without_nfo[:10]:
-            print(f"  ❌ {serie.name} ({serie.folder})")
+            logger.debug("Missing NFO: %s (%s)", serie.name, serie.folder)
         if len(without_nfo) > 10:
-            print(f"  ... and {len(without_nfo) - 10} more")
-    
+            logger.info("... and %d more", len(without_nfo) - 10)
+
     # Media file statistics
     with_poster = sum(1 for s in all_series if s.has_poster())
     with_logo = sum(1 for s in all_series if s.has_logo())
     with_fanart = sum(1 for s in all_series if s.has_fanart())
-    
-    print("\nMedia Files:")
-    print(f"  Posters: {with_poster}/{len(all_series)} ({with_poster * 100 // len(all_series)}%)")
-    print(f"  Logos:   {with_logo}/{len(all_series)} ({with_logo * 100 // len(all_series)}%)")
-    print(f"  Fanart:  {with_fanart}/{len(all_series)} ({with_fanart * 100 // len(all_series)}%)")
-    
+
+    logger.info(
+        "Media file coverage",
+        extra={
+            "posters": with_poster,
+            "logos": with_logo,
+            "fanart": with_fanart,
+            "total": len(all_series),
+        },
+    )
+
     return 0
 
 
 async def update_nfo_files():
     """Update existing NFO files with fresh data from TMDB."""
-    print("=" * 70)
-    print("NFO Update Tool")
-    print("=" * 70)
-    
+    logger.info("%s", "=" * 70)
+    logger.info("NFO Update Tool")
+    logger.info("%s", "=" * 70)
+
     if not settings.tmdb_api_key:
-        print("\n❌ Error: TMDB_API_KEY not configured")
-        print("   Set TMDB_API_KEY in .env file or environment")
-        print("   Get API key from: https://www.themoviedb.org/settings/api")
+        logger.error("TMDB_API_KEY not configured")
+        logger.error("Set TMDB_API_KEY in .env file or environment")
+        logger.error("Get API key from: https://www.themoviedb.org/settings/api")
         return 1
-    
+
     if not settings.anime_directory:
-        print("\n❌ Error: ANIME_DIRECTORY not configured")
+        logger.error("ANIME_DIRECTORY not configured")
         return 1
-    
-    print(f"\nAnime Directory: {settings.anime_directory}")
-    print(f"Download media: {settings.nfo_download_poster or settings.nfo_download_logo or settings.nfo_download_fanart}")
+
+    logger.info("Anime Directory: %s", settings.anime_directory)
+    logger.info(
+        "Download media: %s",
+        settings.nfo_download_poster or settings.nfo_download_logo or settings.nfo_download_fanart,
+    )
     
     # Get series with NFO
     from src.core.entities.SerieList import SerieList
@@ -191,57 +208,55 @@ async def update_nfo_files():
     series_with_nfo = [s for s in all_series if s.has_nfo()]
     
     if not series_with_nfo:
-        print("\n⚠️  No series with NFO files found")
-        print("   Run 'scan' command first to create NFO files")
+        logger.warning("No series with NFO files found")
+        logger.info("Run 'scan' command first to create NFO files")
         return 0
-    
-    print(f"\nFound {len(series_with_nfo)} series with NFO files")
-    print("Updating NFO files with fresh data from TMDB...")
-    print("(This may take a while)")
-    
+
+    logger.info("Found %d series with NFO files", len(series_with_nfo))
+    logger.info("Updating NFO files with fresh data from TMDB...")
+    logger.info("This may take a while")
+
     # Initialize NFO service using factory
     from src.core.services.nfo_factory import create_nfo_service
     try:
         nfo_service = create_nfo_service()
     except ValueError as e:
-        print(f"\nError: {e}")
+        logger.error("Error creating NFO service: %s", e)
         return 1
-    
+
     success_count = 0
     error_count = 0
-    
+
     try:
         for i, serie in enumerate(series_with_nfo, 1):
-            print(f"\n[{i}/{len(series_with_nfo)}] Updating: {serie.name}")
-            
+            logger.info("[%d/%d] Updating: %s", i, len(series_with_nfo), serie.name)
+
             try:
                 await nfo_service.update_tvshow_nfo(
                     serie_folder=serie.folder,
                     download_media=(
-                        settings.nfo_download_poster or 
-                        settings.nfo_download_logo or 
+                        settings.nfo_download_poster or
+                        settings.nfo_download_logo or
                         settings.nfo_download_fanart
-                    )
+                    ),
                 )
-                print(f"  ✅ Updated successfully")
+                logger.info("Updated successfully: %s", serie.name)
                 success_count += 1
-                
+
                 # Small delay to respect API rate limits
                 await asyncio.sleep(0.5)
-                
+
             except Exception as e:
-                print(f"  ❌ Error: {e}")
+                logger.exception("Failed to update NFO for %s", serie.name)
                 error_count += 1
-        
-        print("\n" + "=" * 70)
-        print(f"✅ Update complete!")
-        print(f"  Success: {success_count}")
-        print(f"  Errors:  {error_count}")
-        
-    except Exception as e:
-        print(f"\n❌ Fatal error: {e}")
-        import traceback
-        traceback.print_exc()
+
+        logger.info("%s", "=" * 70)
+        logger.info("Update complete")
+        logger.info("Success: %d", success_count)
+        logger.info("Errors: %d", error_count)
+
+    except Exception:
+        logger.exception("Fatal error during NFO update")
         return 1
     finally:
         await nfo_service.close()
@@ -251,20 +266,22 @@ async def update_nfo_files():
 
 def main():
     """Main CLI entry point."""
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+
     if len(sys.argv) < 2:
-        print("NFO Management Tool")
-        print("\nUsage:")
-        print("  python -m src.cli.nfo_cli scan     # Scan and create missing NFO files")
-        print("  python -m src.cli.nfo_cli status   # Check NFO status for all series")
-        print("  python -m src.cli.nfo_cli update   # Update existing NFO files with fresh data")
-        print("\nConfiguration:")
-        print("  Set TMDB_API_KEY in .env file")
-        print("  Set NFO_AUTO_CREATE=true to enable auto-creation")
-        print("  Set NFO_UPDATE_ON_SCAN=true to update existing NFOs during scan")
+        logger.info("NFO Management Tool")
+        logger.info("\nUsage:")
+        logger.info("  python -m src.cli.nfo_cli scan     # Scan and create missing NFO files")
+        logger.info("  python -m src.cli.nfo_cli status   # Check NFO status for all series")
+        logger.info("  python -m src.cli.nfo_cli update   # Update existing NFO files with fresh data")
+        logger.info("\nConfiguration:")
+        logger.info("  Set TMDB_API_KEY in .env file")
+        logger.info("  Set NFO_AUTO_CREATE=true to enable auto-creation")
+        logger.info("  Set NFO_UPDATE_ON_SCAN=true to update existing NFOs during scan")
         return 1
-    
+
     command = sys.argv[1].lower()
-    
+
     if command == "scan":
         return asyncio.run(scan_and_create_nfo())
     elif command == "status":
@@ -272,8 +289,8 @@ def main():
     elif command == "update":
         return asyncio.run(update_nfo_files())
     else:
-        print(f"Unknown command: {command}")
-        print("Use 'scan', 'status', or 'update'")
+        logger.error("Unknown command: %s", command)
+        logger.info("Use 'scan', 'status', or 'update'")
         return 1
 
 

src/core/SerieScanner.py

@@ -15,7 +15,7 @@ import os
 import re
 import traceback
 import uuid
-from typing import Iterable, Iterator, Optional
+from typing import Callable, Iterable, Iterator, Optional
 
 from events import Events
 
@@ -43,12 +43,17 @@ class SerieScanner:
         scanner = SerieScanner("/path/to/anime", loader)
         scanner.scan()
         # Results are in scanner.keyDict
+
+        # With DB lookup fallback:
+        scanner = SerieScanner("/path/to/anime", loader,
+                               db_lookup=lambda folder: my_db.get_by_folder(folder))
     """
 
     def __init__(
         self,
         basePath: str,
         loader: Loader,
+        db_lookup: Optional[Callable[[str], Optional["Serie"]]] = None,
     ) -> None:
         """
         Initialize the SerieScanner.
@@ -56,8 +61,12 @@ class SerieScanner:
         Args:
             basePath: Base directory containing anime series
             loader: Loader instance for fetching series information
-            callback_manager: Optional callback manager for progress updates
-            
+            db_lookup: Optional callable ``(folder_name) -> Serie | None``.
+                When provided, it is called as a fallback when neither a
+                ``key`` file nor a ``data`` file is found in the folder.
+                This allows the database to supply the series key for
+                folders that have never had a local key file.
+
         Raises:
             ValueError: If basePath is invalid or doesn't exist
         """
@@ -75,6 +84,7 @@ class SerieScanner:
         self.directory: str = abs_path
         self.keyDict: dict[str, Serie] = {}
         self.loader: Loader = loader
+        self._db_lookup: Optional[Callable[[str], Optional[Serie]]] = db_lookup
         self._current_operation_id: Optional[str] = None
         self.events = Events()
         
@@ -268,6 +278,30 @@ class SerieScanner:
                     )
 
                     serie = self.__read_data_from_file(folder)
+                    if serie is None or not serie.key or not serie.key.strip():
+                        # Fallback: ask the database for a matching series
+                        if self._db_lookup is not None:
+                            try:
+                                serie = self._db_lookup(folder)
+                                if serie:
+                                    logger.info(
+                                        "DB lookup resolved folder '%s' -> key='%s'",
+                                        folder,
+                                        serie.key,
+                                    )
+                            except Exception as exc:
+                                logger.warning(
+                                    "DB lookup failed for folder '%s': %s",
+                                    folder,
+                                    exc,
+                                )
+                                serie = None
+
+                    if serie is None or not serie.key or not serie.key.strip():
+                        logger.warning(
+                            "No key or data file found for folder '%s', skipping",
+                            folder,
+                        )
                     if (
                         serie is not None
                         and serie.key

src/core/SeriesApp.py

@@ -14,7 +14,7 @@ import asyncio
 import logging
 import os
 from concurrent.futures import ThreadPoolExecutor
-from typing import Any, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional
 
 from events import Events
 
@@ -143,12 +143,16 @@ class SeriesApp:
     def __init__(
         self,
         directory_to_search: str,
+        db_lookup: Optional[Callable[[str], Optional["Serie"]]] = None,
     ):
         """
         Initialize SeriesApp.
 
         Args:
             directory_to_search: Base directory for anime series
+            db_lookup: Optional callable ``(folder_name) -> Serie | None``
+                passed through to ``SerieScanner`` as a fallback key source
+                when no local ``key`` or ``data`` file exists.
         """
 
         self.directory_to_search = directory_to_search
@@ -162,7 +166,7 @@ class SeriesApp:
         self.loaders = Loaders()
         self.loader = self.loaders.GetLoader(key="aniworld.to")
         self.serie_scanner = SerieScanner(
-            directory_to_search, self.loader
+            directory_to_search, self.loader, db_lookup=db_lookup
         )
         # Skip automatic loading from data files - series will be loaded
         # from database by the service layer during application setup
@@ -171,23 +175,26 @@ class SeriesApp:
         # Initialize empty list - series loaded later via load_series_from_list()
         # No need to call _init_list_sync() anymore
         
-        # Initialize NFO service if TMDB API key is configured
+        # Initialize NFO service if a TMDB API key is configured
         self.nfo_service: Optional[NFOService] = None
-        if settings.tmdb_api_key:
-            try:
-                from src.core.services.nfo_factory import get_nfo_factory
-                factory = get_nfo_factory()
-                self.nfo_service = factory.create()
-                logger.info("NFO service initialized successfully")
-            except (ValueError, Exception) as e:  # pylint: disable=broad-except
-                logger.warning(
-                    "Failed to initialize NFO service: %s", str(e)
-                )
-                self.nfo_service = None
+        try:
+            from src.core.services.nfo_factory import get_nfo_factory
+
+            factory = get_nfo_factory()
+            self.nfo_service = factory.create()
+            logger.info("NFO service initialized successfully")
+        except ValueError:
+            logger.info(
+                "NFO service not available — TMDB API key not configured"
+            )
+            self.nfo_service = None
+        except Exception as e:  # pylint: disable=broad-except
+            logger.warning("Failed to initialize NFO service: %s", str(e))
+            self.nfo_service = None
 
         logger.info(
             "SeriesApp initialized for directory: %s",
-            directory_to_search
+            directory_to_search,
         )
 
     @property
@@ -438,9 +445,12 @@ class SeriesApp:
         try:
             def download_progress_handler(progress_info):
                 """Handle download progress events from loader."""
-                logger.debug(
-                    "download_progress_handler called with: %s", progress_info
-                )
+                # Throttle progress logging to avoid spam
+                status = progress_info.get("status", "")
+                if status in ("downloading", "finished"):
+                    logger.debug(
+                        "download_progress_handler called with: %s", progress_info
+                    )
 
                 downloaded = progress_info.get('downloaded_bytes', 0)
                 total_bytes = (

src/core/entities/SerieList.py

@@ -121,11 +121,11 @@ class SerieList:
     def load_series(self) -> None:
         """Populate the in-memory map with metadata discovered on disk."""
 
-        logging.info("Scanning anime folders in %s", self.directory)
+        logger.info("Scanning anime folders in %s", self.directory)
         try:
             entries: Iterable[str] = os.listdir(self.directory)
         except OSError as error:
-            logging.error(
+            logger.error(
                 "Unable to scan directory %s: %s",
                 self.directory,
                 error,
@@ -145,7 +145,7 @@ class SerieList:
         for anime_folder in entries:
             anime_path = os.path.join(self.directory, anime_folder, "data")
             if os.path.isfile(anime_path):
-                logging.debug("Found data file for folder %s", anime_folder)
+                logger.debug("Found data file for folder %s", anime_folder)
                 serie = self._load_data(anime_folder, anime_path)
                 
                 if serie:
@@ -159,7 +159,7 @@ class SerieList:
                         nfo_stats["with_nfo"] += 1
                     else:
                         nfo_stats["without_nfo"] += 1
-                        logging.debug(
+                        logger.debug(
                             "Series '%s' (key: %s) is missing tvshow.nfo",
                             serie.name,
                             serie.key
@@ -173,7 +173,7 @@ class SerieList:
                         media_stats["with_poster"] += 1
                     else:
                         media_stats["without_poster"] += 1
-                        logging.debug(
+                        logger.debug(
                             "Series '%s' (key: %s) is missing poster.jpg",
                             serie.name,
                             serie.key
@@ -184,7 +184,7 @@ class SerieList:
                         media_stats["with_logo"] += 1
                     else:
                         media_stats["without_logo"] += 1
-                        logging.debug(
+                        logger.debug(
                             "Series '%s' (key: %s) is missing logo.png",
                             serie.name,
                             serie.key
@@ -195,7 +195,7 @@ class SerieList:
                         media_stats["with_fanart"] += 1
                     else:
                         media_stats["without_fanart"] += 1
-                        logging.debug(
+                        logger.debug(
                             "Series '%s' (key: %s) is missing fanart.jpg",
                             serie.name,
                             serie.key
@@ -203,20 +203,20 @@ class SerieList:
                 
                 continue
 
-            logging.warning(
+            logger.warning(
                 "Skipping folder %s because no metadata file was found",
                 anime_folder,
             )
         
         # Log summary statistics
         if nfo_stats["total"] > 0:
-            logging.info(
+            logger.info(
                 "NFO scan complete: %d series total, %d with NFO, %d without NFO",
                 nfo_stats["total"],
                 nfo_stats["with_nfo"],
                 nfo_stats["without_nfo"]
             )
-            logging.info(
+            logger.info(
                 "Media scan complete: Poster (%d/%d), Logo (%d/%d), Fanart (%d/%d)",
                 media_stats["with_poster"],
                 nfo_stats["total"],
@@ -241,14 +241,14 @@ class SerieList:
             serie = Serie.load_from_file(data_path)
             # Store by key, not folder
             self.keyDict[serie.key] = serie
-            logging.debug(
+            logger.debug(
                 "Successfully loaded metadata for %s (key: %s)",
                 anime_folder,
                 serie.key
             )
             return serie
         except (OSError, JSONDecodeError, KeyError, ValueError) as error:
-            logging.error(
+            logger.error(
                 "Failed to load metadata for folder %s from %s: %s",
                 anime_folder,
                 data_path,

src/core/entities/series.py

@@ -64,6 +64,16 @@ class Serie:
             f"episodeDict={self.episodeDict}{year_str})"
         )
 
+    def __repr__(self):
+        """Concise developer representation of Serie object."""
+        season_count = len(self.episodeDict)
+        episode_count = sum(len(eps) for eps in self.episodeDict.values())
+        year_str = f", year={self.year}" if self.year else ""
+        return (
+            f"Serie(key={self.key!r}, name={self.name!r}"
+            f"{year_str}, seasons={season_count}, episodes={episode_count})"
+        )
+
     @property
     def key(self) -> str:
         """
@@ -261,7 +271,11 @@ class Serie:
             'Dororo (2025)'
         """
         if self._year:
-            return f"{self._name} ({self._year})"
+            import re
+            year_suffix = f" ({self._year})"
+            # Strip ALL trailing year suffixes before appending to prevent duplication
+            clean_name = re.sub(r'(\s*\(\d{4}\))+\s*$', '', self._name).strip()
+            return f"{clean_name}{year_suffix}"
         return self._name
 
     @property

src/core/error_handler.py

@@ -55,7 +55,8 @@ class RecoveryStrategies:
                 if attempt == max_retries - 1:
                     raise
                 logger.warning(
-                    f"Network error on attempt {attempt + 1}, retrying..."
+                    "Network error on attempt %d, retrying...",
+                    attempt + 1,
                 )
                 continue
 
@@ -72,7 +73,8 @@ class RecoveryStrategies:
                 if attempt == max_retries - 1:
                     raise
                 logger.warning(
-                    f"Download error on attempt {attempt + 1}, retrying..."
+                    "Download error on attempt %d, retrying...",
+                    attempt + 1,
                 )
                 continue
 
@@ -92,7 +94,7 @@ class FileCorruptionDetector:
             # Video files should be at least 1MB
             return file_size > 1024 * 1024
         except Exception as e:
-            logger.error(f"Error checking file validity: {e}")
+            logger.error("Error checking file validity: %s", e)
             return False
 
 
@@ -123,13 +125,18 @@ def with_error_recovery(
                     last_error = e
                     if attempt < max_retries - 1:
                         logger.warning(
-                            f"Error in {context} (attempt {attempt + 1}/"
-                            f"{max_retries}): {e}, retrying..."
+                            "Error in %s (attempt %d/%d): %s, retrying...",
+                            context,
+                            attempt + 1,
+                            max_retries,
+                            e,
                         )
                     else:
                         logger.error(
-                            f"Error in {context} failed after {max_retries} "
-                            f"attempts: {e}"
+                            "Error in %s failed after %d attempts: %s",
+                            context,
+                            max_retries,
+                            e,
                         )
 
             if last_error:

src/core/interfaces/callbacks.py

@@ -12,6 +12,8 @@ from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any, Dict, Optional
 
+logger = logging.getLogger(__name__)
+
 
 class OperationType(str, Enum):
     """Types of operations that can report progress."""
@@ -313,7 +315,7 @@ class CallbackManager:
                 callback.on_progress(context)
             except Exception as e:
                 # Log but don't let callback errors break the operation
-                logging.error(
+                logger.error(
                     "Error in progress callback %s: %s",
                     callback,
                     e,
@@ -332,7 +334,7 @@ class CallbackManager:
                 callback.on_error(context)
             except Exception as e:
                 # Log but don't let callback errors break the operation
-                logging.error(
+                logger.error(
                     "Error in error callback %s: %s",
                     callback,
                     e,
@@ -351,7 +353,7 @@ class CallbackManager:
                 callback.on_completion(context)
             except Exception as e:
                 # Log but don't let callback errors break the operation
-                logging.error(
+                logger.error(
                     "Error in completion callback %s: %s",
                     callback,
                     e,

src/core/providers/config_manager.py

@@ -87,7 +87,7 @@ class ProviderConfigManager:
             settings: Provider settings to apply.
         """
         self._provider_settings[provider_name] = settings
-        logger.info(f"Updated settings for provider: {provider_name}")
+        logger.info("Updated settings for provider: %s", provider_name)
 
     def update_provider_settings(
         self, provider_name: str, **kwargs
@@ -106,7 +106,7 @@ class ProviderConfigManager:
             self._provider_settings[provider_name] = ProviderSettings(
                 name=provider_name, **kwargs
             )
-            logger.info(f"Created new settings for provider: {provider_name}")  # noqa: E501
+            logger.info("Created new settings for provider: %s", provider_name)  # noqa: E501
             return True
 
         settings = self._provider_settings[provider_name]
@@ -152,7 +152,7 @@ class ProviderConfigManager:
         """
         if provider_name in self._provider_settings:
             self._provider_settings[provider_name].enabled = True
-            logger.info(f"Enabled provider: {provider_name}")
+            logger.info("Enabled provider: %s", provider_name)
             return True
         return False
 
@@ -167,7 +167,7 @@ class ProviderConfigManager:
         """
         if provider_name in self._provider_settings:
             self._provider_settings[provider_name].enabled = False
-            logger.info(f"Disabled provider: {provider_name}")
+            logger.info("Disabled provider: %s", provider_name)
             return True
         return False
 
@@ -224,7 +224,7 @@ class ProviderConfigManager:
             value: Setting value.
         """
         self._global_settings[key] = value
-        logger.info(f"Updated global setting {key}: {value}")
+        logger.info("Updated global setting %s: %s", key, value)
 
     def get_all_global_settings(self) -> Dict[str, Any]:
         """Get all global settings.
@@ -307,7 +307,7 @@ class ProviderConfigManager:
             with open(config_path, "w", encoding="utf-8") as f:
                 json.dump(data, f, indent=2)
 
-            logger.info(f"Saved configuration to {config_path}")
+            logger.info("Saved configuration to %s", config_path)
             return True
 
         except Exception as e:

src/core/providers/failover.py

@@ -207,7 +207,7 @@ class ProviderFailover:
         """
         if provider_name not in self._providers:
             self._providers.append(provider_name)
-            logger.info(f"Added provider to failover chain: {provider_name}")
+            logger.info("Added provider to failover chain: %s", provider_name)
 
     def remove_provider(self, provider_name: str) -> bool:
         """Remove a provider from the failover chain.

src/core/providers/health_monitor.py

@@ -151,7 +151,7 @@ class ProviderHealthMonitor:
             except asyncio.CancelledError:
                 break
             except Exception as e:
-                logger.error(f"Error in health check loop: {e}", exc_info=True)
+                logger.exception("Error in health check loop: %s", e)
                 await asyncio.sleep(self._health_check_interval)
 
     async def _perform_health_checks(self) -> None:
@@ -314,7 +314,7 @@ class ProviderHealthMonitor:
         )
 
         best_provider = available[0][0]
-        logger.debug(f"Best provider selected: {best_provider}")
+        logger.debug("Best provider selected: %s", best_provider)
         return best_provider
 
     def _get_recent_metrics(
@@ -355,7 +355,7 @@ class ProviderHealthMonitor:
             provider_name=provider_name
         )
         self._request_history[provider_name].clear()
-        logger.info(f"Reset metrics for provider: {provider_name}")
+        logger.info("Reset metrics for provider: %s", provider_name)
         return True
 
     def get_health_summary(self) -> Dict[str, Any]:

src/core/services/nfo_repair_service.py

@@ -120,6 +120,37 @@ def nfo_needs_repair(nfo_path: Path) -> bool:
     return bool(find_missing_tags(nfo_path))
 
 
+def _read_tmdb_id(nfo_path: Path) -> int | None:
+    """Return the TMDB ID stored in an existing NFO, or ``None``.
+
+    Checks both ``<tmdbid>`` and ``<uniqueid type="tmdb">`` elements.
+
+    Args:
+        nfo_path: Absolute path to the ``tvshow.nfo`` file.
+
+    Returns:
+        Integer TMDB ID, or ``None`` if not found or not parseable.
+    """
+    if not nfo_path.exists():
+        return None
+    try:
+        root = etree.parse(str(nfo_path)).getroot()
+
+        for uniqueid in root.findall(".//uniqueid"):
+            if uniqueid.get("type") == "tmdb" and uniqueid.text:
+                return int(uniqueid.text)
+
+        tmdbid_elem = root.find(".//tmdbid")
+        if tmdbid_elem is not None and tmdbid_elem.text:
+            return int(tmdbid_elem.text)
+
+    except (etree.XMLSyntaxError, ValueError):
+        pass
+    except Exception:  # pylint: disable=broad-except
+        pass
+    return None
+
+
 class NfoRepairService:
     """Service that detects and repairs incomplete tvshow.nfo files.
 

src/core/services/nfo_service.py

@@ -83,11 +83,12 @@ class NFOService:
             >>> _extract_year_from_name("Attack on Titan")
             ("Attack on Titan", None)
         """
-        # Match year in parentheses at the end: (YYYY)
+        # Match the last year in parentheses at the end: (YYYY)
         match = re.search(r'\((\d{4})\)\s*$', serie_name)
         if match:
             year = int(match.group(1))
-            clean_name = serie_name[:match.start()].strip()
+            # Strip ALL trailing year suffixes to get a fully clean name
+            clean_name = re.sub(r'(\s*\(\d{4}\))+\s*$', '', serie_name).strip()
             return clean_name, year
         return serie_name, None
     
@@ -134,48 +135,76 @@ class NFOService:
         clean_name, extracted_year = self._extract_year_from_name(serie_name)
         if year is None and extracted_year is not None:
             year = extracted_year
-            logger.info(f"Extracted year {year} from series name")
+            logger.info("Extracted year %s from series name", year)
         
         # Use clean name for search
         search_name = clean_name
         
-        logger.info(f"Creating NFO for {search_name} (year: {year})")
+        logger.info("Creating NFO for %s (year: %s)", search_name, year)
         
         folder_path = self.anime_directory / serie_folder
         if not folder_path.exists():
-            logger.info(f"Creating series folder: {folder_path}")
+            logger.info("Creating series folder: %s", folder_path)
             folder_path.mkdir(parents=True, exist_ok=True)
         
-        async with self.tmdb_client:
+        try:
+            await self.tmdb_client._ensure_session()
+
             # Search for TV show with clean name (without year)
-            logger.debug(f"Searching TMDB for: {search_name}")
+            logger.debug("Searching TMDB for: %s", search_name)
             search_results = await self.tmdb_client.search_tv_show(search_name)
-            
+
             if not search_results.get("results"):
                 raise TMDBAPIError(f"No results found for: {search_name}")
-            
+
             # Find best match (consider year if provided)
             tv_show = self._find_best_match(search_results["results"], search_name, year)
             tv_id = tv_show["id"]
-            
-            logger.info(f"Found match: {tv_show['name']} (ID: {tv_id})")
-            
+
+            logger.info("Found match: %s (ID: %s)", tv_show['name'], tv_id)
+
             # Get detailed information with multi-language image support
             details = await self.tmdb_client.get_tv_show_details(
                 tv_id,
                 append_to_response="credits,external_ids,images"
             )
-            
+
             # Get content ratings for FSK
             content_ratings = await self.tmdb_client.get_tv_show_content_ratings(tv_id)
-            
+
             # Enrich with fallback languages for empty overview/tagline
             # Pass search result overview as last resort fallback
             search_overview = tv_show.get("overview") or None
+            if not search_overview:
+                try:
+                    logger.debug(
+                        "No overview in German search result, trying en-US search fallback for: %s",
+                        search_name,
+                    )
+                    en_search_results = await self.tmdb_client.search_tv_show(
+                        search_name,
+                        language="en-US",
+                    )
+                    if en_search_results.get("results"):
+                        en_match = self._find_best_match(
+                            en_search_results["results"], search_name, year
+                        )
+                        search_overview = en_match.get("overview") or None
+                        if search_overview:
+                            logger.info(
+                                "Using en-US search overview fallback for %s",
+                                search_name,
+                            )
+                except (TMDBAPIError, Exception) as exc:
+                    logger.warning(
+                        "Failed en-US search fallback for overview: %s",
+                        exc,
+                    )
+
             details = await self._enrich_details_with_fallback(
                 details, search_overview=search_overview
             )
-            
+
             # Convert TMDB data to TVShowNFO model
             nfo_model = tmdb_to_nfo_model(
                 details,
@@ -183,15 +212,15 @@ class NFOService:
                 self.tmdb_client.get_image_url,
                 self.image_size,
             )
-            
+
             # Generate XML
             nfo_xml = generate_tvshow_nfo(nfo_model)
-            
+
             # Save NFO file
             nfo_path = folder_path / "tvshow.nfo"
             nfo_path.write_text(nfo_xml, encoding="utf-8")
-            logger.info(f"Created NFO: {nfo_path}")
-            
+            logger.info("Created NFO: %s", nfo_path)
+
             # Download media files
             await self._download_media_files(
                 details,
@@ -200,8 +229,10 @@ class NFOService:
                 download_logo=download_logo,
                 download_fanart=download_fanart
             )
-            
+
             return nfo_path
+        finally:
+            await self.tmdb_client.close()
     
     async def update_tvshow_nfo(
         self,
@@ -227,7 +258,7 @@ class NFOService:
         if not nfo_path.exists():
             raise FileNotFoundError(f"NFO file not found: {nfo_path}")
         
-        logger.info(f"Updating NFO for {serie_folder}")
+        logger.info("Updating NFO for %s", serie_folder)
         
         # Parse existing NFO to extract TMDB ID
         try:
@@ -253,26 +284,26 @@ class NFOService:
                     f"Delete the NFO and create a new one instead."
                 )
             
-            logger.debug(f"Found TMDB ID: {tmdb_id}")
+            logger.debug("Found TMDB ID: %s", tmdb_id)
             
         except etree.XMLSyntaxError as e:
             raise TMDBAPIError(f"Invalid XML in NFO file: {e}")
         except ValueError as e:
             raise TMDBAPIError(f"Invalid TMDB ID format in NFO: {e}")
         
-        # Fetch fresh data from TMDB
-        async with self.tmdb_client:
-            logger.debug(f"Fetching fresh data for TMDB ID: {tmdb_id}")
+        try:
+            await self.tmdb_client._ensure_session()
+            logger.debug("Fetching fresh data for TMDB ID: %s", tmdb_id)
             details = await self.tmdb_client.get_tv_show_details(
                 tmdb_id,
                 append_to_response="credits,external_ids,images"
             )
-            
+
             # Get content ratings for FSK
             content_ratings = await self.tmdb_client.get_tv_show_content_ratings(tmdb_id)
-            
+
             # Enrich with fallback languages for empty overview/tagline
-            details = await self._enrich_details_with_fallback(details)            
+            details = await self._enrich_details_with_fallback(details)
             # Convert TMDB data to TVShowNFO model
             nfo_model = tmdb_to_nfo_model(
                 details,
@@ -280,14 +311,14 @@ class NFOService:
                 self.tmdb_client.get_image_url,
                 self.image_size,
             )
-            
+
             # Generate XML
             nfo_xml = generate_tvshow_nfo(nfo_model)
-            
+
             # Save updated NFO file
             nfo_path.write_text(nfo_xml, encoding="utf-8")
-            logger.info(f"Updated NFO: {nfo_path}")
-            
+            logger.info("Updated NFO: %s", nfo_path)
+
             # Re-download media files if requested
             if download_media:
                 await self._download_media_files(
@@ -297,8 +328,10 @@ class NFOService:
                     download_logo=True,
                     download_fanart=True
                 )
-            
+
             return nfo_path
+        finally:
+            await self.tmdb_client.close()
     
     def parse_nfo_ids(self, nfo_path: Path) -> Dict[str, Optional[int]]:
         """Parse TMDB ID and TVDB ID from an existing NFO file.
@@ -318,7 +351,7 @@ class NFOService:
         result = {"tmdb_id": None, "tvdb_id": None}
         
         if not nfo_path.exists():
-            logger.debug(f"NFO file not found: {nfo_path}")
+            logger.debug("NFO file not found: %s", nfo_path)
             return result
         
         try:
@@ -375,9 +408,9 @@ class NFOService:
             )
             
         except etree.XMLSyntaxError as e:
-            logger.error(f"Invalid XML in NFO file {nfo_path}: {e}")
+            logger.error("Invalid XML in NFO file %s: %s", nfo_path, e)
         except Exception as e:  # pylint: disable=broad-except
-            logger.error(f"Error parsing NFO file {nfo_path}: {e}")
+            logger.error("Error parsing NFO file %s: %s", nfo_path, e)
         
         return result
     
@@ -480,7 +513,7 @@ class NFOService:
             for result in results:
                 first_air_date = result.get("first_air_date", "")
                 if first_air_date.startswith(str(year)):
-                    logger.debug(f"Found year match: {result['name']} ({first_air_date})")
+                    logger.debug("Found year match: %s (%s)", result['name'], first_air_date)
                     return result
         
         # Return first result (usually best match)
@@ -545,7 +578,7 @@ class NFOService:
             skip_existing=True
         )
         
-        logger.info(f"Media download results: {results}")
+        logger.info("Media download results: %s", results)
         return results
     
 

src/core/services/series_manager_service.py

@@ -136,7 +136,7 @@ class SeriesManagerService:
             
             # If NFO exists, parse IDs and update database
             if nfo_exists:
-                logger.debug(f"Parsing IDs from existing NFO for '{serie_name}'")
+                logger.debug("Parsing IDs from existing NFO for '%s'", serie_name)
                 ids = self.nfo_service.parse_nfo_ids(nfo_path)
                 
                 if ids["tmdb_id"] or ids["tvdb_id"]:
@@ -203,14 +203,14 @@ class SeriesManagerService:
                     download_logo=self.download_logo,
                     download_fanart=self.download_fanart
                 )
-                logger.info(f"Successfully created NFO for '{serie_name}'")
+                logger.info("Successfully created NFO for '%s'", serie_name)
             elif nfo_exists:
                 logger.debug(
                     f"NFO exists for '{serie_name}', skipping download"
                 )
                     
         except TMDBAPIError as e:
-            logger.error(f"TMDB API error processing '{serie_name}': {e}")
+            logger.error("TMDB API error processing '%s': %s", serie_name, e)
         except Exception as e:
             logger.error(
                 f"Unexpected error processing NFO for '{serie_name}': {e}",
@@ -246,7 +246,7 @@ class SeriesManagerService:
             logger.info("No series found in database to process")
             return
         
-        logger.info(f"Processing NFO for {len(anime_series_list)} series...")
+        logger.info("Processing NFO for %s series...", len(anime_series_list))
         
         # Create tasks for concurrent processing
         # Each task creates its own database session

src/core/services/tmdb_client.py

@@ -107,7 +107,7 @@ class TMDBClient:
         # Cache key for deduplication
         cache_key = f"{endpoint}:{str(sorted(params.items()))}"
         if cache_key in self._cache:
-            logger.debug(f"Cache hit for {endpoint}")
+            logger.debug("Cache hit for %s", endpoint)
             return self._cache[cache_key]
         
         delay = 1
@@ -121,7 +121,7 @@ class TMDBClient:
                 if self.session is None:
                     raise TMDBAPIError("Session is not available")
                 
-                logger.debug(f"TMDB API request: {endpoint} (attempt {attempt + 1})")
+                logger.debug("TMDB API request: %s (attempt %s)", endpoint, attempt + 1)
                 async with self.session.get(url, params=params, timeout=aiohttp.ClientTimeout(total=60)) as resp:
                     if resp.status == 401:
                         raise TMDBAPIError("Invalid TMDB API key")
@@ -130,7 +130,7 @@ class TMDBClient:
                     elif resp.status == 429:
                         # Rate limit - wait longer
                         retry_after = int(resp.headers.get('Retry-After', delay * 2))
-                        logger.warning(f"Rate limited, waiting {retry_after}s")
+                        logger.warning("Rate limited, waiting %ss", retry_after)
                         await asyncio.sleep(retry_after)
                         continue
                     
@@ -142,26 +142,26 @@ class TMDBClient:
             except asyncio.TimeoutError as e:
                 last_error = e
                 if attempt < max_retries - 1:
-                    logger.warning(f"Request timeout (attempt {attempt + 1}), retrying in {delay}s")
+                    logger.warning("Request timeout (attempt %s), retrying in %ss", attempt + 1, delay)
                     await asyncio.sleep(delay)
                     delay *= 2
                 else:
-                    logger.error(f"Request timed out after {max_retries} attempts")
+                    logger.error("Request timed out after %s attempts", max_retries)
                     
             except (aiohttp.ClientError, AttributeError) as e:
                 last_error = e
                 # If connector/session was closed, try to recreate it
                 if "Connector is closed" in str(e) or isinstance(e, AttributeError):
-                    logger.warning(f"Session issue detected, recreating session: {e}")
+                    logger.warning("Session issue detected, recreating session: %s", e)
                     self.session = None
                     await self._ensure_session()
                 
                 if attempt < max_retries - 1:
-                    logger.warning(f"Request failed (attempt {attempt + 1}): {e}, retrying in {delay}s")
+                    logger.warning("Request failed (attempt %s): %s, retrying in %ss", attempt + 1, e, delay)
                     await asyncio.sleep(delay)
                     delay *= 2
                 else:
-                    logger.error(f"Request failed after {max_retries} attempts: {e}")
+                    logger.error("Request failed after %s attempts: %s", max_retries, e)
         
         raise TMDBAPIError(f"Request failed after {max_retries} attempts: {last_error}")
     
@@ -275,7 +275,7 @@ class TMDBClient:
         url = f"{self.image_base_url}/{size}{image_path}"
         
         try:
-            logger.debug(f"Downloading image from {url}")
+            logger.debug("Downloading image from %s", url)
             async with self.session.get(url, timeout=aiohttp.ClientTimeout(total=60)) as resp:
                 resp.raise_for_status()
                 
@@ -286,7 +286,7 @@ class TMDBClient:
                 with open(local_path, "wb") as f:
                     f.write(await resp.read())
                 
-                logger.info(f"Downloaded image to {local_path}")
+                logger.info("Downloaded image to %s", local_path)
                 
         except aiohttp.ClientError as e:
             raise TMDBAPIError(f"Failed to download image: {e}")

src/core/utils/image_downloader.py

@@ -125,7 +125,7 @@ class ImageDownloader:
         # Check if file already exists
         if skip_existing and local_path.exists():
             if local_path.stat().st_size >= self.min_file_size:
-                logger.debug(f"Image already exists: {local_path}")
+                logger.debug("Image already exists: %s", local_path)
                 return True
         
         # Ensure parent directory exists
@@ -137,15 +137,16 @@ class ImageDownloader:
         for attempt in range(self.max_retries):
             try:
                 logger.debug(
-                    f"Downloading image from {url} "
-                    f"(attempt {attempt + 1})"
+                    "Downloading image from %s (attempt %d)",
+                    url,
+                    attempt + 1,
                 )
                 
                 # Use persistent session
                 session = self._get_session()
                 async with session.get(url) as resp:
                     if resp.status == 404:
-                        logger.warning(f"Image not found: {url}")
+                        logger.warning("Image not found: %s", url)
                         return False
                     
                     resp.raise_for_status()
@@ -168,21 +169,25 @@ class ImageDownloader:
                         local_path.unlink(missing_ok=True)
                         raise ImageDownloadError("Image validation failed")
                     
-                    logger.info(f"Downloaded image to {local_path}")
+                    logger.info("Downloaded image to %s", local_path)
                     return True
                         
             except (aiohttp.ClientError, IOError, ImageDownloadError) as e:
                 last_error = e
                 if attempt < self.max_retries - 1:
                     logger.warning(
-                        f"Download failed (attempt {attempt + 1}): {e}, "
-                        f"retrying in {delay}s"
+                        "Download failed (attempt %d): %s, retrying in %s",
+                        attempt + 1,
+                        e,
+                        delay,
                     )
                     await asyncio.sleep(delay)
                     delay *= 2
                 else:
                     logger.error(
-                        f"Download failed after {self.max_retries} attempts: {e}"
+                        "Download failed after %d attempts: %s",
+                        self.max_retries,
+                        e,
                     )
         
         raise ImageDownloadError(
@@ -211,7 +216,7 @@ class ImageDownloader:
         try:
             return await self.download_image(url, local_path, skip_existing)
         except ImageDownloadError as e:
-            logger.warning(f"Failed to download poster: {e}")
+            logger.warning("Failed to download poster: %s", e)
             return False
     
     async def download_logo(
@@ -236,7 +241,7 @@ class ImageDownloader:
         try:
             return await self.download_image(url, local_path, skip_existing)
         except ImageDownloadError as e:
-            logger.warning(f"Failed to download logo: {e}")
+            logger.warning("Failed to download logo: %s", e)
             return False
     
     async def download_fanart(
@@ -261,7 +266,7 @@ class ImageDownloader:
         try:
             return await self.download_image(url, local_path, skip_existing)
         except ImageDownloadError as e:
-            logger.warning(f"Failed to download fanart: {e}")
+            logger.warning("Failed to download fanart: %s", e)
             return False
     
     def validate_image(self, image_path: Path) -> bool:
@@ -280,13 +285,13 @@ class ImageDownloader:
             
             # Check file size
             if image_path.stat().st_size < self.min_file_size:
-                logger.warning(f"Image file too small: {image_path}")
+                logger.warning("Image file too small: %s", image_path)
                 return False
             
             return True
             
         except Exception as e:
-            logger.warning(f"Image validation failed for {image_path}: {e}")
+            logger.warning("Image validation failed for %s: %s", image_path, e)
             return False
     
     async def download_all_media(
@@ -341,7 +346,7 @@ class ImageDownloader:
             
             for (media_type, _), result in zip(tasks, task_results):
                 if isinstance(result, Exception):
-                    logger.error(f"Error downloading {media_type}: {result}")
+                    logger.error("Error downloading %s: %s", media_type, result)
                     results[media_type] = False
                 else:
                     results[media_type] = result

src/core/utils/nfo_generator.py

@@ -209,5 +209,5 @@ def validate_nfo_xml(xml_string: str) -> bool:
         etree.fromstring(xml_string.encode('utf-8'))
         return True
     except etree.XMLSyntaxError as e:
-        logger.error(f"Invalid NFO XML: {e}")
+        logger.error("Invalid NFO XML: %s", e)
         return False

src/infrastructure/security/config_encryption.py

@@ -36,10 +36,10 @@ class ConfigEncryption:
     def _ensure_key_exists(self) -> None:
         """Ensure encryption key exists or create one."""
         if not self.key_file.exists():
-            logger.info(f"Creating new encryption key at {self.key_file}")
+            logger.info("Creating new encryption key at %s", self.key_file)
             self._generate_new_key()
         else:
-            logger.info(f"Using existing encryption key from {self.key_file}")
+            logger.info("Using existing encryption key from %s", self.key_file)
 
     def _generate_new_key(self) -> None:
         """Generate and store a new encryption key."""
@@ -56,7 +56,7 @@ class ConfigEncryption:
             logger.info("Generated new encryption key")
 
         except IOError as e:
-            logger.error(f"Failed to generate encryption key: {e}")
+            logger.error("Failed to generate encryption key: %s", e)
             raise
 
     def _load_key(self) -> bytes:
@@ -77,7 +77,7 @@ class ConfigEncryption:
             key = self.key_file.read_bytes()
             return key
         except IOError as e:
-            logger.error(f"Failed to load encryption key: {e}")
+            logger.error("Failed to load encryption key: %s", e)
             raise
 
     def _get_cipher(self) -> Fernet:
@@ -117,7 +117,7 @@ class ConfigEncryption:
             return encrypted_str
 
         except Exception as e:
-            logger.error(f"Failed to encrypt value: {e}")
+            logger.error("Failed to encrypt value: %s", e)
             raise
 
     def decrypt_value(self, encrypted_value: str) -> str:
@@ -149,7 +149,7 @@ class ConfigEncryption:
             return decrypted_str
 
         except Exception as e:
-            logger.error(f"Failed to decrypt value: {e}")
+            logger.error("Failed to decrypt value: %s", e)
             raise
 
     def encrypt_config(self, config: Dict[str, Any]) -> Dict[str, Any]:
@@ -191,9 +191,9 @@ class ConfigEncryption:
                         'encrypted': True,
                         'value': self.encrypt_value(value)
                     }
-                    logger.debug(f"Encrypted config field: {key}")
+                    logger.debug("Encrypted config field: %s", key)
                 except Exception as e:
-                    logger.warning(f"Failed to encrypt {key}: {e}")
+                    logger.warning("Failed to encrypt %s: %s", key, e)
                     encrypted_config[key] = value
             else:
                 encrypted_config[key] = value
@@ -222,9 +222,9 @@ class ConfigEncryption:
                     decrypted_config[key] = self.decrypt_value(
                         value['value']
                     )
-                    logger.debug(f"Decrypted config field: {key}")
+                    logger.debug("Decrypted config field: %s", key)
                 except Exception as e:
-                    logger.error(f"Failed to decrypt {key}: {e}")
+                    logger.error("Failed to decrypt %s: %s", key, e)
                     decrypted_config[key] = None
             else:
                 decrypted_config[key] = value
@@ -248,7 +248,7 @@ class ConfigEncryption:
         if self.key_file.exists():
             backup_path = self.key_file.with_suffix('.key.bak')
             self.key_file.rename(backup_path)
-            logger.info(f"Backed up old key to {backup_path}")
+            logger.info("Backed up old key to %s", backup_path)
 
         # Generate new key
         if new_key_file:

src/infrastructure/security/database_integrity.py

@@ -276,13 +276,13 @@ class DatabaseIntegrityChecker:
                 removed += 1
 
             self.session.commit()
-            logger.info(f"Removed {removed} orphaned records")
+            logger.info("Removed %s orphaned records", removed)
 
             return removed
 
         except Exception as e:
             self.session.rollback()
-            logger.error(f"Error removing orphaned records: {e}")
+            logger.error("Error removing orphaned records: %s", e)
             raise
 
 

src/infrastructure/security/file_integrity.py

@@ -39,13 +39,15 @@ class FileIntegrityManager:
                     self.checksums = json.load(f)
                 count = len(self.checksums)
                 logger.info(
-                    f"Loaded {count} checksums from {self.checksum_file}"
+                    "Loaded %d checksums from %s",
+                    count,
+                    self.checksum_file,
                 )
             except (json.JSONDecodeError, IOError) as e:
-                logger.error(f"Failed to load checksums: {e}")
+                logger.error("Failed to load checksums: %s", e)
                 self.checksums = {}
         else:
-            logger.info(f"Checksum file does not exist: {self.checksum_file}")
+            logger.info("Checksum file does not exist: %s", self.checksum_file)
             self.checksums = {}
 
     def _save_checksums(self) -> None:
@@ -56,10 +58,12 @@ class FileIntegrityManager:
                 json.dump(self.checksums, f, indent=2)
             count = len(self.checksums)
             logger.debug(
-                f"Saved {count} checksums to {self.checksum_file}"
+                "Saved %d checksums to %s",
+                count,
+                self.checksum_file,
             )
         except IOError as e:
-            logger.error(f"Failed to save checksums: {e}")
+            logger.error("Failed to save checksums: %s", e)
 
     def calculate_checksum(
         self, file_path: Path, algorithm: str = "sha256"
@@ -94,12 +98,15 @@ class FileIntegrityManager:
             checksum = hash_obj.hexdigest()
             filename = file_path.name
             logger.debug(
-                f"Calculated {algorithm} checksum for {filename}: {checksum}"
+                "Calculated %s checksum for %s: %s",
+                algorithm,
+                filename,
+                checksum,
             )
             return checksum
         
         except IOError as e:
-            logger.error(f"Failed to read file {file_path}: {e}")
+            logger.error("Failed to read file %s: %s", file_path, e)
             raise
 
     def store_checksum(
@@ -126,7 +133,7 @@ class FileIntegrityManager:
         self.checksums[key] = checksum
         self._save_checksums()
         
-        logger.info(f"Stored checksum for {file_path.name}")
+        logger.info("Stored checksum for %s", file_path.name)
         return checksum
 
     def verify_checksum(
@@ -197,10 +204,10 @@ class FileIntegrityManager:
         if key in self.checksums:
             del self.checksums[key]
             self._save_checksums()
-            logger.info(f"Removed checksum for {file_path.name}")
+            logger.info("Removed checksum for %s", file_path.name)
             return True
         else:
-            logger.debug(f"No checksum found to remove for {file_path.name}")
+            logger.debug("No checksum found to remove for %s", file_path.name)
             return False
 
     def has_checksum(self, file_path: Path) -> bool:

src/server/api/anime.py

@@ -236,8 +236,8 @@ async def list_anime(
         sort_by: Optional sorting parameter. Allowed: title, id, name,
             missing_episodes
         filter: Optional filter parameter. Allowed values:
-            - "no_episodes": Show only series with no downloaded
-              episodes in folder
+            - "missing_episodes": Show only series that have any missing episodes
+            - "no_episodes": Show only series that have no downloaded episodes
         _auth: Ensures the caller is authenticated (value unused)
         anime_service: AnimeService instance provided via dependency
 
@@ -298,7 +298,7 @@ async def list_anime(
     # Validate filter parameter
     if filter:
         try:
-            allowed_filters = ["no_episodes"]
+            allowed_filters = ["missing_episodes", "no_episodes"]
             validate_filter_value(filter, allowed_filters)
         except ValueError as e:
             raise ValidationError(message=str(e))
@@ -724,13 +724,17 @@ async def add_series(
         if series_app and hasattr(series_app, 'loader'):
             try:
                 year = series_app.loader.get_year(key)
-                logger.info(f"Fetched year for {key}: {year}")
+                logger.info("Fetched year for %s: %s", key, year)
             except Exception as e:
-                logger.warning(f"Could not fetch year for {key}: {e}")
+                logger.warning("Could not fetch year for %s: %s", key, e)
         
         # Create folder name with year if available
         if year:
-            folder_name_with_year = f"{name} ({year})"
+            year_suffix = f" ({year})"
+            if name.endswith(year_suffix):
+                folder_name_with_year = name
+            else:
+                folder_name_with_year = f"{name}{year_suffix}"
         else:
             folder_name_with_year = name
         
@@ -834,9 +838,9 @@ async def add_series(
         # Step F: Scan missing episodes immediately if background loader is not running
         # Uses existing SerieScanner and AnimeService sync to avoid duplicates
         try:
-            loader_running = (
-                background_loader.worker_task is not None
-                and not background_loader.worker_task.done()
+            loader_running = bool(
+                background_loader.worker_tasks
+                and any(not t.done() for t in background_loader.worker_tasks)
             )
             if (
                 not loader_running

src/server/api/auth.py

@@ -76,6 +76,8 @@ async def setup_auth(req: SetupRequest):
             config.scheduler.schedule_days = req.scheduler_schedule_days
         if req.scheduler_auto_download_after_rescan is not None:
             config.scheduler.auto_download_after_rescan = req.scheduler_auto_download_after_rescan
+        if req.scheduler_folder_scan_enabled is not None:
+            config.scheduler.folder_scan_enabled = req.scheduler_folder_scan_enabled
         
         # Update logging configuration
         if req.logging_level:

src/server/api/health.py

@@ -22,7 +22,7 @@ class HealthStatus(BaseModel):
 
     status: str
     timestamp: str
-    version: str = "1.0.0"
+    version: str = "1.0.1"
     service: str = "aniworld-api"
     series_app_initialized: bool = False
     anime_directory_configured: bool = False
@@ -60,7 +60,7 @@ class DetailedHealthStatus(BaseModel):
 
     status: str
     timestamp: str
-    version: str = "1.0.0"
+    version: str = "1.0.1"
     dependencies: DependencyHealth
     startup_time: datetime
 
@@ -91,7 +91,7 @@ async def check_database_health(db: AsyncSession) -> DatabaseHealth:
             message="Database connection successful",
         )
     except Exception as e:
-        logger.error(f"Database health check failed: {e}")
+        logger.error("Database health check failed: %s", e)
         return DatabaseHealth(
             status="unhealthy",
             connection_time_ms=0,
@@ -121,7 +121,7 @@ async def check_filesystem_health() -> Dict[str, Any]:
             "message": "Filesystem check completed",
         }
     except Exception as e:
-        logger.error(f"Filesystem health check failed: {e}")
+        logger.error("Filesystem health check failed: %s", e)
         return {
             "status": "unhealthy",
             "message": f"Filesystem check failed: {str(e)}",
@@ -164,7 +164,7 @@ def get_system_metrics() -> SystemMetrics:
             uptime_seconds=uptime_seconds,
         )
     except Exception as e:
-        logger.error(f"System metrics collection failed: {e}")
+        logger.error("System metrics collection failed: %s", e)
         raise HTTPException(
             status_code=500, detail=f"Failed to collect system metrics: {str(e)}"
         )
@@ -236,7 +236,7 @@ async def detailed_health_check(
             startup_time=startup_time,
         )
     except Exception as e:
-        logger.error(f"Detailed health check failed: {e}")
+        logger.error("Detailed health check failed: %s", e)
         raise HTTPException(status_code=500, detail="Health check failed")
 
 

src/server/api/nfo.py

@@ -243,7 +243,7 @@ async def get_missing_nfo(
         )
         
     except Exception as e:
-        logger.error(f"Error getting missing NFOs: {e}", exc_info=True)
+        logger.exception("Error getting missing NFOs: %s", e)
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail=f"Failed to get missing NFOs: {str(e)}"
@@ -334,7 +334,7 @@ async def check_nfo(
     except HTTPException:
         raise
     except Exception as e:
-        logger.error(f"Error checking NFO for {serie_id}: {e}", exc_info=True)
+        logger.exception("Error checking NFO for %s: %s", serie_id, e)
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail=f"Failed to check NFO: {str(e)}"
@@ -429,7 +429,7 @@ async def create_nfo(
     except HTTPException:
         raise
     except TMDBAPIError as e:
-        logger.warning(f"TMDB API error creating NFO for {serie_id}: {e}")
+        logger.warning("TMDB API error creating NFO for %s: %s", serie_id, e)
         raise HTTPException(
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
             detail=f"TMDB API error: {str(e)}"
@@ -524,7 +524,7 @@ async def update_nfo(
     except HTTPException:
         raise
     except TMDBAPIError as e:
-        logger.warning(f"TMDB API error updating NFO for {serie_id}: {e}")
+        logger.warning("TMDB API error updating NFO for %s: %s", serie_id, e)
         raise HTTPException(
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
             detail=f"TMDB API error: {str(e)}"

src/server/api/scheduler.py

@@ -31,6 +31,7 @@ def _build_response(config: SchedulerConfig) -> Dict[str, Any]:
             "schedule_time": config.schedule_time,
             "schedule_days": config.schedule_days,
             "auto_download_after_rescan": config.auto_download_after_rescan,
+            "folder_scan_enabled": config.folder_scan_enabled,
         },
         "status": {
             "is_running": runtime.get("is_running", False),

src/server/config/__init__.py

@@ -39,7 +39,7 @@ def get_settings() -> Union[DevelopmentSettings, ProductionSettings]:
     Example:
         >>> settings = get_settings()
         >>> print(settings.log_level)
-        DEBUG
+        INFO
     """
     if ENVIRONMENT in {"development", "testing"}:
         return get_development_settings()

src/server/config/development.py

@@ -215,7 +215,7 @@ class DevelopmentSettings(BaseSettings):
     @property
     def debug_enabled(self) -> bool:
         """Check if debug mode is enabled."""
-        return True
+        return False
 
     @property
     def reload_enabled(self) -> bool:

src/server/config/logging_config.py

@@ -95,10 +95,10 @@ def setup_logging() -> Dict[str, logging.Logger]:
     # Log initial setup
     root_logger.info("=" * 80)
     root_logger.info("FastAPI Server Logging Initialized")
-    root_logger.info(f"Log Level: {settings.log_level.upper()}")
-    root_logger.info(f"Server Log: {server_log_file.absolute()}")
-    root_logger.info(f"Error Log: {error_log_file.absolute()}")
-    root_logger.info(f"Access Log: {access_log_file.absolute()}")
+    root_logger.info("Log Level: %s", settings.log_level.upper())
+    root_logger.info("Server Log: %s", server_log_file.absolute())
+    root_logger.info("Error Log: %s", error_log_file.absolute())
+    root_logger.info("Access Log: %s", access_log_file.absolute())
     root_logger.info("=" * 80)
     
     return {

src/server/database/connection.py

@@ -88,7 +88,7 @@ async def init_db() -> None:
     try:
         # Get database URL
         db_url = _get_database_url()
-        logger.info(f"Initializing database: {db_url}")
+        logger.info("Initializing database: %s", db_url)
         
         # Build engine kwargs based on database type
         is_sqlite = "sqlite" in db_url
@@ -143,7 +143,7 @@ async def init_db() -> None:
         logger.info("Database initialization complete")
         
     except Exception as e:
-        logger.error(f"Failed to initialize database: {e}")
+        logger.error("Failed to initialize database: %s", e)
         raise
 
 
@@ -171,7 +171,7 @@ async def close_db() -> None:
                     conn.commit()
                 logger.info("SQLite WAL checkpoint completed")
             except Exception as e:
-                logger.warning(f"WAL checkpoint failed (non-critical): {e}")
+                logger.warning("WAL checkpoint failed (non-critical): %s", e)
         
         if _engine:
             logger.info("Closing async database engine...")
@@ -188,7 +188,7 @@ async def close_db() -> None:
         logger.info("Database connections closed")
         
     except Exception as e:
-        logger.error(f"Error closing database: {e}")
+        logger.error("Error closing database: %s", e)
 
 
 def get_engine() -> AsyncEngine:

src/server/database/init.py

@@ -27,7 +27,7 @@ logger = logging.getLogger(__name__)
 # Schema Version Constants
 # =============================================================================
 
-CURRENT_SCHEMA_VERSION = "1.0.0"
+CURRENT_SCHEMA_VERSION = "1.0.1"
 SCHEMA_VERSION_TABLE = "schema_version"
 
 # Expected tables in the current schema
@@ -98,7 +98,7 @@ async def initialize_database(
             seed_data=True
         )
         if result["success"]:
-            logger.info(f"Database initialized: {result['schema_version']}")
+            logger.info("Database initialized: %s", result['schema_version'])
     """
     if engine is None:
         engine = get_engine()
@@ -117,7 +117,7 @@ async def initialize_database(
         if create_schema:
             tables = await create_database_schema(engine)
             result["tables_created"] = tables
-            logger.info(f"Created {len(tables)} tables")
+            logger.info("Created %s tables", len(tables))
         
         # Validate schema if requested
         if validate_schema:
@@ -148,7 +148,7 @@ async def initialize_database(
         return result
         
     except Exception as e:
-        logger.error(f"Database initialization failed: {e}", exc_info=True)
+        logger.exception("Database initialization failed: %s", e)
         raise RuntimeError(f"Failed to initialize database: {e}") from e
 
 
@@ -194,14 +194,14 @@ async def create_database_schema(
         created_tables = [t for t in new_tables if t not in existing_tables]
         
         if created_tables:
-            logger.info(f"Created tables: {', '.join(created_tables)}")
+            logger.info("Created tables: %s", ', '.join(created_tables))
         else:
             logger.info("All tables already exist")
         
         return new_tables
         
     except Exception as e:
-        logger.error(f"Failed to create schema: {e}", exc_info=True)
+        logger.exception("Failed to create schema: %s", e)
         raise RuntimeError(f"Schema creation failed: {e}") from e
 
 
@@ -295,7 +295,7 @@ async def validate_database_schema(
         return result
         
     except Exception as e:
-        logger.error(f"Schema validation failed: {e}", exc_info=True)
+        logger.exception("Schema validation failed: %s", e)
         return {
             "valid": False,
             "missing_tables": [],
@@ -319,7 +319,7 @@ async def get_schema_version(engine: Optional[AsyncEngine] = None) -> str:
         engine: Optional database engine (uses default if not provided)
     
     Returns:
-        Schema version string (e.g., "1.0.0", "empty", "unknown")
+        Schema version string (e.g., "1.0.1", "empty", "unknown")
     """
     if engine is None:
         engine = get_engine()
@@ -342,7 +342,7 @@ async def get_schema_version(engine: Optional[AsyncEngine] = None) -> str:
                 return "unknown"
                 
     except Exception as e:
-        logger.error(f"Failed to get schema version: {e}")
+        logger.error("Failed to get schema version: %s", e)
         return "error"
 
 
@@ -409,7 +409,7 @@ async def seed_initial_data(engine: Optional[AsyncEngine] = None) -> None:
             logger.info("Data will be populated via normal application usage")
             
     except Exception as e:
-        logger.error(f"Failed to seed initial data: {e}", exc_info=True)
+        logger.exception("Failed to seed initial data: %s", e)
         raise
 
 
@@ -484,12 +484,12 @@ async def check_database_health(
                 f"(connectivity: {result['connectivity_ms']}ms)"
             )
         else:
-            logger.warning(f"Database health issues: {result['issues']}")
+            logger.warning("Database health issues: %s", result['issues'])
         
         return result
         
     except Exception as e:
-        logger.error(f"Database health check failed: {e}")
+        logger.error("Database health check failed: %s", e)
         return {
             "healthy": False,
             "accessible": False,
@@ -547,13 +547,13 @@ async def create_database_backup(
         backup_path = backup_dir / f"aniworld_{timestamp}.db"
     
     try:
-        logger.info(f"Creating database backup: {backup_path}")
+        logger.info("Creating database backup: %s", backup_path)
         shutil.copy2(db_path, backup_path)
-        logger.info(f"Backup created successfully: {backup_path}")
+        logger.info("Backup created successfully: %s", backup_path)
         return backup_path
         
     except Exception as e:
-        logger.error(f"Failed to create backup: {e}", exc_info=True)
+        logger.exception("Failed to create backup: %s", e)
         raise RuntimeError(f"Backup creation failed: {e}") from e
 
 

src/server/database/service.py

@@ -107,7 +107,7 @@ class AnimeSeriesService:
         db.add(series)
         await db.flush()
         await db.refresh(series)
-        logger.info(f"Created anime series: {series.name} (key={series.key}, year={year})")
+        logger.info("Created anime series: %s (key=%s, year=%s)", series.name, series.key, year)
         return series
     
     @staticmethod
@@ -148,7 +148,27 @@ class AnimeSeriesService:
             select(AnimeSeries).where(AnimeSeries.key == key)
         )
         return result.scalar_one_or_none()
-    
+
+    @staticmethod
+    def get_by_folder_sync(db: Session, folder: str) -> Optional[AnimeSeries]:
+        """Look up an anime series by its filesystem folder name (sync).
+
+        Intended as a fallback for ``SerieScanner`` when neither a ``key``
+        file nor a ``data`` file exists on disk for a given folder.
+
+        Args:
+            db: Synchronous database session (from ``get_sync_session``).
+            folder: Filesystem folder name to match (e.g.
+                ``"Rooster Fighter (2026)"``).
+
+        Returns:
+            ``AnimeSeries`` instance or ``None`` if not found.
+        """
+        result = db.execute(
+            select(AnimeSeries).where(AnimeSeries.folder == folder)
+        )
+        return result.scalar_one_or_none()
+
     @staticmethod
     async def get_all(
         db: AsyncSession,
@@ -205,7 +225,7 @@ class AnimeSeriesService:
         
         await db.flush()
         await db.refresh(series)
-        logger.info(f"Updated anime series: {series.name} (id={series_id})")
+        logger.info("Updated anime series: %s (id=%s)", series.name, series_id)
         return series
     
     @staticmethod
@@ -226,7 +246,7 @@ class AnimeSeriesService:
         )
         deleted = result.rowcount > 0
         if deleted:
-            logger.info(f"Deleted anime series with id={series_id}")
+            logger.info("Deleted anime series with id=%s", series_id)
         return deleted
     
     @staticmethod
@@ -253,48 +273,92 @@ class AnimeSeriesService:
         return list(result.scalars().all())
     
     @staticmethod
-    async def get_series_with_no_episodes(
+    async def get_series_with_missing_episodes(
         db: AsyncSession,
         limit: Optional[int] = None,
         offset: int = 0,
     ) -> List[AnimeSeries]:
-        """Get anime series that have no episodes found in folder.
-        
-        Since episodes in the database represent MISSING episodes
-        (from episodeDict), this returns series that have episodes
-        in the DB with is_downloaded=False, meaning they have missing
-        episodes and no files were found in the folder for those episodes.
-        
-        Returns series where:
-        - At least one episode exists in database with is_downloaded=False
-        
+        """Get anime series that currently have missing episodes.
+
+        Episodes in the database represent missing episodes (from episodeDict).
+        This returns series that have at least one missing episode recorded in
+        the database (is_downloaded=False).
+
         Args:
             db: Database session
             limit: Optional limit for results
             offset: Offset for pagination
-        
+
         Returns:
-            List of AnimeSeries with missing episodes (not in folder)
+            List of AnimeSeries that have missing episodes.
         """
-        # Subquery to find series IDs with at least one undownloaded episode
-        undownloaded_series_ids = (
+        # Subquery to find series IDs with at least one missing episode
+        missing_series_ids = (
             select(Episode.series_id)
             .where(Episode.is_downloaded == False)
             .distinct()
             .subquery()
         )
-        
-        # Select series that have undownloaded episodes
+
         query = (
             select(AnimeSeries)
-            .where(AnimeSeries.id.in_(select(undownloaded_series_ids.c.series_id)))
+            .where(AnimeSeries.id.in_(select(missing_series_ids.c.series_id)))
             .order_by(AnimeSeries.name)
             .offset(offset)
         )
-        
+
         if limit:
             query = query.limit(limit)
-        
+
+        result = await db.execute(query)
+        return list(result.scalars().all())
+
+    @staticmethod
+    async def get_series_with_no_episodes(
+        db: AsyncSession,
+        limit: Optional[int] = None,
+        offset: int = 0,
+    ) -> List[AnimeSeries]:
+        """Get anime series that have no downloaded episodes.
+
+        A series has "no episodes" if it has at least one missing episode
+        (is_downloaded=False) and no downloaded episodes (is_downloaded=True).
+
+        Args:
+            db: Database session
+            limit: Optional limit for results
+            offset: Offset for pagination
+
+        Returns:
+            List of AnimeSeries where no episodes are downloaded.
+        """
+        # Series with missing episodes
+        missing_series_ids = (
+            select(Episode.series_id)
+            .where(Episode.is_downloaded == False)
+            .distinct()
+            .subquery()
+        )
+
+        # Series with any downloaded episodes
+        downloaded_series_ids = (
+            select(Episode.series_id)
+            .where(Episode.is_downloaded == True)
+            .distinct()
+            .subquery()
+        )
+
+        query = (
+            select(AnimeSeries)
+            .where(AnimeSeries.id.in_(select(missing_series_ids.c.series_id)))
+            .where(~AnimeSeries.id.in_(select(downloaded_series_ids.c.series_id)))
+            .order_by(AnimeSeries.name)
+            .offset(offset)
+        )
+
+        if limit:
+            query = query.limit(limit)
+
         result = await db.execute(query)
         return list(result.scalars().all())
     
@@ -657,7 +721,7 @@ class EpisodeService:
                 updated_count += 1
         
         await db.flush()
-        logger.info(f"Bulk marked {updated_count} episodes as downloaded")
+        logger.info("Bulk marked %s episodes as downloaded", updated_count)
         
         return updated_count
 
@@ -806,7 +870,7 @@ class DownloadQueueService:
         
         await db.flush()
         await db.refresh(item)
-        logger.debug(f"Set error on download queue item {item_id}")
+        logger.debug("Set error on download queue item %s", item_id)
         return item
     
     @staticmethod
@@ -825,7 +889,7 @@ class DownloadQueueService:
         )
         deleted = result.rowcount > 0
         if deleted:
-            logger.info(f"Deleted download queue item with id={item_id}")
+            logger.info("Deleted download queue item with id=%s", item_id)
         return deleted
     
     @staticmethod
@@ -887,7 +951,7 @@ class DownloadQueueService:
         )
         
         count = result.rowcount
-        logger.info(f"Bulk deleted {count} download queue items")
+        logger.info("Bulk deleted %s download queue items", count)
         
         return count
 
@@ -908,7 +972,7 @@ class DownloadQueueService:
         """
         result = await db.execute(delete(DownloadQueueItem))
         count = result.rowcount
-        logger.info(f"Cleared all {count} download queue items")
+        logger.info("Cleared all %s download queue items", count)
         return count
 
 
@@ -962,7 +1026,7 @@ class UserSessionService:
         db.add(session)
         await db.flush()
         await db.refresh(session)
-        logger.info(f"Created user session: {session_id}")
+        logger.info("Created user session: %s", session_id)
         return session
     
     @staticmethod
@@ -1049,7 +1113,7 @@ class UserSessionService:
         
         session.revoke()
         await db.flush()
-        logger.info(f"Revoked user session: {session_id}")
+        logger.info("Revoked user session: %s", session_id)
         return True
     
     @staticmethod
@@ -1071,7 +1135,7 @@ class UserSessionService:
             )
         )
         count = result.rowcount
-        logger.info(f"Cleaned up {count} expired sessions")
+        logger.info("Cleaned up %s expired sessions", count)
         return count
 
     @staticmethod

src/server/fastapi_app.py

@@ -6,6 +6,7 @@ configuration, middleware setup, static file serving, and Jinja2 template
 integration.
 """
 import asyncio
+import logging
 from contextlib import asynccontextmanager
 from pathlib import Path
 
@@ -51,7 +52,7 @@ async def _check_incomplete_series_on_startup(background_loader) -> None:
     Args:
         background_loader: BackgroundLoaderService instance
     """
-    logger = setup_logging(log_level="INFO")
+    logger = logging.getLogger("aniworld")
     
     try:
         from src.server.database.connection import get_db_session
@@ -96,11 +97,11 @@ async def _check_incomplete_series_on_startup(background_loader) -> None:
                 else:
                     logger.info("All series data is complete. No background loading needed.")
                 
-            except Exception as e:
-                logger.error(f"Error checking incomplete series: {e}", exc_info=True)
+            except Exception:
+                logger.exception("Error checking incomplete series")
             
-    except Exception as e:
-        logger.error(f"Failed to check incomplete series on startup: {e}", exc_info=True)
+    except Exception:
+        logger.exception("Failed to check incomplete series on startup")
 
 
 @asynccontextmanager
@@ -241,7 +242,6 @@ async def lifespan(_application: FastAPI):
         from src.server.services.initialization_service import (
             perform_initial_setup,
             perform_media_scan_if_needed,
-            perform_nfo_repair_scan,
             perform_nfo_scan_if_needed,
         )
         
@@ -312,10 +312,6 @@ async def lifespan(_application: FastAPI):
 
                 # Run media scan only on first run
                 await perform_media_scan_if_needed(background_loader)
-
-                # Scan every series NFO on startup and repair any that are
-                # missing required tags by queuing them for background reload
-                await perform_nfo_repair_scan(background_loader)
             else:
                 logger.info(
                     "Download service initialization skipped - "
@@ -484,7 +480,7 @@ async def lifespan(_application: FastAPI):
 app = FastAPI(
     title="Aniworld Download Manager",
     description="Modern web interface for Aniworld anime download management",
-    version="1.0.0",
+    version="1.0.1",
     docs_url="/api/docs",
     redoc_url="/api/redoc",
     lifespan=lifespan

src/server/middleware/error_handler.py

@@ -74,7 +74,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle authentication errors (401)."""
         logger.warning(
-            f"Authentication error: {exc.message}",
+            "Authentication error: %s",
+            exc.message,
             extra={"details": exc.details, "path": str(request.url.path)},
         )
         return JSONResponse(
@@ -94,7 +95,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle authorization errors (403)."""
         logger.warning(
-            f"Authorization error: {exc.message}",
+            "Authorization error: %s",
+            exc.message,
             extra={"details": exc.details, "path": str(request.url.path)},
         )
         return JSONResponse(
@@ -114,7 +116,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle validation errors (422)."""
         logger.info(
-            f"Validation error: {exc.message}",
+            "Validation error: %s",
+            exc.message,
             extra={"details": exc.details, "path": str(request.url.path)},
         )
         return JSONResponse(
@@ -134,7 +137,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle bad request errors (400)."""
         logger.info(
-            f"Bad request error: {exc.message}",
+            "Bad request error: %s",
+            exc.message,
             extra={"details": exc.details, "path": str(request.url.path)},
         )
         return JSONResponse(
@@ -154,7 +158,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle not found errors (404)."""
         logger.info(
-            f"Not found error: {exc.message}",
+            "Not found error: %s",
+            exc.message,
             extra={"details": exc.details, "path": str(request.url.path)},
         )
         return JSONResponse(
@@ -174,7 +179,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle conflict errors (409)."""
         logger.info(
-            f"Conflict error: {exc.message}",
+            "Conflict error: %s",
+            exc.message,
             extra={"details": exc.details, "path": str(request.url.path)},
         )
         return JSONResponse(
@@ -194,7 +200,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle rate limit errors (429)."""
         logger.warning(
-            f"Rate limit exceeded: {exc.message}",
+            "Rate limit exceeded: %s",
+            exc.message,
             extra={"details": exc.details, "path": str(request.url.path)},
         )
         return JSONResponse(
@@ -214,7 +221,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle generic API exceptions."""
         logger.error(
-            f"API error: {exc.message}",
+            "API error: %s",
+            exc.message,
             extra={
                 "error_code": exc.error_code,
                 "details": exc.details,
@@ -238,12 +246,13 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle unexpected exceptions."""
         logger.exception(
-            f"Unexpected error: {str(exc)}",
+            "Unexpected error: %s",
+            str(exc),
             extra={"path": str(request.url.path)},
         )
 
         # Log full traceback for debugging
-        logger.debug(f"Traceback: {traceback.format_exc()}")
+        logger.debug("Traceback: %s", traceback.format_exc())
 
         # Return generic error response for security
         return JSONResponse(

src/server/middleware/security.py

@@ -315,11 +315,11 @@ class RequestSanitizationMiddleware(BaseHTTPMiddleware):
             None if malicious content detected, sanitized value otherwise
         """
         if self.check_sql_injection and self._check_sql_injection(value):
-            logger.warning(f"Potential SQL injection detected: {value[:100]}")
+            logger.warning("Potential SQL injection detected: %s", value[:100])
             return None
 
         if self.check_xss and self._check_xss(value):
-            logger.warning(f"Potential XSS detected: {value[:100]}")
+            logger.warning("Potential XSS detected: %s", value[:100])
             return None
 
         return value
@@ -341,7 +341,7 @@ class RequestSanitizationMiddleware(BaseHTTPMiddleware):
             content_type
             and not any(ct in content_type for ct in self.allowed_content_types)
         ):
-            logger.warning(f"Unsupported content type: {content_type}")
+            logger.warning("Unsupported content type: %s", content_type)
             return JSONResponse(
                 status_code=415,
                 content={"detail": "Unsupported Media Type"},
@@ -350,7 +350,7 @@ class RequestSanitizationMiddleware(BaseHTTPMiddleware):
         # Check request size
         content_length = request.headers.get("content-length")
         if content_length and int(content_length) > self.max_request_size:
-            logger.warning(f"Request too large: {content_length} bytes")
+            logger.warning("Request too large: %s bytes", content_length)
             return JSONResponse(
                 status_code=413,
                 content={"detail": "Request Entity Too Large"},
@@ -361,7 +361,7 @@ class RequestSanitizationMiddleware(BaseHTTPMiddleware):
             if isinstance(value, str):
                 sanitized = self._sanitize_value(value)
                 if sanitized is None:
-                    logger.warning(f"Malicious query parameter detected: {key}")
+                    logger.warning("Malicious query parameter detected: %s", key)
                     return JSONResponse(
                         status_code=400,
                         content={"detail": "Malicious request detected"},
@@ -372,7 +372,7 @@ class RequestSanitizationMiddleware(BaseHTTPMiddleware):
             if isinstance(value, str):
                 sanitized = self._sanitize_value(value)
                 if sanitized is None:
-                    logger.warning(f"Malicious path parameter detected: {key}")
+                    logger.warning("Malicious path parameter detected: %s", key)
                     return JSONResponse(
                         status_code=400,
                         content={"detail": "Malicious request detected"},

src/server/models/auth.py

@@ -73,6 +73,9 @@ class SetupRequest(BaseModel):
     scheduler_auto_download_after_rescan: Optional[bool] = Field(
         default=False, description="Auto-download missing episodes after rescan"
     )
+    scheduler_folder_scan_enabled: Optional[bool] = Field(
+        default=False, description="Run folder maintenance during scheduled run"
+    )
     
     # Logging configuration
     logging_level: Optional[str] = Field(

src/server/models/config.py

@@ -39,6 +39,11 @@ class SchedulerConfig(BaseModel):
         description="Automatically queue and start downloads for all missing "
                     "episodes after a scheduled rescan completes.",
     )
+    folder_scan_enabled: bool = Field(
+        default=False,
+        description="Run folder maintenance (NFO repair, folder renaming, "
+                    "poster checks) during the scheduled run.",
+    )
 
     @field_validator("schedule_time")
     @classmethod

src/server/services/anime_service.py

@@ -524,19 +524,20 @@ class AnimeService:
                         "series_id": db_series.id,
                     }
                 
-                # If filter is "no_episodes", get series with no
-                # downloaded episodes
-                if filter_type == "no_episodes":
-                    # Use service method to get series with
-                    # undownloaded episodes
-                    series_no_downloads = (
-                        await AnimeSeriesService
-                        .get_series_with_no_episodes(db)
+                # If filter is "missing_episodes", get series with any missing episodes
+                if filter_type == "missing_episodes":
+                    series_missing = (
+                        await AnimeSeriesService.get_series_with_missing_episodes(db)
                     )
-                    series_with_no_episodes = {
-                        s.folder for s in series_no_downloads
-                    }
-            
+                    series_with_missing_episodes = {s.folder for s in series_missing}
+
+                # If filter is "no_episodes", get series with no downloaded episodes
+                if filter_type == "no_episodes":
+                    series_no_downloads = (
+                        await AnimeSeriesService.get_series_with_no_episodes(db)
+                    )
+                    series_with_no_episodes = {s.folder for s in series_no_downloads}
+
             # Build result list with enriched metadata
             result_list = []
             for serie in series:
@@ -545,8 +546,11 @@ class AnimeService:
                 site = getattr(serie, "site", "")
                 folder = getattr(serie, "folder", "")
                 episode_dict = getattr(serie, "episodeDict", {}) or {}
-                
+
                 # Apply filter if specified
+                if filter_type == "missing_episodes":
+                    if folder not in series_with_missing_episodes:
+                        continue
                 if filter_type == "no_episodes":
                     if folder not in series_with_no_episodes:
                         continue
@@ -941,12 +945,12 @@ class AnimeService:
 
         # Get the serie from in-memory cache
         if not hasattr(self._app, 'list') or not hasattr(self._app.list, 'keyDict'):
-            logger.warning(f"Series list not available for episode sync: {series_key}")
+            logger.warning("Series list not available for episode sync: %s", series_key)
             return 0
         
         serie = self._app.list.keyDict.get(series_key)
         if not serie:
-            logger.warning(f"Series not found in memory for episode sync: {series_key}")
+            logger.warning("Series not found in memory for episode sync: %s", series_key)
             return 0
         
         episodes_added = 0
@@ -955,7 +959,7 @@ class AnimeService:
             # Get series from database
             series_db = await AnimeSeriesService.get_by_key(db, series_key)
             if not series_db:
-                logger.warning(f"Series not found in database: {series_key}")
+                logger.warning("Series not found in database: %s", series_key)
                 return 0
             
             # Get existing episodes from database
@@ -996,7 +1000,7 @@ class AnimeService:
                 try:
                     await self._broadcast_series_updated(series_key)
                 except Exception as e:
-                    logger.warning(f"Failed to broadcast series update: {e}")
+                    logger.warning("Failed to broadcast series update: %s", e)
         
         return episodes_added
     

src/server/services/background_loader_service.py

@@ -22,6 +22,7 @@ from typing import Any, Dict, List, Optional
 
 import structlog
 
+from src.core.services.nfo_factory import get_nfo_factory
 from src.server.services.websocket_service import WebSocketService
 
 logger = structlog.get_logger(__name__)
@@ -188,7 +189,7 @@ class BackgroundLoaderService:
         """
         # Check if task already exists
         if key in self.active_tasks:
-            logger.debug(f"Task for series {key} already exists, skipping")
+            logger.debug("Task for series %s already exists, skipping", key)
             return
         
         task = SeriesLoadingTask(
@@ -202,7 +203,7 @@ class BackgroundLoaderService:
         self.active_tasks[key] = task
         await self.task_queue.put(task)
         
-        logger.info(f"Added loading task for series: {key}")
+        logger.info("Added loading task for series: %s", key)
         
         # Broadcast initial status
         await self._broadcast_status(task)
@@ -277,7 +278,7 @@ class BackgroundLoaderService:
         Args:
             worker_id: Unique identifier for this worker instance
         """
-        logger.info(f"Background worker {worker_id} started processing tasks")
+        logger.info("Background worker %s started processing tasks", worker_id)
         
         while not self._shutdown:
             try:
@@ -301,14 +302,14 @@ class BackgroundLoaderService:
                 # No task available, continue loop
                 continue
             except asyncio.CancelledError:
-                logger.info(f"Worker {worker_id} task cancelled")
+                logger.info("Worker %s task cancelled", worker_id)
                 break
             except Exception as e:
-                logger.exception(f"Error in background worker {worker_id}: {e}")
+                logger.exception("Error in background worker %s: %s", worker_id, e)
                 # Continue processing other tasks
                 continue
         
-        logger.info(f"Background worker {worker_id} stopped")
+        logger.info("Background worker %s stopped", worker_id)
     
     async def _load_series_data(self, task: SeriesLoadingTask) -> None:
         """Load all missing data for a series.
@@ -362,10 +363,10 @@ class BackgroundLoaderService:
                     # Broadcast completion
                     await self._broadcast_status(task)
                     
-                    logger.info(f"Successfully loaded all data for series: {task.key}")
+                    logger.info("Successfully loaded all data for series: %s", task.key)
                     
                 except Exception as e:
-                    logger.exception(f"Error loading series data: {e}")
+                    logger.exception("Error loading series data: %s", e)
                     task.status = LoadingStatus.FAILED
                     task.error = str(e)
                     task.completed_at = datetime.now(timezone.utc)
@@ -400,14 +401,14 @@ class BackgroundLoaderService:
             
             # Check if directory exists
             if series_dir.exists() and series_dir.is_dir():
-                logger.debug(f"Found series directory: {series_dir}")
+                logger.debug("Found series directory: %s", series_dir)
                 return series_dir
             else:
-                logger.warning(f"Series directory not found: {series_dir}")
+                logger.warning("Series directory not found: %s", series_dir)
                 return None
                 
         except Exception as e:
-            logger.error(f"Error finding series directory for {task.key}: {e}")
+            logger.error("Error finding series directory for %s: %s", task.key, e)
             return None
     
     async def _scan_series_episodes(self, series_dir: Path, task: SeriesLoadingTask) -> Dict[str, List[str]]:
@@ -440,13 +441,13 @@ class BackgroundLoaderService:
                 
                 if episodes:
                     episodes_by_season[season_name] = episodes
-                    logger.debug(f"Found {len(episodes)} episodes in {season_name}")
+                    logger.debug("Found %s episodes in %s", len(episodes), season_name)
             
-            logger.info(f"Scanned {len(episodes_by_season)} seasons for {task.key}")
+            logger.info("Scanned %s seasons for %s", len(episodes_by_season), task.key)
             return episodes_by_season
             
         except Exception as e:
-            logger.error(f"Error scanning episodes for {task.key}: {e}")
+            logger.error("Error scanning episodes for %s: %s", task.key, e)
             return {}
     
     async def _load_episodes(self, task: SeriesLoadingTask, db: Any) -> None:
@@ -466,7 +467,7 @@ class BackgroundLoaderService:
             # Find series directory without full rescan
             series_dir = await self._find_series_directory(task)
             if not series_dir:
-                logger.error(f"Cannot load episodes - directory not found for {task.key}")
+                logger.error("Cannot load episodes - directory not found for %s", task.key)
                 task.progress["episodes"] = False
                 return
             
@@ -474,7 +475,7 @@ class BackgroundLoaderService:
             episodes_by_season = await self._scan_series_episodes(series_dir, task)
             
             if not episodes_by_season:
-                logger.warning(f"No episodes found for {task.key}")
+                logger.warning("No episodes found for %s", task.key)
                 task.progress["episodes"] = False
                 return
             
@@ -489,10 +490,10 @@ class BackgroundLoaderService:
                 series_db.loading_status = "loading_episodes"
                 await db.commit()
             
-            logger.info(f"Episodes loaded for series: {task.key} ({len(episodes_by_season)} seasons)")
+            logger.info("Episodes loaded for series: %s (%s seasons)", task.key, len(episodes_by_season))
             
         except Exception as e:
-            logger.exception(f"Failed to load episodes for {task.key}: {e}")
+            logger.exception("Failed to load episodes for %s: %s", task.key, e)
             raise
     
     async def _load_nfo_and_images(self, task: SeriesLoadingTask, db: Any) -> bool:
@@ -521,7 +522,7 @@ class BackgroundLoaderService:
             
             # Check if NFO already exists
             if self.series_app.nfo_service.has_nfo(task.folder):
-                logger.info(f"NFO already exists for {task.key}, skipping creation")
+                logger.info("NFO already exists for %s, skipping creation", task.key)
                 
                 # Update task progress
                 task.progress["nfo"] = True
@@ -536,31 +537,46 @@ class BackgroundLoaderService:
                     if not series_db.has_nfo:
                         series_db.has_nfo = True
                         series_db.nfo_created_at = datetime.now(timezone.utc)
-                        logger.info(f"Updated database with existing NFO for {task.key}")
+                        logger.info("Updated database with existing NFO for %s", task.key)
                     if not series_db.logo_loaded:
                         series_db.logo_loaded = True
                     if not series_db.images_loaded:
                         series_db.images_loaded = True
                     await db.commit()
                 
-                logger.info(f"Existing NFO found and database updated for series: {task.key}")
+                logger.info("Existing NFO found and database updated for series: %s", task.key)
                 return False
             
             # NFO doesn't exist, create it
             await self._broadcast_status(task, "Generating NFO file...")
-            logger.info(f"Creating new NFO for {task.key}")
-            
-            # Use existing NFOService to create NFO with all images
-            # This reuses all existing TMDB API logic and image downloading
-            nfo_path = await self.series_app.nfo_service.create_tvshow_nfo(
-                serie_name=task.name,
-                serie_folder=task.folder,
-                year=task.year,
-                download_poster=True,
-                download_logo=True,
-                download_fanart=True
-            )
+            logger.info("Creating new NFO for %s", task.key)
             
+            # Create a fresh NFOService for this task to avoid shared TMDB session closure
+            try:
+                factory = get_nfo_factory()
+                nfo_service = factory.create()
+            except ValueError:
+                logger.warning(
+                    "NFOService unavailable for %s, skipping NFO/images",
+                    task.key
+                )
+                task.progress["nfo"] = False
+                task.progress["logo"] = False
+                task.progress["images"] = False
+                return False
+
+            try:
+                nfo_path = await nfo_service.create_tvshow_nfo(
+                    serie_name=task.name,
+                    serie_folder=task.folder,
+                    year=task.year,
+                    download_poster=True,
+                    download_logo=True,
+                    download_fanart=True
+                )
+            finally:
+                await nfo_service.close()
+
             # Update task progress
             task.progress["nfo"] = True
             task.progress["logo"] = True
@@ -577,11 +593,11 @@ class BackgroundLoaderService:
                 series_db.loading_status = "loading_nfo"
                 await db.commit()
             
-            logger.info(f"NFO and images created and loaded for series: {task.key}")
+            logger.info("NFO and images created and loaded for series: %s", task.key)
             return True
             
         except Exception as e:
-            logger.exception(f"Failed to load NFO/images for {task.key}: {e}")
+            logger.exception("Failed to load NFO/images for %s: %s", task.key, e)
             # Don't fail the entire task if NFO fails
             task.progress["nfo"] = False
             task.progress["logo"] = False
@@ -611,7 +627,7 @@ class BackgroundLoaderService:
             
             # Scan for missing episodes using the targeted scan method
             # This populates the episodeDict without triggering a full rescan
-            logger.info(f"Scanning missing episodes for {task.key}")
+            logger.info("Scanning missing episodes for %s", task.key)
             missing_episodes = self.series_app.serie_scanner.scan_single_series(
                 key=task.key,
                 folder=task.folder
@@ -628,12 +644,12 @@ class BackgroundLoaderService:
                 # Notify anime_service to sync episodes to database
                 # Use sync_single_series_after_scan which gets data from serie_scanner.keyDict
                 if self.anime_service:
-                    logger.debug(f"Calling anime_service.sync_single_series_after_scan for {task.key}")
+                    logger.debug("Calling anime_service.sync_single_series_after_scan for %s", task.key)
                     await self.anime_service.sync_single_series_after_scan(task.key)
                 else:
-                    logger.warning(f"anime_service not available, episodes will not be synced to DB for {task.key}")
+                    logger.warning("anime_service not available, episodes will not be synced to DB for %s", task.key)
             else:
-                logger.info(f"No missing episodes found for {task.key}")
+                logger.info("No missing episodes found for %s", task.key)
             
             # Update series status in database
             from src.server.database.service import AnimeSeriesService
@@ -648,7 +664,7 @@ class BackgroundLoaderService:
             task.progress["episodes"] = True
             
         except Exception as e:
-            logger.exception(f"Failed to scan missing episodes for {task.key}: {e}")
+            logger.exception("Failed to scan missing episodes for %s: %s", task.key, e)
             task.progress["episodes"] = False
     
     async def _broadcast_status(

src/server/services/cache_service.py

@@ -170,14 +170,17 @@ class InMemoryCacheBackend(CacheBackend):
         """Get value from cache."""
         async with self._lock:
             if key not in self.cache:
+                logger.debug("Cache miss for key: %s", key)
                 return None
 
             item = self.cache[key]
 
             if self._is_expired(item):
+                logger.debug("Cache expired for key: %s", key)
                 del self.cache[key]
                 return None
 
+            logger.debug("Cache hit for key: %s", key)
             return item["value"]
 
     async def set(
@@ -196,6 +199,7 @@ class InMemoryCacheBackend(CacheBackend):
                 "expiry": expiry,
                 "created": datetime.utcnow(),
             }
+            logger.debug("Cached key: %s (ttl=%s)", key, ttl)
             return True
 
     async def delete(self, key: str) -> bool:
@@ -203,7 +207,9 @@ class InMemoryCacheBackend(CacheBackend):
         async with self._lock:
             if key in self.cache:
                 del self.cache[key]
+                logger.debug("Deleted cache key: %s", key)
                 return True
+            logger.debug("Cache delete skipped; key not found: %s", key)
             return False
 
     async def exists(self, key: str) -> bool:
@@ -223,6 +229,7 @@ class InMemoryCacheBackend(CacheBackend):
         """Clear all cached values."""
         async with self._lock:
             self.cache.clear()
+            logger.debug("Cleared in-memory cache")
             return True
 
     async def get_many(self, keys: List[str]) -> Dict[str, Any]:
@@ -281,13 +288,14 @@ class RedisCacheBackend(CacheBackend):
                 import aioredis
 
                 self._redis = await aioredis.create_redis_pool(self.redis_url)
+                logger.debug("Connected to Redis at %s", self.redis_url)
             except ImportError:
                 logger.error(
                     "aioredis not installed. Install with: pip install aioredis"
                 )
                 raise
             except Exception as e:
-                logger.error(f"Failed to connect to Redis: {e}")
+                logger.error("Failed to connect to Redis: %s", e)
                 raise
 
         return self._redis
@@ -308,7 +316,7 @@ class RedisCacheBackend(CacheBackend):
             return pickle.loads(data)
 
         except Exception as e:
-            logger.error(f"Redis get error: {e}")
+            logger.error("Redis get error: %s", e)
             return None
 
     async def set(
@@ -327,7 +335,7 @@ class RedisCacheBackend(CacheBackend):
             return True
 
         except Exception as e:
-            logger.error(f"Redis set error: {e}")
+            logger.error("Redis set error: %s", e)
             return False
 
     async def delete(self, key: str) -> bool:
@@ -338,7 +346,7 @@ class RedisCacheBackend(CacheBackend):
             return result > 0
 
         except Exception as e:
-            logger.error(f"Redis delete error: {e}")
+            logger.error("Redis delete error: %s", e)
             return False
 
     async def exists(self, key: str) -> bool:
@@ -348,7 +356,7 @@ class RedisCacheBackend(CacheBackend):
             return await redis.exists(self._make_key(key))
 
         except Exception as e:
-            logger.error(f"Redis exists error: {e}")
+            logger.error("Redis exists error: %s", e)
             return False
 
     async def clear(self) -> bool:
@@ -361,7 +369,7 @@ class RedisCacheBackend(CacheBackend):
             return True
 
         except Exception as e:
-            logger.error(f"Redis clear error: {e}")
+            logger.error("Redis clear error: %s", e)
             return False
 
     async def get_many(self, keys: List[str]) -> Dict[str, Any]:
@@ -379,7 +387,7 @@ class RedisCacheBackend(CacheBackend):
             return result
 
         except Exception as e:
-            logger.error(f"Redis get_many error: {e}")
+            logger.error("Redis get_many error: %s", e)
             return {}
 
     async def set_many(
@@ -392,7 +400,7 @@ class RedisCacheBackend(CacheBackend):
             return True
 
         except Exception as e:
-            logger.error(f"Redis set_many error: {e}")
+            logger.error("Redis set_many error: %s", e)
             return False
 
     async def delete_pattern(self, pattern: str) -> int:
@@ -409,7 +417,7 @@ class RedisCacheBackend(CacheBackend):
             return 0
 
         except Exception as e:
-            logger.error(f"Redis delete_pattern error: {e}")
+            logger.error("Redis delete_pattern error: %s", e)
             return 0
 
     async def close(self) -> None:

src/server/services/config_service.py

@@ -8,6 +8,7 @@ This service handles:
 """
 
 import json
+import logging
 import shutil
 from datetime import datetime
 from pathlib import Path
@@ -15,6 +16,8 @@ from typing import Dict, List, Optional
 
 from src.server.models.config import AppConfig, ConfigUpdate, ValidationResult
 
+logger = logging.getLogger(__name__)
+
 
 class ConfigServiceError(Exception):
     """Base exception for configuration service errors."""
@@ -41,7 +44,7 @@ class ConfigService:
     """
     
     # Current configuration schema version
-    CONFIG_VERSION = "1.0.0"
+    CONFIG_VERSION = "1.0.1"
     
     def __init__(
         self,
@@ -136,7 +139,7 @@ class ConfigService:
                 self.create_backup()
             except ConfigBackupError as e:
                 # Log but don't fail save operation
-                print(f"Warning: Failed to create backup: {e}")
+                logger.warning("Failed to create backup: %s", e)
         
         # Save configuration with version
         data = config.model_dump()

src/server/services/folder_rename_service.py

@@ -0,0 +1,342 @@
+"""Folder rename service for validating and renaming series folders.
+
+After NFO repair, this service iterates over every subfolder in
+``settings.anime_directory`` that contains a ``tvshow.nfo``. For each
+folder it parses the NFO to extract ``<title>`` and ``<year>``, computes
+the expected folder name ``f"{title} ({year})"``, sanitises it for
+filesystem safety, and renames the folder if the current name differs.
+
+Database records (``AnimeSeries.folder``, ``Episode.file_path``,
+``DownloadQueueItem.file_destination``) are updated atomically to
+reflect the new paths.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from lxml import etree
+
+from src.config.settings import settings
+from src.server.database.connection import get_db_session
+from src.server.database.service import (
+    AnimeSeriesService,
+    DownloadQueueService,
+    EpisodeService,
+)
+from src.server.utils.dependencies import get_download_service
+from src.server.utils.filesystem import sanitize_folder_name
+
+logger = logging.getLogger(__name__)
+
+# Characters that are invalid in filesystem paths across platforms
+INVALID_PATH_CHARS = '<>:"/\\|?*\x00'
+
+
+def _parse_nfo_title_and_year(nfo_path: Path) -> Tuple[Optional[str], Optional[str]]:
+    """Parse a tvshow.nfo and return (title, year) text values.
+
+    Args:
+        nfo_path: Absolute path to the ``tvshow.nfo`` file.
+
+    Returns:
+        Tuple of (title, year) where either may be ``None`` if missing
+        or empty.
+    """
+    try:
+        tree = etree.parse(str(nfo_path))
+        root = tree.getroot()
+
+        title_elem = root.find("./title")
+        year_elem = root.find("./year")
+
+        title = title_elem.text.strip() if title_elem is not None and title_elem.text and title_elem.text.strip() else None
+        year = year_elem.text.strip() if year_elem is not None and year_elem.text and year_elem.text.strip() else None
+
+        return title, year
+    except etree.XMLSyntaxError as exc:
+        logger.warning("Malformed XML in %s: %s", nfo_path, exc)
+        return None, None
+    except Exception as exc:  # pylint: disable=broad-except
+        logger.warning("Unexpected error parsing %s: %s", nfo_path, exc)
+        return None, None
+
+
+def _compute_expected_folder_name(title: str, year: str) -> str:
+    """Compute the expected folder name from title and year.
+
+    Removes any existing year suffixes (e.g., "(2021)") before adding the
+    canonical one to prevent duplication across multiple folder rename runs.
+
+    Args:
+        title: Series title from NFO.
+        year: Release year from NFO.
+
+    Returns:
+        Sanitised folder name in the format ``"{title} ({year})"``.
+    """
+    import re
+
+    # Remove all trailing year suffixes to prevent duplication.
+    # This handles cases where the title already contains one or more years.
+    # Regex pattern: matches one or more " (YYYY)" at the end of the string
+    clean_title = re.sub(r'(\s*\(\d{4}\))+\s*$', '', title).strip()
+
+    year_suffix = f" ({year})"
+    raw_name = f"{clean_title}{year_suffix}"
+    return sanitize_folder_name(raw_name)
+
+
+def _is_series_being_downloaded(series_folder: str) -> bool:
+    """Check whether the given series has an active or pending download.
+
+    Args:
+        series_folder: The series folder name (as stored in the DB).
+
+    Returns:
+        ``True`` if the series appears in the active download or the
+        pending queue.
+    """
+    try:
+        download_service = get_download_service()
+        active = download_service._active_download  # pylint: disable=protected-access
+        if active and active.serie_folder == series_folder:
+            return True
+        for item in download_service._pending_queue:  # pylint: disable=protected-access
+            if item.serie_folder == series_folder:
+                return True
+        return False
+    except Exception as exc:  # pylint: disable=broad-except
+        logger.warning(
+            "Could not check download status for %s: %s", series_folder, exc
+        )
+        # Safer to skip renaming if we can't verify download status.
+        return True
+
+
+async def _update_database_paths(
+    old_folder: str,
+    new_folder: str,
+    anime_dir: Path,
+) -> None:
+    """Update all database records that reference the old folder path.
+
+    Updates:
+    - ``AnimeSeries.folder`` → ``new_folder``
+    - ``Episode.file_path`` → adjusted to new folder
+    - ``DownloadQueueItem.file_destination`` → adjusted to new folder
+
+    Args:
+        old_folder: Previous folder name.
+        new_folder: New folder name.
+        anime_dir: Root anime directory path.
+    """
+    old_series_path = anime_dir / old_folder
+    new_series_path = anime_dir / new_folder
+
+    async with get_db_session() as db:
+        # 1. Update AnimeSeries.folder
+        series = await AnimeSeriesService.get_by_key(db, old_folder)
+        if series is None:
+            # Fallback: try to find by folder name
+            all_series = await AnimeSeriesService.get_all(db)
+            for s in all_series:
+                if s.folder == old_folder:
+                    series = s
+                    break
+
+        if series is None:
+            logger.warning(
+                "No database record found for folder '%s', skipping DB update",
+                old_folder,
+            )
+            return
+
+        await AnimeSeriesService.update(db, series.id, folder=new_folder)
+        logger.info(
+            "Updated AnimeSeries.folder: %s → %s (id=%s)",
+            old_folder,
+            new_folder,
+            series.id,
+        )
+
+        # 2. Update Episode.file_path for all episodes of this series
+        episodes = await EpisodeService.get_by_series(db, series.id)
+        for episode in episodes:
+            if episode.file_path:
+                old_file_path = Path(episode.file_path)
+                # Only update if the path is under the old series folder
+                try:
+                    old_file_path.relative_to(old_series_path)
+                    new_file_path = new_series_path / old_file_path.relative_to(
+                        old_series_path
+                    )
+                    episode.file_path = str(new_file_path)
+                    logger.debug(
+                        "Updated Episode.file_path: %s → %s",
+                        old_file_path,
+                        new_file_path,
+                    )
+                except ValueError:
+                    # Path is not under old_series_path, skip
+                    pass
+
+        await db.flush()
+
+        # 3. Update DownloadQueueItem.file_destination for pending items
+        queue_items = await DownloadQueueService.get_all(db, with_series=True)
+        for item in queue_items:
+            if item.series_id == series.id and item.file_destination:
+                old_dest = Path(item.file_destination)
+                try:
+                    old_dest.relative_to(old_series_path)
+                    new_dest = new_series_path / old_dest.relative_to(
+                        old_series_path
+                    )
+                    item.file_destination = str(new_dest)
+                    logger.debug(
+                        "Updated DownloadQueueItem.file_destination: %s → %s",
+                        old_dest,
+                        new_dest,
+                    )
+                except ValueError:
+                    pass
+
+        await db.flush()
+        logger.info(
+            "Database paths updated for series '%s' → '%s'",
+            old_folder,
+            new_folder,
+        )
+
+
+async def validate_and_rename_series_folders() -> Dict[str, int]:
+    """Validate and rename series folders to match NFO metadata.
+
+    Iterates over every subfolder in ``settings.anime_directory`` that
+    contains a ``tvshow.nfo``. For each folder:
+
+    1. Parse the NFO to extract ``<title>`` and ``<year>``.
+    2. Compute the expected folder name: ``f"{title} ({year})"``.
+    3. Sanitise the expected name for filesystem safety.
+    4. Compare with the current folder name.
+    5. If different, rename the folder and update the database.
+
+    Skips folders where title or year is missing/empty. Logs every
+    rename action.
+
+    Returns:
+        Dictionary with counts:
+        - ``"scanned"``: total folders scanned
+        - ``"renamed"``: folders renamed
+        - ``"skipped"``: folders skipped (missing title/year)
+        - ``"errors"``: folders that caused an error
+    """
+    if not settings.anime_directory:
+        logger.warning("Folder rename skipped — anime directory not configured")
+        return {"scanned": 0, "renamed": 0, "skipped": 0, "errors": 0}
+
+    anime_dir = Path(settings.anime_directory)
+    if not anime_dir.is_dir():
+        logger.warning(
+            "Folder rename skipped — anime directory not found: %s", anime_dir
+        )
+        return {"scanned": 0, "renamed": 0, "skipped": 0, "errors": 0}
+
+    stats = {"scanned": 0, "renamed": 0, "skipped": 0, "errors": 0}
+
+    for series_dir in sorted(anime_dir.iterdir()):
+        if not series_dir.is_dir():
+            continue
+
+        nfo_path = series_dir / "tvshow.nfo"
+        if not nfo_path.exists():
+            continue
+
+        stats["scanned"] += 1
+
+        title, year = _parse_nfo_title_and_year(nfo_path)
+        if not title or not year:
+            logger.info(
+                "Skipping rename for '%s' — missing title or year in NFO",
+                series_dir.name,
+            )
+            stats["skipped"] += 1
+            continue
+
+        expected_name = _compute_expected_folder_name(title, year)
+        current_name = series_dir.name
+
+        if expected_name == current_name:
+            logger.debug(
+                "Folder name already correct: '%s'", current_name
+            )
+            continue
+
+        # Check for active downloads
+        if _is_series_being_downloaded(current_name):
+            logger.info(
+                "Skipping rename for '%s' — series has active or pending downloads",
+                current_name,
+            )
+            stats["skipped"] += 1
+            continue
+
+        expected_path = anime_dir / expected_name
+
+        # Check for duplicate target
+        if expected_path.exists():
+            logger.warning(
+                "Cannot rename '%s' → '%s' — target already exists",
+                current_name,
+                expected_name,
+            )
+            stats["errors"] += 1
+            continue
+
+        # Check path length limits
+        if len(str(expected_path)) > 4096:
+            logger.warning(
+                "Cannot rename '%s' → '%s' — path exceeds OS limit",
+                current_name,
+                expected_name,
+            )
+            stats["errors"] += 1
+            continue
+
+        try:
+            series_dir.rename(expected_path)
+            logger.info(
+                "Renamed folder: '%s' → '%s'", current_name, expected_name
+            )
+            stats["renamed"] += 1
+
+            # Update database records
+            await _update_database_paths(current_name, expected_name, anime_dir)
+
+        except PermissionError as exc:
+            logger.error(
+                "Permission denied renaming '%s' → '%s': %s",
+                current_name,
+                expected_name,
+                exc,
+            )
+            stats["errors"] += 1
+        except OSError as exc:
+            logger.error(
+                "OS error renaming '%s' → '%s': %s",
+                current_name,
+                expected_name,
+                exc,
+            )
+            stats["errors"] += 1
+
+    logger.info(
+        "Folder rename scan complete: scanned=%d, renamed=%d, skipped=%d, errors=%d",
+        stats["scanned"],
+        stats["renamed"],
+        stats["skipped"],
+        stats["errors"],
+    )
+    return stats

src/server/services/folder_scan_service.py

@@ -0,0 +1,377 @@
+"""Folder scan service for daily maintenance tasks.
+
+Encapsulates the daily folder-scan logic (orphaned-file detection,
+metadata refresh, and missing-episode queuing) so that the scheduler
+remains clean and the scan can be tested independently.
+"""
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Optional
+
+import structlog
+from lxml import etree
+
+from src.config.settings import settings as _settings
+from src.core.utils.image_downloader import ImageDownloader
+
+logger = structlog.get_logger(__name__)
+
+# Module-level semaphore to limit concurrent TMDB operations to 3.
+_TMDB_SEMAPHORE: asyncio.Semaphore = asyncio.Semaphore(3)
+
+# Semaphore to limit concurrent poster image downloads to 3.
+_POSTER_DOWNLOAD_SEMAPHORE: asyncio.Semaphore = asyncio.Semaphore(3)
+
+# Semaphore to limit concurrent NFO repair TMDB operations to 3.
+_NFO_REPAIR_SEMAPHORE: asyncio.Semaphore = asyncio.Semaphore(3)
+
+
+async def _repair_one_series(series_dir: Path, series_name: str) -> None:
+    """Repair a single series NFO in isolation.
+
+    Creates a fresh :class:`NFOService` and :class:`NfoRepairService` per
+    invocation so that each repair owns its own ``aiohttp`` session/connector
+    and concurrent tasks cannot interfere with each other.
+
+    A module-level semaphore (``_NFO_REPAIR_SEMAPHORE``) limits the number of
+    simultaneous TMDB requests to avoid rate-limiting.
+
+    Any exception is caught and logged so the asyncio task never silently
+    drops an unhandled error.
+
+    Args:
+        series_dir: Absolute path to the series folder.
+        series_name: Human-readable series name for log messages.
+    """
+    from src.core.services.nfo_factory import NFOServiceFactory
+    from src.core.services.nfo_repair_service import NfoRepairService
+
+    async with _NFO_REPAIR_SEMAPHORE:
+        try:
+            factory = NFOServiceFactory()
+            nfo_service = factory.create()
+            repair_service = NfoRepairService(nfo_service)
+            await repair_service.repair_series(series_dir, series_name)
+        except Exception as exc:  # pylint: disable=broad-except
+            logger.error(
+                "NFO repair failed for %s: %s",
+                series_name,
+                exc,
+            )
+
+
+async def perform_nfo_repair_scan(background_loader=None) -> None:
+    """Scan all series folders and repair incomplete tvshow.nfo files.
+
+    Called from ``FolderScanService.run_folder_scan()`` during the scheduled
+    daily folder scan (not on every startup).  Checks each subfolder of
+    ``settings.anime_directory`` for a ``tvshow.nfo`` and calls
+    ``_repair_one_series`` for every file with absent or empty required tags.
+
+    Each repair task creates its own isolated :class:`NFOService` /
+    :class:`TMDBClient` so concurrent tasks never share an ``aiohttp``
+    session — this prevents "Connector is closed" errors when many repairs
+    run in parallel.  A semaphore caps TMDB concurrency at 3 to stay within
+    rate limits.
+
+    The ``background_loader`` parameter is accepted for backwards-compatibility
+    but is no longer used.
+
+    Args:
+        background_loader: Unused.  Kept to avoid breaking call-sites.
+    """
+    from src.core.services.nfo_repair_service import nfo_needs_repair
+
+    if not _settings.tmdb_api_key:
+        logger.warning("NFO repair scan skipped — TMDB API key not configured")
+        return
+    if not _settings.anime_directory:
+        logger.warning("NFO repair scan skipped — anime directory not configured")
+        return
+    anime_dir = Path(_settings.anime_directory)
+    if not anime_dir.is_dir():
+        logger.warning("NFO repair scan skipped — anime directory not found: %s", anime_dir)
+        return
+
+    queued = 0
+    total = 0
+    for series_dir in sorted(anime_dir.iterdir()):
+        if not series_dir.is_dir():
+            continue
+        nfo_path = series_dir / "tvshow.nfo"
+        if not nfo_path.exists():
+            continue
+        total += 1
+        series_name = series_dir.name
+        if nfo_needs_repair(nfo_path):
+            queued += 1
+            # Each task creates its own NFOService so connectors are isolated.
+            asyncio.create_task(
+                _repair_one_series(series_dir, series_name),
+                name=f"nfo_repair:{series_name}",
+            )
+
+    logger.info(
+        "NFO repair scan complete: %d of %d series queued for repair",
+        queued,
+        total,
+    )
+
+
+class FolderScanServiceError(Exception):
+    """Service-level exception for folder-scan operations."""
+
+
+class FolderScanService:
+    """Performs daily maintenance scans over the anime library folder.
+
+    The service is intentionally stateless; a new instance can be created
+    for every scheduled invocation or test case.
+    """
+
+    async def run_folder_scan(self) -> None:
+        """Execute the daily folder scan.
+
+        Checks prerequisites, logs progress, and delegates to sub-task
+        helpers.  Any unhandled exception is caught and logged so the
+        scheduler task never crashes.
+        """
+        logger.info("Folder scan started")
+
+        try:
+            if not self._prerequisites_met():
+                return
+
+            # 1.3 — Repair incomplete NFO files in the background.
+            logger.info("Starting NFO repair scan as part of folder scan")
+            await perform_nfo_repair_scan(background_loader=None)
+            logger.info("NFO repair scan queued; repairs will continue in background")
+
+            # 1.4 — Validate and rename series folders after NFO repair.
+            logger.info("Starting folder rename validation")
+            from src.server.services.folder_rename_service import (
+                validate_and_rename_series_folders,
+            )
+
+            rename_stats = await validate_and_rename_series_folders()
+            logger.info(
+                "Folder rename validation complete",
+                scanned=rename_stats["scanned"],
+                renamed=rename_stats["renamed"],
+                skipped=rename_stats["skipped"],
+                errors=rename_stats["errors"],
+            )
+
+            # 1.5 — Check and download missing poster.jpg files.
+            logger.info("Starting poster check")
+            poster_stats = await self.check_and_download_missing_posters()
+            logger.info(
+                "Poster check complete",
+                scanned=poster_stats["scanned"],
+                downloaded=poster_stats["downloaded"],
+                skipped=poster_stats["skipped"],
+                errors=poster_stats["errors"],
+            )
+
+            logger.info("Folder scan completed")
+        except Exception as exc:  # pylint: disable=broad-exception-caught
+            logger.error("Folder scan failed", error=str(exc), exc_info=True)
+
+    # ------------------------------------------------------------------
+    # Poster check helpers
+    # ------------------------------------------------------------------
+
+    async def check_and_download_missing_posters(self) -> dict[str, int]:
+        """Iterate over series folders and download missing poster.jpg files.
+
+        For each folder containing a ``tvshow.nfo``:
+        1. Check if ``poster.jpg`` exists and is at least
+           :attr:`ImageDownloader.min_file_size` bytes.
+        2. If missing or too small, parse ``tvshow.nfo`` for a ``<thumb>``
+           URL (preferring ``aspect="poster"``).
+        3. Download the image via :class:`ImageDownloader` under a
+           semaphore that limits concurrency to 3.
+
+        Returns:
+            Dictionary with counts:
+            - ``"scanned"``: total folders scanned
+            - ``"downloaded"``: posters successfully downloaded
+            - ``"skipped"``: folders skipped (no NFO, no thumb URL,
+              or poster already valid)
+            - ``"errors"``: folders that caused a download error
+        """
+        from src.config.settings import settings  # noqa: PLC0415
+
+        stats = {"scanned": 0, "downloaded": 0, "skipped": 0, "errors": 0}
+
+        if not settings.anime_directory:
+            logger.warning("Poster check skipped — anime directory not configured")
+            return stats
+
+        anime_dir = Path(settings.anime_directory)
+        if not anime_dir.is_dir():
+            logger.warning(
+                "Poster check skipped — anime directory not found: %s", anime_dir
+            )
+            return stats
+
+        # Gather all series directories that contain a tvshow.nfo
+        series_dirs = [
+            d for d in anime_dir.iterdir()
+            if d.is_dir() and (d / "tvshow.nfo").exists()
+        ]
+
+        if not series_dirs:
+            logger.debug("No series folders found for poster check")
+            return stats
+
+        # Process each series folder concurrently with semaphore
+        tasks = [
+            self._check_and_download_poster(series_dir, stats)
+            for series_dir in series_dirs
+        ]
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+        return stats
+
+    async def _check_and_download_poster(
+        self, series_dir: Path, stats: dict[str, int]
+    ) -> None:
+        """Check and download poster for a single series folder.
+
+        Args:
+            series_dir: Path to the series folder.
+            stats: Mutable stats dictionary to update.
+        """
+        stats["scanned"] += 1
+        poster_path = series_dir / "poster.jpg"
+
+        # Check if poster already exists and is large enough
+        if poster_path.exists():
+            try:
+                # Default min_file_size from ImageDownloader is 1024 bytes (1 KB)
+                if poster_path.stat().st_size >= 1024:
+                    logger.debug(
+                        "Poster already valid for '%s'", series_dir.name
+                    )
+                    stats["skipped"] += 1
+                    return
+            except OSError:
+                pass  # Fall through to re-download
+
+        # Parse NFO for thumb URL
+        nfo_path = series_dir / "tvshow.nfo"
+        poster_url = self._extract_poster_url_from_nfo(nfo_path)
+
+        if not poster_url:
+            logger.info(
+                "No poster URL found in NFO for '%s', skipping",
+                series_dir.name,
+            )
+            stats["skipped"] += 1
+            return
+
+        # Respect the nfo_download_poster setting
+        from src.config.settings import settings as app_settings  # noqa: PLC0415
+
+        if not app_settings.nfo_download_poster:
+            logger.debug(
+                "Poster download disabled by nfo_download_poster setting for '%s'",
+                series_dir.name,
+            )
+            stats["skipped"] += 1
+            return
+
+        # Download poster with semaphore
+        async with _POSTER_DOWNLOAD_SEMAPHORE:
+            try:
+                async with ImageDownloader() as downloader:
+                    success = await downloader.download_poster(
+                        poster_url, series_dir, skip_existing=False
+                    )
+                if success:
+                    logger.info(
+                        "Downloaded poster for '%s'", series_dir.name
+                    )
+                    stats["downloaded"] += 1
+                else:
+                    logger.warning(
+                        "Failed to download poster for '%s'", series_dir.name
+                    )
+                    stats["errors"] += 1
+            except Exception as exc:  # pylint: disable=broad-except
+                logger.error(
+                    "Error downloading poster for '%s': %s",
+                    series_dir.name,
+                    exc,
+                )
+                stats["errors"] += 1
+
+    @staticmethod
+    def _extract_poster_url_from_nfo(nfo_path: Path) -> Optional[str]:
+        """Parse tvshow.nfo and extract the poster thumb URL.
+
+        Prefers ``<thumb aspect="poster">``; falls back to the first
+        ``<thumb>`` element if no aspect attribute is present.
+
+        Args:
+            nfo_path: Absolute path to the ``tvshow.nfo`` file.
+
+        Returns:
+            The poster URL string, or ``None`` if not found.
+        """
+        if not nfo_path.exists():
+            return None
+
+        try:
+            tree = etree.parse(str(nfo_path))
+            root = tree.getroot()
+
+            # Prefer thumb with aspect="poster"
+            for thumb in root.findall(".//thumb"):
+                if thumb.get("aspect") == "poster" and thumb.text:
+                    return thumb.text.strip()
+
+            # Fallback to first thumb with text
+            for thumb in root.findall(".//thumb"):
+                if thumb.text:
+                    return thumb.text.strip()
+
+            return None
+        except etree.XMLSyntaxError:
+            logger.warning("Malformed XML in %s", nfo_path)
+            return None
+        except Exception:  # pylint: disable=broad-except
+            return None
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _prerequisites_met(self) -> bool:
+        """Verify that the environment is ready for a folder scan.
+
+        Returns:
+            True when ``settings.anime_directory`` exists and
+            ``settings.tmdb_api_key`` is configured.
+        """
+        from src.config.settings import settings  # noqa: PLC0415
+
+        if not settings.tmdb_api_key:
+            logger.warning("Folder scan skipped — TMDB API key not configured")
+            return False
+
+        if not settings.anime_directory:
+            logger.warning("Folder scan skipped — anime directory not configured")
+            return False
+
+        anime_dir = Path(settings.anime_directory)
+        if not anime_dir.is_dir():
+            logger.warning(
+                "Folder scan skipped — anime directory not found: %s", anime_dir
+            )
+            return False
+
+        return True

src/server/services/initialization_service.py

@@ -342,7 +342,7 @@ async def perform_nfo_scan_if_needed(progress_service=None):
             if not settings.tmdb_api_key
             else "Skipped - NFO features disabled"
         )
-        logger.info(f"NFO scan skipped: {message}")
+        logger.info("NFO scan skipped: %s", message)
         
         if progress_service:
             await progress_service.complete_progress(
@@ -377,101 +377,6 @@ async def perform_nfo_scan_if_needed(progress_service=None):
             )
 
 
-_NFO_REPAIR_SEMAPHORE: asyncio.Semaphore = asyncio.Semaphore(3)
-
-
-async def _repair_one_series(series_dir: Path, series_name: str) -> None:
-    """Repair a single series NFO in isolation.
-
-    Creates a fresh :class:`NFOService` and :class:`NfoRepairService` per
-    invocation so that each repair owns its own ``aiohttp`` session/connector
-    and concurrent tasks cannot interfere with each other.
-
-    A module-level semaphore (``_NFO_REPAIR_SEMAPHORE``) limits the number of
-    simultaneous TMDB requests to avoid rate-limiting.
-
-    Any exception is caught and logged so the asyncio task never silently
-    drops an unhandled error.
-
-    Args:
-        series_dir: Absolute path to the series folder.
-        series_name: Human-readable series name for log messages.
-    """
-    from src.core.services.nfo_factory import NFOServiceFactory
-    from src.core.services.nfo_repair_service import NfoRepairService
-
-    async with _NFO_REPAIR_SEMAPHORE:
-        try:
-            factory = NFOServiceFactory()
-            nfo_service = factory.create()
-            repair_service = NfoRepairService(nfo_service)
-            await repair_service.repair_series(series_dir, series_name)
-        except Exception as exc:  # pylint: disable=broad-except
-            logger.error(
-                "NFO repair failed for %s: %s",
-                series_name,
-                exc,
-            )
-
-
-async def perform_nfo_repair_scan(background_loader=None) -> None:
-    """Scan all series folders and repair incomplete tvshow.nfo files.
-
-    Runs on every application startup (not guarded by a run-once DB flag).
-    Checks each subfolder of ``settings.anime_directory`` for a ``tvshow.nfo``
-    and calls ``_repair_one_series`` for every file with absent or empty
-    required tags.
-
-    Each repair task creates its own isolated :class:`NFOService` /
-    :class:`TMDBClient` so concurrent tasks never share an ``aiohttp``
-    session — this prevents "Connector is closed" errors when many repairs
-    run in parallel.  A semaphore caps TMDB concurrency at 3 to stay within
-    rate limits.
-
-    The ``background_loader`` parameter is accepted for backwards-compatibility
-    but is no longer used.
-
-    Args:
-        background_loader: Unused.  Kept to avoid breaking call-sites.
-    """
-    from src.core.services.nfo_repair_service import nfo_needs_repair
-
-    if not settings.tmdb_api_key:
-        logger.warning("NFO repair scan skipped — TMDB API key not configured")
-        return
-    if not settings.anime_directory:
-        logger.warning("NFO repair scan skipped — anime directory not configured")
-        return
-    anime_dir = Path(settings.anime_directory)
-    if not anime_dir.is_dir():
-        logger.warning("NFO repair scan skipped — anime directory not found: %s", anime_dir)
-        return
-
-    queued = 0
-    total = 0
-    for series_dir in sorted(anime_dir.iterdir()):
-        if not series_dir.is_dir():
-            continue
-        nfo_path = series_dir / "tvshow.nfo"
-        if not nfo_path.exists():
-            continue
-        total += 1
-        series_name = series_dir.name
-        if nfo_needs_repair(nfo_path):
-            queued += 1
-            # Each task creates its own NFOService so connectors are isolated.
-            asyncio.create_task(
-                _repair_one_series(series_dir, series_name),
-                name=f"nfo_repair:{series_name}",
-            )
-
-    logger.info(
-        "NFO repair scan complete: %d of %d series queued for repair",
-        queued,
-        total,
-    )
-
-
 async def _check_media_scan_status() -> bool:
     """Check if initial media scan has been completed.
     

src/server/services/notification_service.py

@@ -151,7 +151,7 @@ class EmailNotificationService:
                 start_tls=True,
             )
 
-            logger.info(f"Email notification sent to {to_address}")
+            logger.info("Email notification sent to %s", to_address)
             return True
 
         except ImportError:
@@ -160,7 +160,7 @@ class EmailNotificationService:
             )
             return False
         except Exception as e:
-            logger.error(f"Failed to send email notification: {e}")
+            logger.error("Failed to send email notification: %s", e)
             return False
 
 
@@ -205,7 +205,7 @@ class WebhookNotificationService:
                         timeout=aiohttp.ClientTimeout(total=self.timeout),
                     ) as response:
                         if response.status < 400:
-                            logger.info(f"Webhook notification sent to {url}")
+                            logger.info("Webhook notification sent to %s", url)
                             return True
                         else:
                             logger.warning(
@@ -213,9 +213,9 @@ class WebhookNotificationService:
                             )
 
             except asyncio.TimeoutError:
-                logger.warning(f"Webhook timeout (attempt {attempt + 1}/{self.max_retries}): {url}")
+                logger.warning("Webhook timeout (attempt %s/%s): %s", attempt + 1, self.max_retries, url)
             except Exception as e:
-                logger.error(f"Failed to send webhook (attempt {attempt + 1}/{self.max_retries}): {e}")
+                logger.error("Failed to send webhook (attempt %s/%s): %s", attempt + 1, self.max_retries, e)
 
             if attempt < self.max_retries - 1:
                 await asyncio.sleep(2 ** attempt)  # Exponential backoff
@@ -436,7 +436,7 @@ class NotificationService:
                 await self.in_app_service.add_notification(notification)
                 results["in_app"] = True
             except Exception as e:
-                logger.error(f"Failed to send in-app notification: {e}")
+                logger.error("Failed to send in-app notification: %s", e)
                 results["in_app"] = False
 
         # Send email notification
@@ -452,7 +452,7 @@ class NotificationService:
                 )
                 results["email"] = success
             except Exception as e:
-                logger.error(f"Failed to send email notification: {e}")
+                logger.error("Failed to send email notification: %s", e)
                 results["email"] = False
 
         # Send webhook notifications
@@ -476,7 +476,7 @@ class NotificationService:
                     success = await self.webhook_service.send_webhook(str(url), payload)
                     webhook_results.append(success)
                 except Exception as e:
-                    logger.error(f"Failed to send webhook notification to {url}: {e}")
+                    logger.error("Failed to send webhook notification to %s: %s", url, e)
                     webhook_results.append(False)
 
             results["webhook"] = all(webhook_results) if webhook_results else False

src/server/services/scheduler_service.py

@@ -145,6 +145,7 @@ class SchedulerService:
             schedule_time=config.schedule_time,
             schedule_days=config.schedule_days,
             auto_download=config.auto_download_after_rescan,
+            folder_scan=config.folder_scan_enabled,
         )
 
         if not self._scheduler or not self._scheduler.running:
@@ -204,6 +205,9 @@ class SchedulerService:
             "auto_download_after_rescan": (
                 self._config.auto_download_after_rescan if self._config else False
             ),
+            "folder_scan_enabled": (
+                self._config.folder_scan_enabled if self._config else False
+            ),
             "last_run": self._last_scan_time.isoformat() if self._last_scan_time else None,
             "next_run": next_run,
             "scan_in_progress": self._scan_in_progress,
@@ -352,6 +356,28 @@ class SchedulerService:
             else:
                 logger.debug("Auto-download after rescan is disabled — skipping")
 
+            # Folder scan (daily maintenance)
+            if self._config and self._config.folder_scan_enabled:
+                logger.info("Folder scan is enabled — starting")
+                try:
+                    from src.server.services.folder_scan_service import (  # noqa: PLC0415
+                        FolderScanService,
+                    )
+
+                    folder_scan_service = FolderScanService()
+                    await folder_scan_service.run_folder_scan()
+                except Exception as fs_exc:  # pylint: disable=broad-exception-caught
+                    logger.error(
+                        "Folder scan failed",
+                        error=str(fs_exc),
+                        exc_info=True,
+                    )
+                    await self._broadcast(
+                        "folder_scan_error", {"error": str(fs_exc)}
+                    )
+            else:
+                logger.debug("Folder scan is disabled — skipping")
+
         except Exception as exc:  # pylint: disable=broad-exception-caught
             logger.error("Scheduled rescan failed", error=str(exc), exc_info=True)
             await self._broadcast(

src/server/utils/dependencies.py

@@ -57,6 +57,44 @@ _rate_limit_lock = Lock()
 _RATE_LIMIT_WINDOW_SECONDS = 60.0
 
 
+def _make_db_lookup():
+    """Build a synchronous ``(folder) -> Serie | None`` callable for SerieScanner.
+
+    The returned function opens a short-lived sync DB session, queries for a
+    series whose ``folder`` column matches the given name, and converts the
+    ORM row to a ``Serie`` domain object.  Returns ``None`` when the DB is not
+    yet initialised or no matching row is found.
+    """
+    from src.core.entities.series import Serie
+
+    def _lookup(folder: str) -> Optional["Serie"]:
+        try:
+            from src.server.database.connection import get_sync_session
+            from src.server.database.service import AnimeSeriesService
+
+            db = get_sync_session()
+            try:
+                row = AnimeSeriesService.get_by_folder_sync(db, folder)
+            finally:
+                db.close()
+
+            if row is None:
+                return None
+            return Serie(
+                key=row.key,
+                name=row.name or "",
+                site=row.site,
+                folder=row.folder,
+                episodeDict={},
+                year=row.year,
+            )
+        except RuntimeError:
+            # DB not initialised yet (e.g. first boot before init_db())
+            return None
+
+    return _lookup
+
+
 def get_series_app() -> SeriesApp:
     """
     Dependency to get SeriesApp instance.
@@ -134,7 +172,7 @@ def get_series_app() -> SeriesApp:
                         ),
                     )
 
-            _series_app = SeriesApp(anime_dir)
+            _series_app = SeriesApp(anime_dir, db_lookup=_make_db_lookup())
         except Exception as e:
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,

src/server/utils/log_manager.py

@@ -82,7 +82,7 @@ class LogManager:
             log_path = self.log_dir / log_file
 
             if not log_path.exists():
-                logger.warning(f"Log file not found: {log_file}")
+                logger.warning("Log file not found: %s", log_file)
                 return False
 
             stat = log_path.stat()
@@ -99,10 +99,10 @@ class LogManager:
             # Compress the rotated file
             self._compress_log(rotated_path)
 
-            logger.info(f"Rotated log file: {log_file} -> {rotated_name}")
+            logger.info("Rotated log file: %s -> %s", log_file, rotated_name)
             return True
         except Exception as e:
-            logger.error(f"Failed to rotate log file {log_file}: {e}")
+            logger.error("Failed to rotate log file %s: %s", log_file, e)
             return False
 
     def _compress_log(self, log_path: Path) -> bool:
@@ -122,10 +122,10 @@ class LogManager:
                     shutil.copyfileobj(f_in, f_out)
 
             log_path.unlink()
-            logger.debug(f"Compressed log file: {log_path.name}")
+            logger.debug("Compressed log file: %s", log_path.name)
             return True
         except Exception as e:
-            logger.error(f"Failed to compress log {log_path}: {e}")
+            logger.error("Failed to compress log %s: %s", log_path, e)
             return False
 
     def archive_old_logs(
@@ -160,10 +160,10 @@ class LogManager:
                             f"Failed to archive {log_file.filename}: {e}"
                         )
 
-            logger.info(f"Archived {archived_count} old log files")
+            logger.info("Archived %s old log files", archived_count)
             return archived_count
         except Exception as e:
-            logger.error(f"Failed to archive logs: {e}")
+            logger.error("Failed to archive logs: %s", e)
             return 0
 
     def search_logs(
@@ -209,7 +209,7 @@ class LogManager:
             )
             return results
         except Exception as e:
-            logger.error(f"Failed to search logs: {e}")
+            logger.error("Failed to search logs: %s", e)
             return {}
 
     def export_logs(
@@ -243,7 +243,7 @@ class LogManager:
                             arcname=log_file.filename,
                         )
 
-                logger.info(f"Exported logs to: {tar_path}")
+                logger.info("Exported logs to: %s", tar_path)
                 return True
             else:
                 # Concatenate all logs
@@ -253,10 +253,10 @@ class LogManager:
                         with open(log_file.path, "r") as in_f:
                             out_f.write(in_f.read())
 
-                logger.info(f"Exported logs to: {output_path}")
+                logger.info("Exported logs to: %s", output_path)
                 return True
         except Exception as e:
-            logger.error(f"Failed to export logs: {e}")
+            logger.error("Failed to export logs: %s", e)
             return False
 
     def get_log_stats(self) -> Dict[str, Any]:
@@ -294,7 +294,7 @@ class LogManager:
                 "newest_file": log_files[0].filename,
             }
         except Exception as e:
-            logger.error(f"Failed to get log stats: {e}")
+            logger.error("Failed to get log stats: %s", e)
             return {}
 
     def cleanup_logs(
@@ -330,16 +330,16 @@ class LogManager:
                     log_file.path.unlink()
                     total_size -= log_file.size_bytes
                     deleted_count += 1
-                    logger.debug(f"Deleted log file: {log_file.filename}")
+                    logger.debug("Deleted log file: %s", log_file.filename)
                 except Exception as e:
                     logger.warning(
                         f"Failed to delete {log_file.filename}: {e}"
                     )
 
-            logger.info(f"Cleaned up {deleted_count} log files")
+            logger.info("Cleaned up %s log files", deleted_count)
             return deleted_count
         except Exception as e:
-            logger.error(f"Failed to cleanup logs: {e}")
+            logger.error("Failed to cleanup logs: %s", e)
             return 0
 
     def set_log_level(self, logger_name: str, level: str) -> bool:
@@ -357,10 +357,10 @@ class LogManager:
             target_logger = logging.getLogger(logger_name)
             target_logger.setLevel(log_level)
 
-            logger.info(f"Set {logger_name} log level to {level}")
+            logger.info("Set %s log level to %s", logger_name, level)
             return True
         except Exception as e:
-            logger.error(f"Failed to set log level: {e}")
+            logger.error("Failed to set log level: %s", e)
             return False
 
 

src/server/utils/logging.py

@@ -416,9 +416,9 @@ def cleanup_old_logs(log_dir: Union[str, Path],
         try:
             if log_file.stat().st_mtime < cutoff_time:
                 log_file.unlink()
-                logger.info(f"Deleted old log file: {log_file}")
+                logger.info("Deleted old log file: %s", log_file)
         except Exception as e:
-            logger.error(f"Failed to delete log file {log_file}: {e}")
+            logger.error("Failed to delete log file %s: %s", log_file, e)
 
 
 # Initialize default logging configuration

src/server/utils/metrics.py

@@ -161,7 +161,7 @@ class MetricsCollector:
             Duration in seconds.
         """
         if timer_name not in self._timers:
-            logger.warning(f"Timer {timer_name} not started")
+            logger.warning("Timer %s not started", timer_name)
             return 0.0
 
         duration = time.time() - self._timers[timer_name]

src/server/utils/system.py

@@ -60,7 +60,7 @@ class SystemUtilities:
                 path=path,
             )
         except Exception as e:
-            logger.error(f"Failed to get disk usage for {path}: {e}")
+            logger.error("Failed to get disk usage for %s: %s", path, e)
             return None
 
     @staticmethod
@@ -93,7 +93,7 @@ class SystemUtilities:
 
             return disk_infos
         except Exception as e:
-            logger.error(f"Failed to get all disk usage: {e}")
+            logger.error("Failed to get all disk usage: %s", e)
             return []
 
     @staticmethod
@@ -115,7 +115,7 @@ class SystemUtilities:
 
             path = Path(directory)
             if not path.exists():
-                logger.warning(f"Directory not found: {directory}")
+                logger.warning("Directory not found: %s", directory)
                 return 0
 
             deleted_count = 0
@@ -130,16 +130,16 @@ class SystemUtilities:
                         try:
                             file_path.unlink()
                             deleted_count += 1
-                            logger.debug(f"Deleted file: {file_path}")
+                            logger.debug("Deleted file: %s", file_path)
                         except Exception as e:
                             logger.warning(
                                 f"Failed to delete {file_path}: {e}"
                             )
 
-            logger.info(f"Cleaned up {deleted_count} files from {directory}")
+            logger.info("Cleaned up %s files from %s", deleted_count, directory)
             return deleted_count
         except Exception as e:
-            logger.error(f"Failed to cleanup directory {directory}: {e}")
+            logger.error("Failed to cleanup directory %s: %s", directory, e)
             return 0
 
     @staticmethod
@@ -171,12 +171,12 @@ class SystemUtilities:
                                 f"Deleted empty directory: {dir_path}"
                             )
                     except Exception as e:
-                        logger.debug(f"Cannot delete {dir_path}: {e}")
+                        logger.debug("Cannot delete %s: %s", dir_path, e)
 
-            logger.info(f"Cleaned up {deleted_count} empty directories")
+            logger.info("Cleaned up %s empty directories", deleted_count)
             return deleted_count
         except Exception as e:
-            logger.error(f"Failed to cleanup empty directories: {e}")
+            logger.error("Failed to cleanup empty directories: %s", e)
             return 0
 
     @staticmethod
@@ -201,7 +201,7 @@ class SystemUtilities:
 
             return total_size
         except Exception as e:
-            logger.error(f"Failed to get directory size for {directory}: {e}")
+            logger.error("Failed to get directory size for %s: %s", directory, e)
             return 0
 
     @staticmethod
@@ -232,7 +232,7 @@ class SystemUtilities:
                     ),
                 )
         except Exception as e:
-            logger.error(f"Failed to get process info for {pid}: {e}")
+            logger.error("Failed to get process info for %s: %s", pid, e)
             return None
 
     @staticmethod
@@ -260,7 +260,7 @@ class SystemUtilities:
 
             return processes
         except Exception as e:
-            logger.error(f"Failed to get all processes: {e}")
+            logger.error("Failed to get all processes: %s", e)
             return []
 
     @staticmethod
@@ -285,7 +285,7 @@ class SystemUtilities:
                 "python_version": platform.python_version(),
             }
         except Exception as e:
-            logger.error(f"Failed to get system info: {e}")
+            logger.error("Failed to get system info: %s", e)
             return {}
 
     @staticmethod
@@ -308,7 +308,7 @@ class SystemUtilities:
                 "dropped_out": net_io.dropout,
             }
         except Exception as e:
-            logger.error(f"Failed to get network info: {e}")
+            logger.error("Failed to get network info: %s", e)
             return {}
 
     @staticmethod
@@ -330,7 +330,7 @@ class SystemUtilities:
             dest_path = Path(dest)
 
             if not src_path.exists():
-                logger.error(f"Source file not found: {src}")
+                logger.error("Source file not found: %s", src)
                 return False
 
             # Create temporary file
@@ -342,10 +342,10 @@ class SystemUtilities:
             # Atomic rename
             temp_path.replace(dest_path)
 
-            logger.debug(f"Atomically copied {src} to {dest}")
+            logger.debug("Atomically copied %s to %s", src, dest)
             return True
         except Exception as e:
-            logger.error(f"Failed to copy file {src} to {dest}: {e}")
+            logger.error("Failed to copy file %s to %s: %s", src, dest, e)
             return False
 
 

src/server/utils/template_helpers.py

@@ -48,7 +48,7 @@ def get_base_context(
         "request": request,
         "title": title,
         "app_name": "Aniworld Download Manager",
-        "version": "1.0.0",
+        "version": "1.0.1",
         "static_v": STATIC_VERSION,
     }
 

src/server/web/static/js/app.js

@@ -1561,6 +1561,8 @@ class AniWorldApp {
                 document.getElementById('scheduled-rescan-enabled').checked = !!config.enabled;
                 document.getElementById('scheduled-rescan-time').value = config.schedule_time || '03:00';
                 document.getElementById('auto-download-after-rescan').checked = !!config.auto_download_after_rescan;
+                const folderScanEl = document.getElementById('folder-scan-enabled');
+                if (folderScanEl) folderScanEl.checked = !!config.folder_scan_enabled;
 
                 // Update day-of-week checkboxes
                 const days = Array.isArray(config.schedule_days) ? config.schedule_days : ['mon','tue','wed','thu','fri','sat','sun'];
@@ -1603,6 +1605,8 @@ class AniWorldApp {
             const enabled = document.getElementById('scheduled-rescan-enabled').checked;
             const scheduleTime = document.getElementById('scheduled-rescan-time').value || '03:00';
             const autoDownload = document.getElementById('auto-download-after-rescan').checked;
+            const folderScanEl = document.getElementById('folder-scan-enabled');
+            const folderScan = folderScanEl ? folderScanEl.checked : false;
 
             // Collect checked day-of-week values
             const scheduleDays = ['mon','tue','wed','thu','fri','sat','sun']
@@ -1618,7 +1622,8 @@ class AniWorldApp {
                     enabled: enabled,
                     schedule_time: scheduleTime,
                     schedule_days: scheduleDays,
-                    auto_download_after_rescan: autoDownload
+                    auto_download_after_rescan: autoDownload,
+                    folder_scan_enabled: folderScan
                 })
             });
 

src/server/web/static/js/index/scheduler-config.js

@@ -35,6 +35,11 @@ AniWorld.SchedulerConfig = (function() {
                     autoDownload.checked = config.auto_download_after_rescan || false;
                 }
 
+                const folderScan = document.getElementById('folder-scan-enabled');
+                if (folderScan) {
+                    folderScan.checked = config.folder_scan_enabled || false;
+                }
+
                 // Update schedule day checkboxes
                 const days = config.schedule_days || ['mon','tue','wed','thu','fri','sat','sun'];
                 ['mon','tue','wed','thu','fri','sat','sun'].forEach(function(day) {
@@ -82,12 +87,16 @@ AniWorld.SchedulerConfig = (function() {
             const autoDownloadEl = document.getElementById('auto-download-after-rescan');
             const autoDownload = autoDownloadEl ? autoDownloadEl.checked : false;
 
+            const folderScanEl = document.getElementById('folder-scan-enabled');
+            const folderScan = folderScanEl ? folderScanEl.checked : false;
+
             // POST directly to the scheduler config endpoint
             const payload = {
                 enabled: enabled,
                 schedule_time: scheduleTime,
                 schedule_days: scheduleDays,
-                auto_download_after_rescan: autoDownload
+                auto_download_after_rescan: autoDownload,
+                folder_scan_enabled: folderScan
             };
 
             const response = await AniWorld.ApiClient.post(API.SCHEDULER_CONFIG, payload);

src/server/web/static/js/index/series-manager.js

@@ -16,7 +16,7 @@ AniWorld.SeriesManager = (function() {
     // State
     let seriesData = [];
     let filteredSeriesData = [];
-    let showMissingOnly = false;
+    let filterMode = 'all'; // 'all' | 'missing_episodes' | 'no_episodes'
     let sortAlphabetical = false;
 
     /**
@@ -24,15 +24,16 @@ AniWorld.SeriesManager = (function() {
      */
     function init() {
         bindEvents();
+        updateFilterButtonUI();
     }
 
     /**
      * Bind UI events for filtering and sorting
      */
     function bindEvents() {
-        const missingOnlyBtn = document.getElementById('show-missing-only');
-        if (missingOnlyBtn) {
-            missingOnlyBtn.addEventListener('click', toggleMissingOnlyFilter);
+        const filterBtn = document.getElementById('show-missing-only');
+        if (filterBtn) {
+            filterBtn.addEventListener('click', toggleFilterMode);
         }
 
         const sortBtn = document.getElementById('sort-alphabetical');
@@ -49,7 +50,10 @@ AniWorld.SeriesManager = (function() {
         try {
             AniWorld.UI.showLoading();
 
-            const response = await AniWorld.ApiClient.get(API.ANIME_LIST);
+            const url = filterMode && filterMode !== 'all'
+                ? `${API.ANIME_LIST}?filter=${encodeURIComponent(filterMode)}`
+                : API.ANIME_LIST;
+            const response = await AniWorld.ApiClient.get(url);
 
             if (!response) {
                 return [];
@@ -111,28 +115,28 @@ AniWorld.SeriesManager = (function() {
     }
 
     /**
-     * Toggle missing episodes only filter
+     * Cycle through filter modes:
+     *   - all: Show all series
+     *   - missing_episodes: Show only series with missing episodes
+     *   - no_episodes: Show only series with zero downloaded episodes
      */
-    function toggleMissingOnlyFilter() {
-        showMissingOnly = !showMissingOnly;
+    async function toggleFilterMode() {
         const button = document.getElementById('show-missing-only');
-
-        button.setAttribute('data-active', showMissingOnly);
-        button.classList.toggle('active', showMissingOnly);
-
         const icon = button.querySelector('i');
         const text = button.querySelector('span');
 
-        if (showMissingOnly) {
-            icon.className = 'fas fa-filter-circle-xmark';
-            text.textContent = 'Show All Series';
+        // Cycle through modes
+        if (filterMode === 'all') {
+            filterMode = 'missing_episodes';
+        } else if (filterMode === 'missing_episodes') {
+            filterMode = 'no_episodes';
         } else {
-            icon.className = 'fas fa-filter';
-            text.textContent = 'Missing Episodes Only';
+            filterMode = 'all';
         }
 
-        applyFiltersAndSort();
-        renderSeries();
+        // Update button UI and reload list based on new filter.
+        updateFilterButtonUI();
+        await loadSeries();
 
         // Clear selection when filter changes
         if (AniWorld.SelectionManager) {
@@ -140,6 +144,34 @@ AniWorld.SeriesManager = (function() {
         }
     }
 
+    /**
+     * Update the filter button UI to reflect current filter mode
+     */
+    function updateFilterButtonUI() {
+        const button = document.getElementById('show-missing-only');
+        if (!button) {
+            return;
+        }
+
+        const icon = button.querySelector('i');
+        const text = button.querySelector('span');
+
+        const isActive = filterMode !== 'all';
+        button.setAttribute('data-active', isActive);
+        button.classList.toggle('active', isActive);
+
+        if (filterMode === 'missing_episodes') {
+            icon.className = 'fas fa-filter';
+            text.textContent = 'Missing Episodes Only';
+        } else if (filterMode === 'no_episodes') {
+            icon.className = 'fas fa-ban';
+            text.textContent = 'No Episodes';
+        } else {
+            icon.className = 'fas fa-filter-circle-xmark';
+            text.textContent = 'Show All Series';
+        }
+    }
+
     /**
      * Toggle alphabetical sorting
      */
@@ -193,13 +225,6 @@ AniWorld.SeriesManager = (function() {
             }
         });
 
-        // Apply missing episodes filter
-        if (showMissingOnly) {
-            filtered = filtered.filter(function(serie) {
-                return serie.missing_episodes > 0;
-            });
-        }
-
         filteredSeriesData = filtered;
     }
 
@@ -212,9 +237,14 @@ AniWorld.SeriesManager = (function() {
             (seriesData.length > 0 ? seriesData : []);
 
         if (dataToRender.length === 0) {
-            const message = showMissingOnly ?
-                'No series with missing episodes found.' :
-                'No series found. Try searching for anime or rescanning your directory.';
+            let message;
+            if (filterMode === 'missing_episodes') {
+                message = 'No series with missing episodes found.';
+            } else if (filterMode === 'no_episodes') {
+                message = 'No series with zero downloaded episodes found.';
+            } else {
+                message = 'No series found. Try searching for anime or rescanning your directory.';
+            }
 
             grid.innerHTML =
                 '<div class="text-center" style="grid-column: 1 / -1; padding: 2rem;">' +

src/server/web/templates/index.html

@@ -309,6 +309,17 @@
                             </label>
                         </div>
 
+                        <div class="config-item">
+                            <label class="checkbox-label">
+                                <input type="checkbox" id="folder-scan-enabled">
+                                <span class="checkbox-custom"></span>
+                                <span data-text="folder-scan-enabled">Run folder maintenance (NFO repair, renaming, poster checks)</span>
+                            </label>
+                            <small class="config-hint" data-text="folder-scan-hint">
+                                Automatically repair NFOs, rename folders, and check posters during scheduled runs.
+                            </small>
+                        </div>
+
 
                         <div class="config-item scheduler-status" id="scheduler-status">
                             <div class="scheduler-info">

src/server/web/templates/setup.html

@@ -479,6 +479,13 @@
                                 <span>Auto-download missing episodes after rescan</span>
                             </label>
                         </div>
+                        <div class="form-group">
+                            <label class="form-checkbox">
+                                <input type="checkbox" id="scheduler_folder_scan" name="scheduler_folder_scan">
+                                <span>Run folder maintenance (NFO repair, renaming, poster checks)</span>
+                            </label>
+                            <div class="form-help">Automatically repair NFOs, rename folders, and check posters during scheduled runs</div>
+                        </div>
                     </div>
                 </div>
 
@@ -761,6 +768,7 @@
                 scheduler_schedule_time: document.getElementById('scheduler_schedule_time').value || '03:00',
                 scheduler_schedule_days: Array.from(document.querySelectorAll('.scheduler-day-setup-cb:checked')).map(cb => cb.value),
                 scheduler_auto_download_after_rescan: document.getElementById('scheduler_auto_download').checked,
+                scheduler_folder_scan_enabled: document.getElementById('scheduler_folder_scan').checked,
                 logging_level: document.getElementById('logging_level').value,
                 logging_file: document.getElementById('logging_file').value.trim() || null,
                 logging_max_bytes: document.getElementById('logging_max_bytes').value ? 

tests/api/test_anime_endpoints.py

@@ -334,6 +334,25 @@ async def test_add_series_sanitizes_folder_name(authenticated_client):
     assert "?" not in folder
 
 
+@pytest.mark.asyncio
+async def test_add_series_does_not_duplicate_year(authenticated_client):
+    """Test that add_series doesn't duplicate year when name already contains it."""
+    response = await authenticated_client.post(
+        "/api/anime/add",
+        json={
+            "link": "https://aniworld.to/anime/stream/eighty-six",
+            "name": "86 Eighty Six (2021)"
+        }
+    )
+    
+    assert response.status_code == 202
+    data = response.json()
+    
+    # Folder should contain year only once
+    folder = data["folder"]
+    assert folder.count("(2021)") == 1
+
+
 @pytest.mark.asyncio
 async def test_add_series_returns_missing_episodes(authenticated_client):
     """Test that add_series returns loading progress info."""

tests/api/test_concurrent_anime_add.py

@@ -4,12 +4,15 @@ This test verifies that the /api/anime/add endpoint can handle
 multiple concurrent requests without blocking.
 """
 import asyncio
+import logging
 import time
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 from httpx import ASGITransport, AsyncClient
 
+logger = logging.getLogger(__name__)
+
 from src.server.fastapi_app import app
 from src.server.services.auth_service import auth_service
 from src.server.services.background_loader_service import get_background_loader_service
@@ -103,7 +106,7 @@ async def test_concurrent_anime_add_requests(authenticated_client):
         f"indicating possible blocking issues"
     )
 
-    print(f"3 concurrent anime add requests completed in {total_time:.2f}s")
+    logger.info("3 concurrent anime add requests completed in %.2fs", total_time)
 
 
 @pytest.mark.asyncio
@@ -130,4 +133,4 @@ async def test_same_anime_concurrent_add(authenticated_client):
     keys = [r.json().get("key") for r in responses]
     assert keys[0] == keys[1], "Both responses should have the same key"
 
-    print(f"Concurrent same-anime requests handled correctly: {statuses}")
+    logger.info("Concurrent same-anime requests handled correctly: %s", statuses)

tests/integration/test_add_anime_nfo_content.py

@@ -0,0 +1,314 @@
+"""Integration test: add an anime and verify NFO contains required information.
+
+This test adds 'Sacrificial Princess And The King Of Beasts' and verifies
+that the generated tvshow.nfo contains all required tags including plot,
+outline, title, year, etc.
+"""
+
+from pathlib import Path
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from lxml import etree
+
+from src.core.services.nfo_service import NFOService
+
+# ---------------------------------------------------------------------------
+# Mock TMDB data for "Sacrificial Princess And The King Of Beasts"
+# ---------------------------------------------------------------------------
+MOCK_TMDB_DATA = {
+    "id": 222093,
+    "name": "Sacrificial Princess and the King of Beasts",
+    "original_name": "贄姫と獣の王",
+    "overview": (
+        "A girl is offered as a sacrifice to a beastly king, "
+        "but instead of being eaten, she becomes his bride."
+    ),
+    "tagline": "A tale of love between a sacrifice and a beast king.",
+    "first_air_date": "2023-04-20",
+    "vote_average": 7.5,
+    "vote_count": 150,
+    "status": "Ended",
+    "episode_run_time": [24],
+    "genres": [
+        {"id": 16, "name": "Animation"},
+        {"id": 10749, "name": "Romance"},
+    ],
+    "networks": [{"id": 1, "name": "TBS"}],
+    "origin_country": ["JP"],
+    "poster_path": "/poster.jpg",
+    "backdrop_path": "/backdrop.jpg",
+    "external_ids": {"imdb_id": "tt19896734", "tvdb_id": 421737},
+    "credits": {
+        "cast": [
+            {
+                "id": 1,
+                "name": "Test Actor",
+                "character": "Sariphi",
+                "profile_path": "/actor.jpg",
+            }
+        ]
+    },
+    "images": {"logos": [{"file_path": "/logo.png"}]},
+    "seasons": [{"season_number": 1, "name": "Season 1"}],
+}
+
+MOCK_CONTENT_RATINGS = {
+    "results": [
+        {"iso_3166_1": "DE", "rating": "12"},
+        {"iso_3166_1": "US", "rating": "TV-14"},
+    ]
+}
+
+# ---------------------------------------------------------------------------
+# Required XML tags that must exist and be non-empty after creation
+# ---------------------------------------------------------------------------
+REQUIRED_SINGLE_TAGS = [
+    "title",
+    "originaltitle",
+    "sorttitle",
+    "year",
+    "plot",
+    "outline",
+    "runtime",
+    "premiered",
+    "status",
+    "tmdbid",
+    "imdbid",
+    "tvdbid",
+    "dateadded",
+    "watched",
+    "mpaa",
+    "tagline",
+]
+
+REQUIRED_MULTI_TAGS = [
+    "genre",
+    "studio",
+    "country",
+]
+
+
+@pytest.fixture
+def anime_dir(tmp_path: Path) -> Path:
+    """Temporary anime root directory."""
+    d = tmp_path / "anime"
+    d.mkdir()
+    return d
+
+
+@pytest.fixture
+def nfo_service(anime_dir: Path) -> NFOService:
+    """NFOService pointing at the temp directory."""
+    return NFOService(
+        tmdb_api_key="test_api_key",
+        anime_directory=str(anime_dir),
+        image_size="w500",
+        auto_create=True,
+    )
+
+
+class TestAddAnimeNFOContent:
+    """Test that adding an anime produces an NFO with required information."""
+
+    @pytest.mark.asyncio
+    async def test_add_anime_nfo_contains_required_tags(
+        self,
+        nfo_service: NFOService,
+        anime_dir: Path,
+    ) -> None:
+        """Add 'Sacrificial Princess And The King Of Beasts' and verify NFO.
+
+        Steps:
+        1. Create the series folder on disk.
+        2. Mock TMDB API responses.
+        3. Call create_tvshow_nfo to generate the NFO.
+        4. Parse the resulting XML and assert every required tag is present
+           and non-empty.
+        """
+        series_key = "sacrificial-princess-and-the-king-of-beasts"
+        series_name = "Sacrificial Princess And The King Of Beasts"
+        series_folder = f"{series_name} (2023)"
+
+        # Step 1: Create series folder
+        series_path = anime_dir / series_folder
+        series_path.mkdir()
+
+        # Step 2: Mock TMDB API calls
+        with patch.object(
+            nfo_service.tmdb_client,
+            "search_tv_show",
+            new_callable=AsyncMock,
+        ) as mock_search, patch.object(
+            nfo_service.tmdb_client,
+            "get_tv_show_details",
+            new_callable=AsyncMock,
+        ) as mock_details, patch.object(
+            nfo_service.tmdb_client,
+            "get_tv_show_content_ratings",
+            new_callable=AsyncMock,
+        ) as mock_ratings, patch.object(
+            nfo_service.image_downloader,
+            "download_all_media",
+            new_callable=AsyncMock,
+        ) as mock_download:
+
+            mock_search.return_value = {
+                "results": [
+                    {
+                        "id": 222093,
+                        "name": series_name,
+                        "first_air_date": "2023-04-20",
+                        "overview": (
+                            "A girl is offered as a sacrifice to a beastly king..."
+                        ),
+                    }
+                ]
+            }
+            mock_details.return_value = MOCK_TMDB_DATA
+            mock_ratings.return_value = MOCK_CONTENT_RATINGS
+            mock_download.return_value = {
+                "poster": True,
+                "logo": True,
+                "fanart": True,
+            }
+
+            # Step 3: Create NFO
+            nfo_path = await nfo_service.create_tvshow_nfo(
+                serie_name=series_name,
+                serie_folder=series_folder,
+                year=2023,
+                download_poster=True,
+                download_logo=True,
+                download_fanart=True,
+            )
+
+        # Verify NFO was created
+        assert nfo_path.exists(), f"NFO file not created at {nfo_path}"
+        assert nfo_path.name == "tvshow.nfo"
+
+        # Step 4: Parse NFO XML and verify required tags
+        nfo_content = nfo_path.read_text(encoding="utf-8")
+        root = etree.fromstring(nfo_content.encode("utf-8"))
+
+        missing: list[str] = []
+        for tag in REQUIRED_SINGLE_TAGS:
+            elem = root.find(f".//{tag}")
+            if elem is None or not (elem.text or "").strip():
+                missing.append(tag)
+
+        for tag in REQUIRED_MULTI_TAGS:
+            elems = root.findall(f".//{tag}")
+            if not elems or not any((e.text or "").strip() for e in elems):
+                missing.append(tag)
+
+        # At least one actor must be present
+        actors = root.findall(".//actor/name")
+        if not actors or not any((a.text or "").strip() for a in actors):
+            missing.append("actor/name")
+
+        assert not missing, (
+            f"Missing or empty required tags in NFO for '{series_name}':\n  "
+            + "\n  ".join(missing)
+            + f"\n\nFull NFO content:\n{nfo_content}"
+        )
+
+        # Verify specific values for the requested anime
+        assert root.findtext(".//title") == "Sacrificial Princess and the King of Beasts"
+        assert root.findtext(".//year") == "2023"
+        assert root.findtext(".//status") == "Ended"
+        assert root.findtext(".//watched") == "false"
+        assert root.findtext(".//tmdbid") == "222093"
+        assert root.findtext(".//imdbid") == "tt19896734"
+        assert root.findtext(".//tvdbid") == "421737"
+
+        # Plot and outline must be non-trivial
+        plot = root.findtext(".//plot") or ""
+        outline = root.findtext(".//outline") or ""
+        assert len(plot) >= 10, f"plot too short: {plot!r}"
+        assert len(outline) >= 10, f"outline too short: {outline!r}"
+
+        # Verify multi-value fields
+        genres = [g.text for g in root.findall(".//genre") if g.text]
+        assert "Animation" in genres
+        assert "Romance" in genres
+
+        studios = [s.text for s in root.findall(".//studio") if s.text]
+        assert "TBS" in studios
+
+        countries = [c.text for c in root.findall(".//country") if c.text]
+        assert "JP" in countries
+
+    @pytest.mark.asyncio
+    async def test_add_anime_nfo_has_plot_and_outline(
+        self,
+        nfo_service: NFOService,
+        anime_dir: Path,
+    ) -> None:
+        """Specifically verify that plot and outline tags are populated.
+
+        This is a focused regression test ensuring the NFO always contains
+        meaningful plot and outline data.
+        """
+        series_name = "Sacrificial Princess And The King Of Beasts"
+        series_folder = f"{series_name} (2023)"
+        series_path = anime_dir / series_folder
+        series_path.mkdir()
+
+        with patch.object(
+            nfo_service.tmdb_client,
+            "search_tv_show",
+            new_callable=AsyncMock,
+        ) as mock_search, patch.object(
+            nfo_service.tmdb_client,
+            "get_tv_show_details",
+            new_callable=AsyncMock,
+        ) as mock_details, patch.object(
+            nfo_service.tmdb_client,
+            "get_tv_show_content_ratings",
+            new_callable=AsyncMock,
+        ) as mock_ratings, patch.object(
+            nfo_service.image_downloader,
+            "download_all_media",
+            new_callable=AsyncMock,
+        ) as mock_download:
+
+            mock_search.return_value = {
+                "results": [
+                    {
+                        "id": 222093,
+                        "name": series_name,
+                        "first_air_date": "2023-04-20",
+                    }
+                ]
+            }
+            mock_details.return_value = MOCK_TMDB_DATA
+            mock_ratings.return_value = MOCK_CONTENT_RATINGS
+            mock_download.return_value = {"poster": False, "logo": False, "fanart": False}
+
+            nfo_path = await nfo_service.create_tvshow_nfo(
+                serie_name=series_name,
+                serie_folder=series_folder,
+                year=2023,
+                download_poster=False,
+                download_logo=False,
+                download_fanart=False,
+            )
+
+        assert nfo_path.exists()
+        root = etree.parse(str(nfo_path)).getroot()
+
+        plot_elem = root.find(".//plot")
+        outline_elem = root.find(".//outline")
+
+        assert plot_elem is not None, "<plot> tag missing from NFO"
+        assert outline_elem is not None, "<outline> tag missing from NFO"
+
+        plot_text = (plot_elem.text or "").strip()
+        outline_text = (outline_elem.text or "").strip()
+
+        assert plot_text, "<plot> tag is empty"
+        assert outline_text, "<outline> tag is empty"
+        assert "sacrifice" in plot_text.lower() or "beast" in plot_text.lower(), (
+            f"plot does not contain expected content: {plot_text!r}"
+        )

tests/integration/test_anime_add_nfo_isolation.py

@@ -91,6 +91,13 @@ def _setup_loader_mocks(loader_service):
     loader_service._broadcast_status = AsyncMock()
 
 
+def _mock_nfo_factory(mock_nfo_service):
+    """Create a mock NFO factory that returns the given mock service."""
+    mock_factory = MagicMock()
+    mock_factory.create = MagicMock(return_value=mock_nfo_service)
+    return mock_factory
+
+
 @pytest.mark.asyncio
 async def test_add_anime_loads_nfo_only_for_new_anime(
     temp_anime_dir,
@@ -112,49 +119,55 @@ async def test_add_anime_loads_nfo_only_for_new_anime(
     )
     _setup_loader_mocks(loader_service)
 
-    await loader_service.start()
+    # Set up mock NFO service via factory
+    mock_nfo_service = AsyncMock()
+    mock_nfo_service.create_tvshow_nfo = AsyncMock(return_value="/anime/New Anime (2024)/tvshow.nfo")
+    mock_factory = _mock_nfo_factory(mock_nfo_service)
 
-    try:
-        new_anime_key = "new-anime"
-        new_anime_folder = "New Anime (2024)"
-        new_anime_name = "New Anime"
-        new_anime_year = 2024
+    with patch("src.server.services.background_loader_service.get_nfo_factory", return_value=mock_factory):
+        await loader_service.start()
 
-        new_anime_dir = Path(temp_anime_dir) / new_anime_folder
-        new_anime_dir.mkdir()
+        try:
+            new_anime_key = "new-anime"
+            new_anime_folder = "New Anime (2024)"
+            new_anime_name = "New Anime"
+            new_anime_year = 2024
 
-        await loader_service.add_series_loading_task(
-            key=new_anime_key,
-            folder=new_anime_folder,
-            name=new_anime_name,
-            year=new_anime_year,
-        )
+            new_anime_dir = Path(temp_anime_dir) / new_anime_folder
+            new_anime_dir.mkdir()
 
-        await asyncio.sleep(1.0)
+            await loader_service.add_series_loading_task(
+                key=new_anime_key,
+                folder=new_anime_folder,
+                name=new_anime_name,
+                year=new_anime_year,
+            )
 
-        assert mock_series_app.nfo_service.create_tvshow_nfo.call_count == 1
+            await asyncio.sleep(1.0)
 
-        call_args = mock_series_app.nfo_service.create_tvshow_nfo.call_args
-        assert call_args is not None
+            assert mock_nfo_service.create_tvshow_nfo.call_count == 1
 
-        kwargs = call_args.kwargs
-        assert kwargs["serie_name"] == new_anime_name
-        assert kwargs["serie_folder"] == new_anime_folder
-        assert kwargs["year"] == new_anime_year
-        assert kwargs["download_poster"] is True
-        assert kwargs["download_logo"] is True
-        assert kwargs["download_fanart"] is True
+            call_args = mock_nfo_service.create_tvshow_nfo.call_args
+            assert call_args is not None
 
-        all_calls = mock_series_app.nfo_service.create_tvshow_nfo.call_args_list
-        for call_obj in all_calls:
-            call_kwargs = call_obj.kwargs
-            assert call_kwargs["serie_name"] != "Existing Anime 1"
-            assert call_kwargs["serie_name"] != "Existing Anime 2"
-            assert call_kwargs["serie_folder"] != "Existing Anime 1"
-            assert call_kwargs["serie_folder"] != "Existing Anime 2"
+            kwargs = call_args.kwargs
+            assert kwargs["serie_name"] == new_anime_name
+            assert kwargs["serie_folder"] == new_anime_folder
+            assert kwargs["year"] == new_anime_year
+            assert kwargs["download_poster"] is True
+            assert kwargs["download_logo"] is True
+            assert kwargs["download_fanart"] is True
 
-    finally:
-        await loader_service.stop()
+            all_calls = mock_nfo_service.create_tvshow_nfo.call_args_list
+            for call_obj in all_calls:
+                call_kwargs = call_obj.kwargs
+                assert call_kwargs["serie_name"] != "Existing Anime 1"
+                assert call_kwargs["serie_name"] != "Existing Anime 2"
+                assert call_kwargs["serie_folder"] != "Existing Anime 1"
+                assert call_kwargs["serie_folder"] != "Existing Anime 2"
+
+        finally:
+            await loader_service.stop()
 
 
 @pytest.mark.asyncio
@@ -216,48 +229,54 @@ async def test_multiple_anime_added_each_loads_independently(
     )
     _setup_loader_mocks(loader_service)
 
-    await loader_service.start()
+    # Set up mock NFO service via factory
+    mock_nfo_service = AsyncMock()
+    mock_nfo_service.create_tvshow_nfo = AsyncMock(return_value="/anime/tvshow.nfo")
+    mock_factory = _mock_nfo_factory(mock_nfo_service)
 
-    try:
-        anime_to_add = [
-            ("anime-a", "Anime A (2024)", "Anime A", 2024),
-            ("anime-b", "Anime B (2023)", "Anime B", 2023),
-            ("anime-c", "Anime C (2025)", "Anime C", 2025),
-        ]
+    with patch("src.server.services.background_loader_service.get_nfo_factory", return_value=mock_factory):
+        await loader_service.start()
 
-        for key, folder, name, year in anime_to_add:
-            anime_dir = Path(temp_anime_dir) / folder
-            anime_dir.mkdir()
+        try:
+            anime_to_add = [
+                ("anime-a", "Anime A (2024)", "Anime A", 2024),
+                ("anime-b", "Anime B (2023)", "Anime B", 2023),
+                ("anime-c", "Anime C (2025)", "Anime C", 2025),
+            ]
 
-            await loader_service.add_series_loading_task(
-                key=key,
-                folder=folder,
-                name=name,
-                year=year,
-            )
+            for key, folder, name, year in anime_to_add:
+                anime_dir = Path(temp_anime_dir) / folder
+                anime_dir.mkdir()
 
-        await asyncio.sleep(2.0)
+                await loader_service.add_series_loading_task(
+                    key=key,
+                    folder=folder,
+                    name=name,
+                    year=year,
+                )
 
-        assert mock_series_app.nfo_service.create_tvshow_nfo.call_count == 3
+            await asyncio.sleep(2.0)
 
-        all_calls = mock_series_app.nfo_service.create_tvshow_nfo.call_args_list
+            assert mock_nfo_service.create_tvshow_nfo.call_count == 3
 
-        called_names = [call_obj.kwargs["serie_name"] for call_obj in all_calls]
-        called_folders = [call_obj.kwargs["serie_folder"] for call_obj in all_calls]
+            all_calls = mock_nfo_service.create_tvshow_nfo.call_args_list
 
-        assert "Anime A" in called_names
-        assert "Anime B" in called_names
-        assert "Anime C" in called_names
+            called_names = [call_obj.kwargs["serie_name"] for call_obj in all_calls]
+            called_folders = [call_obj.kwargs["serie_folder"] for call_obj in all_calls]
 
-        assert "Anime A (2024)" in called_folders
-        assert "Anime B (2023)" in called_folders
-        assert "Anime C (2025)" in called_folders
+            assert "Anime A" in called_names
+            assert "Anime B" in called_names
+            assert "Anime C" in called_names
 
-        assert "Existing Anime 1" not in called_names
-        assert "Existing Anime 2" not in called_names
+            assert "Anime A (2024)" in called_folders
+            assert "Anime B (2023)" in called_folders
+            assert "Anime C (2025)" in called_folders
 
-    finally:
-        await loader_service.stop()
+            assert "Existing Anime 1" not in called_names
+            assert "Existing Anime 2" not in called_names
+
+        finally:
+            await loader_service.stop()
 
 
 @pytest.mark.asyncio
@@ -275,38 +294,44 @@ async def test_nfo_service_receives_correct_parameters(
     )
     _setup_loader_mocks(loader_service)
 
-    await loader_service.start()
+    # Set up mock NFO service via factory
+    mock_nfo_service = AsyncMock()
+    mock_nfo_service.create_tvshow_nfo = AsyncMock(return_value="/anime/Test Anime Series (2024)/tvshow.nfo")
+    mock_factory = _mock_nfo_factory(mock_nfo_service)
 
-    try:
-        test_key = "test-anime-key"
-        test_folder = "Test Anime Series (2024)"
-        test_name = "Test Anime Series"
-        test_year = 2024
+    with patch("src.server.services.background_loader_service.get_nfo_factory", return_value=mock_factory):
+        await loader_service.start()
 
-        anime_dir = Path(temp_anime_dir) / test_folder
-        anime_dir.mkdir()
+        try:
+            test_key = "test-anime-key"
+            test_folder = "Test Anime Series (2024)"
+            test_name = "Test Anime Series"
+            test_year = 2024
 
-        await loader_service.add_series_loading_task(
-            key=test_key,
-            folder=test_folder,
-            name=test_name,
-            year=test_year,
-        )
+            anime_dir = Path(temp_anime_dir) / test_folder
+            anime_dir.mkdir()
 
-        await asyncio.sleep(1.0)
+            await loader_service.add_series_loading_task(
+                key=test_key,
+                folder=test_folder,
+                name=test_name,
+                year=test_year,
+            )
 
-        assert mock_series_app.nfo_service.create_tvshow_nfo.call_count == 1
+            await asyncio.sleep(1.0)
 
-        call_kwargs = mock_series_app.nfo_service.create_tvshow_nfo.call_args.kwargs
+            assert mock_nfo_service.create_tvshow_nfo.call_count == 1
 
-        assert call_kwargs["serie_name"] == test_name
-        assert call_kwargs["serie_folder"] == test_folder
-        assert call_kwargs["year"] == test_year
-        assert call_kwargs["download_poster"] is True
-        assert call_kwargs["download_logo"] is True
-        assert call_kwargs["download_fanart"] is True
+            call_kwargs = mock_nfo_service.create_tvshow_nfo.call_args.kwargs
 
-        assert "Existing Anime" not in str(call_kwargs)
+            assert call_kwargs["serie_name"] == test_name
+            assert call_kwargs["serie_folder"] == test_folder
+            assert call_kwargs["year"] == test_year
+            assert call_kwargs["download_poster"] is True
+            assert call_kwargs["download_logo"] is True
+            assert call_kwargs["download_fanart"] is True
 
-    finally:
-        await loader_service.stop()
+            assert "Existing Anime" not in str(call_kwargs)
+
+        finally:
+            await loader_service.stop()

tests/integration/test_folder_rename_startup.py

@@ -0,0 +1,109 @@
+"""Integration tests for folder rename service wiring.
+
+These tests verify that:
+1. FolderScanService.run_folder_scan calls validate_and_rename_series_folders.
+2. The rename logic is properly integrated into the scheduled folder scan.
+"""
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+
+class TestFolderRenameScanCalledInFolderScan:
+    """Verify validate_and_rename_series_folders is invoked from FolderScanService."""
+
+    def test_validate_and_rename_imported_in_folder_scan_service(self):
+        """folder_scan_service.py imports validate_and_rename_series_folders."""
+        import importlib
+
+        source = importlib.util.find_spec(
+            "src.server.services.folder_scan_service"
+        ).origin
+        with open(source, "r", encoding="utf-8") as fh:
+            content = fh.read()
+
+        assert "validate_and_rename_series_folders" in content, (
+            "validate_and_rename_series_folders must be imported in folder_scan_service.py"
+        )
+
+    def test_validate_and_rename_called_in_run_folder_scan(self):
+        """validate_and_rename_series_folders must be called inside run_folder_scan."""
+        import importlib
+
+        source = importlib.util.find_spec(
+            "src.server.services.folder_scan_service"
+        ).origin
+        with open(source, "r", encoding="utf-8") as fh:
+            content = fh.read()
+
+        run_folder_scan_pos = content.find("def run_folder_scan")
+        rename_call_pos = content.find("validate_and_rename_series_folders()")
+
+        assert run_folder_scan_pos != -1, "run_folder_scan method not found"
+        assert rename_call_pos != -1, "validate_and_rename_series_folders call not found"
+        assert rename_call_pos > run_folder_scan_pos, (
+            "validate_and_rename_series_folders must be called INSIDE run_folder_scan"
+        )
+
+
+class TestFolderRenameIntegration:
+    """Integration test: folder rename is triggered during folder scan."""
+
+    @pytest.mark.asyncio
+    async def test_folder_rename_runs_during_scan(self, tmp_path):
+        """When folder_scan_enabled is true, the scan renames mismatched folders."""
+        from src.server.services.folder_scan_service import FolderScanService
+
+        anime_dir = tmp_path / "anime"
+        anime_dir.mkdir()
+        series_dir = anime_dir / "Attack on Titan"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow><title>Attack on Titan</title><year>2013</year></tvshow>"
+        )
+
+        mock_settings = MagicMock()
+        mock_settings.tmdb_api_key = "test-key"
+        mock_settings.anime_directory = str(anime_dir)
+
+        with patch(
+            "src.config.settings.settings", mock_settings
+        ), patch(
+            "src.server.services.folder_rename_service.settings", mock_settings
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan",
+            new_callable=AsyncMock,
+        ), patch(
+            "src.server.services.folder_rename_service._is_series_being_downloaded",
+            return_value=False,
+        ), patch(
+            "src.server.services.folder_rename_service._update_database_paths",
+            new_callable=AsyncMock,
+        ):
+            service = FolderScanService()
+            await service.run_folder_scan()
+
+        assert not series_dir.exists()
+        assert (anime_dir / "Attack on Titan (2013)").is_dir()
+
+    @pytest.mark.asyncio
+    async def test_folder_rename_skipped_when_prerequisites_not_met(self, tmp_path):
+        """If anime directory is missing, rename logic is skipped gracefully."""
+        from src.server.services.folder_scan_service import FolderScanService
+
+        mock_settings = MagicMock()
+        mock_settings.tmdb_api_key = "test-key"
+        mock_settings.anime_directory = str(tmp_path / "nonexistent")
+
+        with patch(
+            "src.config.settings.settings", mock_settings
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan",
+            new_callable=AsyncMock,
+        ), patch(
+            "src.server.services.folder_rename_service.validate_and_rename_series_folders"
+        ) as mock_rename:
+            service = FolderScanService()
+            await service.run_folder_scan()
+
+        mock_rename.assert_not_called()

tests/integration/test_nfo_repair_startup.py

@@ -1,46 +1,63 @@
-"""Integration tests verifying perform_nfo_repair_scan is wired into app startup.
+"""Integration tests verifying perform_nfo_repair_scan is wired into folder scan
+and NOT called during FastAPI lifespan startup.
 
 These tests confirm that:
-1. The lifespan calls perform_nfo_repair_scan after perform_media_scan_if_needed.
-2. Series with incomplete NFO files are queued via the background_loader.
+1. FolderScanService.run_folder_scan calls perform_nfo_repair_scan.
+2. perform_nfo_repair_scan is NOT imported or called in fastapi_app.py lifespan.
+3. Series with incomplete NFO files are queued via asyncio.create_task.
 """
 from unittest.mock import AsyncMock, MagicMock, call, patch
 
 import pytest
 
 
-class TestNfoRepairScanCalledOnStartup:
-    """Verify perform_nfo_repair_scan is invoked during the FastAPI lifespan."""
+class TestNfoRepairScanNotCalledOnStartup:
+    """Verify perform_nfo_repair_scan is NOT invoked during FastAPI lifespan startup."""
 
-    def test_perform_nfo_repair_scan_imported_in_lifespan(self):
-        """fastapi_app.py lifespan imports perform_nfo_repair_scan."""
+    def test_perform_nfo_repair_scan_not_imported_in_lifespan(self):
+        """fastapi_app.py lifespan must not import or call perform_nfo_repair_scan."""
         import importlib
 
-        import src.server.fastapi_app as app_module
-
         source = importlib.util.find_spec("src.server.fastapi_app").origin
         with open(source, "r", encoding="utf-8") as fh:
             content = fh.read()
 
+        assert "perform_nfo_repair_scan" not in content, (
+            "perform_nfo_repair_scan must NOT be imported or called in fastapi_app.py"
+        )
+
+
+class TestNfoRepairScanCalledInFolderScan:
+    """Verify perform_nfo_repair_scan is invoked from FolderScanService."""
+
+    def test_perform_nfo_repair_scan_imported_in_folder_scan_service(self):
+        """folder_scan_service.py imports perform_nfo_repair_scan."""
+        import importlib
+
+        source = importlib.util.find_spec("src.server.services.folder_scan_service").origin
+        with open(source, "r", encoding="utf-8") as fh:
+            content = fh.read()
+
         assert "perform_nfo_repair_scan" in content, (
-            "perform_nfo_repair_scan must be imported and called in fastapi_app.py"
+            "perform_nfo_repair_scan must be imported in folder_scan_service.py"
         )
 
-    def test_perform_nfo_repair_scan_called_after_media_scan(self):
-        """perform_nfo_repair_scan must appear after perform_media_scan_if_needed."""
+    def test_perform_nfo_repair_scan_called_in_run_folder_scan(self):
+        """perform_nfo_repair_scan must be called inside run_folder_scan."""
         import importlib
 
-        source = importlib.util.find_spec("src.server.fastapi_app").origin
+        source = importlib.util.find_spec("src.server.services.folder_scan_service").origin
         with open(source, "r", encoding="utf-8") as fh:
             content = fh.read()
 
-        media_scan_pos = content.find("perform_media_scan_if_needed(background_loader)")
-        repair_scan_pos = content.find("perform_nfo_repair_scan(background_loader)")
+        run_folder_scan_pos = content.find("def run_folder_scan")
+        # Find the call inside the method body (after the import line)
+        repair_scan_call_pos = content.find("await perform_nfo_repair_scan(background_loader=None)")
 
-        assert media_scan_pos != -1, "perform_media_scan_if_needed call not found"
-        assert repair_scan_pos != -1, "perform_nfo_repair_scan call not found"
-        assert repair_scan_pos > media_scan_pos, (
-            "perform_nfo_repair_scan must be called AFTER perform_media_scan_if_needed"
+        assert run_folder_scan_pos != -1, "run_folder_scan method not found"
+        assert repair_scan_call_pos != -1, "perform_nfo_repair_scan call not found"
+        assert repair_scan_call_pos > run_folder_scan_pos, (
+            "perform_nfo_repair_scan must be called INSIDE run_folder_scan"
         )
 
 
@@ -50,7 +67,7 @@ class TestNfoRepairScanIntegrationWithBackgroundLoader:
     @pytest.mark.asyncio
     async def test_incomplete_nfo_series_scheduled_for_repair(self, tmp_path):
         """Series whose tvshow.nfo is missing required tags are scheduled via asyncio.create_task."""
-        from src.server.services.initialization_service import perform_nfo_repair_scan
+        from src.server.services.folder_scan_service import perform_nfo_repair_scan
 
         series_dir = tmp_path / "IncompleteAnime"
         series_dir.mkdir()
@@ -66,7 +83,7 @@ class TestNfoRepairScanIntegrationWithBackgroundLoader:
         mock_repair_service.repair_series = AsyncMock(return_value=True)
 
         with patch(
-            "src.server.services.initialization_service.settings", mock_settings
+            "src.server.services.folder_scan_service._settings", mock_settings
         ), patch(
             "src.core.services.nfo_repair_service.nfo_needs_repair",
             return_value=True,
@@ -86,7 +103,7 @@ class TestNfoRepairScanIntegrationWithBackgroundLoader:
     @pytest.mark.asyncio
     async def test_complete_nfo_series_not_scheduled(self, tmp_path):
         """Series whose tvshow.nfo has all required tags are not scheduled for repair."""
-        from src.server.services.initialization_service import perform_nfo_repair_scan
+        from src.server.services.folder_scan_service import perform_nfo_repair_scan
 
         series_dir = tmp_path / "CompleteAnime"
         series_dir.mkdir()
@@ -99,7 +116,7 @@ class TestNfoRepairScanIntegrationWithBackgroundLoader:
         mock_settings.anime_directory = str(tmp_path)
 
         with patch(
-            "src.server.services.initialization_service.settings", mock_settings
+            "src.server.services.folder_scan_service._settings", mock_settings
         ), patch(
             "src.core.services.nfo_repair_service.nfo_needs_repair",
             return_value=False,

tests/integration/test_nfo_workflow.py

@@ -96,6 +96,8 @@ class TestCompleteNFOWorkflow:
             mock_tmdb = Mock()
             mock_tmdb.__aenter__ = AsyncMock(return_value=mock_tmdb)
             mock_tmdb.__aexit__ = AsyncMock(return_value=None)
+            mock_tmdb._ensure_session = AsyncMock()
+            mock_tmdb.close = AsyncMock()
             mock_tmdb.search_tv_show = AsyncMock(return_value={"results": [mock_tmdb_show]})
             mock_tmdb.get_tv_show = AsyncMock(return_value=mock_tmdb_show)
             mock_tmdb.get_tv_show_details = AsyncMock(return_value=mock_tmdb_show)
@@ -158,6 +160,8 @@ class TestCompleteNFOWorkflow:
             mock_tmdb = Mock()
             mock_tmdb.__aenter__ = AsyncMock(return_value=mock_tmdb)
             mock_tmdb.__aexit__ = AsyncMock(return_value=None)
+            mock_tmdb._ensure_session = AsyncMock()
+            mock_tmdb.close = AsyncMock()
             mock_tmdb.search_tv_show = AsyncMock(
                 return_value={"results": [{
                     "id": 999,
@@ -208,6 +212,8 @@ class TestCompleteNFOWorkflow:
             mock_tmdb = Mock()
             mock_tmdb.__aenter__ = AsyncMock(return_value=mock_tmdb)
             mock_tmdb.__aexit__ = AsyncMock(return_value=None)
+            mock_tmdb._ensure_session = AsyncMock()
+            mock_tmdb.close = AsyncMock()
             mock_tmdb.search_tv_show = AsyncMock(
                 side_effect=TMDBAPIError("API error")
             )
@@ -253,6 +259,8 @@ class TestCompleteNFOWorkflow:
             mock_tmdb = Mock()
             mock_tmdb.__aenter__ = AsyncMock(return_value=mock_tmdb)
             mock_tmdb.__aexit__ = AsyncMock(return_value=None)
+            mock_tmdb._ensure_session = AsyncMock()
+            mock_tmdb.close = AsyncMock()
             mock_tmdb.search_tv_show = AsyncMock(
                 return_value={"results": [{
                     "id": 999,
@@ -307,16 +315,22 @@ class TestCompleteNFOWorkflow:
             mock_tmdb = Mock()
             mock_tmdb.__aenter__ = AsyncMock(return_value=mock_tmdb)
             mock_tmdb.__aexit__ = AsyncMock(return_value=None)
+            mock_tmdb._ensure_session = AsyncMock()
+            mock_tmdb.close = AsyncMock()
             mock_tmdb.search_tv_show = AsyncMock(
                 side_effect=[
                     {"results": [{"id": 1, "name": "Anime 1", "first_air_date": "2020-01-01"}]},
                     {"results": [{"id": 2, "name": "Anime 2", "first_air_date": "2021-01-01"}]},
+                    {"results": [{"id": 1, "name": "Anime 1", "first_air_date": "2020-01-01"}]},
+                    {"results": [{"id": 2, "name": "Anime 2", "first_air_date": "2021-01-01"}]},
                 ]
             )
             mock_tmdb.get_tv_show_details = AsyncMock(
                 side_effect=[
                     {"id": 1, "name": "Anime 1", "first_air_date": "2020-01-01"},
                     {"id": 2, "name": "Anime 2", "first_air_date": "2021-01-01"},
+                    {"id": 1, "name": "Anime 1", "first_air_date": "2020-01-01"},
+                    {"id": 2, "name": "Anime 2", "first_air_date": "2021-01-01"},
                 ]
             )
             mock_tmdb.get_tv_show_content_ratings = AsyncMock(return_value={"results": []})
@@ -366,6 +380,8 @@ class TestNFOWorkflowWithDownloads:
             mock_tmdb = Mock()
             mock_tmdb.__aenter__ = AsyncMock(return_value=mock_tmdb)
             mock_tmdb.__aexit__ = AsyncMock(return_value=None)
+            mock_tmdb._ensure_session = AsyncMock()
+            mock_tmdb.close = AsyncMock()
             mock_tmdb.search_tv_show = AsyncMock(
                 return_value={"results": [{
                     "id": 999,

tests/integration/test_poster_check_startup.py

@@ -0,0 +1,294 @@
+"""Integration tests for poster check service wiring.
+
+These tests verify that:
+1. FolderScanService.run_folder_scan calls check_and_download_missing_posters.
+2. The poster check logic is properly integrated into the scheduled folder scan.
+3. Missing posters are downloaded, valid posters are skipped, and errors are handled.
+"""
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+
+class TestPosterCheckScanCalledInFolderScan:
+    """Verify check_and_download_missing_posters is invoked from FolderScanService."""
+
+    def test_check_and_download_missing_posters_imported_in_folder_scan_service(self):
+        """folder_scan_service.py imports check_and_download_missing_posters."""
+        import importlib
+
+        source = importlib.util.find_spec(
+            "src.server.services.folder_scan_service"
+        ).origin
+        with open(source, "r", encoding="utf-8") as fh:
+            content = fh.read()
+
+        assert "check_and_download_missing_posters" in content, (
+            "check_and_download_missing_posters must be imported in folder_scan_service.py"
+        )
+
+    def test_check_and_download_missing_posters_called_in_run_folder_scan(self):
+        """check_and_download_missing_posters must be called inside run_folder_scan."""
+        import importlib
+
+        source = importlib.util.find_spec(
+            "src.server.services.folder_scan_service"
+        ).origin
+        with open(source, "r", encoding="utf-8") as fh:
+            content = fh.read()
+
+        run_folder_scan_pos = content.find("def run_folder_scan")
+        poster_call_pos = content.find("check_and_download_missing_posters()")
+
+        assert run_folder_scan_pos != -1, "run_folder_scan method not found"
+        assert poster_call_pos != -1, "check_and_download_missing_posters call not found"
+        assert poster_call_pos > run_folder_scan_pos, (
+            "check_and_download_missing_posters must be called INSIDE run_folder_scan"
+        )
+
+
+class TestPosterCheckIntegration:
+    """Integration test: poster check is triggered during folder scan."""
+
+    @pytest.mark.asyncio
+    async def test_poster_check_downloads_missing_poster(self, tmp_path):
+        """When poster.jpg is missing, the scan downloads it from the NFO thumb URL."""
+        from src.server.services.folder_scan_service import FolderScanService
+
+        anime_dir = tmp_path / "anime"
+        anime_dir.mkdir()
+        series_dir = anime_dir / "Attack on Titan (2013)"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<?xml version='1.0' encoding='UTF-8'?>\n"
+            "<tvshow>\n"
+            "  <title>Attack on Titan</title>\n"
+            "  <year>2013</year>\n"
+            '  <thumb aspect="poster">https://example.com/poster.jpg</thumb>\n'
+            "</tvshow>\n"
+        )
+
+        mock_settings = MagicMock()
+        mock_settings.tmdb_api_key = "test-key"
+        mock_settings.anime_directory = str(anime_dir)
+
+        call_log = []
+
+        class MockDownloader:
+            """Fake ImageDownloader that records calls."""
+
+            async def __aenter__(self):
+                return self
+
+            async def __aexit__(self, *args):
+                return False
+
+            async def download_poster(self, url, folder, skip_existing=True):
+                call_log.append({"url": url, "folder": folder, "skip_existing": skip_existing})
+                return True
+
+        with patch(
+            "src.config.settings.settings", mock_settings
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan",
+            new_callable=AsyncMock,
+        ), patch(
+            "src.server.services.folder_rename_service.validate_and_rename_series_folders",
+            new_callable=AsyncMock,
+            return_value={"scanned": 0, "renamed": 0, "skipped": 0, "errors": 0},
+        ), patch(
+            "src.server.services.folder_scan_service.ImageDownloader",
+            new=MockDownloader,
+        ):
+            service = FolderScanService()
+            await service.run_folder_scan()
+
+        assert len(call_log) == 1, f"Expected 1 download call, got {len(call_log)}"
+        assert call_log[0]["url"] == "https://example.com/poster.jpg"
+        assert call_log[0]["folder"] == series_dir
+        assert call_log[0]["skip_existing"] is False
+
+    @pytest.mark.asyncio
+    async def test_poster_check_skips_valid_poster(self, tmp_path):
+        """When poster.jpg exists and is large enough, the scan skips it."""
+        from src.server.services.folder_scan_service import FolderScanService
+
+        anime_dir = tmp_path / "anime"
+        anime_dir.mkdir()
+        series_dir = anime_dir / "Attack on Titan (2013)"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow>"
+            "<title>Attack on Titan</title>"
+            "<year>2013</year>"
+            "<thumb aspect='poster'>https://example.com/poster.jpg</thumb>"
+            "</tvshow>"
+        )
+        # Create a valid poster.jpg (larger than 1 KB)
+        poster_path = series_dir / "poster.jpg"
+        poster_path.write_bytes(b"x" * 2048)
+
+        mock_settings = MagicMock()
+        mock_settings.tmdb_api_key = "test-key"
+        mock_settings.anime_directory = str(anime_dir)
+
+        with patch(
+            "src.config.settings.settings", mock_settings
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan",
+            new_callable=AsyncMock,
+        ), patch(
+            "src.server.services.folder_rename_service.validate_and_rename_series_folders",
+            new_callable=AsyncMock,
+            return_value={"scanned": 0, "renamed": 0, "skipped": 0, "errors": 0},
+        ), patch(
+            "src.server.services.folder_scan_service.ImageDownloader"
+        ) as mock_downloader_cls:
+            service = FolderScanService()
+            await service.run_folder_scan()
+
+        mock_downloader_cls.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_poster_check_skips_when_no_thumb_url(self, tmp_path):
+        """When NFO has no thumb URL, the scan skips the folder."""
+        from src.server.services.folder_scan_service import FolderScanService
+
+        anime_dir = tmp_path / "anime"
+        anime_dir.mkdir()
+        series_dir = anime_dir / "Attack on Titan (2013)"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow>"
+            "<title>Attack on Titan</title>"
+            "<year>2013</year>"
+            "</tvshow>"
+        )
+
+        mock_settings = MagicMock()
+        mock_settings.tmdb_api_key = "test-key"
+        mock_settings.anime_directory = str(anime_dir)
+
+        with patch(
+            "src.config.settings.settings", mock_settings
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan",
+            new_callable=AsyncMock,
+        ), patch(
+            "src.server.services.folder_rename_service.validate_and_rename_series_folders",
+            new_callable=AsyncMock,
+            return_value={"scanned": 0, "renamed": 0, "skipped": 0, "errors": 0},
+        ), patch(
+            "src.server.services.folder_scan_service.ImageDownloader"
+        ) as mock_downloader_cls:
+            service = FolderScanService()
+            await service.run_folder_scan()
+
+        mock_downloader_cls.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_poster_check_skipped_when_prerequisites_not_met(self, tmp_path):
+        """If anime directory is missing, poster check logic is skipped gracefully."""
+        from src.server.services.folder_scan_service import FolderScanService
+
+        mock_settings = MagicMock()
+        mock_settings.tmdb_api_key = "test-key"
+        mock_settings.anime_directory = str(tmp_path / "nonexistent")
+
+        with patch(
+            "src.config.settings.settings", mock_settings
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan",
+            new_callable=AsyncMock,
+        ), patch(
+            "src.server.services.folder_rename_service.validate_and_rename_series_folders"
+        ) as mock_rename, patch(
+            "src.server.services.folder_scan_service.ImageDownloader"
+        ) as mock_downloader_cls:
+            service = FolderScanService()
+            await service.run_folder_scan()
+
+        mock_downloader_cls.assert_not_called()
+
+
+class TestPosterCheckSemaphore:
+    """Verify the poster download semaphore limits concurrency."""
+
+    def test_poster_download_semaphore_defined(self):
+        """_POSTER_DOWNLOAD_SEMAPHORE must be defined in folder_scan_service.py."""
+        import importlib
+
+        source = importlib.util.find_spec(
+            "src.server.services.folder_scan_service"
+        ).origin
+        with open(source, "r", encoding="utf-8") as fh:
+            content = fh.read()
+
+        assert "_POSTER_DOWNLOAD_SEMAPHORE" in content, (
+            "_POSTER_DOWNLOAD_SEMAPHORE must be defined in folder_scan_service.py"
+        )
+
+    @pytest.mark.asyncio
+    async def test_poster_download_uses_semaphore(self, tmp_path):
+        """Poster downloads are gated by the semaphore."""
+        from src.server.services.folder_scan_service import (
+            _POSTER_DOWNLOAD_SEMAPHORE,
+            FolderScanService,
+        )
+
+        anime_dir = tmp_path / "anime"
+        anime_dir.mkdir()
+
+        # Create multiple series folders
+        for i in range(5):
+            series_dir = anime_dir / f"Series {i}"
+            series_dir.mkdir()
+            (series_dir / "tvshow.nfo").write_text(
+                f"<tvshow>"
+                f"<title>Series {i}</title>"
+                f"<year>202{i}</year>"
+                f"<thumb aspect='poster'>https://example.com/poster{i}.jpg</thumb>"
+                f"</tvshow>"
+            )
+
+        mock_settings = MagicMock()
+        mock_settings.tmdb_api_key = "test-key"
+        mock_settings.anime_directory = str(anime_dir)
+
+        active_count = 0
+        max_active = 0
+
+        async def tracked_download(*args, **kwargs):
+            nonlocal active_count, max_active
+            active_count += 1
+            max_active = max(max_active, active_count)
+            await asyncio.sleep(0.05)
+            active_count -= 1
+            return True
+
+        with patch(
+            "src.config.settings.settings", mock_settings
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan",
+            new_callable=AsyncMock,
+        ), patch(
+            "src.server.services.folder_rename_service.validate_and_rename_series_folders",
+            new_callable=AsyncMock,
+            return_value={"scanned": 0, "renamed": 0, "skipped": 0, "errors": 0},
+        ), patch(
+            "src.server.services.folder_scan_service.ImageDownloader"
+        ) as mock_downloader_cls:
+            mock_downloader = AsyncMock()
+            mock_downloader.download_poster = AsyncMock(side_effect=tracked_download)
+            mock_downloader_cls.return_value.__aenter__ = AsyncMock(
+                return_value=mock_downloader
+            )
+            mock_downloader_cls.return_value.__aexit__ = AsyncMock(return_value=False)
+
+            service = FolderScanService()
+            await service.run_folder_scan()
+
+        assert max_active <= 3, (
+            f"Expected max concurrent downloads <= 3, got {max_active}"
+        )

tests/integration/test_sacrificial_princess_nfo.py

@@ -0,0 +1,429 @@
+"""Integration test: add 'Sacrificial Princess And The King Of Beasts' and verify NFO completeness.
+
+Simulates the production scenario where this anime is added and validates
+that the generated tvshow.nfo contains plot, outline, and all other required
+information. Also tests the repair path for an incomplete NFO.
+"""
+
+from pathlib import Path
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from lxml import etree
+
+from src.core.services.nfo_repair_service import (
+    NfoRepairService,
+    _read_tmdb_id,
+    find_missing_tags,
+    nfo_needs_repair,
+)
+from src.core.services.nfo_service import NFOService
+
+# ---------------------------------------------------------------------------
+# TMDB mock data matching production responses for this anime
+# ---------------------------------------------------------------------------
+SERIES_KEY = "sacrificial-princess-and-the-king-of-beasts"
+SERIES_NAME = "Sacrificial Princess And The King Of Beasts"
+SERIES_FOLDER = "Sacrificial Princess And The King Of Beasts (2023)"
+TMDB_ID = 222093
+
+MOCK_TMDB_DETAILS = {
+    "id": TMDB_ID,
+    "name": "Sacrificial Princess and the King of Beasts",
+    "original_name": "贄姫と獣の王",
+    "overview": (
+        "On the outskirts of the Demon King's realm lies a small village of "
+        "humans who offer a sacrifice to the beast king every year. Sariphi, "
+        "the latest sacrificial girl, expects to be devoured — but instead "
+        "her fearless nature catches the king's attention and she becomes "
+        "his unlikely companion."
+    ),
+    "tagline": "A tale of love between a sacrifice and a beast king.",
+    "first_air_date": "2023-04-20",
+    "last_air_date": "2023-09-28",
+    "vote_average": 7.5,
+    "vote_count": 150,
+    "status": "Ended",
+    "episode_run_time": [24],
+    "number_of_seasons": 1,
+    "number_of_episodes": 24,
+    "genres": [
+        {"id": 16, "name": "Animation"},
+        {"id": 10749, "name": "Romance"},
+        {"id": 10765, "name": "Sci-Fi & Fantasy"},
+    ],
+    "networks": [{"id": 160, "name": "TBS"}],
+    "production_companies": [{"id": 291, "name": "J.C.Staff"}],
+    "origin_country": ["JP"],
+    "poster_path": "/sacrificial_poster.jpg",
+    "backdrop_path": "/sacrificial_backdrop.jpg",
+    "external_ids": {"imdb_id": "tt19896734", "tvdb_id": 421737},
+    "credits": {
+        "cast": [
+            {
+                "id": 2072089,
+                "name": "Kana Hanazawa",
+                "character": "Sariphi",
+                "profile_path": "/hanazawa.jpg",
+                "order": 0,
+            },
+            {
+                "id": 1254783,
+                "name": "Satoshi Hino",
+                "character": "Leonhart",
+                "profile_path": "/hino.jpg",
+                "order": 1,
+            },
+        ]
+    },
+    "images": {"logos": [{"file_path": "/sacrificial_logo.png"}]},
+    "seasons": [
+        {"season_number": 0, "name": "Specials"},
+        {"season_number": 1, "name": "Season 1"},
+    ],
+}
+
+MOCK_CONTENT_RATINGS = {
+    "results": [
+        {"iso_3166_1": "DE", "rating": "12"},
+        {"iso_3166_1": "US", "rating": "TV-14"},
+    ]
+}
+
+MOCK_SEARCH_RESULTS = {
+    "results": [
+        {
+            "id": TMDB_ID,
+            "name": "Sacrificial Princess and the King of Beasts",
+            "first_air_date": "2023-04-20",
+            "overview": (
+                "On the outskirts of the Demon King's realm lies a small village "
+                "of humans who offer a sacrifice to the beast king every year."
+            ),
+        }
+    ]
+}
+
+# ---------------------------------------------------------------------------
+# Tags that MUST be present and non-empty in a complete NFO
+# ---------------------------------------------------------------------------
+REQUIRED_TAGS = [
+    "title",
+    "originaltitle",
+    "year",
+    "plot",
+    "outline",
+    "runtime",
+    "premiered",
+    "status",
+    "tmdbid",
+    "imdbid",
+    "genre",
+    "studio",
+    "country",
+    "watched",
+]
+
+
+@pytest.fixture
+def anime_dir(tmp_path: Path) -> Path:
+    """Temporary anime directory."""
+    d = tmp_path / "anime"
+    d.mkdir()
+    return d
+
+
+@pytest.fixture
+def nfo_service(anime_dir: Path) -> NFOService:
+    """NFOService configured for the temp directory."""
+    return NFOService(
+        tmdb_api_key="test_api_key",
+        anime_directory=str(anime_dir),
+        image_size="w500",
+        auto_create=True,
+    )
+
+
+def _mock_tmdb_calls(nfo_service: NFOService):
+    """Context manager that patches all TMDB calls with mock data."""
+    return _PatchContext(nfo_service)
+
+
+class _PatchContext:
+    """Helper to patch TMDB calls on an NFOService instance."""
+
+    def __init__(self, svc: NFOService):
+        self._svc = svc
+        self._patches = []
+
+    def __enter__(self):
+        p1 = patch.object(
+            self._svc.tmdb_client, "search_tv_show", new_callable=AsyncMock
+        )
+        p2 = patch.object(
+            self._svc.tmdb_client, "get_tv_show_details", new_callable=AsyncMock
+        )
+        p3 = patch.object(
+            self._svc.tmdb_client, "get_tv_show_content_ratings", new_callable=AsyncMock
+        )
+        p4 = patch.object(
+            self._svc.image_downloader, "download_all_media", new_callable=AsyncMock
+        )
+        p5 = patch.object(
+            self._svc.tmdb_client, "_ensure_session", new_callable=AsyncMock
+        )
+        p6 = patch.object(
+            self._svc.tmdb_client, "close", new_callable=AsyncMock
+        )
+
+        self._patches = [p1, p2, p3, p4, p5, p6]
+        mocks = [p.start() for p in self._patches]
+
+        mocks[0].return_value = MOCK_SEARCH_RESULTS
+        mocks[1].return_value = MOCK_TMDB_DETAILS
+        mocks[2].return_value = MOCK_CONTENT_RATINGS
+        mocks[3].return_value = {"poster": True, "logo": True, "fanart": True}
+
+        return self
+
+    def __exit__(self, *args):
+        for p in self._patches:
+            p.stop()
+
+
+class TestSacrificialPrincessNFO:
+    """Tests for 'Sacrificial Princess And The King Of Beasts' NFO generation."""
+
+    @pytest.mark.asyncio
+    async def test_add_anime_creates_complete_nfo(
+        self, nfo_service: NFOService, anime_dir: Path
+    ) -> None:
+        """Adding the anime produces an NFO with all required tags filled."""
+        series_path = anime_dir / SERIES_FOLDER
+        series_path.mkdir()
+
+        with _PatchContext(nfo_service):
+            nfo_path = await nfo_service.create_tvshow_nfo(
+                serie_name=SERIES_NAME,
+                serie_folder=SERIES_FOLDER,
+                year=2023,
+                download_poster=True,
+                download_logo=True,
+                download_fanart=True,
+            )
+
+        assert nfo_path.exists(), f"NFO not created at {nfo_path}"
+
+        root = etree.parse(str(nfo_path)).getroot()
+        missing = []
+        for tag in REQUIRED_TAGS:
+            elems = root.findall(f".//{tag}")
+            if not elems or not any((e.text or "").strip() for e in elems):
+                missing.append(tag)
+
+        # Actor check
+        actors = root.findall(".//actor/name")
+        if not actors or not any((a.text or "").strip() for a in actors):
+            missing.append("actor/name")
+
+        assert not missing, (
+            f"Missing or empty tags in NFO for '{SERIES_NAME}':\n"
+            f"  {', '.join(missing)}\n\n"
+            f"NFO content:\n{nfo_path.read_text(encoding='utf-8')}"
+        )
+
+    @pytest.mark.asyncio
+    async def test_nfo_plot_and_outline_are_meaningful(
+        self, nfo_service: NFOService, anime_dir: Path
+    ) -> None:
+        """Plot and outline must contain substantial descriptive text."""
+        series_path = anime_dir / SERIES_FOLDER
+        series_path.mkdir()
+
+        with _PatchContext(nfo_service):
+            nfo_path = await nfo_service.create_tvshow_nfo(
+                serie_name=SERIES_NAME,
+                serie_folder=SERIES_FOLDER,
+                year=2023,
+                download_poster=False,
+                download_logo=False,
+                download_fanart=False,
+            )
+
+        root = etree.parse(str(nfo_path)).getroot()
+
+        plot = (root.findtext(".//plot") or "").strip()
+        outline = (root.findtext(".//outline") or "").strip()
+
+        assert len(plot) >= 20, f"Plot too short ({len(plot)} chars): {plot!r}"
+        assert len(outline) >= 20, f"Outline too short ({len(outline)} chars): {outline!r}"
+
+        # Should mention relevant keywords from the series
+        combined = (plot + outline).lower()
+        assert any(
+            kw in combined for kw in ("sacrifice", "beast", "king", "sariphi")
+        ), f"Plot/outline missing expected content:\n  plot={plot!r}\n  outline={outline!r}"
+
+    @pytest.mark.asyncio
+    async def test_nfo_specific_values(
+        self, nfo_service: NFOService, anime_dir: Path
+    ) -> None:
+        """Verify specific metadata values match the anime."""
+        series_path = anime_dir / SERIES_FOLDER
+        series_path.mkdir()
+
+        with _PatchContext(nfo_service):
+            nfo_path = await nfo_service.create_tvshow_nfo(
+                serie_name=SERIES_NAME,
+                serie_folder=SERIES_FOLDER,
+                year=2023,
+                download_poster=False,
+                download_logo=False,
+                download_fanart=False,
+            )
+
+        root = etree.parse(str(nfo_path)).getroot()
+
+        assert root.findtext(".//year") == "2023"
+        assert root.findtext(".//status") == "Ended"
+        assert root.findtext(".//tmdbid") == str(TMDB_ID)
+        assert root.findtext(".//imdbid") == "tt19896734"
+        assert root.findtext(".//watched") == "false"
+        assert root.findtext(".//premiered") == "2023-04-20"
+
+        genres = [g.text for g in root.findall(".//genre") if g.text]
+        assert "Animation" in genres
+
+    @pytest.mark.asyncio
+    async def test_incomplete_nfo_detected_as_needing_repair(
+        self, anime_dir: Path
+    ) -> None:
+        """An NFO with only a <title> tag is detected as incomplete."""
+        series_path = anime_dir / SERIES_FOLDER
+        series_path.mkdir()
+        nfo_path = series_path / "tvshow.nfo"
+
+        # Simulate production state: minimal NFO with only title
+        nfo_path.write_text(
+            '<?xml version="1.0" encoding="UTF-8"?>\n'
+            "<tvshow>\n"
+            f"  <title>{SERIES_NAME}</title>\n"
+            "</tvshow>\n",
+            encoding="utf-8",
+        )
+
+        assert nfo_needs_repair(nfo_path) is True
+
+        missing = find_missing_tags(nfo_path)
+        # All these should be detected as missing
+        for tag_label in ["plot", "year", "runtime", "premiered", "genre", "studio"]:
+            assert tag_label in missing, f"'{tag_label}' not detected as missing"
+
+    @pytest.mark.asyncio
+    async def test_repair_fixes_incomplete_nfo(
+        self, nfo_service: NFOService, anime_dir: Path
+    ) -> None:
+        """NfoRepairService re-fetches and creates a complete NFO from an incomplete one."""
+        series_path = anime_dir / SERIES_FOLDER
+        series_path.mkdir()
+        nfo_path = series_path / "tvshow.nfo"
+
+        # Write an incomplete NFO with a tmdbid so update_tvshow_nfo can work
+        nfo_path.write_text(
+            '<?xml version="1.0" encoding="UTF-8"?>\n'
+            "<tvshow>\n"
+            f"  <title>{SERIES_NAME}</title>\n"
+            f"  <tmdbid>{TMDB_ID}</tmdbid>\n"
+            "</tvshow>\n",
+            encoding="utf-8",
+        )
+
+        assert nfo_needs_repair(nfo_path) is True
+
+        # Patch TMDB calls for the update path
+        with patch.object(
+            nfo_service.tmdb_client, "_ensure_session", new_callable=AsyncMock
+        ), patch.object(
+            nfo_service.tmdb_client, "get_tv_show_details", new_callable=AsyncMock
+        ) as mock_details, patch.object(
+            nfo_service.tmdb_client, "get_tv_show_content_ratings", new_callable=AsyncMock
+        ) as mock_ratings, patch.object(
+            nfo_service.tmdb_client, "close", new_callable=AsyncMock
+        ):
+            mock_details.return_value = MOCK_TMDB_DETAILS
+            mock_ratings.return_value = MOCK_CONTENT_RATINGS
+
+            repair_service = NfoRepairService(nfo_service)
+            repaired = await repair_service.repair_series(series_path, SERIES_FOLDER)
+
+        assert repaired is True
+
+        # After repair, NFO should be complete
+        assert nfo_needs_repair(nfo_path) is False
+
+        # Verify content
+        root = etree.parse(str(nfo_path)).getroot()
+        plot = (root.findtext(".//plot") or "").strip()
+        assert len(plot) >= 20, f"Plot still incomplete after repair: {plot!r}"
+
+    @pytest.mark.asyncio
+    async def test_repair_recreates_nfo_without_tmdb_id(
+        self, nfo_service: NFOService, anime_dir: Path
+    ) -> None:
+        """If the NFO has no <tmdbid>, repair falls back to create_tvshow_nfo."""
+        series_path = anime_dir / SERIES_FOLDER
+        series_path.mkdir()
+        nfo_path = series_path / "tvshow.nfo"
+
+        # Simulate the production worst-case: only a title, no TMDB ID
+        nfo_path.write_text(
+            '<?xml version="1.0" encoding="UTF-8"?>\n'
+            "<tvshow>\n"
+            f"  <title>{SERIES_NAME}</title>\n"
+            "</tvshow>\n",
+            encoding="utf-8",
+        )
+
+        assert _read_tmdb_id(nfo_path) is None
+        assert nfo_needs_repair(nfo_path) is True
+
+        with _PatchContext(nfo_service):
+            repair_service = NfoRepairService(nfo_service)
+            repaired = await repair_service.repair_series(series_path, SERIES_FOLDER)
+
+        assert repaired is True
+        assert nfo_path.exists()
+        assert nfo_needs_repair(nfo_path) is False
+
+        root = etree.parse(str(nfo_path)).getroot()
+        plot = (root.findtext(".//plot") or "").strip()
+        assert len(plot) >= 20, f"Plot incomplete after recreate: {plot!r}"
+        assert root.findtext(".//tmdbid") == str(TMDB_ID)
+
+    @pytest.mark.asyncio
+    async def test_complete_nfo_not_repaired(
+        self, nfo_service: NFOService, anime_dir: Path
+    ) -> None:
+        """A complete NFO should not trigger a repair."""
+        series_path = anime_dir / SERIES_FOLDER
+        series_path.mkdir()
+
+        # First create a complete NFO
+        with _PatchContext(nfo_service):
+            await nfo_service.create_tvshow_nfo(
+                serie_name=SERIES_NAME,
+                serie_folder=SERIES_FOLDER,
+                year=2023,
+                download_poster=False,
+                download_logo=False,
+                download_fanart=False,
+            )
+
+        nfo_path = series_path / "tvshow.nfo"
+        assert nfo_path.exists()
+        assert nfo_needs_repair(nfo_path) is False
+
+        # Repair should be skipped
+        repair_service = NfoRepairService(nfo_service)
+        repaired = await repair_service.repair_series(series_path, SERIES_FOLDER)
+        assert repaired is False

tests/integration/test_series_parsing_edge_cases.py

@@ -495,6 +495,20 @@ class TestNameWithYearProperty:
         assert "(2013)" in sanitized
         assert "Attack on Titan" in sanitized
 
+    def test_name_with_year_does_not_duplicate(self):
+        """Test that name_with_year doesn't duplicate year."""
+        serie = Serie(
+            key="eighty-six",
+            name="86 Eighty Six (2021)",
+            site="aniworld.to",
+            folder="86 Eighty Six (2021)",
+            episodeDict={},
+            year=2021
+        )
+        
+        assert serie.name_with_year == "86 Eighty Six (2021)"
+        assert serie.name_with_year.count("(2021)") == 1
+
 
 class TestEnsureFolderWithYear:
     """Test Serie.ensure_folder_with_year method."""

tests/performance/test_nfo_batch_performance.py

@@ -4,6 +4,7 @@ This module tests the performance characteristics of batch NFO creation
 including concurrent operations, TMDB API request optimization, and memory usage.
 """
 import asyncio
+import logging
 import time
 from pathlib import Path
 from typing import List
@@ -15,6 +16,8 @@ from src.core.services.nfo_service import NFOService
 from src.server.api.nfo import batch_create_nfo
 from src.server.models.nfo import NFOBatchCreateRequest
 
+logger = logging.getLogger(__name__)
+
 
 class TestConcurrentNFOCreation:
     """Test performance of concurrent NFO creation operations."""
@@ -83,8 +86,11 @@ class TestConcurrentNFOCreation:
         # Concurrent should take roughly (num_series / 5) * 0.1 = 0.2s
         assert elapsed_time < 1.0, "Concurrency not providing speedup"
         
-        print(f"\nPerformance: {num_series} series in {elapsed_time:.2f}s")
-        print(f"Rate: {num_series / elapsed_time:.2f} series/second")
+        logger.info("Batch NFO creation completed", extra={"num_series": num_series, "elapsed_s": elapsed_time})
+        logger.debug(
+            "Batch NFO creation rate",
+            extra={"series_per_second": num_series / elapsed_time},
+        )
     
     @pytest.mark.asyncio
     async def test_concurrent_nfo_creation_50_series(self):

tests/performance/test_websocket_load.py

@@ -4,6 +4,7 @@ This module tests the performance characteristics of WebSocket connections
 including concurrent clients, message throughput, and progress update throttling.
 """
 import asyncio
+import logging
 import time
 from typing import List
 from unittest.mock import AsyncMock, Mock
@@ -12,6 +13,8 @@ import pytest
 
 from src.server.services.websocket_service import WebSocketService
 
+logger = logging.getLogger(__name__)
+
 
 class MockWebSocket:
     """Mock WebSocket client for testing."""
@@ -82,8 +85,14 @@ class TestWebSocketConcurrentClients:
         for i in range(num_clients):
             await websocket_service.disconnect(f"client_{i:03d}")
         
-        print(f"\n100 clients: Broadcast in {elapsed_time:.2f}s")
-        print(f"Average per client: {elapsed_time / num_clients * 1000:.2f}ms")
+        logger.info("Broadcast completed for %d clients", num_clients, extra={"elapsed_s": elapsed_time})
+        logger.debug(
+            "Broadcast performance per client",
+            extra={
+                "num_clients": num_clients,
+                "avg_ms_per_client": elapsed_time / num_clients * 1000,
+            },
+        )
     
     @pytest.mark.asyncio
     async def test_200_concurrent_clients_scalability(self):
@@ -114,7 +123,7 @@ class TestWebSocketConcurrentClients:
         for i in range(num_clients):
             await websocket_service.disconnect(f"client_{i:03d}")
         
-        print(f"\n200 clients: Broadcast in {elapsed_time:.2f}s")
+        logger.info("Broadcast completed for %d clients", num_clients, extra={"elapsed_s": elapsed_time})
     
     @pytest.mark.asyncio
     async def test_connection_pool_efficiency(self):
@@ -144,8 +153,8 @@ class TestWebSocketConcurrentClients:
         for i in range(num_clients):
             await websocket_service.disconnect(f"client_{i:02d}")
         
-        print(f"\nConnected {num_clients} clients in {connection_time:.3f}s")
-        print(f"Average: {connection_time / num_clients * 1000:.2f}ms per connection")
+        logger.info("Connected %d clients in %.3fs", num_clients, connection_time)
+        logger.info("Average: %.2fms per connection", connection_time / num_clients * 1000)
 
 
 class TestMessageThroughput:
@@ -192,8 +201,13 @@ class TestMessageThroughput:
         for i in range(num_clients):
             await websocket_service.disconnect(f"client_{i}")
         
-        print(f"\nThroughput: {messages_per_second:.2f} messages/second")
-        print(f"Total: {num_messages} messages to {num_clients} clients in {elapsed_time:.2f}s")
+        logger.info("Throughput: %.2f messages/second", messages_per_second)
+        logger.info(
+            "Total: %d messages to %d clients in %.2fs",
+            num_messages,
+            num_clients,
+            elapsed_time,
+        )
     
     @pytest.mark.asyncio
     async def test_high_frequency_updates(self):
@@ -234,7 +248,7 @@ class TestMessageThroughput:
         for i in range(5):
             await websocket_service.disconnect(f"client_{i}")
         
-        print(f"\nHigh-frequency: {updates_per_second:.2f} updates/second")
+        logger.info("High-frequency: %.2f updates/second", updates_per_second)
     
     @pytest.mark.asyncio
     async def test_burst_message_handling(self):
@@ -275,7 +289,7 @@ class TestMessageThroughput:
         for i in range(num_clients):
             await websocket_service.disconnect(f"client_{i:02d}")
         
-        print(f"\nBurst: {num_messages} messages in {elapsed_time:.2f}s")
+        logger.info("Burst: %d messages in %.2fs", num_messages, elapsed_time)
 
 
 class TestProgressUpdateThrottling:
@@ -313,7 +327,10 @@ class TestProgressUpdateThrottling:
         
         await websocket_service.disconnect("test_client")
         
-        print(f"\nThrottling: {len(client.received_messages)} updates sent (100 possible)")
+        logger.info(
+            "Throttling: %d updates sent (100 possible)",
+            len(client.received_messages),
+        )
     
     @pytest.mark.asyncio
     async def test_throttling_reduces_network_load(self):
@@ -356,7 +373,11 @@ class TestProgressUpdateThrottling:
         for i in range(10):
             await websocket_service.disconnect(f"client_{i}")
         
-        print(f"\nThrottling: {throttled_updates}/1000 updates sent ({reduction_percent:.1f}% reduction)")
+        logger.info(
+            "Throttling: %d/1000 updates sent (%.1f%% reduction)",
+            throttled_updates,
+            reduction_percent,
+        )
 
 
 class TestRoomIsolation:
@@ -402,7 +423,7 @@ class TestRoomIsolation:
             for i in range(clients_per_room):
                 await websocket_service.disconnect(f"{room}_client_{i:02d}")
         
-        print(f"\nRoom isolation: 3 rooms × 30 clients in {elapsed_time:.2f}s")
+        logger.info("Room isolation: 3 rooms × 30 clients in %.2fs", elapsed_time)
     
     @pytest.mark.asyncio
     async def test_selective_room_broadcast_performance(self):
@@ -435,7 +456,7 @@ class TestRoomIsolation:
             for i in range(clients_per_room):
                 await websocket_service.disconnect(f"{room}_{i:02d}")
         
-        print(f"\nSelective broadcast: 25/100 clients in {elapsed_time:.3f}s")
+        logger.info("Selective broadcast: 25/100 clients in %.3fs", elapsed_time)
 
 
 class TestConnectionStability:
@@ -472,7 +493,7 @@ class TestConnectionStability:
         # All connections should be cleaned up
         assert len(websocket_service.manager._active_connections) == 0
         
-        print(f"\nRapid cycles: {cycles_per_second:.2f} cycles/second")
+        logger.info("Rapid cycles: %.2f cycles/second", cycles_per_second)
     
     @pytest.mark.asyncio
     async def test_concurrent_connect_disconnect(self):
@@ -497,7 +518,7 @@ class TestConnectionStability:
         # All should be cleaned up
         assert len(websocket_service.manager._active_connections) == 0
         
-        print(f"\nConcurrent ops: 30 clients in {elapsed_time:.2f}s")
+        logger.info("Concurrent ops: 30 clients in %.2fs", elapsed_time)
 
 
 class TestMemoryEfficiency:
@@ -533,8 +554,8 @@ class TestMemoryEfficiency:
         for i in range(100):
             await websocket_service.disconnect(f"mem_client_{i:03d}")
         
-        print(f"\nMemory: {memory_increase_mb:.2f}MB for 100 connections")
-        print(f"Per connection: {per_connection_kb:.2f}KB")
+        logger.info("Memory: %.2fMB for 100 connections", memory_increase_mb)
+        logger.info("Per connection: %.2fKB", per_connection_kb)
     
     @pytest.mark.asyncio
     async def test_message_queue_memory_efficiency(self):
@@ -567,5 +588,5 @@ class TestMemoryEfficiency:
         
         await websocket_service.disconnect("queue_test")
         
-        print(f"\nMessage queue: {total_size} bytes for 100 messages")
-        print(f"Average: {total_size / 100:.2f} bytes/message")
+        logger.info("Message queue: %d bytes for 100 messages", total_size)
+        logger.info("Average: %.2f bytes/message", total_size / 100)

tests/unit/test_background_loader_service.py

@@ -36,6 +36,7 @@ def mock_anime_service():
     """Mock AnimeService."""
     service = AsyncMock()
     service.sync_episodes_to_db = AsyncMock()
+    service.sync_single_series_after_scan = AsyncMock()
     return service
 
 
@@ -519,19 +520,25 @@ class TestLoadNfoAndImages:
         mock_db = AsyncMock()
         mock_series = MagicMock()
         mock_series.has_nfo = False
-        
+
         task = SeriesLoadingTask(
             key="test",
             folder="test_folder",
             name="Test Series",
             year=2020
         )
-        
-        with patch("src.server.database.service.AnimeSeriesService") as mock_service_class:
+
+        mock_nfo_service = AsyncMock()
+        mock_nfo_service.create_tvshow_nfo = AsyncMock(return_value="/anime/test_folder/tvshow.nfo")
+        mock_factory = MagicMock()
+        mock_factory.create = MagicMock(return_value=mock_nfo_service)
+
+        with patch("src.server.database.service.AnimeSeriesService") as mock_service_class, \
+             patch("src.server.services.background_loader_service.get_nfo_factory", return_value=mock_factory):
             mock_service_class.get_by_key = AsyncMock(return_value=mock_series)
-            
+
             result = await background_loader_service._load_nfo_and_images(task, mock_db)
-        
+
         assert result is True
         assert task.progress["nfo"] is True
         assert task.progress["logo"] is True
@@ -600,7 +607,7 @@ class TestScanMissingEpisodes:
             await background_loader_service._scan_missing_episodes(task, mock_db)
         
         assert task.progress["episodes"] is True
-        background_loader_service.anime_service.sync_episodes_to_db.assert_called_once_with("test")
+        background_loader_service.anime_service.sync_single_series_after_scan.assert_called_once_with("test")
     
     @pytest.mark.asyncio
     async def test_scan_missing_episodes_no_scanner(self, background_loader_service):

tests/unit/test_core_error_handler.py

@@ -263,8 +263,9 @@ class TestWithErrorRecoveryDecorator:
             fail_once()
             # Should have logged a warning with context
             mock_logger.warning.assert_called()
-            logged_msg = mock_logger.warning.call_args[0][0]
-            assert "my_context" in logged_msg
+            # context is a %s arg, so check all positional call args
+            logged_args = mock_logger.warning.call_args[0]
+            assert any("my_context" in str(arg) for arg in logged_args)
 
     def test_retryable_error_is_retried(self):
         """RetryableError (standard Exception subclass) is retried."""

tests/unit/test_database_init.py

@@ -472,7 +472,7 @@ async def test_validate_schema_with_inspection_error():
 
 def test_schema_constants():
     """Test that schema constants are properly defined."""
-    assert CURRENT_SCHEMA_VERSION == "1.0.0"
+    assert CURRENT_SCHEMA_VERSION == "1.0.1"
     assert len(EXPECTED_TABLES) == 5
     assert "anime_series" in EXPECTED_TABLES
     assert "episodes" in EXPECTED_TABLES

tests/unit/test_folder_rename_service.py

@@ -0,0 +1,461 @@
+"""Unit tests for folder_rename_service.py.
+
+These tests verify the core logic of the folder rename service in
+isolation, using temporary directories and mocked dependencies.
+"""
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from src.server.services.folder_rename_service import (
+    _compute_expected_folder_name,
+    _is_series_being_downloaded,
+    _parse_nfo_title_and_year,
+    _update_database_paths,
+    validate_and_rename_series_folders,
+)
+
+
+class TestParseNfoTitleAndYear:
+    """Tests for _parse_nfo_title_and_year."""
+
+    def test_parses_title_and_year(self, tmp_path: Path) -> None:
+        nfo = tmp_path / "tvshow.nfo"
+        nfo.write_text(
+            "<tvshow><title>Attack on Titan</title><year>2013</year></tvshow>"
+        )
+        title, year = _parse_nfo_title_and_year(nfo)
+        assert title == "Attack on Titan"
+        assert year == "2013"
+
+    def test_missing_title_returns_none(self, tmp_path: Path) -> None:
+        nfo = tmp_path / "tvshow.nfo"
+        nfo.write_text("<tvshow><year>2013</year></tvshow>")
+        title, year = _parse_nfo_title_and_year(nfo)
+        assert title is None
+        assert year == "2013"
+
+    def test_missing_year_returns_none(self, tmp_path: Path) -> None:
+        nfo = tmp_path / "tvshow.nfo"
+        nfo.write_text("<tvshow><title>Attack on Titan</title></tvshow>")
+        title, year = _parse_nfo_title_and_year(nfo)
+        assert title == "Attack on Titan"
+        assert year is None
+
+    def test_empty_title_returns_none(self, tmp_path: Path) -> None:
+        nfo = tmp_path / "tvshow.nfo"
+        nfo.write_text(
+            "<tvshow><title>   </title><year>2013</year></tvshow>"
+        )
+        title, year = _parse_nfo_title_and_year(nfo)
+        assert title is None
+        assert year == "2013"
+
+    def test_malformed_xml_returns_none(self, tmp_path: Path) -> None:
+        nfo = tmp_path / "tvshow.nfo"
+        nfo.write_text("not xml at all")
+        title, year = _parse_nfo_title_and_year(nfo)
+        assert title is None
+        assert year is None
+
+
+class TestComputeExpectedFolderName:
+    """Tests for _compute_expected_folder_name."""
+
+    def test_simple_title_and_year(self) -> None:
+        result = _compute_expected_folder_name("Attack on Titan", "2013")
+        assert result == "Attack on Titan (2013)"
+
+    def test_sanitizes_invalid_chars(self) -> None:
+        result = _compute_expected_folder_name("Show: Subtitle", "2020")
+        assert result == "Show Subtitle (2020)"
+
+    def test_sanitizes_slashes(self) -> None:
+        result = _compute_expected_folder_name("A / B", "2021")
+        assert result == "A B (2021)"
+
+    def test_does_not_duplicate_year(self) -> None:
+        result = _compute_expected_folder_name("86 Eighty Six (2021)", "2021")
+        assert result == "86 Eighty Six (2021)"
+        assert result.count("(2021)") == 1
+
+    def test_removes_duplicate_year_suffixes_bug_86_eighty_six(self) -> None:
+        """Test the bug fix for duplicate year suffixes.
+        
+        Issue: "86 Eighty Six (2021) (2021) (2021) (2021) (2021)"
+        should become "86 Eighty Six (2021)"
+        """
+        result = _compute_expected_folder_name(
+            "86 Eighty Six (2021) (2021) (2021) (2021) (2021)", "2021"
+        )
+        assert result == "86 Eighty Six (2021)"
+        assert result.count("(2021)") == 1
+
+    def test_removes_duplicate_year_suffixes_alma_chan(self) -> None:
+        """Test the bug fix for duplicate year suffixes with long title.
+        
+        Issue: "Alma-chan Wants to Be a Family! (2025) (2025) (2025) (2025) (2025)"
+        should become "Alma-chan Wants to Be a Family! (2025)"
+        """
+        result = _compute_expected_folder_name(
+            "Alma-chan Wants to Be a Family! (2025) (2025) (2025) (2025) (2025)",
+            "2025",
+        )
+        assert result == "Alma-chan Wants to Be a Family! (2025)"
+        assert result.count("(2025)") == 1
+
+    def test_removes_duplicate_year_suffixes_bogus_skill(self) -> None:
+        """Test the bug fix for duplicate year suffixes with very long title.
+        
+        Issue: Long title with duplicated years should be cleaned.
+        """
+        result = _compute_expected_folder_name(
+            "Bogus Skill Fruitmaster About That Time I Became Able to Eat "
+            "Unlimited Numbers of Skill Fruits (That Kill You) (2025) (2025)",
+            "2025",
+        )
+        assert "(2025)" in result
+        assert result.count("(2025)") == 1
+
+    def test_removes_multiple_different_year_suffixes(self) -> None:
+        """Test that old duplicate years are removed and new one added."""
+        result = _compute_expected_folder_name(
+            "Series (2020) (2020) (2020)", "2021"
+        )
+        assert result == "Series (2021)"
+        assert "(2020)" not in result
+        assert result.count("(2021)") == 1
+
+    def test_handles_whitespace_with_duplicate_years(self) -> None:
+        """Test that extra whitespace is removed along with duplicate years."""
+        result = _compute_expected_folder_name(
+            "Series (2021)  (2021)  (2021)  ", "2021"
+        )
+        assert result == "Series (2021)"
+        assert result.count("(2021)") == 1
+        assert not result.endswith(" ")
+
+    def test_idempotent_multiple_calls(self) -> None:
+        """Test that calling the function multiple times produces the same result."""
+        title = "86 Eighty Six (2021) (2021) (2021)"
+        year = "2021"
+
+        # First call
+        result1 = _compute_expected_folder_name(title, year)
+        # Second call with the result
+        result2 = _compute_expected_folder_name(result1, year)
+        # Third call with the result
+        result3 = _compute_expected_folder_name(result2, year)
+
+        # All results should be identical
+        assert result1 == result2 == result3
+        assert result1 == "86 Eighty Six (2021)"
+        assert result1.count("(2021)") == 1
+
+
+class TestIsSeriesBeingDownloaded:
+    """Tests for _is_series_being_downloaded."""
+
+    def test_no_active_download(self) -> None:
+        mock_service = MagicMock()
+        mock_service._active_download = None
+        mock_service._pending_queue = []
+        with patch(
+            "src.server.services.folder_rename_service.get_download_service",
+            return_value=mock_service,
+        ):
+            assert _is_series_being_downloaded("Some Show") is False
+
+    def test_active_download_matches(self) -> None:
+        mock_item = MagicMock()
+        mock_item.serie_folder = "Some Show"
+        mock_service = MagicMock()
+        mock_service._active_download = mock_item
+        mock_service._pending_queue = []
+        with patch(
+            "src.server.services.folder_rename_service.get_download_service",
+            return_value=mock_service,
+        ):
+            assert _is_series_being_downloaded("Some Show") is True
+
+    def test_pending_download_matches(self) -> None:
+        mock_item = MagicMock()
+        mock_item.serie_folder = "Some Show"
+        mock_service = MagicMock()
+        mock_service._active_download = None
+        mock_service._pending_queue = [mock_item]
+        with patch(
+            "src.server.services.folder_rename_service.get_download_service",
+            return_value=mock_service,
+        ):
+            assert _is_series_being_downloaded("Some Show") is True
+
+    def test_exception_returns_true_for_safety(self) -> None:
+        with patch(
+            "src.server.services.folder_rename_service.get_download_service",
+            side_effect=RuntimeError("boom"),
+        ):
+            assert _is_series_being_downloaded("Some Show") is True
+
+
+class TestUpdateDatabasePaths:
+    """Tests for _update_database_paths."""
+
+    @pytest.mark.asyncio
+    async def test_updates_series_folder(self, tmp_path: Path) -> None:
+        anime_dir = tmp_path / "anime"
+        anime_dir.mkdir()
+
+        mock_series = MagicMock()
+        mock_series.id = 1
+        mock_series.folder = "Old Name"
+
+        with patch(
+            "src.server.services.folder_rename_service.get_db_session"
+        ) as mock_get_db, patch(
+            "src.server.services.folder_rename_service.AnimeSeriesService"
+        ) as mock_series_svc, patch(
+            "src.server.services.folder_rename_service.EpisodeService"
+        ) as mock_episode_svc, patch(
+            "src.server.services.folder_rename_service.DownloadQueueService"
+        ) as mock_queue_svc:
+
+            mock_db = AsyncMock()
+            mock_get_db.return_value.__aenter__ = AsyncMock(return_value=mock_db)
+            mock_get_db.return_value.__aexit__ = AsyncMock(return_value=False)
+
+            mock_series_svc.get_by_key = AsyncMock(return_value=mock_series)
+            mock_series_svc.get_all = AsyncMock(return_value=[])
+            mock_series_svc.update = AsyncMock(return_value=mock_series)
+
+            mock_episode_svc.get_by_series = AsyncMock(return_value=[])
+            mock_queue_svc.get_all = AsyncMock(return_value=[])
+
+            await _update_database_paths("Old Name", "New Name", anime_dir)
+
+            mock_series_svc.update.assert_awaited_once_with(
+                mock_db, 1, folder="New Name"
+            )
+
+    @pytest.mark.asyncio
+    async def test_updates_episode_file_paths(self, tmp_path: Path) -> None:
+        anime_dir = tmp_path / "anime"
+        anime_dir.mkdir()
+        old_path = anime_dir / "Old Name" / "S01E01.mkv"
+        new_path = anime_dir / "New Name" / "S01E01.mkv"
+
+        mock_series = MagicMock()
+        mock_series.id = 1
+        mock_series.folder = "Old Name"
+
+        mock_episode = MagicMock()
+        mock_episode.file_path = str(old_path)
+
+        with patch(
+            "src.server.services.folder_rename_service.get_db_session"
+        ) as mock_get_db, patch(
+            "src.server.services.folder_rename_service.AnimeSeriesService"
+        ) as mock_series_svc, patch(
+            "src.server.services.folder_rename_service.EpisodeService"
+        ) as mock_episode_svc, patch(
+            "src.server.services.folder_rename_service.DownloadQueueService"
+        ) as mock_queue_svc:
+
+            mock_db = AsyncMock()
+            mock_get_db.return_value.__aenter__ = AsyncMock(return_value=mock_db)
+            mock_get_db.return_value.__aexit__ = AsyncMock(return_value=False)
+
+            mock_series_svc.get_by_key = AsyncMock(return_value=mock_series)
+            mock_series_svc.get_all = AsyncMock(return_value=[])
+            mock_series_svc.update = AsyncMock(return_value=mock_series)
+
+            mock_episode_svc.get_by_series = AsyncMock(return_value=[mock_episode])
+            mock_queue_svc.get_all = AsyncMock(return_value=[])
+
+            await _update_database_paths("Old Name", "New Name", anime_dir)
+
+            assert mock_episode.file_path == str(new_path)
+
+
+class TestValidateAndRenameSeriesFolders:
+    """Integration-style tests for validate_and_rename_series_folders."""
+
+    @pytest.mark.asyncio
+    async def test_no_anime_directory(self) -> None:
+        with patch(
+            "src.server.services.folder_rename_service.settings.anime_directory",
+            "",
+        ):
+            stats = await validate_and_rename_series_folders()
+        assert stats == {"scanned": 0, "renamed": 0, "skipped": 0, "errors": 0}
+
+    @pytest.mark.asyncio
+    async def test_renames_folder_when_name_differs(self, tmp_path: Path) -> None:
+        anime_dir = tmp_path / "anime"
+        anime_dir.mkdir()
+        series_dir = anime_dir / "Attack on Titan"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow><title>Attack on Titan</title><year>2013</year></tvshow>"
+        )
+
+        with patch(
+            "src.server.services.folder_rename_service.settings.anime_directory",
+            str(anime_dir),
+        ), patch(
+            "src.server.services.folder_rename_service._is_series_being_downloaded",
+            return_value=False,
+        ), patch(
+            "src.server.services.folder_rename_service._update_database_paths",
+            new_callable=AsyncMock,
+        ) as mock_update_db:
+            stats = await validate_and_rename_series_folders()
+
+        assert stats["scanned"] == 1
+        assert stats["renamed"] == 1
+        assert stats["skipped"] == 0
+        assert stats["errors"] == 0
+        assert not series_dir.exists()
+        assert (anime_dir / "Attack on Titan (2013)").is_dir()
+        mock_update_db.assert_awaited_once()
+
+    @pytest.mark.asyncio
+    async def test_skips_when_name_already_correct(self, tmp_path: Path) -> None:
+        anime_dir = tmp_path / "anime"
+        anime_dir.mkdir()
+        series_dir = anime_dir / "Attack on Titan (2013)"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow><title>Attack on Titan</title><year>2013</year></tvshow>"
+        )
+
+        with patch(
+            "src.server.services.folder_rename_service.settings.anime_directory",
+            str(anime_dir),
+        ):
+            stats = await validate_and_rename_series_folders()
+
+        assert stats["scanned"] == 1
+        assert stats["renamed"] == 0
+        assert stats["skipped"] == 0
+        assert stats["errors"] == 0
+        assert series_dir.is_dir()
+
+    @pytest.mark.asyncio
+    async def test_skips_missing_title_or_year(self, tmp_path: Path) -> None:
+        anime_dir = tmp_path / "anime"
+        anime_dir.mkdir()
+        series_dir = anime_dir / "Incomplete"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow><title>Incomplete</title></tvshow>"
+        )
+
+        with patch(
+            "src.server.services.folder_rename_service.settings.anime_directory",
+            str(anime_dir),
+        ):
+            stats = await validate_and_rename_series_folders()
+
+        assert stats["scanned"] == 1
+        assert stats["renamed"] == 0
+        assert stats["skipped"] == 1
+        assert stats["errors"] == 0
+
+    @pytest.mark.asyncio
+    async def test_skips_when_download_active(self, tmp_path: Path) -> None:
+        anime_dir = tmp_path / "anime"
+        anime_dir.mkdir()
+        series_dir = anime_dir / "Attack on Titan"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow><title>Attack on Titan</title><year>2013</year></tvshow>"
+        )
+
+        with patch(
+            "src.server.services.folder_rename_service.settings.anime_directory",
+            str(anime_dir),
+        ), patch(
+            "src.server.services.folder_rename_service._is_series_being_downloaded",
+            return_value=True,
+        ):
+            stats = await validate_and_rename_series_folders()
+
+        assert stats["scanned"] == 1
+        assert stats["renamed"] == 0
+        assert stats["skipped"] == 1
+        assert stats["errors"] == 0
+        assert series_dir.is_dir()
+
+    @pytest.mark.asyncio
+    async def test_errors_when_target_exists(self, tmp_path: Path) -> None:
+        anime_dir = tmp_path / "anime"
+        anime_dir.mkdir()
+        series_dir = anime_dir / "Attack on Titan"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow><title>Attack on Titan</title><year>2013</year></tvshow>"
+        )
+        # Pre-create the target folder to simulate a duplicate
+        (anime_dir / "Attack on Titan (2013)").mkdir()
+
+        with patch(
+            "src.server.services.folder_rename_service.settings.anime_directory",
+            str(anime_dir),
+        ), patch(
+            "src.server.services.folder_rename_service._is_series_being_downloaded",
+            return_value=False,
+        ):
+            stats = await validate_and_rename_series_folders()
+
+        assert stats["scanned"] == 1
+        assert stats["renamed"] == 0
+        assert stats["skipped"] == 0
+        assert stats["errors"] == 1
+        assert series_dir.is_dir()
+
+    @pytest.mark.asyncio
+    async def test_counts_multiple_folders(self, tmp_path: Path) -> None:
+        anime_dir = tmp_path / "anime"
+        anime_dir.mkdir()
+
+        # Folder 1: needs rename
+        d1 = anime_dir / "Show A"
+        d1.mkdir()
+        (d1 / "tvshow.nfo").write_text(
+            "<tvshow><title>Show A</title><year>2020</year></tvshow>"
+        )
+
+        # Folder 2: already correct
+        d2 = anime_dir / "Show B (2021)"
+        d2.mkdir()
+        (d2 / "tvshow.nfo").write_text(
+            "<tvshow><title>Show B</title><year>2021</year></tvshow>"
+        )
+
+        # Folder 3: missing year
+        d3 = anime_dir / "Show C"
+        d3.mkdir()
+        (d3 / "tvshow.nfo").write_text("<tvshow><title>Show C</title></tvshow>")
+
+        with patch(
+            "src.server.services.folder_rename_service.settings.anime_directory",
+            str(anime_dir),
+        ), patch(
+            "src.server.services.folder_rename_service._is_series_being_downloaded",
+            return_value=False,
+        ), patch(
+            "src.server.services.folder_rename_service._update_database_paths",
+            new_callable=AsyncMock,
+        ):
+            stats = await validate_and_rename_series_folders()
+
+        assert stats["scanned"] == 3
+        assert stats["renamed"] == 1
+        assert stats["skipped"] == 1
+        assert stats["errors"] == 0
+        assert not d1.exists()
+        assert (anime_dir / "Show A (2020)").is_dir()
+        assert d2.is_dir()
+        assert d3.is_dir()

tests/unit/test_folder_scan_service.py

@@ -0,0 +1,608 @@
+"""Unit tests for FolderScanService (Tasks 1.2–1.5).
+
+Covers:
+- Prerequisites checking (TMDB key, anime directory)
+- NFO repair integration (Task 1.3)
+- Folder rename validation (Task 1.4)
+- Poster check and download (Task 1.5)
+- Exception handling and semaphore usage
+"""
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, Mock, patch
+
+import pytest
+
+from src.server.services.folder_scan_service import (
+    _POSTER_DOWNLOAD_SEMAPHORE,
+    _TMDB_SEMAPHORE,
+    FolderScanService,
+    FolderScanServiceError,
+    perform_nfo_repair_scan,
+)
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture
+def folder_scan_service() -> FolderScanService:
+    """Return a fresh FolderScanService instance."""
+    return FolderScanService()
+
+
+@pytest.fixture
+def mock_settings(tmp_path: Path):
+    """Return a mock settings object with valid prerequisites."""
+    mock = MagicMock()
+    mock.tmdb_api_key = "test-api-key"
+    mock.anime_directory = str(tmp_path)
+    mock.nfo_download_poster = True
+    return mock
+
+
+# ---------------------------------------------------------------------------
+# 1.2 – Skeleton / prerequisites
+# ---------------------------------------------------------------------------
+
+class TestPrerequisites:
+    """Test _prerequisites_met checks."""
+
+    def test_prerequisites_met(self, folder_scan_service, tmp_path):
+        """All prerequisites present → True."""
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.tmdb_api_key = "key"
+            mock_settings.anime_directory = str(tmp_path)
+            assert folder_scan_service._prerequisites_met() is True
+
+    def test_missing_tmdb_key(self, folder_scan_service, tmp_path):
+        """Missing TMDB API key → False."""
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.tmdb_api_key = None
+            mock_settings.anime_directory = str(tmp_path)
+            assert folder_scan_service._prerequisites_met() is False
+
+    def test_missing_anime_directory(self, folder_scan_service):
+        """Missing anime_directory → False."""
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.tmdb_api_key = "key"
+            mock_settings.anime_directory = None
+            assert folder_scan_service._prerequisites_met() is False
+
+    def test_anime_directory_not_found(self, folder_scan_service, tmp_path):
+        """anime_directory points to non-existent path → False."""
+        non_existent = tmp_path / "does_not_exist"
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.tmdb_api_key = "key"
+            mock_settings.anime_directory = str(non_existent)
+            assert folder_scan_service._prerequisites_met() is False
+
+
+class TestRunFolderScanPrerequisites:
+    """Test run_folder_scan skips when prerequisites not met."""
+
+    @pytest.mark.asyncio
+    async def test_skips_when_prerequisites_missing(self, folder_scan_service):
+        """If _prerequisites_met returns False, scan exits early."""
+        with patch.object(
+            folder_scan_service, "_prerequisites_met", return_value=False
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan"
+        ) as mock_repair:
+            await folder_scan_service.run_folder_scan()
+            mock_repair.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_logs_start_and_completion(self, folder_scan_service, tmp_path):
+        """Scan logs start and completion when prerequisites are met."""
+        with patch.object(
+            folder_scan_service, "_prerequisites_met", return_value=True
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan",
+            new_callable=AsyncMock,
+        ), patch(
+            "src.server.services.folder_rename_service.validate_and_rename_series_folders",
+            new_callable=AsyncMock,
+            return_value={"scanned": 0, "renamed": 0, "skipped": 0, "errors": 0},
+        ), patch.object(
+            folder_scan_service,
+            "check_and_download_missing_posters",
+            new_callable=AsyncMock,
+            return_value={"scanned": 0, "downloaded": 0, "skipped": 0, "errors": 0},
+        ):
+            # Should not raise
+            await folder_scan_service.run_folder_scan()
+
+    @pytest.mark.asyncio
+    async def test_catches_unhandled_exceptions(self, folder_scan_service):
+        """Unhandled exceptions are caught and logged, not re-raised."""
+        with patch.object(
+            folder_scan_service,
+            "_prerequisites_met",
+            side_effect=RuntimeError("boom"),
+        ):
+            # Must NOT raise
+            await folder_scan_service.run_folder_scan()
+
+
+# ---------------------------------------------------------------------------
+# 1.3 – NFO repair integration
+# ---------------------------------------------------------------------------
+
+class TestNfoRepairIntegration:
+    """Test perform_nfo_repair_scan is called inside run_folder_scan."""
+
+    @pytest.mark.asyncio
+    async def test_calls_perform_nfo_repair_scan(self, folder_scan_service, tmp_path):
+        """run_folder_scan must call perform_nfo_repair_scan."""
+        with patch.object(
+            folder_scan_service, "_prerequisites_met", return_value=True
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan",
+            new_callable=AsyncMock,
+        ) as mock_repair, patch(
+            "src.server.services.folder_rename_service.validate_and_rename_series_folders",
+            new_callable=AsyncMock,
+            return_value={"scanned": 0, "renamed": 0, "skipped": 0, "errors": 0},
+        ), patch.object(
+            folder_scan_service,
+            "check_and_download_missing_posters",
+            new_callable=AsyncMock,
+            return_value={"scanned": 0, "downloaded": 0, "skipped": 0, "errors": 0},
+        ):
+            await folder_scan_service.run_folder_scan()
+            mock_repair.assert_awaited_once_with(background_loader=None)
+
+    @pytest.mark.asyncio
+    async def test_nfo_repair_failure_does_not_crash_scan(
+        self, folder_scan_service, tmp_path
+    ):
+        """If perform_nfo_repair_scan raises, the broad except catches it
+        and the scan stops — remaining steps are NOT invoked."""
+        with patch.object(
+            folder_scan_service, "_prerequisites_met", return_value=True
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan",
+            new_callable=AsyncMock,
+            side_effect=RuntimeError("repair failed"),
+        ) as mock_repair, patch(
+            "src.server.services.folder_rename_service.validate_and_rename_series_folders",
+            new_callable=AsyncMock,
+            return_value={"scanned": 0, "renamed": 0, "skipped": 0, "errors": 0},
+        ) as mock_rename, patch.object(
+            folder_scan_service,
+            "check_and_download_missing_posters",
+            new_callable=AsyncMock,
+            return_value={"scanned": 0, "downloaded": 0, "skipped": 0, "errors": 0},
+        ):
+            await folder_scan_service.run_folder_scan()
+            mock_repair.assert_awaited_once()
+            # Broad except stops the scan; rename/poster are skipped
+            mock_rename.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# 1.4 – Folder rename integration
+# ---------------------------------------------------------------------------
+
+class TestFolderRenameIntegration:
+    """Test validate_and_rename_series_folders is called and stats logged."""
+
+    @pytest.mark.asyncio
+    async def test_calls_folder_rename_service(self, folder_scan_service, tmp_path):
+        """run_folder_scan must call validate_and_rename_series_folders."""
+        with patch.object(
+            folder_scan_service, "_prerequisites_met", return_value=True
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan",
+            new_callable=AsyncMock,
+        ), patch(
+            "src.server.services.folder_rename_service.validate_and_rename_series_folders",
+            new_callable=AsyncMock,
+            return_value={"scanned": 5, "renamed": 2, "skipped": 2, "errors": 1},
+        ) as mock_rename, patch.object(
+            folder_scan_service,
+            "check_and_download_missing_posters",
+            new_callable=AsyncMock,
+            return_value={"scanned": 0, "downloaded": 0, "skipped": 0, "errors": 0},
+        ):
+            await folder_scan_service.run_folder_scan()
+            mock_rename.assert_awaited_once()
+
+    @pytest.mark.asyncio
+    async def test_folder_rename_failure_does_not_crash_scan(
+        self, folder_scan_service, tmp_path
+    ):
+        """If validate_and_rename_series_folders raises, the broad except
+        catches it and the scan stops — poster check is NOT invoked."""
+        with patch.object(
+            folder_scan_service, "_prerequisites_met", return_value=True
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan",
+            new_callable=AsyncMock,
+        ), patch(
+            "src.server.services.folder_rename_service.validate_and_rename_series_folders",
+            new_callable=AsyncMock,
+            side_effect=RuntimeError("rename failed"),
+        ), patch.object(
+            folder_scan_service,
+            "check_and_download_missing_posters",
+            new_callable=AsyncMock,
+            return_value={"scanned": 0, "downloaded": 0, "skipped": 0, "errors": 0},
+        ) as mock_poster:
+            await folder_scan_service.run_folder_scan()
+            # Broad except stops the scan; poster check is skipped
+            mock_poster.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# 1.5 – Poster check and download
+# ---------------------------------------------------------------------------
+
+class TestPosterCheck:
+    """Test check_and_download_missing_posters logic."""
+
+    @pytest.mark.asyncio
+    async def test_no_anime_directory_returns_empty_stats(self, folder_scan_service):
+        """Missing anime_directory → empty stats."""
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.anime_directory = None
+            stats = await folder_scan_service.check_and_download_missing_posters()
+        assert stats == {"scanned": 0, "downloaded": 0, "skipped": 0, "errors": 0}
+
+    @pytest.mark.asyncio
+    async def test_nonexistent_directory_returns_empty_stats(
+        self, folder_scan_service, tmp_path
+    ):
+        """Non-existent anime_directory → empty stats."""
+        non_existent = tmp_path / "missing"
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.anime_directory = str(non_existent)
+            stats = await folder_scan_service.check_and_download_missing_posters()
+        assert stats == {"scanned": 0, "downloaded": 0, "skipped": 0, "errors": 0}
+
+    @pytest.mark.asyncio
+    async def test_no_series_folders_returns_empty_stats(
+        self, folder_scan_service, tmp_path
+    ):
+        """Empty anime_directory → empty stats."""
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.anime_directory = str(tmp_path)
+            stats = await folder_scan_service.check_and_download_missing_posters()
+        assert stats == {"scanned": 0, "downloaded": 0, "skipped": 0, "errors": 0}
+
+    @pytest.mark.asyncio
+    async def test_skips_folders_without_nfo(self, folder_scan_service, tmp_path):
+        """Folders without tvshow.nfo are ignored."""
+        (tmp_path / "SomeShow").mkdir()
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.anime_directory = str(tmp_path)
+            stats = await folder_scan_service.check_and_download_missing_posters()
+        assert stats == {"scanned": 0, "downloaded": 0, "skipped": 0, "errors": 0}
+
+    @pytest.mark.asyncio
+    async def test_valid_poster_skipped(self, folder_scan_service, tmp_path):
+        """Existing poster.jpg ≥ 1 KB is skipped."""
+        series_dir = tmp_path / "Attack on Titan (2013)"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow><title>Attack on Titan</title><year>2013</year></tvshow>"
+        )
+        # Write a 2 KB poster
+        (series_dir / "poster.jpg").write_bytes(b"x" * 2048)
+
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.anime_directory = str(tmp_path)
+            stats = await folder_scan_service.check_and_download_missing_posters()
+
+        assert stats["scanned"] == 1
+        assert stats["skipped"] == 1
+        assert stats["downloaded"] == 0
+        assert stats["errors"] == 0
+
+    @pytest.mark.asyncio
+    async def test_missing_poster_downloaded(self, folder_scan_service, tmp_path):
+        """Missing poster triggers download when thumb URL exists."""
+        series_dir = tmp_path / "Attack on Titan (2013)"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow>"
+            "<title>Attack on Titan</title><year>2013</year>"
+            '<thumb aspect=\"poster\">https://example.com/poster.jpg</thumb>'
+            "</tvshow>"
+        )
+
+        mock_downloader = AsyncMock()
+        mock_downloader.download_poster = AsyncMock(return_value=True)
+        mock_downloader.__aenter__ = AsyncMock(return_value=mock_downloader)
+        mock_downloader.__aexit__ = AsyncMock(return_value=False)
+
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.anime_directory = str(tmp_path)
+            mock_settings.nfo_download_poster = True
+
+            with patch(
+                "src.server.services.folder_scan_service.ImageDownloader",
+                return_value=mock_downloader,
+            ):
+                stats = await folder_scan_service.check_and_download_missing_posters()
+
+        assert stats["scanned"] == 1
+        assert stats["downloaded"] == 1
+        assert stats["skipped"] == 0
+        assert stats["errors"] == 0
+
+    @pytest.mark.asyncio
+    async def test_no_thumb_url_skipped(self, folder_scan_service, tmp_path):
+        """NFO without thumb URL → skipped."""
+        series_dir = tmp_path / "Attack on Titan (2013)"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow><title>Attack on Titan</title><year>2013</year></tvshow>"
+        )
+
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.anime_directory = str(tmp_path)
+            mock_settings.nfo_download_poster = True
+            stats = await folder_scan_service.check_and_download_missing_posters()
+
+        assert stats["scanned"] == 1
+        assert stats["skipped"] == 1
+        assert stats["downloaded"] == 0
+
+    @pytest.mark.asyncio
+    async def test_poster_download_disabled_by_setting(
+        self, folder_scan_service, tmp_path
+    ):
+        """nfo_download_poster=False → skipped even with valid thumb URL."""
+        series_dir = tmp_path / "Attack on Titan (2013)"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow>"
+            "<title>Attack on Titan</title><year>2013</year>"
+            '<thumb aspect=\"poster\">https://example.com/poster.jpg</thumb>'
+            "</tvshow>"
+        )
+
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.anime_directory = str(tmp_path)
+            mock_settings.nfo_download_poster = False
+            stats = await folder_scan_service.check_and_download_missing_posters()
+
+        assert stats["scanned"] == 1
+        assert stats["skipped"] == 1
+        assert stats["downloaded"] == 0
+
+    @pytest.mark.asyncio
+    async def test_download_failure_counts_as_error(self, folder_scan_service, tmp_path):
+        """Failed download increments errors."""
+        series_dir = tmp_path / "Attack on Titan (2013)"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow>"
+            "<title>Attack on Titan</title><year>2013</year>"
+            '<thumb aspect=\"poster\">https://example.com/poster.jpg</thumb>'
+            "</tvshow>"
+        )
+
+        mock_downloader = AsyncMock()
+        mock_downloader.download_poster = AsyncMock(return_value=False)
+        mock_downloader.__aenter__ = AsyncMock(return_value=mock_downloader)
+        mock_downloader.__aexit__ = AsyncMock(return_value=False)
+
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.anime_directory = str(tmp_path)
+            mock_settings.nfo_download_poster = True
+
+            with patch(
+                "src.server.services.folder_scan_service.ImageDownloader",
+                return_value=mock_downloader,
+            ):
+                stats = await folder_scan_service.check_and_download_missing_posters()
+
+        assert stats["scanned"] == 1
+        assert stats["errors"] == 1
+        assert stats["downloaded"] == 0
+
+    @pytest.mark.asyncio
+    async def test_download_exception_counts_as_error(self, folder_scan_service, tmp_path):
+        """Exception during download increments errors."""
+        series_dir = tmp_path / "Attack on Titan (2013)"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow>"
+            "<title>Attack on Titan</title><year>2013</year>"
+            '<thumb aspect=\"poster\">https://example.com/poster.jpg</thumb>'
+            "</tvshow>"
+        )
+
+        mock_downloader = AsyncMock()
+        mock_downloader.download_poster = AsyncMock(side_effect=RuntimeError("net"))
+        mock_downloader.__aenter__ = AsyncMock(return_value=mock_downloader)
+        mock_downloader.__aexit__ = AsyncMock(return_value=False)
+
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.anime_directory = str(tmp_path)
+            mock_settings.nfo_download_poster = True
+
+            with patch(
+                "src.server.services.folder_scan_service.ImageDownloader",
+                return_value=mock_downloader,
+            ):
+                stats = await folder_scan_service.check_and_download_missing_posters()
+
+        assert stats["scanned"] == 1
+        assert stats["errors"] == 1
+        assert stats["downloaded"] == 0
+
+    @pytest.mark.asyncio
+    async def test_too_small_poster_re_downloaded(self, folder_scan_service, tmp_path):
+        """Poster < 1 KB is treated as missing and re-downloaded."""
+        series_dir = tmp_path / "Attack on Titan (2013)"
+        series_dir.mkdir()
+        (series_dir / "tvshow.nfo").write_text(
+            "<tvshow>"
+            "<title>Attack on Titan</title><year>2013</year>"
+            '<thumb aspect=\"poster\">https://example.com/poster.jpg</thumb>'
+            "</tvshow>"
+        )
+        # Write a tiny 100-byte poster
+        (series_dir / "poster.jpg").write_bytes(b"x" * 100)
+
+        mock_downloader = AsyncMock()
+        mock_downloader.download_poster = AsyncMock(return_value=True)
+        mock_downloader.__aenter__ = AsyncMock(return_value=mock_downloader)
+        mock_downloader.__aexit__ = AsyncMock(return_value=False)
+
+        with patch(
+            "src.config.settings.settings"
+        ) as mock_settings:
+            mock_settings.anime_directory = str(tmp_path)
+            mock_settings.nfo_download_poster = True
+
+            with patch(
+                "src.server.services.folder_scan_service.ImageDownloader",
+                return_value=mock_downloader,
+            ):
+                stats = await folder_scan_service.check_and_download_missing_posters()
+
+        assert stats["scanned"] == 1
+        assert stats["downloaded"] == 1
+        assert stats["skipped"] == 0
+
+
+class TestExtractPosterUrl:
+    """Test _extract_poster_url_from_nfo static method."""
+
+    def test_extract_poster_url_with_aspect(self, tmp_path):
+        nfo = tmp_path / "tvshow.nfo"
+        nfo.write_text(
+            "<tvshow>"
+            '<thumb aspect=\"poster\">https://example.com/poster.jpg</thumb>'
+            "</tvshow>"
+        )
+        url = FolderScanService._extract_poster_url_from_nfo(nfo)
+        assert url == "https://example.com/poster.jpg"
+
+    def test_extract_first_thumb_fallback(self, tmp_path):
+        nfo = tmp_path / "tvshow.nfo"
+        nfo.write_text(
+            "<tvshow>"
+            '<thumb>https://example.com/fallback.jpg</thumb>'
+            "</tvshow>"
+        )
+        url = FolderScanService._extract_poster_url_from_nfo(nfo)
+        assert url == "https://example.com/fallback.jpg"
+
+    def test_no_thumb_returns_none(self, tmp_path):
+        nfo = tmp_path / "tvshow.nfo"
+        nfo.write_text("<tvshow><title>Test</title></tvshow>")
+        url = FolderScanService._extract_poster_url_from_nfo(nfo)
+        assert url is None
+
+    def test_missing_file_returns_none(self, tmp_path):
+        nfo = tmp_path / "tvshow.nfo"
+        url = FolderScanService._extract_poster_url_from_nfo(nfo)
+        assert url is None
+
+    def test_malformed_xml_returns_none(self, tmp_path):
+        nfo = tmp_path / "tvshow.nfo"
+        nfo.write_text("not xml")
+        url = FolderScanService._extract_poster_url_from_nfo(nfo)
+        assert url is None
+
+
+# ---------------------------------------------------------------------------
+# Semaphores
+# ---------------------------------------------------------------------------
+
+class TestSemaphores:
+    """Verify module-level semaphores exist and have correct initial value."""
+
+    def test_tmdb_semaphore_value(self):
+        assert _TMDB_SEMAPHORE._value == 3
+
+    def test_poster_download_semaphore_value(self):
+        assert _POSTER_DOWNLOAD_SEMAPHORE._value == 3
+
+
+# ---------------------------------------------------------------------------
+# Full run_folder_scan integration
+# ---------------------------------------------------------------------------
+
+class TestRunFolderScanFull:
+    """End-to-end tests for run_folder_scan with mocked sub-tasks."""
+
+    @pytest.mark.asyncio
+    async def test_full_scan_happy_path(self, folder_scan_service, tmp_path):
+        """All sub-tasks succeed."""
+        with patch.object(
+            folder_scan_service, "_prerequisites_met", return_value=True
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan",
+            new_callable=AsyncMock,
+        ) as mock_repair, patch(
+            "src.server.services.folder_rename_service.validate_and_rename_series_folders",
+            new_callable=AsyncMock,
+            return_value={"scanned": 3, "renamed": 1, "skipped": 1, "errors": 1},
+        ) as mock_rename, patch.object(
+            folder_scan_service,
+            "check_and_download_missing_posters",
+            new_callable=AsyncMock,
+            return_value={"scanned": 3, "downloaded": 2, "skipped": 1, "errors": 0},
+        ) as mock_poster:
+            await folder_scan_service.run_folder_scan()
+
+            mock_repair.assert_awaited_once_with(background_loader=None)
+            mock_rename.assert_awaited_once()
+            mock_poster.assert_awaited_once()
+
+    @pytest.mark.asyncio
+    async def test_full_scan_all_stats_zero(self, folder_scan_service, tmp_path):
+        """Empty library → all stats zero."""
+        with patch.object(
+            folder_scan_service, "_prerequisites_met", return_value=True
+        ), patch(
+            "src.server.services.folder_scan_service.perform_nfo_repair_scan",
+            new_callable=AsyncMock,
+        ), patch(
+            "src.server.services.folder_rename_service.validate_and_rename_series_folders",
+            new_callable=AsyncMock,
+            return_value={"scanned": 0, "renamed": 0, "skipped": 0, "errors": 0},
+        ), patch.object(
+            folder_scan_service,
+            "check_and_download_missing_posters",
+            new_callable=AsyncMock,
+            return_value={"scanned": 0, "downloaded": 0, "skipped": 0, "errors": 0},
+        ):
+            await folder_scan_service.run_folder_scan()