diff --git a/docs/devices/KOREADER_SETUP.md b/docs/devices/KOREADER_SETUP.md
index 3c86d2e..23902b0 100644
--- a/docs/devices/KOREADER_SETUP.md
+++ b/docs/devices/KOREADER_SETUP.md
@@ -1,553 +1,295 @@
-# KOReader Wireless Sync Setup Guide
+# KOReader Device Setup Guide
 
-## Overview
+This guide will help you set up KOReader on your e-reader device to sync with Bookmann.
 
-This guide will walk you through setting up KOReader to sync wirelessly with your Bookmann server.
+## What is KOReader?
 
----
+KOReader is an open-source e-reader application that supports a wide range of e-reader devices including:
+- Kindle devices (Paperwhite, Oasis, Voyage, etc.)
+- Kobo devices (Clara, Aura, Nia, etc.)
+- PocketBook devices
+- Android tablets and phones
 
 ## Prerequisites
 
-- ✅ KOReader installed on your device (Kindle, Kobo, PocketBook, Android, etc.)
-- ✅ Bookmann server running and accessible
-- ✅ Wi-Fi connection (device and server on same network, or server accessible via internet)
-- ✅ Device registered in Bookmann (see [User Guide](../SYNC_USER_GUIDE.md#device-registration))
+Before you begin, make sure you have:
+- ✅ A Bookmann instance running and accessible on your network
+- ✅ Your Bookmann credentials (username and password)
+- ✅ A KOReader-compatible e-reader device
+- ✅ Your device connected to the same Wi-Fi network as your Bookmann instance
 
----
+## Installation
 
-## Quick Setup (5 Minutes)
+### Kindle Devices
 
-### Step 1: Get Device Credentials
+1. **Install KOReader**
+   - Download the latest KOReader release from [koreader.rocks](https://koreader.rocks/)
+   - Extract the `koreader` folder to your Kindle's root directory
+   - Safely eject your Kindle from your computer
 
-1. In Bookmann web interface, go to **Settings → Devices**
-2. Find or register your KOReader device
-3. Copy the **Sync URL**:
+2. **Launch KOReader**
+   - On your Kindle, go to Home → Settings → Device Options → Personalize Your Kindle
+   - Select `koreader` from the launcher options
+   - Alternatively, you can use the `linkjail` method to access KOReader directly
+
+3. **Enable Wi-Fi**
+   - In KOReader, tap the network icon in the top menu
+   - Connect to your Wi-Fi network
+
+### Kobo Devices
+
+1. **Install KOReader**
+   - Download the latest KOReader Kobo package from [koreader.rocks](https://koreader.rocks/)
+   - Copy the `koreader` folder to your Kobo's `.adds/` directory
+   - Safely eject your Kobo from your computer
+
+2. **Launch KOReader**
+   - Eject and disconnect your Kobo
+   - Kobo will restart and you'll see KOReader as an option
+   - Alternatively, create a shortcut on your home screen
+
+3. **Enable Wi-Fi**
+   - In KOReader, tap the network icon
+   - Connect to your Wi-Fi network
+
+### PocketBook Devices
+
+1. **Install KOReader**
+   - Download the PocketBook version from [koreader.rocks](https://koreader.rocks/)
+   - Copy to your device and install via the package manager
+
+2. **Launch KOReader**
+   - Open KOReader from your apps menu
+   - Enable Wi-Fi in the network settings
+
+## Device Registration
+
+### Step 1: Get Your Bookmann Instance URL
+
+Find your Bookmann instance URL. This will typically be one of:
+- **Local Network**: `http://YOUR_COMPUTER_IP:8765`
+- **Localhost (if testing)**: `http://localhost:8765`
+- **Domain (if configured)**: `https://bookmann.yourdomain.com`
+
+### Step 2: Register Your Device in Bookmann
+
+1. Log in to your Bookmann web interface
+2. Navigate to **Device Management** → **Add New Device**
+3. Fill in the device details:
+   - **Device Name**: A friendly name (e.g., "My Kindle Paperwhite")
+   - **Device Type**: Select "KOReader"
+   - **Device Identifier**: Enter your device's hardware ID or serial number
+     - On Kindle: Settings → Device Options → Device Info → Serial Number
+     - On Kobo: Settings → Device Information → Serial Number
+4. Click **Register Device**
+
+You'll receive:
+- An **Auth URL** to approve the device
+- A **Device Token** (automatically generated after approval)
+
+### Step 3: Approve Your Device
+
+1. **Method A: QR Code**
+   - If displayed, scan the QR code with your phone's camera
+   - This will open the approval page in your browser
+   - Log in and click **Approve**
+
+2. **Method B: Manual URL**
+   - Copy the Auth URL from the registration confirmation
+   - Open it in your web browser
+   - Log in to your Bookmann account
+   - Click **Approve Device**
+
+Your device is now registered and ready to sync!
+
+## Configure KOReader Sync
+
+### Step 1: Access KOReader Settings
+
+1. Open KOReader on your device
+2. Tap the menu icon (≡) in the top-left corner
+3. Select **Tools** → **Calibre**
+
+### Step 2: Configure Wireless Connection
+
+1. **Enable Calibre Wireless Connection**: Toggle ON
+2. **Server Address**: Enter your Bookmann instance URL
    ```
-   https://bookmann.example.com/api/sync/koreader
+   http://YOUR_COMPUTER_IP:8765/api/sync/koreader
    ```
-4. Copy the **Auth Token** (if shown)
+   Replace `YOUR_COMPUTER_IP` with your actual IP address
 
-### Step 2: Configure KOReader
+3. **Set Custom Port** (if needed): Keep default or enter `8765`
 
-#### On Your Device
+### Step 3: Configure Authentication
 
-1. Open KOReader
-2. Tap the menu icon (≡)
-3. Navigate to **Tools → More plugins**
-4. Find **Calibre Sync** (or **Wireless Sync**)
-5. Tap to configure
+1. **Authentication Method**: Select "Basic Auth"
+2. **Username**: Your Bookmann email or username
+3. **Password**: Your Bookmann password
 
-#### Enter Server Details
+### Step 4: Configure Sync Settings
 
-```
-Server Type: Calibre (compatible)
-Server URL: https://bookmann.example.com
-Port: 8765 (or leave blank for default)
-Username: (leave blank)
-Password: [Paste your device auth token]
-```
+1. **Auto Sync**: Enable for automatic sync
+2. **Sync Frequency**: Choose from:
+   - Every page turn (recommended for real-time sync)
+   - Every bookmark save
+   - Every highlight
+   - Manual only (sync when you press the sync button)
 
-### Step 3: Test Connection
+3. **What to Sync**: Enable:
+   - ✅ Reading progress
+   - ✅ Bookmarks
+   - ✅ Highlights
+   - ✅ Notes
 
-1. Tap **Test Connection** or **Verify**
-2. Should see: "✓ Connection successful"
-3. Tap **Save**
+### Step 5: Test Connection
 
-### Step 4: Enable Auto-Sync
+1. Tap **Test Connection** in the Calibre settings
+2. You should see a success message if configured correctly
+3. If it fails:
+   - Verify your device is connected to Wi-Fi
+   - Check the server URL is correct
+   - Ensure your Bookmann instance is running
+   - Verify username and password are correct
 
-1. In sync settings, enable **Auto-sync**
-2. Set sync frequency: **Every page turn** (recommended)
-3. Enable **Wireless connection** must be on
-4. Tap **Save**
+## Using Sync Features
 
----
+### Initial Sync
 
-## Detailed Configuration
+When you first enable sync, KOReader will:
+1. Connect to Bookmann
+2. Upload your current reading progress
+3. Download any annotations from the server
+4. Set up bidirectional sync for future changes
 
-### Creating a Custom Sync Profile
+### Reading Progress Sync
 
-For advanced users, you can create a custom sync profile:
+As you read:
+- Progress updates automatically sync based on your sync frequency
+- Page turns, chapter changes, and bookmark saves all trigger sync
+- Sync occurs in the background without interrupting reading
 
-**File Location**: `config/calibre.lua` on your device's SD card
+### Annotations Sync
 
-```lua
-return {
-    -- Bookmann server details
-    calibre_opds = {
-        ["https://bookmann.example.com"] = {
-            protocol = "http",
-            host = "bookmann.example.com",
-            port = 8765,
-        },
-    },
-    
-    -- Sync settings
-    wireless_sync = true,
-    auto_sync = true,
-    sync_frequency = "every_page_turn",
-    
-    -- Authentication
-    username = "",
-        password = "YOUR_DEVICE_TOKEN_HERE",
-    },
-}
-```
+- **Bookmarks**: Sync when created or deleted
+- **Highlights**: Sync when created, edited, or deleted
+- **Notes**: Sync when created, edited, or deleted
+- **Linked Notes**: Notes attached to highlights sync together
 
-### Sync Mode Configuration
+### Manual Sync
 
-**Immediate Mode** (Recommended for daily reading):
-```lua
-sync_mode = "immediate"
-page_turn_sync = true
-```
+To manually trigger a sync:
+1. Open the KOReader menu (≡)
+2. Select **Tools** → **Calibre**
+3. Tap **Sync Now**
 
-**Checkpoint Mode** (Better for battery):
-```lua
-sync_mode = "checkpoint"
-checkpoint_interval = 300 -- 5 minutes
-```
-
----
-
-## Advanced Features
-
-### Custom Sync Intervals
-
-You can configure when KOReader syncs:
-
-| Setting | Description | Battery Impact |
-|---------|-------------|----------------|
-| Every page turn | Instant sync across devices | High |
-| Every 5 minutes | Balance of speed and battery | Medium |
-| Every chapter | Good for long chapters | Low |
-| Manual only | Only when you tap "Sync" | Lowest |
-
-**To Configure**:
-```
-Tools → Wireless Sync → Sync Interval → Select option
-```
-
-### Progress Tracking Options
-
-KOReader can send multiple types of progress data:
-
-**For EPUB files**:
-- ✅ Percentage (0-100%)
-- ✅ EPUB CFI (precise location)
-- ✅ Chapter number
-- ✅ Character offset
-
-**For PDF files**:
-- ✅ Page number
-- ✅ Page position (X, Y coordinates)
-- ✅ Zoom level
-
-**Configure**:
-```
-Settings → Status Bar → Progress Indicator → Select type
-```
-
-### Annotation Sync
-
-**What Syncs**:
-- ✅ Highlights (with colors)
-- ✅ Bookmarks
-- ✅ Notes
-- ✅ Underlines
-- ✅ Column/area selections
-
-**Configure**:
-```
-Reader → Highlight → Store in: Device + Cloud (Bookmann)
-```
-
----
-
-## Troubleshooting
-
-### "Connection Failed" Error
-
-**Causes**:
-1. Server URL incorrect
-2. Network firewall blocking connection
-3. Device token expired
-4. Server not running
-
-**Solutions**:
-
-1. **Verify Server URL**:
-   - Check for typos
-   - Include `https://` prefix
-   - Use correct domain/IP
-
-2. **Test Network**:
-   - Open browser on device
-   - Try accessing: `https://bookmann.example.com/api/sync/koreader/`
-   - Should see JSON response or method not allowed
-
-3. **Check Token**:
-   - Go to Bookmann → Settings → Devices
-   - Verify device is "Sync Enabled"
-   - Regenerate token if needed
-
-4. **Verify Server**:
-   - Check Bookmann server is running
-   - View server logs for errors
-   - Test from web browser
-
-### "Authentication Failed" Error
-
-**Causes**:
-1. Wrong auth token
-2. Device revoked
-3. Token expired
-
-**Solutions**:
-1. Go to Bookmann → Settings → Devices
-2. Find your device
-3. Copy new auth token
-4. Update in KOReader sync settings
-5. Save and retry
-
-### Sync Not Working
-
-**Checklist**:
-- [ ] Wi-Fi is enabled on device
-- [ ] Bookmann server is running
-- [ ] Device is "Sync Enabled" in Bookmann
-- [ ] Auto-sync is enabled in KOReader
-- [ ] Same book exists in both libraries
-- [ ] Network connection is stable
-
-**Steps**:
-1. Open a book in KOReader
-2. Turn a page
-3. Wait 5 seconds
-4. Check Bookmann web interface
-5. Progress should be updated
-
-### Battery Drain
-
-**If battery drains quickly**:
-
-1. **Switch to checkpoint mode**:
-   - Open: `Tools → Wireless Sync`
-   - Set: Sync mode to "Checkpoint"
-   - Set: Interval to 5 minutes
-
-2. **Reduce sync frequency**:
-   - Set: Sync to "Manual only"
-   - Tap sync button when needed
-
-3. **Use 2.4GHz Wi-Fi**:
-   - Uses less power than 5GHz
-   - Better range through walls
-
-### Partial Sync
-
-**If some books sync but others don't**:
-
-1. **Check file paths**:
-   - Bookmann and KOReader must have same file
-   - File names must match exactly
-   - Check library folders are configured
-
-2. **Match by metadata**:
-   - Ensure Title and Author match
-   - Open book details on both sides
-   - Check for typos in metadata
-
-3. **View sync logs**:
-   - KOReader: `Tools → Statistics → Sync log`
-   - Look for "book not found" errors
-   - Note the UUID or file path
-
----
-
-## File Matching
-
-### How KOReader Finds Books
-
-Bookmann matches books in this order:
-
-1. **By UUID** (most reliable)
-2. **By file path**
-3. **By title + author**
-
-### Ensuring Matches
-
-**Best Practices**:
-1. **Use consistent file names**:
-   ```
-   Good: The Great Gatsby.epub
-   Bad: EBOOK_12345.epub
-   ```
-
-2. **Include metadata**:
-   - Title: "The Great Gatsby"
-   - Author: "F. Scott Fitzgerald"
-   - ISBN: 9780743273565 (if available)
-
-3. **Use library folders**:
-   - Organize by author or series
-   - Keep Bookmann and KOReader folders in sync
-
----
-
-## Performance Optimization
-
-### For Faster Sync
-
-**Network**:
-- Use 5GHz Wi-Fi (if close to router)
-- Ensure good signal strength
-- Use wired Ethernet for server
-
-**Device**:
-- Close unused apps
-- Restart device weekly
-- Keep KOReader updated
-
-**Server**:
-- Use SSD for database
-- Ensure adequate bandwidth
-- Monitor queue processing
-
-### For Better Battery
-
-**Settings**:
-```
-Auto-sync: Checkpoint mode
-Sync interval: Every 5 minutes
-Wi-Fi: 2.4GHz only
-Screen refresh: Lower frequency
-```
-
-**Device Habits**:
-- Sleep device when not reading
-- Disable Wi-Fi when reading offline
-- Use airplane mode with Wi-Fi only
-
----
-
-## Security Considerations
-
-### Token Storage
-
-**Where Token is Stored**:
-- File: `/mnt/onboard/addons/calibre.lua` or similar
-- Encrypted: No (plaintext)
-- Accessible: Anyone with device access
-
-**Security Tips**:
-- 🔒 Keep device physically secure
-- 🔒 Don't share auth tokens
-- 🔒 Revoke device if lost/stolen
-- 🔒 Use HTTPS only (never HTTP)
-
-### Network Security
-
-**Public Wi-Fi**:
-- ⚠️ Avoid public Wi-Fi if possible
-- ✅ Use VPN if on public Wi-Fi
-- ✅ Ensure HTTPS (TLS 1.3)
-- ✅ Verify server certificate
-
-### Data Privacy
-
-**What Syncs**:
-- ✅ Reading progress
-- ✅ Highlights and notes
-- ✅ Bookmarks
-
-**What DOESN'T Sync**:
-- ❌ Book content (your books stay on device)
-- ❌ Personal files
-- ❌ System data
-- ❌ Other apps' data
-
----
+The sync status will display:
+- 🟢 **Synced** - All changes uploaded
+- 🟡 **Syncing...** - In progress
+- 🔴 **Failed** - Check your network connection
 
 ## Advanced Configuration
 
-### Custom Timeout Settings
+### Offline Mode
 
-**File**: `config/calibre.lua`
+KOReader automatically handles offline scenarios:
+1. Changes are queued locally when offline
+2. Auto-sync resumes when connected
+3. Queue processes all pending changes in priority order
 
-```lua
-return {
-    timeout = 30,        -- Connection timeout (seconds)
-    read_timeout = 60,   -- Read operation timeout
-    max_retries = 3,      -- Retry failed requests
-    retry_delay = 5,      -- Delay between retries (seconds)
-}
-```
+### Checkpoint Sync
 
-### Batch Sync Configuration
-
-**For processing multiple books**:
-
-```lua
-batch_size = 10,          -- Books per batch
-batch_delay = 1,          -- Delay between batches (seconds)
-concurrent_uploads = 2,    -- Parallel uploads
-```
+For better battery life, use checkpoint mode:
+1. In KOReader Calibre settings
+2. Set **Sync Mode** to "Checkpoint"
+3. Set **Checkpoint Interval** (e.g., every 5 minutes)
+4. Syncs occur in batches instead of every action
 
 ### Debug Mode
 
-**Enable sync logging**:
+Enable debug logging if sync isn't working:
+1. KOReader menu → Tools → Calibre
+2. Enable **Debug Logging**
+3. Sync and check logs at `/mnt/us/koreader/calibre.log`
 
-```lua
-log_level = "DEBUG"
-log_sync = true
-log_file = "/mnt/onboard/sync.log"
-```
+## Troubleshooting
 
-**View logs**:
-```
-Tools → Statistics → Sync log
-Or: Connect via SSH and view log file
-```
+### Connection Refused
+
+**Problem**: "Connection refused" error
+
+**Solutions**:
+- Verify Bookmann is running on your computer
+- Check the server URL and port (8765)
+- Ensure device is on same Wi-Fi network
+- Try using your computer's IP address instead of "localhost"
+
+### Authentication Failed
+
+**Problem**: "Authentication failed" error
+
+**Solutions**:
+- Verify username and password
+- Check your account is active and not locked
+- Try logging in to Bookmann web interface first
+- Reset password if needed
+
+### Sync Not Working
+
+**Problem**: Changes not appearing in Bookmann
+
+**Solutions**:
+- Enable debug logging in KOReader
+- Check Bookmann Device Management page for errors
+- Verify sync is enabled in KOReader settings
+- Try manual sync to trigger immediate update
+- Check Bookmann logs for sync errors
+
+### Conflicts Detected
+
+**Problem**: Sync conflicts when reading on multiple devices
+
+**Solutions**:
+1. Go to Bookmann **Conflicts** page
+2. Review conflicting progress from each device
+3. Choose which device's progress to keep
+4. Set auto-resolution preference for future conflicts
+
+### Large Files Not Syncing
+
+**Problem**: Large annotations or highlights fail to sync
+
+**Solutions**:
+- Check Bookmann sync queue for stuck items
+- Increase sync timeout in KOReader settings
+- Break up large highlights into smaller segments
+- Verify network bandwidth is sufficient
+
+## Security Best Practices
+
+1. **Use HTTPS**: If deploying Bookmann publicly, configure SSL/TLS
+2. **Strong Password**: Use a secure password for your Bookmann account
+3. **Network Security**: Ensure your Wi-Fi network is secure (WPA2/WPA3)
+4. **Device Authorization**: Only approve devices you recognize
+5. **Regular Updates**: Keep KOReader updated to the latest version
+
+## Additional Resources
+
+- [KOReader Documentation](https://github.com/koreader/koreader)
+- [KOReader Forum](https://www.mobileread.com/forums/forumdisplay.php?f=271)
+- [Bookmann Universal Sync Guide](UNIVERSAL_SYNC_IMPLEMENTATION_GUIDE.md)
+- [Kobo Setup Guide](KOBO_SETUP.md)
+
+## Support
+
+If you encounter issues:
+1. Check the troubleshooting section above
+2. Enable debug logging and review KOReader logs
+3. Check Bookmann sync queue and device management pages
+4. Open an issue on the Bookmann GitHub repository
 
 ---
 
-## Uninstalling / Disabling
-
-### Temporary Disable
-
-**To temporarily stop syncing**:
-```
-Tools → Wireless Sync → Disable Auto-sync
-```
-
-### Permanent Disable
-
-**To remove sync configuration**:
-```
-Tools → More plugins → Calibre Sync → Uninstall
-```
-
-**To revoke device on server**:
-```
-Web Interface → Settings → Devices → Select Device → Delete
-```
-
----
-
-## FAQ
-
-### General Questions
-
-**Q: Does this work with all Kindle models?**
-A: Most Kindles from 2012+ that can run KOReader.
-
-**Q: Can I sync with Calibre AND Bookmann?**
-A: Yes! KOReader supports multiple sync servers.
-
-**Q: What happens if I edit metadata?**
-A: Sync updates reading progress only, not metadata.
-
-**Q: Can I sync over cellular (3G/4G/5G)?**
-A: Technically yes, but not recommended (high data usage).
-
-**Q: Does sync work with sideloaded books?**
-A: Yes, if the file path/name matches in Bookmann library.
-
-### Technical Questions
-
-**Q: What protocol does it use?**
-A: Calibre-compatible HTTP/JSON over HTTPS.
-
-**Q: Port requirements?**
-A: Only port 443 (HTTPS) needed from device to server.
-
-**Q: Can I sync without Wi-Fi?**
-A: Only via cellular or USB (not recommended).
-
-**Q: How much data per sync?**
-A: ~1KB per page turn, ~50KB per annotation.
-
-**Q: Does sync work while device is sleeping?**
-A: No, device must be awake and connected to Wi-Fi.
-
----
-
-## Device-Specific Notes
-
-### Kindle Paperwhite
-
-**File Location**:
-```
-/mnt/us/addons/calibre.lua
-```
-
-**Auto-Sync**: Not supported, use manual sync
-
-**Wi-Fi**: Only when device is awake
-
-### Kobo Clara/Libra
-
-**File Location**:
-```
-/mnt/onboard/.adds/koreader/
-```
-
-**Auto-Sync**: Supported
-
-**Battery**: Excellent with checkpoint mode
-
-### PocketBook
-
-**File Location**:
-```
-/mnt/ext1/system/config/calibre.lua
-```
-
-**Auto-Sync**: Supported
-
-**Network**: Supports both 2.4GHz and 5GHz
-
-### Android Tablets
-
-**File Location**:
-```
-/storage/emulated/0/KOReader/config/
-```
-
-**Auto-Sync**: Supported
-
-**Background Sync**: Yes (with restrictions)
-
----
-
-## Getting Help
-
-### Documentation
-
-- **Bookmann Docs**: `/docs/`
-- **KOReader Docs**: https://koreader.rocks/userguide/
-- **Sync API**: `/docs/api.md`
-
-### Support
-
-- **Issues**: GitHub Issues
-- **Forum**: community.bookmann.example.com
-- **Email**: support@bookmann.example.com
-
----
-
-## Changelog
-
-### v1.0.0 (January 2026)
-- Initial KOReader sync support
-- Calibre-compatible protocol
-- Real-time progress sync
-- Annotation sync
-- Checkpoint mode
-- Conflict resolution
-
----
-
-**Last Updated**: January 31, 2026  
-**Compatible With**: KOReader 2024.01+  
-**Bookmann Version**: 1.0.0+
+**Last Updated**: 2026-01-31  
+**Bookmann Version**: 1.0  
+**KOReader Version**: 2024.01+