docs(api): add WebSocket real-time sync API documentation

- sync_api.md - Comprehensive WebSocket API guide

Covers:
- Connection and authentication (JWT + device)
- Client→Server messages (subscribe, ping)
- Server→Client messages (progress, conflicts, scan status, etc.)
- Message formats with examples
- Connection lifecycle
- Topics: progress, conflicts, scanner, devices, queue
- JavaScript usage example with reconnection
- Best practices for heartbeat and error handling

Documents bidirectional real-time sync API

docs/developer/api/koreader/get_library.md

@@ -0,0 +1,53 @@
+# Get Library
+
+Get library metadata for KOReader device.
+
+**Endpoint**: `GET /api/sync/koreader/library`
+**Auth**: Required (Device authentication)
+
+## Device Authentication
+
+This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials.
+
+## Request Headers
+
+| Header | Type | Required | Description |
+|--------|------|-----------|-------------|
+| X-Device-ID | string | Yes | Device UUID |
+| X-Device-Key | string | Yes | Device authentication key |
+
+### Example Request
+
+```http
+GET /api/sync/koreader/library
+X-Device-ID: 550e8400-e29b-41d4-a716-446655440000
+X-Device-Key: device-auth-key
+```
+
+## Response (200 OK)
+
+```json
+{
+  "books": [
+    {
+      "id": "uuid",
+      "title": "Book Title",
+      "authors": ["Author Name"],
+      "file": "book.epub",
+      "size": 1234567
+    }
+  ],
+  "total": 42
+}
+```
+
+## Error Responses
+
+| Code | Description |
+|------|-------------|
+| 401 | Device authentication failed |
+| 404 | Device not found |
+
+## Try It Out
+
+<!-- API Explorer will be inserted here in Phase 3 -->

docs/developer/api/koreader/get_metadata.md

@@ -0,0 +1,55 @@
+# Get Metadata
+
+Get metadata for a book from KOReader device.
+
+**Endpoint**: `GET /api/sync/koreader/metadata/:uuid`
+**Auth**: Required (Device authentication)
+
+## Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|-----------|-------------|
+| uuid | string (UUID) | Yes | Book UUID |
+
+## Device Authentication
+
+This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials.
+
+## Request Headers
+
+| Header | Type | Required | Description |
+|--------|------|-----------|-------------|
+| X-Device-ID | string | Yes | Device UUID |
+| X-Device-Key | string | Yes | Device authentication key |
+
+### Example Request
+
+```http
+GET /api/sync/koreader/metadata/550e8400-e29b-41d4-a716-446655440000
+X-Device-ID: 550e8400-e29b-41d4-a716-446655440000
+X-Device-Key: device-auth-key
+```
+
+## Response (200 OK)
+
+```json
+{
+  "id": "uuid",
+  "title": "Book Title",
+  "authors": ["Author Name"],
+  "path": "/path/to/book.epub",
+  "file_size": 1234567,
+  "modified_at": "2026-02-08T10:00:00Z"
+}
+```
+
+## Error Responses
+
+| Code | Description |
+|------|-------------|
+| 401 | Device authentication failed |
+| 404 | Book or device not found |
+
+## Try It Out
+
+<!-- API Explorer will be inserted here in Phase 3 -->

docs/developer/api/koreader/sync_bookmarks.md

@@ -0,0 +1,71 @@
+# Sync Bookmarks
+
+Sync bookmarks from KOReader device.
+
+**Endpoint**: `POST /api/sync/koreader/bookmarks`
+**Auth**: Required (Device authentication)
+
+## Device Authentication
+
+This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials.
+
+## Request Body
+
+| Field | Type | Required | Description |
+|--------|------|-----------|-------------|
+| device_id | string (UUID) | Yes | Device UUID |
+| bookmarks | array | Yes | Array of bookmark objects |
+
+### Bookmark Object
+
+| Field | Type | Required | Description |
+|--------|------|-----------|-------------|
+| book | string | Yes | Book identifier |
+| chapter | string | No | Chapter title |
+| page | integer | No | Page number |
+| position | float | Yes | Position in document (0-1) |
+| notes | string | No | Bookmark notes |
+| highlighted_text | string | No | Highlighted text |
+| time | string | Yes | ISO 8601 timestamp |
+| created_at | string | Yes | ISO 8601 timestamp |
+
+### Example Request
+
+```json
+{
+  "device_id": "550e8400-e29b-41d4-a716-446655440000",
+  "bookmarks": [
+    {
+      "book": "book.epub",
+      "chapter": "Chapter 1",
+      "page": 25,
+      "position": 0.125,
+      "notes": "Important section",
+      "highlighted_text": "Text to remember",
+      "time": "2026-02-08T10:00:00Z",
+      "created_at": "2026-02-08T10:00:00Z"
+    }
+  ]
+}
+```
+
+## Response (200 OK)
+
+```json
+{
+  "message": "Bookmarks synced successfully",
+  "synced_count": 1
+}
+```
+
+## Error Responses
+
+| Code | Description |
+|------|-------------|
+| 401 | Device authentication failed |
+| 400 | Invalid request data |
+| 404 | Device not found |
+
+## Try It Out
+
+<!-- API Explorer will be inserted here in Phase 3 -->

docs/developer/api/koreader/sync_progress.md

@@ -0,0 +1,67 @@
+# Sync Progress
+
+Sync reading progress from KOReader device.
+
+**Endpoint**: `POST /api/sync/koreader/progress`
+**Auth**: Required (Device authentication)
+
+## Device Authentication
+
+This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials.
+
+## Request Body
+
+| Field | Type | Required | Description |
+|--------|------|-----------|-------------|
+| device_id | string (UUID) | Yes | Device UUID |
+| progress | array | Yes | Array of progress objects |
+
+### Progress Object
+
+| Field | Type | Required | Description |
+|--------|------|-----------|-------------|
+| book | string | Yes | Book identifier (filename or UUID) |
+| percent | float | Yes | Progress percentage (0-100) |
+| page | integer | No | Current page number |
+| total_pages | integer | No | Total pages in document |
+| date_read | string | No | ISO 8601 timestamp of last read |
+| updated_at | string | Yes | ISO 8601 timestamp |
+
+### Example Request
+
+```json
+{
+  "device_id": "550e8400-e29b-41d4-a716-446655440000",
+  "progress": [
+    {
+      "book": "book.epub",
+      "percent": 75.5,
+      "page": 150,
+      "total_pages": 200,
+      "date_read": "2026-02-08T10:00:00Z",
+      "updated_at": "2026-02-08T10:00:00Z"
+    }
+  ]
+}
+```
+
+## Response (200 OK)
+
+```json
+{
+  "message": "Progress synced successfully",
+  "synced_count": 1
+}
+```
+
+## Error Responses
+
+| Code | Description |
+|------|-------------|
+| 401 | Device authentication failed |
+| 400 | Invalid request data |
+| 404 | Device not found |
+
+## Try It Out
+
+<!-- API Explorer will be inserted here in Phase 3 -->