Document NFO folder naming fix

docs/instructions.md

@@ -123,6 +123,33 @@ All tasks completed! Recent issues have been resolved.
 
 ## Recently Fixed Issues:
 
+### ✅ Fixed: NFO Folder Naming Without Year (2026-01-18)
+
+**Issue:** After creating NFO files, the folder name is created as "<name>" but should be "<name> (<year>)" to properly distinguish series with the same name but different years (e.g., "Perfect Blue" vs "Perfect Blue (1997)").
+
+**Root Cause:** The NFO endpoints were using `serie.folder` directly without ensuring it includes the year. The `Serie` class already had a `sanitized_folder` property that creates proper folder names with year format, but it wasn't being used consistently during NFO creation.
+
+**Solution:** 
+1. Added `Serie.ensure_folder_with_year()` method that checks if the folder name includes the year and updates it if needed
+2. Updated all NFO API endpoints (`create`, `update`, `check`, `view`, `download_media`, `batch_create`, `get_series_without_nfo`) to call `ensure_folder_with_year()` before any NFO operations
+3. This ensures there's a single code location responsible for folder name generation with year format
+4. The NFO service creates folders using the updated folder name
+
+**Files Modified:**
+- [src/core/entities/series.py](../src/core/entities/series.py) - Added `ensure_folder_with_year()` method
+- [src/server/api/nfo.py](../src/server/api/nfo.py) - Updated all endpoints to use `ensure_folder_with_year()`
+
+**Tests Added:**
+- [tests/unit/test_serie_folder_with_year.py](../tests/unit/test_serie_folder_with_year.py) - 5 comprehensive tests covering all scenarios
+
+**Verification:**
+- All 5 unit tests pass
+- Folder names now consistently use "Name (Year)" format when year is available
+- Existing folders without year are automatically updated when NFO operations are performed
+- Single centralized method ensures consistency across the application
+
+---
+
 ### ✅ Fixed: NFO JavaScript JSON Parsing Error (2026-01-18)
 
 **Issue:** Browser console shows `Error creating NFO: Error: Failed to create NFO` from [nfo-manager.js](../src/server/web/static/js/index/nfo-manager.js) and [series-manager.js](../src/server/web/static/js/index/series-manager.js). The API calls were failing because the code was trying to access response properties directly without parsing the JSON.