docs: update comprehensive API documentation and project guides

This commit updates all documentation files throughout the project: - Updated IMPLEMENTATION_PLAN.md with new implementation details - Updated PROJECT_GUIDELINES.md with coding standards and practices - Updated README.md with current project information - Updated SCREENSHOT_AUTOMATION.md with new automation details - Added TEST_DATA.md with test fixtures data - Updated cover_image_serving_plan.md with static URL patterns Documentation API updates: - Updated API reference documentation for all endpoints including: - Authentication (login, logout, register, refresh_token) - Book matching (auto_link, bulk_link, link_book, search) - Collections (CRUD operations, shelf mappings, auto-assign rules) - Conflicts (bulk operations, resolve/dismiss) - Devices (registration, approval, shelf management) - Highlights (create, update, delete, get) - Kobo sync (bookmark, markup, initialization, sync) - KOReader sync (library, metadata, bookmarks, progress) - Libraries (CRUD, folders, media items, stats) - Media items (bulk operations, CRUD) - Notes (CRUD operations) - OPDS (acquisition, feeds, publication) - Progress (reading progress tracking) - Queue (device queue management) - Ratings (star ratings) - Scanner (watch mode, scan operations) - Sync protocols (Kobo, KOReader) - Users (profile, password, admin operations) - WebSocket protocols - Updated user guides (admin, dashboard, settings, sync) - Updated device setup guides (Kobo, KOReader) - Updated developer guides (testing, contributing, operations) - Updated scripts/README.md
2026-02-27 17:06:22 -05:00
parent 6562b20ee5
commit 4d321528b2
154 changed files with 2817 additions and 2152 deletions
@@ -5,6 +5,7 @@ This guide will help you set up KOReader on your e-reader device to sync with Bo
 ## 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
@@ -13,6 +14,7 @@ KOReader is an open-source e-reader application that supports a wide range of e-
 ## Prerequisites

 Before you begin, make sure you have:
+
 - ✅ A Bookhoard instance running and accessible on your network
 - ✅ Your Bookhoard credentials (username and password)
 - ✅ A KOReader-compatible e-reader device
@@ -67,6 +69,7 @@ Before you begin, make sure you have:
 ### Step 1: Get Your Bookhoard Instance URL

 Find your Bookhoard 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://bookhoard.yourdomain.com`
@@ -84,6 +87,7 @@ Find your Bookhoard instance URL. This will typically be one of:
 4. Click **Register Device**

 You'll receive:
+
 - An **Auth URL** to approve the device
 - A **Device Token** (automatically generated after approval)

@@ -114,9 +118,11 @@ Your device is now registered and ready to sync!

 1. **Enable Calibre Wireless Connection**: Toggle ON
 2. **Server Address**: Enter your Bookhoard instance URL
+
   ```
   http://YOUR_COMPUTER_IP:8765/api/sync/koreader
   ```
+
   Replace `YOUR_COMPUTER_IP` with your actual IP address

 3. **Set Custom Port** (if needed): Keep default or enter `8765`
@@ -157,6 +163,7 @@ Your device is now registered and ready to sync!
 ### Initial Sync

 When you first enable sync, KOReader will:
+
 1. Connect to Bookhoard
 2. Upload your current reading progress
 3. Download any annotations from the server
@@ -165,6 +172,7 @@ When you first enable sync, KOReader will:
 ### Reading Progress Sync

 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
@@ -179,11 +187,13 @@ As you read:
 ### Manual Sync

 To manually trigger a sync:
+
 1. Open the KOReader menu (≡)
 2. Select **Tools** → **Calibre**
 3. Tap **Sync Now**

 The sync status will display:
+
 - 🟢 **Synced** - All changes uploaded
 - 🟡 **Syncing...** - In progress
 - 🔴 **Failed** - Check your network connection
@@ -193,6 +203,7 @@ The sync status will display:
 ### Offline Mode

 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
@@ -200,6 +211,7 @@ KOReader automatically handles offline scenarios:
 ### Checkpoint Sync

 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)
