docs: update scan settings documentation for new polling system

- Update validation from minutes (15-1440) to seconds (1-3600)
- Clarify behavior: real-time file watching with polling fallback
- Remove scheduler references from development docs
- Update migration notes for the new implementation

docs/contributing/development.md

@@ -66,9 +66,8 @@ bookhoard/
 **Services** (`internal/services/`):
 
 - `library_service.go` - Library operations
-- `media_scanner.go` - File scanning & metadata extraction
+- `media_scanner.go` - File scanning, metadata extraction, and real-time file watching
 - `worker.go` - Job queue worker pool
-- `scheduler.go` - Scheduled task manager
 - `collection_service.go` - Collection rules processing
 - `conversion_service.go` - EPUB→KEPUB conversion
 - `book_matching.go` - Book matching algorithms

docs/developer/api/system/settings.md

@@ -38,7 +38,7 @@ Retrieve the current system-wide scan settings.
 
 **Fields**:
 
-- `scan_poll_interval_seconds` (integer): How often to scan all libraries in minutes (15-1440)
+- `scan_poll_interval_seconds` (integer): How often to poll for file changes in seconds (1-3600)
 - `auto_scan_enabled` (boolean): Whether auto-scanning is enabled system-wide
 
 **Example**:
@@ -69,9 +69,9 @@ Update the system-wide scan settings.
 
 **Fields**:
 
-- `scan_poll_interval_seconds` (integer, required): How often to scan all libraries in minutes
-  - Minimum: 15 (15 minutes)
-  - Maximum: 1440 (24 hours)
+- `scan_poll_interval_seconds` (integer, required): How often to poll for file changes in seconds
+  - Minimum: 1 (1 second)
+  - Maximum: 3600 (1 hour)
   - Default: 60
 - `auto_scan_enabled` (boolean, required): Whether auto-scanning is enabled system-wide
   - Default: true
@@ -104,7 +104,7 @@ Update the system-wide scan settings.
 
 **Validation Rules**:
 
-- `scan_poll_interval_seconds` must be between 15 and 1440 minutes
+- `scan_poll_interval_seconds` must be between 1 and 3600 seconds (1 second to 1 hour)
 - Both fields are required
 
 **Example**:
@@ -123,26 +123,31 @@ curl -X PUT https://bookhoard.example.com/api/libraries/scan-settings \
 
 ## Behavior
 
-### Scan Frequency
+### Poll Interval
 
-The `scan_poll_interval_seconds` setting determines how often the system will automatically scan all libraries for new media files. The scheduler will trigger scans for all libraries at the configured interval.
+The `scan_poll_interval_seconds` setting determines how often the system will poll library folders for file changes as a fallback to real-time file watching.
 
 **Constraints**:
 
-- Minimum: 15 minutes (to prevent excessive scanning)
-- Maximum: 1440 minutes (24 hours)
-- Default: 60 minutes (1 hour)
+- Minimum: 1 second
+- Maximum: 3600 seconds (1 hour)
+- Default: 60 seconds
 
 ### Auto-Scan Toggle
 
 The `auto_scan_enabled` setting acts as a master switch for automatic scanning:
 
-- When `true`: All libraries will be scanned automatically at the configured interval
-- When `false`: No automatic scans will occur (manual scans still available)
+- When `true`: File watching and polling fallback are active for all libraries
+- When `false`: No automatic file monitoring occurs (manual scans still available)
 
-### System-Wide Scope
+### File Watching System
 
-These settings apply to **all libraries** in the system. Individual users can no longer configure per-user scan settings. This ensures consistent scanning behavior across the entire Bookhoard instance.
+The scan settings control the file watching system which consists of:
+
+1. **Real-time file watching**: Uses fsnotify to detect file changes immediately
+2. **Polling fallback**: If file watching fails or is unavailable, polls folders at the configured interval
+
+The system applies these settings to all configured libraries automatically on startup.
 
 ---
 
@@ -167,16 +172,18 @@ These settings apply to **all libraries** in the system. Individual users can no
 
 ## Migration Notes
 
-This API replaces the previous per-user scan settings system. The following changes were made:
+This API has been updated to use a new polling-based scanning system. The following changes were made:
 
-- **Removed**: Per-user scan settings (previously in users table)
-- **Added**: System-wide scan settings (now in system_settings table)
-- **Changed**: Access control from user-specific to admin-only
-- **Preserved**: Endpoint paths remain the same for backward compatibility
+- **Changed**: `scan_frequency_minutes` renamed to `scan_poll_interval_seconds`
+- **Changed**: Unit changed from minutes to seconds (15-1440 minutes → 1-3600 seconds)
+- **Removed**: Old scheduler-based scanning system
+- **Added**: Real-time file watching with polling fallback
+- **Preserved**: API endpoint paths remain the same
 
-The migration ensures that:
+The new system ensures that:
 
-1. All libraries scan at the same frequency
-2. Only administrators can modify scan settings
-3. The API endpoints remain unchanged for existing clients
-4. The scheduler uses system-wide settings instead of user-specific settings
+1. File changes are detected in real-time when possible (via fsnotify)
+2. Polling fallback catches missed events at the configured interval
+3. Settings apply to all libraries system-wide
+4. Only administrators can modify scan settings
+5. The `auto_scan_enabled` setting controls both file watching and polling