docs/API.md

@@ -268,7 +268,7 @@ Source: [src/server/api/anime.py](../src/server/api/anime.py#L477-L495)
 
 ### POST /api/anime/add
 
-Add a new series to the library.
+Add a new series to the library with automatic database persistence, folder creation, and episode scanning.
 
 **Authentication:** Required
 
@@ -289,10 +289,28 @@ Add a new series to the library.
     "message": "Successfully added series: Attack on Titan",
     "key": "attack-on-titan",
     "folder": "Attack on Titan",
-    "db_id": 1
+    "db_id": 1,
+    "missing_episodes": ["1-1", "1-2", "1-3"],
+    "total_missing": 3
 }
 ```
 
+**Enhanced Flow:**
+
+1. Validates the request (link format, name)
+2. Creates Serie object with sanitized folder name
+3. Saves to database via AnimeDBService
+4. Creates folder using sanitized display name (not internal key)
+5. Performs targeted episode scan for this anime only
+6. Returns response with missing episodes count
+
+**Folder Name Sanitization:**
+
+- Removes invalid filesystem characters: `< > : " / \ | ? *`
+- Trims leading/trailing whitespace and dots
+- Preserves Unicode characters (for Japanese titles)
+- Example: `"Attack on Titan: Final Season"` → `"Attack on Titan Final Season"`
+
 Source: [src/server/api/anime.py](../src/server/api/anime.py#L604-L710)
 
 ### POST /api/anime/rescan

docs/ARCHITECTURE.md

@@ -90,6 +90,10 @@ src/server/
 |   +-- connection.py       # Database connection
 |   +-- models.py           # ORM models
 |   +-- service.py          # Database service
++-- utils/                  # Utility modules
+|   +-- filesystem.py       # Folder sanitization, path safety
+|   +-- validators.py       # Input validation utilities
+|   +-- dependencies.py     # FastAPI dependency injection
 +-- web/                    # Static files and templates
     +-- static/             # CSS, JS, images
     +-- templates/          # Jinja2 templates
@@ -104,10 +108,10 @@ Domain logic for anime series management.
 ```
 src/core/
 +-- SeriesApp.py            # Main application facade
-+-- SerieScanner.py         # Directory scanning
++-- SerieScanner.py         # Directory scanning, targeted single-series scan
 +-- entities/               # Domain entities
-|   +-- series.py           # Serie class
-|   +-- SerieList.py        # SerieList collection
+|   +-- series.py           # Serie class with sanitized_folder property
+|   +-- SerieList.py        # SerieList collection with sanitized folder support
 +-- providers/              # External provider adapters
 |   +-- base_provider.py    # Loader interface
 |   +-- provider_factory.py # Provider registry
@@ -117,6 +121,15 @@ src/core/
     +-- Exceptions.py       # Custom exceptions
 ```
 
+**Key Components:**
+
+| Component         | Purpose                                                                 |
+| ----------------- | ----------------------------------------------------------------------- |
+| `SeriesApp`       | Main application facade for anime operations                            |
+| `SerieScanner`    | Scans directories for anime; `scan_single_series()` for targeted scans  |
+| `Serie`           | Domain entity with `sanitized_folder` property for filesystem-safe names |
+| `SerieList`       | Collection management with automatic folder creation using sanitized names |
+
 Source: [src/core/](../src/core/)
 
 ### 2.4 Infrastructure Layer (`src/infrastructure/`)

docs/CHANGELOG.md

@@ -73,6 +73,11 @@ _Changes that are in development but not yet released._
 
 ### Added
 
+-   **Enhanced Anime Add Flow**: Automatic database persistence, targeted episode scanning, and folder creation with sanitized names
+-   Filesystem utility module (`src/server/utils/filesystem.py`) with `sanitize_folder_name()`, `is_safe_path()`, and `create_safe_folder()` functions
+-   `Serie.sanitized_folder` property for generating filesystem-safe folder names from display names
+-   `SerieScanner.scan_single_series()` method for targeted scanning of individual anime without full library rescan
+-   Add series API response now includes `missing_episodes` list and `total_missing` count
 -   Database transaction support with `@transactional` decorator and `atomic()` context manager
 -   Transaction propagation modes (REQUIRED, REQUIRES_NEW, NESTED) for fine-grained control
 -   Savepoint support for nested transactions with partial rollback capability