@@ -208,6 +220,7 @@ For better battery life, use checkpoint mode:
 ### Debug Mode

 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`
@@ -279,6 +292,7 @@ Your Bookhoard library now appears in KOReader's home screen!
 #### Supported Formats

 KOReader OPDS supports:
+
 - **EPUB**: Standard ebook format
 - **KEPUB**: Kobo-optimized format (KOReader handles this well)
 - **PDF**: Fixed-layout documents
@@ -289,6 +303,7 @@ KOReader OPDS supports:
 #### Automatic Book Matching

 Books downloaded via OPDS are automatically matched:
+
 - Uses SHA-256 hashes for precise matching
 - Falls back to title/author matching
 - Links to your existing Bookhoard library
@@ -297,6 +312,7 @@ Books downloaded via OPDS are automatically matched:
 #### Collection Integration

 Your Bookhoard collections appear in KOReader:
+
 - Collection **"To Read"** → KOReader category
 - Collection **"Science Fiction"** → Browseable section
 - Custom collections → Preserved organization
@@ -306,6 +322,7 @@ Your Bookhoard collections appear in KOReader:
 #### Update Interval

 Configure how often KOReader checks for new books:
+
 1. KOReader menu → Tools → OPDS
 2. Set **Update Interval**: 5min, 15min, 1hr, manual
 3. **Recommended**: 15min for balance
@@ -313,6 +330,7 @@ Configure how often KOReader checks for new books:
 #### Download Location

 Choose where to store downloaded books:
+
 1. KOReader menu → File Browser
 2. Set **Default Download Folder**
 3. **Recommended**: `/mnt/us/Documents/` (Kindle) or `/mnt/onboard/Documents/` (Kobo)
@@ -320,6 +338,7 @@ Choose where to store downloaded books:
 #### Auto-Download

 Automatically download new books from collections:
+
 1. KOReader menu → Tools → OPDS
 2. Enable **Auto-Download New Books**
 3. Select collections to monitor
@@ -332,6 +351,7 @@ Automatically download new books from collections:
 **Problem**: Bookhoard catalog shows error or won't load

 **Solutions**:
+
 1. Verify device is connected to Wi-Fi
 2. Check OPDS URL is correct in settings
 3. Try accessing OPDS URL in your browser
@@ -343,6 +363,7 @@ Automatically download new books from collections:
 **Problem**: Book download starts but fails

 **Solutions**:
+
 1. Check Wi-Fi signal strength
 2. Ensure sufficient storage on device
 3. Try downloading a smaller book
@@ -354,6 +375,7 @@ Automatically download new books from collections:
 **Problem**: Downloaded book doesn't sync progress

 **Solutions**:
+
 1. Verify book is matched to Bookhoard library
 2. Check device sync settings are enabled
 3. Try manual sync from device
@@ -365,6 +387,7 @@ Automatically download new books from collections:
 **Problem**: Books take too long to download

 **Solutions**:
+
 1. Stay close to Wi-Fi router
 2. Use 5GHz Wi-Fi if available
 3. Close other apps using bandwidth
@@ -401,14 +424,14 @@ OPDSCompressionEnabled = true

 ### OPDS vs USB Transfer

-| Feature | OPDS (Wireless) | USB Transfer |
-|---------|----------------|--------------|
-| **Convenience** | ⭐⭐⭐⭐⭐ No cable needed | ⭐⭐ Requires cable |
-| **Speed** | ⭐⭐⭐ Fast (Wi-Fi dependent) | ⭐⭐⭐⭐⭐ Very fast |
-| **Bulk Transfer** | ⭐⭐⭐ One at a time | ⭐⭐⭐⭐⭐ Many at once |
-| **Progress Sync** | ⭐⭐⭐⭐⭐ Instant | ⭐⭐⭐⭐ After transfer |
-| **Accessibility** | ⭐⭐⭐⭐⭐ Anywhere | ⭐⭐ At computer only |
-| **Reliability** | ⭐⭐⭐⭐ Very good | ⭐⭐⭐⭐⭐ Excellent |
+| Feature           | OPDS (Wireless)               | USB Transfer            |
+| ----------------- | ----------------------------- | ----------------------- |
+| **Convenience**   | ⭐⭐⭐⭐⭐ No cable needed    | ⭐⭐ Requires cable     |
+| **Speed**         | ⭐⭐⭐ Fast (Wi-Fi dependent) | ⭐⭐⭐⭐⭐ Very fast    |
+| **Bulk Transfer** | ⭐⭐⭐ One at a time          | ⭐⭐⭐⭐⭐ Many at once |
+| **Progress Sync** | ⭐⭐⭐⭐⭐ Instant            | ⭐⭐⭐⭐ After transfer |
+| **Accessibility** | ⭐⭐⭐⭐⭐ Anywhere           | ⭐⭐ At computer only   |
+| **Reliability**   | ⭐⭐⭐⭐ Very good            | ⭐⭐⭐⭐⭐ Excellent    |

 **Recommendation**: Use OPDS for daily reading (convenience), USB for bulk library transfers.

@@ -427,6 +450,7 @@ OPDSCompressionEnabled = true
 **Problem**: "Connection refused" error

 **Solutions**:
+
 - Verify Bookhoard is running on your computer
 - Check the server URL and port (8765)
 - Ensure device is on same Wi-Fi network
@@ -437,6 +461,7 @@ OPDSCompressionEnabled = true
 **Problem**: "Authentication failed" error

 **Solutions**:
+
 - Verify username and password
 - Check your account is active and not locked
 - Try logging in to Bookhoard web interface first
@@ -447,6 +472,7 @@ OPDSCompressionEnabled = true
 **Problem**: Changes not appearing in Bookhoard

 **Solutions**:
+
 - Enable debug logging in KOReader
 - Check Bookhoard Device Management page for errors
 - Verify sync is enabled in KOReader settings
@@ -458,6 +484,7 @@ OPDSCompressionEnabled = true
 **Problem**: Sync conflicts when reading on multiple devices

 **Solutions**:
+
 1. Go to Bookhoard **Conflicts** page
 2. Review conflicting progress from each device
 3. Choose which device's progress to keep
@@ -468,6 +495,7 @@ OPDSCompressionEnabled = true
 **Problem**: Large annotations or highlights fail to sync

 **Solutions**:
+
 - Check Bookhoard sync queue for stuck items
 - Increase sync timeout in KOReader settings
 - Break up large highlights into smaller segments
@@ -491,6 +519,7 @@ OPDSCompressionEnabled = true
 ## Support

 If you encounter issues:
+
 1. Check the troubleshooting section above
 2. Enable debug logging and review KOReader logs
 3. Check Bookhoard sync queue and device management pages