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

docs/README.md

@@ -97,6 +97,42 @@ Production deployment instructions covering:
 -   Status notifications
 -   Error alerts
 
+## Series Identifier Convention
+
+### Understanding Series Identifiers
+
+The application uses two identifiers for anime series:
+
+| Identifier | Purpose                  | Example                    | Used For          |
+| ---------- | ------------------------ | -------------------------- | ----------------- |
+| `key`      | **Primary identifier**   | `"attack-on-titan"`        | All API lookups   |
+| `folder`   | Filesystem metadata only | `"Attack on Titan (2013)"` | Display purposes  |
+
+### Key Format
+
+-   Lowercase letters and numbers only
+-   Words separated by hyphens (`-`)
+-   No spaces, underscores, or uppercase letters
+-   Examples: `"one-piece"`, `"86-eighty-six"`, `"re-zero"`
+
+### Usage Guidelines
+
+```python
+# ✅ Correct: Use 'key' for API operations
+GET /api/anime/attack-on-titan
+POST /api/queue/add {"serie_id": "attack-on-titan", ...}
+
+# ❌ Deprecated: Folder-based lookups (backward compatibility only)
+GET /api/anime/Attack%20on%20Titan%20(2013)  # Will work but deprecated
+```
+
+### Backward Compatibility
+
+For existing integrations, folder-based lookups are still supported but deprecated:
+- API endpoints check `key` first, then fall back to `folder`
+- New code should always use `key` as the identifier
+- Deprecation warnings will be added in future versions
+
 ## Documentation Examples
 
 ### API Usage Example
@@ -285,8 +321,8 @@ docs/
 
 ## Document Info
 
--   **Last Updated**: October 22, 2025
--   **Version**: 1.0.0
+-   **Last Updated**: November 28, 2025
+-   **Version**: 2.0.0
 -   **Status**: Production Ready
 -   **Maintainers**: Development Team