docs(api): document the real book download route

The documented GET /api/media-items/:uuid/download is not registered
anywhere - MediaHandler.DownloadBook exists but no route mounts it.
Book files (and covers) are actually served by the JWT-authenticated
GET /uploads/library-{id}/{path} route that the web reader uses.

Rewrite the download doc around the real file route (URL construction
from the item's library_id and relative file_path, MIME/Cache headers,
error codes), note the dead handler so nobody relies on the phantom
endpoint, and correct the API reference index. Mention the OPDS device
route as the conversion-capable alternative.

docs/developer/api/api-reference.md

@@ -89,7 +89,7 @@ See [Media Item Operations](media-items/)
 - GET /api/media-items/:id - Get media item details
 - POST /api/media-items/bulk-delete - Bulk delete media items
 - POST /api/media-items/bulk-update - Bulk update media items (tags/contributors with normalization)
-- GET /api/media-items/:uuid/download - Download media item file
+- GET /uploads/library-{library_id}/{file_path} - Download book file / cover (JWT; see [Download Media Item](media-items/download_media_item.md))
 - POST /api/media-items/:id/rating - Create rating
 - GET /api/media-items/:id/rating - Get rating
 - PUT /api/media-items/:id/rating - Update rating

docs/developer/api/media-items/download_media_item.md

@@ -2,15 +2,19 @@
 
 Download a media item file (EPUB, PDF, etc.) from the Bookhoard server.
 
-**Endpoint**: `GET /api/media-items/:uuid/download`
+Book files are served by the authenticated file route, the same one the web reader uses. Build the URL from the media item's `library_id` and relative `file_path` (both returned by the media item list/get endpoints):
-**Auth**: None (public endpoint for Kobo devices)
+
-**Content-Type**: Binary file download
+**Endpoint**: `GET /uploads/library-{library_id}/{file_path}`
+**Auth**: Required (JWT - Bearer header or session cookie)
+
+The `file_path` segments are URL-escaped individually; slashes are preserved. `cover_image_path` uses the same route.
 
 ## Path Parameters
 
-| Parameter | Type   | Required | Description     |
+| Parameter   | Type   | Required | Description                          |
-| --------- | ------ | -------- | --------------- |
+| ----------- | ------ | -------- | ------------------------------------ |
-| uuid      | string | Yes      | Media item UUID |
+| library_id  | string | Yes      | Library UUID (the item's library)    |
+| file_path   | string | Yes      | The item's relative `file_path`      |
 
 ## Response
 
@@ -18,25 +22,27 @@ Download a media item file (EPUB, PDF, etc.) from the Bookhoard server.
 
 **Response Headers**:
 
-- `Content-Type`: `application/epub+zip`, `application/pdf`, or appropriate MIME type
+- `Content-Type`: MIME type by file extension (`application/epub+zip`, `application/pdf`, …; `application/octet-stream` fallback)
-- `Content-Disposition`: `attachment; filename="filename.epub"`
+- `Cache-Control`: `public, max-age=86400`
 
 ## Error Responses
 
-| Code | Description                       |
+| Code | Description                 |
-| ---- | --------------------------------- |
+| ---- | --------------------------- |
-| 404  | Media item not found              |
+| 400  | Invalid library ID or path  |
-| 500  | Server error during file download |
+| 401  | Missing/invalid token       |
+| 404  | File not found on disk      |
 
 ## Example
 
 ```bash
-curl -O http://localhost:8765/api/media-items/550e8400-e29b-41d4-a716-446655440000/download
+curl -O -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:8765/uploads/library/550e8400-.../books/1984.epub"
 ```
 
+(URL shape: `/uploads/library-{uuid}/{escaped-relative-path}`.)
+
 ## Notes
 
-- **Public endpoint**: No authentication required for Kobo device downloads
+- **Do not rely on `GET /api/media-items/:id/download`** — it appears in older docs but is **not registered**; `MediaHandler.DownloadBook` exists as dead code. Use the file route above.
-- **File format**: Returns the original file format (EPUB, PDF, etc.)
+- OPDS-capable devices may alternatively use the device-authenticated `GET /opds/devices/{deviceId}/download/{bookId}`, which supports on-the-fly format conversion (epub, kepub, pdf, cbz).
-- **Kobo integration**: Designed for direct downloads from Kobo e-readers
-- **Cover images**: Use `/api/media-items/:uuid/cover` for cover images