feat(docs): update markdown formatting to work well with mkdocs

docs/README.md

@@ -52,12 +52,23 @@ wrangler pages deploy site --project-name=readur-docs
 
 ## Structure
 
-- `docs/` - Documentation source files (Markdown)
+- `docs/`  
-- `mkdocs.yml` - MkDocs configuration
+  Documentation source files (Markdown)
-- `requirements.txt` - Python dependencies
+  
-- `overrides/` - Theme customizations
+- `mkdocs.yml`  
-- `stylesheets/` - Custom CSS
+  MkDocs configuration
-- `javascripts/` - Custom JavaScript
+  
+- `requirements.txt`  
+  Python dependencies
+  
+- `overrides/`  
+  Theme customizations
+  
+- `stylesheets/`  
+  Custom CSS
+  
+- `javascripts/`  
+  Custom JavaScript
 
 ## Writing Documentation
 
@@ -71,11 +82,20 @@ wrangler pages deploy site --project-name=readur-docs
 
 We use several markdown extensions for enhanced functionality:
 
-- **Admonitions** - For notes, warnings, tips
+- **Admonitions**  
-- **Code blocks** - With syntax highlighting
+  For notes, warnings, tips
-- **Tabs** - For grouped content
+  
-- **Tables** - For structured data
+- **Code blocks**  
-- **Emoji** - For visual elements
+  With syntax highlighting
+  
+- **Tabs**  
+  For grouped content
+  
+- **Tables**  
+  For structured data
+  
+- **Emoji**  
+  For visual elements
 
 Example:
 ```markdown

docs/advanced-search.md

@@ -244,8 +244,9 @@ accessed:last-week            # Accessed in the last week
 ### Size Filters
 
 **Size Categories**:
+
 - **Small**: < 1MB
-- **Medium**: 1MB - 10MB  
+- **Medium**: 1MB - 10MB
 - **Large**: 10MB - 50MB
 - **Very Large**: > 50MB
 

docs/analytics-dashboard-guide.md

@@ -12,87 +12,184 @@ Access the Analytics Dashboard through:
 ## Document Statistics
 
 ### Processing Metrics
-- **Total Documents** - Complete count of all documents in the system
+
-- **OCR Success Rate** - Percentage of successful text extractions
+- **Total Documents**  
-- **Processing Speed** - Average documents processed per hour/day
+  Complete count of all documents in the system
-- **Storage Usage** - Total disk space used by documents and metadata
+  
+- **OCR Success Rate**  
+  Percentage of successful text extractions
+  
+- **Processing Speed**  
+  Average documents processed per hour/day
+  
+- **Storage Usage**  
+  Total disk space used by documents and metadata
 
 ### Document Types
-- **File Format Breakdown** - Distribution of PDF, images, Office docs
+
-- **Source Distribution** - Documents by upload method (manual, WebDAV, S3, local)
+- **File Format Breakdown**  
-- **Size Distribution** - Document size ranges and storage impact
+  Distribution of PDF, images, Office docs
-- **Language Detection** - OCR language distribution statistics
+  
+- **Source Distribution**  
+  Documents by upload method (manual, WebDAV, S3, local)
+  
+- **Size Distribution**  
+  Document size ranges and storage impact
+  
+- **Language Detection**  
+  OCR language distribution statistics
 
 ## Processing Status Overview
 
 ### Real-time Status
-- **Queue Length** - Current documents awaiting processing
+
-- **Active Jobs** - Documents currently being processed
+- **Queue Length**  
-- **Recent Completions** - Recently finished processing jobs
+  Current documents awaiting processing
-- **Error Count** - Failed processing attempts requiring attention
+  
+- **Active Jobs**  
+  Documents currently being processed
+  
+- **Recent Completions**  
+  Recently finished processing jobs
+  
+- **Error Count**  
+  Failed processing attempts requiring attention
 
 ### Processing History
-- **Hourly Trends** - Processing volume over time
+
-- **Daily Patterns** - Peak usage times and quiet periods
+- **Hourly Trends**  
-- **Success Rates** - Historical OCR and processing reliability
+  Processing volume over time
-- **Performance Metrics** - Processing speed improvements over time
+  
+- **Daily Patterns**  
+  Peak usage times and quiet periods
+  
+- **Success Rates**  
+  Historical OCR and processing reliability
+  
+- **Performance Metrics**  
+  Processing speed improvements over time
 
 ## User Activity Analytics
 
 ### Usage Patterns
-- **Active Users** - Daily/weekly/monthly active user counts
+
-- **Upload Activity** - Document upload frequency by user
+- **Active Users**  
-- **Search Activity** - Most common search terms and patterns
+  Daily/weekly/monthly active user counts
-- **Feature Usage** - Which features are used most frequently
+  
+- **Upload Activity**  
+  Document upload frequency by user
+  
+- **Search Activity**  
+  Most common search terms and patterns
+  
+- **Feature Usage**  
+  Which features are used most frequently
 
 ### Access Patterns
-- **Login Statistics** - User authentication frequency
+
-- **Session Duration** - Average time spent in the application
+- **Login Statistics**  
-- **Popular Documents** - Most accessed and searched documents
+  User authentication frequency
-- **Peak Hours** - Busiest times for system usage
+  
+- **Session Duration**  
+  Average time spent in the application
+  
+- **Popular Documents**  
+  Most accessed and searched documents
+  
+- **Peak Hours**  
+  Busiest times for system usage
 
 ## Source Performance
 
 ### Sync Statistics
-- **Source Health** - Status of all configured data sources
+
-- **Sync Frequency** - How often sources are synchronized
+- **Source Health**  
-- **Discovery Rate** - New documents found per sync cycle
+  Status of all configured data sources
-- **Error Rates** - Failed sync attempts by source type
+  
+- **Sync Frequency**  
+  How often sources are synchronized
+  
+- **Discovery Rate**  
+  New documents found per sync cycle
+  
+- **Error Rates**  
+  Failed sync attempts by source type
 
 ### Source Comparison
-- **Volume by Source** - Document counts from each source
+
-- **Performance Metrics** - Sync speed and reliability comparison
+- **Volume by Source**  
-- **Storage Usage** - Disk usage by source type
+  Document counts from each source
-- **Processing Success** - OCR success rates by source
+  
+- **Performance Metrics**  
+  Sync speed and reliability comparison
+  
+- **Storage Usage**  
+  Disk usage by source type
+  
+- **Processing Success**  
+  OCR success rates by source
 
 ## System Performance
 
 ### Resource Utilization
-- **CPU Usage** - System load over time
+
-- **Memory Usage** - RAM consumption patterns
+- **CPU Usage**  
-- **Disk I/O** - Storage read/write activity
+  System load over time
-- **Network Usage** - Bandwidth utilization for remote sources
+  
+- **Memory Usage**  
+  RAM consumption patterns
+  
+- **Disk I/O**  
+  Storage read/write activity
+  
+- **Network Usage**  
+  Bandwidth utilization for remote sources
 
 ### Health Indicators
-- **Uptime Statistics** - System availability metrics
+
-- **Response Times** - API and web interface performance
+- **Uptime Statistics**  
-- **Error Rates** - System error frequency and types
+  System availability metrics
-- **Queue Health** - Background job processing efficiency
+  
+- **Response Times**  
+  API and web interface performance
+  
+- **Error Rates**  
+  System error frequency and types
+  
+- **Queue Health**  
+  Background job processing efficiency
 
 ## Custom Reports
 
 ### Report Builder
+
 Create custom analytics reports with:
-- **Date Range Selection** - Custom time periods for analysis
+
-- **Metric Selection** - Choose specific statistics to include
+- **Date Range Selection**  
-- **Filtering Options** - Filter by user, source, document type
+  Custom time periods for analysis
-- **Export Formats** - Download as PDF, Excel, or CSV
+  
+- **Metric Selection**  
+  Choose specific statistics to include
+  
+- **Filtering Options**  
+  Filter by user, source, document type
+  
+- **Export Formats**  
+  Download as PDF, Excel, or CSV
 
 ### Scheduled Reports
-- **Daily Summaries** - Automated daily statistics via email
+
-- **Weekly Reports** - Comprehensive weekly performance reports
+- **Daily Summaries**  
-- **Monthly Analytics** - Detailed monthly usage and health reports
+  Automated daily statistics via email
-- **Custom Schedules** - Configure custom report frequencies
+  
+- **Weekly Reports**  
+  Comprehensive weekly performance reports
+  
+- **Monthly Analytics**  
+  Detailed monthly usage and health reports
+  
+- **Custom Schedules**  
+  Configure custom report frequencies
 
 ## Data Export
 

docs/dev/README.md

@@ -45,7 +45,14 @@ Please read our [Development Guide](development.md) for:
 
 ## 🏷️ Document Categories
 
-- **📘 User Docs**: Installation, configuration, user guide
+- **📘 User Docs**  
-- **🔧 Operations**: Deployment, monitoring, troubleshooting  
+  Installation, configuration, user guide
-- **💻 Developer**: Architecture, development setup, testing
+  
-- **🔌 Integration**: API reference, webhooks, extensions
+- **🔧 Operations**  
+  Deployment, monitoring, troubleshooting
+  
+- **💻 Developer**  
+  Architecture, development setup, testing
+  
+- **🔌 Integration**  
+  API reference, webhooks, extensions

docs/file-upload-guide.md

@@ -4,10 +4,17 @@ Readur provides an intuitive drag-and-drop file upload system that supports mult
 
 ## Supported File Types
 
-- **PDF Files** (.pdf) - Direct text extraction and OCR for scanned PDFs
+- **PDF Files** (.pdf)  
-- **Images** (.png, .jpg, .jpeg, .tiff, .bmp, .webp) - Full OCR text extraction
+  Direct text extraction and OCR for scanned PDFs
-- **Text Files** (.txt, .rtf) - Direct text import
+  
-- **Office Documents** (.docx, .doc, .xlsx, .xls, .pptx, .ppt) - Text extraction and OCR
+- **Images** (.png, .jpg, .jpeg, .tiff, .bmp, .webp)  
+  Full OCR text extraction
+  
+- **Text Files** (.txt, .rtf)  
+  Direct text import
+  
+- **Office Documents** (.docx, .doc, .xlsx, .xls, .pptx, .ppt)  
+  Text extraction and OCR
 
 ## Upload Methods
 
@@ -57,10 +64,17 @@ This enhancement ensures files are correctly identified even when extensions are
 
 ## Best Practices
 
-- **File Size**: Keep individual files under 50MB for optimal performance
+- **File Size**  
-- **File Names**: Use descriptive names for better organization
+  Keep individual files under 50MB for optimal performance
-- **Batch Size**: Upload 10-20 files at once for best performance
+  
-- **Network**: Stable internet connection recommended for large uploads
+- **File Names**  
+  Use descriptive names for better organization
+  
+- **Batch Size**  
+  Upload 10-20 files at once for best performance
+  
+- **Network**  
+  Stable internet connection recommended for large uploads
 
 ## Troubleshooting
 

docs/health-monitoring-guide.md

@@ -41,28 +41,56 @@ Access health information through:
 ## System Health Metrics
 
 ### Performance Indicators
-- **CPU Usage** - System load monitoring
+
-- **Memory Usage** - RAM utilization tracking
+- **CPU Usage**  
-- **Disk Space** - Storage capacity alerts
+  System load monitoring
-- **Queue Length** - Processing backlog size
+  
+- **Memory Usage**  
+  RAM utilization tracking
+  
+- **Disk Space**  
+  Storage capacity alerts
+  
+- **Queue Length**  
+  Processing backlog size
 
 ### Processing Health
-- **OCR Success Rate** - Text extraction reliability
+
-- **Processing Speed** - Documents per minute
+- **OCR Success Rate**  
-- **Error Rates** - Failed operation tracking
+  Text extraction reliability
-- **Retry Attempts** - Automatic recovery metrics
+  
+- **Processing Speed**  
+  Documents per minute
+  
+- **Error Rates**  
+  Failed operation tracking
+  
+- **Retry Attempts**  
+  Automatic recovery metrics
 
 ## Alert Configuration
 
 ### Alert Types
-- **Critical** - System failures requiring immediate attention
+
-- **Warning** - Performance degradation or resource limits
+- **Critical**  
-- **Info** - Status updates and maintenance notifications
+  System failures requiring immediate attention
+  
+- **Warning**  
+  Performance degradation or resource limits
+  
+- **Info**  
+  Status updates and maintenance notifications
 
 ### Notification Methods
-- **In-App Notifications** - Real-time dashboard alerts
+
-- **Email Alerts** - Configurable email notifications
+- **In-App Notifications**  
-- **Webhook Integration** - External system notifications
+  Real-time dashboard alerts
+  
+- **Email Alerts**  
+  Configurable email notifications
+  
+- **Webhook Integration**  
+  External system notifications
 
 ## Health Check Endpoints
 
@@ -98,15 +126,29 @@ GET /api/health/sources/{source_id}
 ## Troubleshooting
 
 ### Common Issues
-- **Source Disconnected** - Check network connectivity and credentials
+
-- **High Queue Length** - Scale processing resources or optimize OCR
+- **Source Disconnected**  
-- **Memory Warnings** - Review document processing batch sizes
+  Check network connectivity and credentials
-- **Disk Space Low** - Clean up temporary files or expand storage
+  
+- **High Queue Length**  
+  Scale processing resources or optimize OCR
+  
+- **Memory Warnings**  
+  Review document processing batch sizes
+  
+- **Disk Space Low**  
+  Clean up temporary files or expand storage
 
 ### Recovery Actions
-- **Automatic Retry** - Failed operations retry with exponential backoff
+
-- **Graceful Degradation** - System continues operating with reduced functionality
+- **Automatic Retry**  
-- **Manual Intervention** - Admin tools for resolving complex issues
+  Failed operations retry with exponential backoff
+  
+- **Graceful Degradation**  
+  System continues operating with reduced functionality
+  
+- **Manual Intervention**  
+  Admin tools for resolving complex issues
 
 ## Configuration
 

docs/index.md

@@ -111,15 +111,29 @@ graph LR
 ## Getting Help
 
 ### Documentation
-- [User Guide](user-guide.md) - Complete feature documentation
+
-- [Configuration Reference](configuration-reference.md) - All environment variables
+- [User Guide](user-guide.md)  
-- [Troubleshooting](s3-troubleshooting.md) - Common issues and solutions
+  Complete feature documentation
-- [Migration Guide](migration-guide.md) - Upgrade and migration procedures
+  
+- [Configuration Reference](configuration-reference.md)  
+  All environment variables
+  
+- [Troubleshooting](s3-troubleshooting.md)  
+  Common issues and solutions
+  
+- [Migration Guide](migration-guide.md)  
+  Upgrade and migration procedures
 
 ### Community & Support
-- [GitHub Issues](https://github.com/readur/readur/issues) - Bug reports and feature requests
+
-- [GitHub Discussions](https://github.com/readur/readur/discussions) - Community help
+- [GitHub Issues](https://github.com/readur/readur/issues)  
-- [Developer Documentation](dev/) - Architecture and development setup
+  Bug reports and feature requests
+  
+- [GitHub Discussions](https://github.com/readur/readur/discussions)  
+  Community help
+  
+- [Developer Documentation](dev/)  
+  Architecture and development setup
 
 ## Latest Updates
 

docs/notifications-guide.md

@@ -5,36 +5,76 @@ Readur provides comprehensive real-time notifications to keep you informed about
 ## Notification Types
 
 ### Document Processing
-- **OCR Completion** - Text extraction finished for uploaded documents
+
-- **Processing Errors** - Failed OCR or document processing alerts
+- **OCR Completion**  
-- **Batch Processing** - Status updates for multiple document uploads
+  Text extraction finished for uploaded documents
-- **Quality Warnings** - Low-quality OCR results requiring attention
+  
+- **Processing Errors**  
+  Failed OCR or document processing alerts
+  
+- **Batch Processing**  
+  Status updates for multiple document uploads
+  
+- **Quality Warnings**  
+  Low-quality OCR results requiring attention
 
 ### Sync Events
-- **Source Sync Complete** - WebDAV, S3, or local folder synchronization finished
+
-- **New Documents Found** - Fresh documents discovered during sync
+- **Source Sync Complete**  
-- **Sync Errors** - Connection issues or permission problems
+  WebDAV, S3, or local folder synchronization finished
-- **Conflict Resolution** - File conflicts requiring user intervention
+  
+- **New Documents Found**  
+  Fresh documents discovered during sync
+  
+- **Sync Errors**  
+  Connection issues or permission problems
+  
+- **Conflict Resolution**  
+  File conflicts requiring user intervention
 
 ### System Status
-- **Health Alerts** - System performance warnings or failures
+
-- **Maintenance Windows** - Scheduled maintenance notifications
+- **Health Alerts**  
-- **Security Events** - Login attempts, permission changes
+  System performance warnings or failures
-- **Storage Warnings** - Disk space or quota limitations
+  
+- **Maintenance Windows**  
+  Scheduled maintenance notifications
+  
+- **Security Events**  
+  Login attempts, permission changes
+  
+- **Storage Warnings**  
+  Disk space or quota limitations
 
 ## Notification Delivery
 
 ### In-App Notifications
-- **Real-time Badge** - Notification counter in the top navigation
+
-- **Notification Panel** - Expandable list of recent alerts
+- **Real-time Badge**  
-- **Toast Messages** - Immediate pop-up notifications for urgent items
+  Notification counter in the top navigation
-- **Dashboard Widgets** - Status cards showing notification summaries
+  
+- **Notification Panel**  
+  Expandable list of recent alerts
+  
+- **Toast Messages**  
+  Immediate pop-up notifications for urgent items
+  
+- **Dashboard Widgets**  
+  Status cards showing notification summaries
 
 ### Email Notifications
-- **Immediate Alerts** - Critical system or processing failures
+
-- **Daily Digest** - Summary of processing activity and status
+- **Immediate Alerts**  
-- **Weekly Reports** - System health and usage statistics
+  Critical system or processing failures
-- **Custom Triggers** - User-configured alert conditions
+  
+- **Daily Digest**  
+  Summary of processing activity and status
+  
+- **Weekly Reports**  
+  System health and usage statistics
+  
+- **Custom Triggers**  
+  User-configured alert conditions
 
 ## Notification Settings
 
@@ -45,16 +85,32 @@ Access notification settings through:
 3. Configure your preferences for each notification type
 
 ### Notification Categories
-- **Critical** - System failures, security alerts (always enabled)
+
-- **Important** - Processing errors, sync failures
+- **Critical**  
-- **Informational** - Completion notifications, status updates
+  System failures, security alerts (always enabled)
-- **Promotional** - Feature updates, tips (can be disabled)
+  
+- **Important**  
+  Processing errors, sync failures
+  
+- **Informational**  
+  Completion notifications, status updates
+  
+- **Promotional**  
+  Feature updates, tips (can be disabled)
 
 ### Delivery Preferences
-- **In-App Only** - Notifications appear only within Readur
+
-- **Email + In-App** - Notifications sent to both locations
+- **In-App Only**  
-- **Email Only** - Notifications sent only via email
+  Notifications appear only within Readur
-- **Disabled** - No notifications for this category
+  
+- **Email + In-App**  
+  Notifications sent to both locations
+  
+- **Email Only**  
+  Notifications sent only via email
+  
+- **Disabled**  
+  No notifications for this category
 
 ## Advanced Configuration
 
@@ -119,15 +175,29 @@ Send notifications to external systems:
 ## Managing Notifications
 
 ### Notification History
-- **View All** - Complete history of notifications
+
-- **Filter by Type** - Show only specific notification categories
+- **View All**  
-- **Search** - Find notifications by content or date
+  Complete history of notifications
-- **Archive** - Mark notifications as read or hide them
+  
+- **Filter by Type**  
+  Show only specific notification categories
+  
+- **Search**  
+  Find notifications by content or date
+  
+- **Archive**  
+  Mark notifications as read or hide them
 
 ### Bulk Actions
-- **Mark All Read** - Clear all unread notification badges
+
-- **Delete Old** - Remove notifications older than specified date
+- **Mark All Read**  
-- **Export** - Download notification history as CSV or JSON
+  Clear all unread notification badges
+  
+- **Delete Old**  
+  Remove notifications older than specified date
+  
+- **Export**  
+  Download notification history as CSV or JSON
 
 ## Troubleshooting
 

docs/sources-guide.md

@@ -422,11 +422,20 @@ ws.onmessage = (event) => {
 
 Sources are continuously monitored and assigned health scores (0-100):
 
-- **90-100**: ✅ Excellent - No issues detected
+- **90-100**: ✅ Excellent  
-- **75-89**: ⚠️ Good - Minor issues or warnings
+  No issues detected
-- **50-74**: ⚠️ Fair - Moderate issues requiring attention
+  
-- **25-49**: ❌ Poor - Significant problems
+- **75-89**: ⚠️ Good  
-- **0-24**: ❌ Critical - Severe issues, manual intervention required
+  Minor issues or warnings
+  
+- **50-74**: ⚠️ Fair  
+  Moderate issues requiring attention
+  
+- **25-49**: ❌ Poor  
+  Significant problems
+  
+- **0-24**: ❌ Critical  
+  Severe issues, manual intervention required
 
 ### Health Checks
 

docs/swagger-ui-guide.md

@@ -12,48 +12,104 @@ Readur includes built-in Swagger UI for interactive API documentation and testin
 ## API Documentation Features
 
 ### Endpoint Explorer
-- **Complete API Reference** - All REST endpoints with detailed descriptions
+
-- **Request/Response Examples** - Sample data for every endpoint
+- **Complete API Reference**  
-- **Parameter Details** - Required and optional parameters with types
+  All REST endpoints with detailed descriptions
-- **Authentication Info** - JWT token requirements and usage
+  
+- **Request/Response Examples**  
+  Sample data for every endpoint
+  
+- **Parameter Details**  
+  Required and optional parameters with types
+  
+- **Authentication Info**  
+  JWT token requirements and usage
 
 ### Interactive Testing
-- **Try It Out** - Execute API calls directly from the documentation
+
-- **Real Data** - Test with your actual Readur data and configuration
+- **Try It Out**  
-- **Response Validation** - See actual responses and status codes
+  Execute API calls directly from the documentation
-- **Error Handling** - View error responses and troubleshooting info
+  
+- **Real Data**  
+  Test with your actual Readur data and configuration
+  
+- **Response Validation**  
+  See actual responses and status codes
+  
+- **Error Handling**  
+  View error responses and troubleshooting info
 
 ## API Categories
 
 ### Authentication
-- **Login/Logout** - User authentication endpoints
+
-- **Token Management** - JWT token refresh and validation
+- **Login/Logout**  
-- **User Registration** - New user account creation
+  User authentication endpoints
-- **Password Reset** - Password recovery workflows
+  
+- **Token Management**  
+  JWT token refresh and validation
+  
+- **User Registration**  
+  New user account creation
+  
+- **Password Reset**  
+  Password recovery workflows
 
 ### Document Management
-- **Upload Documents** - Single and batch file upload endpoints
+
-- **Document Retrieval** - Get document metadata and content
+- **Upload Documents**  
-- **Document Search** - Full-text search with various modes
+  Single and batch file upload endpoints
-- **Document Operations** - Update, delete, and organize documents
+  
+- **Document Retrieval**  
+  Get document metadata and content
+  
+- **Document Search**  
+  Full-text search with various modes
+  
+- **Document Operations**  
+  Update, delete, and organize documents
 
 ### User Management
-- **User CRUD** - Create, read, update, delete user accounts
+
-- **Role Management** - Assign and modify user roles
+- **User CRUD**  
-- **Permission Control** - Manage access rights and restrictions
+  Create, read, update, delete user accounts
-- **User Preferences** - Personal settings and configurations
+  
+- **Role Management**  
+  Assign and modify user roles
+  
+- **Permission Control**  
+  Manage access rights and restrictions
+  
+- **User Preferences**  
+  Personal settings and configurations
 
 ### Source Management
-- **Source Configuration** - WebDAV, S3, and local folder setup
+
-- **Sync Operations** - Manual and automated synchronization
+- **Source Configuration**  
-- **Source Health** - Status monitoring and health checks
+  WebDAV, S3, and local folder setup
-- **Source Statistics** - Usage metrics and performance data
+  
+- **Sync Operations**  
+  Manual and automated synchronization
+  
+- **Source Health**  
+  Status monitoring and health checks
+  
+- **Source Statistics**  
+  Usage metrics and performance data
 
 ### System Administration
-- **Health Monitoring** - System status and performance metrics
+
-- **Analytics Data** - Usage statistics and reporting endpoints
+- **Health Monitoring**  
-- **Configuration** - System settings and environment variables
+  System status and performance metrics
-- **Maintenance** - Backup, cleanup, and administrative tasks
+  
+- **Analytics Data**  
+  Usage statistics and reporting endpoints
+  
+- **Configuration**  
+  System settings and environment variables
+  
+- **Maintenance**  
+  Backup, cleanup, and administrative tasks
 
 ## Authentication in Swagger UI
 
@@ -65,58 +121,122 @@ Readur includes built-in Swagger UI for interactive API documentation and testin
 5. **Test Endpoints** - All authenticated endpoints now work with your credentials
 
 ### Token Management
-- **Token Expiry** - Tokens expire after a configured time period
+
-- **Refresh Tokens** - Use refresh token endpoint to get new access tokens
+- **Token Expiry**  
-- **Logout** - Invalidate tokens using the logout endpoint
+  Tokens expire after a configured time period
-- **Multiple Sessions** - Each browser session needs its own token
+  
+- **Refresh Tokens**  
+  Use refresh token endpoint to get new access tokens
+  
+- **Logout**  
+  Invalidate tokens using the logout endpoint
+  
+- **Multiple Sessions**  
+  Each browser session needs its own token
 
 ## Best Practices
 
 ### Development Usage
-- **Test First** - Use Swagger UI to test API endpoints before implementing
+
-- **Validate Responses** - Check response formats match your expectations
+- **Test First**  
-- **Error Scenarios** - Test error conditions and edge cases
+  Use Swagger UI to test API endpoints before implementing
-- **Performance Testing** - Monitor response times for optimization
+  
+- **Validate Responses**  
+  Check response formats match your expectations
+  
+- **Error Scenarios**  
+  Test error conditions and edge cases
+  
+- **Performance Testing**  
+  Monitor response times for optimization
 
 ### Production Considerations
-- **Access Control** - Swagger UI respects the same authentication as the main app
+
-- **Rate Limiting** - API rate limits apply to Swagger UI requests
+- **Access Control**  
-- **Logging** - All API calls from Swagger UI are logged normally
+  Swagger UI respects the same authentication as the main app
-- **Security** - Use HTTPS in production for secure token transmission
+  
+- **Rate Limiting**  
+  API rate limits apply to Swagger UI requests
+  
+- **Logging**  
+  All API calls from Swagger UI are logged normally
+  
+- **Security**  
+  Use HTTPS in production for secure token transmission
 
 ## Common Use Cases
 
 ### Frontend Development
-- **API Integration** - Test endpoints before implementing in your frontend
+
-- **Data Formats** - Understand expected request/response formats
+- **API Integration**  
-- **Error Handling** - Learn about error codes and messages
+  Test endpoints before implementing in your frontend
-- **Feature Testing** - Validate new features work as expected
+  
+- **Data Formats**  
+  Understand expected request/response formats
+  
+- **Error Handling**  
+  Learn about error codes and messages
+  
+- **Feature Testing**  
+  Validate new features work as expected
 
 ### System Integration
-- **Third-party Tools** - Test integration with external systems
+
-- **Automation Scripts** - Develop scripts using API documentation
+- **Third-party Tools**  
-- **Monitoring Systems** - Integrate health check endpoints
+  Test integration with external systems
-- **Data Migration** - Use bulk operations for data import/export
+  
+- **Automation Scripts**  
+  Develop scripts using API documentation
+  
+- **Monitoring Systems**  
+  Integrate health check endpoints
+  
+- **Data Migration**  
+  Use bulk operations for data import/export
 
 ### Troubleshooting
-- **Debug Issues** - Test API calls to isolate problems
+
-- **Validate Permissions** - Check if user roles have correct access
+- **Debug Issues**  
-- **Network Testing** - Verify connectivity and response times
+  Test API calls to isolate problems
-- **Data Verification** - Confirm data integrity and processing status
+  
+- **Validate Permissions**  
+  Check if user roles have correct access
+  
+- **Network Testing**  
+  Verify connectivity and response times
+  
+- **Data Verification**  
+  Confirm data integrity and processing status
 
 ## Advanced Features
 
 ### Custom Headers
-- **Request Customization** - Add custom headers to API requests
+
-- **Content-Type** - Specify different content types for uploads
+- **Request Customization**  
-- **User-Agent** - Set custom user agent strings
+  Add custom headers to API requests
-- **Cache Control** - Control caching behavior for responses
+  
+- **Content-Type**  
+  Specify different content types for uploads
+  
+- **User-Agent**  
+  Set custom user agent strings
+  
+- **Cache Control**  
+  Control caching behavior for responses
 
 ### Bulk Operations
-- **Batch Uploads** - Test multiple file uploads simultaneously
+
-- **Bulk Updates** - Update multiple documents or users at once
+- **Batch Uploads**  
-- **Mass Operations** - Perform administrative tasks in bulk
+  Test multiple file uploads simultaneously
-- **Data Export** - Export large datasets via API
+  
+- **Bulk Updates**  
+  Update multiple documents or users at once
+  
+- **Mass Operations**  
+  Perform administrative tasks in bulk
+  
+- **Data Export**  
+  Export large datasets via API
 
 ## Configuration Options
 
@@ -138,7 +258,14 @@ SWAGGER_RATE_LIMIT=1000
 
 ## Security Considerations
 
-- **Authentication Required** - Swagger UI requires the same login as the main application
+- **Authentication Required**  
-- **Role-Based Access** - API endpoints respect user role permissions
+  Swagger UI requires the same login as the main application
-- **Audit Logging** - All API calls are logged for security monitoring
+  
-- **Token Security** - JWT tokens should be kept secure and not shared
+- **Role-Based Access**  
+  API endpoints respect user role permissions
+  
+- **Audit Logging**  
+  All API calls are logged for security monitoring
+  
+- **Token Security**  
+  JWT tokens should be kept secure and not shared

docs/user-guide.md

@@ -392,20 +392,46 @@ Readur supports both local and OIDC users in the same installation:
 ## Next Steps
 
 ### Explore Advanced Features
-- [🔗 Sources Guide](sources-guide.md) - Set up WebDAV, Local Folder, and S3 synchronization
+
-- [🔎 Advanced Search](advanced-search.md) - Master search modes, syntax, and optimization
+- [🔗 Sources Guide](sources-guide.md)  
-- [🏷️ Labels & Organization](labels-and-organization.md) - Implement effective document organization
+  Set up WebDAV, Local Folder, and S3 synchronization
-- [👥 User Management](user-management-guide.md) - Configure authentication and user administration
+  
-- [🔐 OIDC Setup](oidc-setup.md) - Integrate with enterprise identity providers
+- [🔎 Advanced Search](advanced-search.md)  
+  Master search modes, syntax, and optimization
+  
+- [🏷️ Labels & Organization](labels-and-organization.md)  
+  Implement effective document organization
+  
+- [👥 User Management](user-management-guide.md)  
+  Configure authentication and user administration
+  
+- [🔐 OIDC Setup](oidc-setup.md)  
+  Integrate with enterprise identity providers
 
 ### System Administration
-- [📦 Installation Guide](installation.md) - Full installation and setup instructions
+
-- [🔧 Configuration](configuration.md) - Environment variables and advanced configuration
+- [📦 Installation Guide](installation.md)  
-- [🚀 Deployment Guide](deployment.md) - Production deployment with SSL and monitoring
+  Full installation and setup instructions
-- [📁 Watch Folder Guide](WATCH_FOLDER.md) - Legacy folder watching setup
+  
+- [🔧 Configuration](configuration.md)  
+  Environment variables and advanced configuration
+  
+- [🚀 Deployment Guide](deployment.md)  
+  Production deployment with SSL and monitoring
+  
+- [📁 Watch Folder Guide](WATCH_FOLDER.md)  
+  Legacy folder watching setup
 
 ### Development and Integration
-- [🔌 API Reference](api-reference.md) - REST API for automation and integration
+
-- [🏗️ Developer Documentation](dev/) - Architecture and development setup
+- [🔌 API Reference](api-reference.md)  
-- [🔍 OCR Optimization](dev/OCR_OPTIMIZATION_GUIDE.md) - Improve OCR performance
+  REST API for automation and integration
-- [📊 Queue Architecture](dev/QUEUE_IMPROVEMENTS.md) - Background processing optimization
+  
+- [🏗️ Developer Documentation](dev/)  
+  Architecture and development setup
+  
+- [🔍 OCR Optimization](dev/OCR_OPTIMIZATION_GUIDE.md)  
+  Improve OCR performance
+  
+- [📊 Queue Architecture](dev/QUEUE_IMPROVEMENTS.md)  
+  Background processing optimization