Phase 8: Documentation and deprecation warnings for identifier standardization

- Enhanced infrastructure.md with identifier convention table, format requirements, migration notes
- Updated docs/README.md with series identifier convention section
- Updated docs/api_reference.md with key-based API examples and notes
- Added deprecation warnings to SerieList.get_by_folder()
- Added deprecation warnings to anime.py folder fallback lookup
- Added deprecation warnings to validate_series_key_or_folder()
- All warnings include v3.0.0 removal timeline
- All 1006 tests pass

src/server/utils/validators.py

@@ -6,6 +6,7 @@ utilities for ensuring data integrity across the application.
 """
 
 import re
+import warnings
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -496,6 +497,10 @@ def validate_series_key_or_folder(
     """
     Validate an identifier that could be either a series key or folder.
 
+    .. deprecated:: 2.0.0
+        Folder-based identification is deprecated. Use series `key` only.
+        This function will require key format only in v3.0.0.
+
     This function provides backward compatibility during the transition
     from folder-based to key-based identification.
 
@@ -532,6 +537,15 @@ def validate_series_key_or_folder(
             "Keys must be lowercase with hyphens (e.g., 'attack-on-titan')."
         )
 
+    # Emit deprecation warning for folder-based identification
+    warnings.warn(
+        f"Folder-based identification for '{identifier}' is deprecated. "
+        "Use series key (lowercase with hyphens) instead. "
+        "Folder-based identification will be removed in v3.0.0.",
+        DeprecationWarning,
+        stacklevel=2
+    )
+
     # Validate as folder (more permissive)
     if len(identifier) > 1000:
         raise ValueError("Identifier too long (max 1000 characters)")