docs(media-items,collections,koreader,admin): Beam batch 11 — final backfill

All remaining endpoint docs frontmatter'd: media-item bulk ops + audio
surface, collections book-listing/preview, koreader rating/review/stats
plugin protocol, hash-conflicts JSON list.

Scope call (Claude): resolve_hash_conflict.md DELETED — the resolve POST
renders an htmx fragment (renderResolved), a web-admin flow under rule 3;
only the GET list is a JSON API. update_media_review skipped by Beam
(correct): ratings/upsert_media_review.md already covers the PUT.

Registry: 16 entries. koreader rating/review/stats all bind
koreaderBookRef (query or body) — odd=half-star rating scale; audio track
endpoint serves raw bytes (ServeContent, Range) — response nil. Fixed
drift: deleted_annotations doc's secondary restore/purge fences
unlabeled (gate validates labeled blocks against the ONE frontmatter
route); chapters example labeled. UNVERIFIED: 1 (koreader book-ref
fields, push_stats). make test 9/9.

docs/developer/api/collections/bulk_add_books.md

@@ -0,0 +1,51 @@
+---
+method: POST
+path: /api/collections/bulk-add-books
+auth: jwt
+area: collections
+---
+<!-- source: internal/handlers/collections.go:1133 CollectionHandler.HandleBulkAddBooks -->
+
+# Bulk Add Books
+
+Adds books to multiple collections in one request.
+
+## Example request
+
+```json example-request
+{
+  "operations": [
+    {
+      "collection_id": "550e8400-e29b-41d4-a716-446655440000",
+      "book_ids": [
+        "660e8400-e29b-41d4-a716-446655440001"
+      ]
+    }
+  ]
+}
+```
+
+## Example response
+
+```json example-response
+{
+  "results": [],
+  "total": 1
+}
+```
+
+## Fields
+
+| Field | Type | Required | Notes |
+| ----- | ---- | -------- | ----- |
+| operations | array | Yes | List of {collection_id, book_ids} |
+| operations[].collection_id | string (uuid) | Yes | Target collection |
+| operations[].book_ids | array of string (uuid) | Yes | Books to add |
+
+## Errors
+
+| Status | Body | When |
+| ------ | ---- | ---- |
+| 400 | `{"error": "Invalid request"}` / `{"error": "operations required"}` | malformed |
+| 400 | `{"error": "smart collections are rule-based..."}` | smart collection |
+| 500 | `{"error": "..."}` | unexpected server error |

docs/developer/api/collections/bulk_remove_books.md

@@ -0,0 +1,45 @@
+---
+method: POST
+path: /api/collections/:id/books/bulk-remove
+auth: jwt
+area: collections
+---
+<!-- source: internal/handlers/collections.go:601 CollectionHandler.BulkRemoveBooks -->
+
+# Bulk Remove Books
+
+Removes multiple books from a collection at once.
+
+## Example request
+
+```json example-request
+{
+  "book_ids": [
+    "550e8400-e29b-41d4-a716-446655440000",
+    "660e8400-e29b-41d4-a716-446655440001"
+  ]
+}
+```
+
+## Example response
+
+```json example-response
+{
+  "removed": 2,
+  "total": 2
+}
+```
+
+## Fields
+
+| Field | Type | Required | Notes |
+| ----- | ---- | -------- | ----- |
+| book_ids | array of string (uuid) | Yes | Book ids to remove |
+
+## Errors
+
+| Status | Body | When |
+| ------ | ---- | ---- |
+| 400 | `{"error": "invalid collection id"}` / `{"error": "invalid request"}` | malformed |
+| 400 | `{"error": "smart collections are rule-based..."}` | smart collection |
+| 500 | `{"error": "..."}` | unexpected server error |

docs/developer/api/collections/delete_shelf_mapping.md

@@ -1,3 +1,11 @@
+---
+method: DELETE
+path: /api/devices/:id/collections/:collectionId
+auth: jwt
+area: collections
+---
+<!-- source: internal/handlers/collections.go:760 CollectionHandler.DeleteDeviceMapping -->
+
 # Delete Shelf Mapping
 
 Remove a collection-to-shelf mapping for a device.

docs/developer/api/collections/get_collection_books.md

@@ -0,0 +1,36 @@
+---
+method: GET
+path: /api/collections/:id/books
+auth: jwt
+area: collections
+---
+<!-- source: internal/handlers/collections.go:774 CollectionHandler.GetBookCollections -->
+
+# Get Book Collections
+
+Returns the collections a given book belongs to.
+
+## Example response
+
+```json example-response
+{
+  "book_id": "550e8400-e29b-41d4-a716-446655440000",
+  "collections": [
+    {
+      "id": "550e8400-e29b-41d4-a716-446655440000",
+      "name": "To Read",
+      "description": "Books I want to read soon",
+      "color": "#00FF00",
+      "icon": "📖"
+    }
+  ],
+  "total": 1
+}
+```
+
+## Errors
+
+| Status | Body | When |
+| ------ | ---- | ---- |
+| 400 | `{"error": "invalid book id"}` | malformed id |
+| 500 | `{"error": "..."}` | unexpected server error |

docs/developer/api/collections/preview_collection.md

@@ -0,0 +1,46 @@
+---
+method: POST
+path: /api/collections/preview
+auth: jwt
+area: collections
+---
+<!-- source: internal/handlers/collections.go:1241 CollectionHandler.PreviewCollection -->
+
+# Preview Collection
+
+Previews which books would match a set of rules without saving.
+
+## Example request
+
+```json example-request
+{
+  "library_id": "550e8400-e29b-41d4-a716-446655440000",
+  "rules": [],
+  "manual_book_ids": [],
+  "limit": 20
+}
+```
+
+## Example response
+
+```json example-response
+{
+  "items": []
+}
+```
+
+## Fields
+
+| Field | Type | Required | Notes |
+| ----- | ---- | -------- | ----- |
+| library_id | string (uuid) | Yes | Library to preview against |
+| rules | array | No | Rule objects |
+| manual_book_ids | array of string (uuid) | No | Manually included books |
+| limit | int | No | Max items (default 20) |
+
+## Errors
+
+| Status | Body | When |
+| ------ | ---- | ---- |
+| 400 | `{"error": "Invalid request"}` / `{"error": "invalid library_id"}` / `{"error": "library not found"}` | malformed |
+| 500 | `{"error": "..."}` | unexpected server error |