docs(highlights,notes,opds,progress,analytics): Beam batch 9 — 13 endpoints

Highlights + notes CRUD (media-item scoped, jwt), progress delete,
reading-stats analytics, and the OPDS trio frontmatter'd. OPDS docs are
the first XML entries: example-response intentionally omitted (Atom
responses), gate contract honored via nil-Response registry pins.

Gate fix: group .Use() middleware now parsed (opds.Use(DeviceAuth...
Authenticate) previously resolved to auth 'none'). Registry: 13 entries.
Drift fixed by gate: reading-stats key names (total_reading_time_minutes,
most_active_day_of_week, daily_reading_minutes — draft invented
reading_time_hours/books_completed); notes/highlights list endpoints
return BARE arrays (no {notes:[]}/{highlights:[]} wrapper); create-note
request has no percentage_location/epubcfi_location. New
/tmp/merge_arrays.py handles array-example merges.

make test 9/9.

docs/developer/api/notes/create_note.md

@@ -1,3 +1,11 @@
+---
+method: POST
+path: /api/media-items/:id/notes
+auth: jwt
+area: media-items
+---
+<!-- source: internal/handlers/media.go:1876 MediaHandler.CreateMediaNote -->
+
 # Create Note
 
 Create a new note for a media item.
@@ -23,18 +31,17 @@ Create a new note for a media item.
 
 ### Example Request
 
-```json
+```json example-request
 {
   "content": "This is a note",
   "position": "epubcfi(/6/4/2:15)",
-  "percentage_location": 0.45,
-  "epubcfi_location": "epubcfi(/6/4/2:15)"
+  "origin": "web"
 }
 ```
 
 ## Response (201 Created)
 
-```json
+```json example-response
 {
   "id": "uuid",
   "media_item_id": "uuid",
@@ -43,7 +50,18 @@ Create a new note for a media item.
   "position": "epubcfi(/6/4/2:15)",
   "percentage_location": 0.45,
   "epubcfi_location": "epubcfi(/6/4/2:15)",
-  "created_at": "2026-01-31T10:00:00Z"
+  "created_at": "2026-01-31T10:00:00Z",
+  "chapter_reference": null,
+  "character_end": null,
+  "character_start": null,
+  "dedup_key": null,
+  "deleted": null,
+  "deleted_at": null,
+  "device_sync_data": null,
+  "last_modified_at": null,
+  "last_modified_source": null,
+  "paragraph_reference": null,
+  "updated_at": null
 }
 ```
 

docs/developer/api/notes/delete_note.md

@@ -1,3 +1,11 @@
+---
+method: DELETE
+path: /api/media-items/:id/notes/:noteId
+auth: jwt
+area: media-items
+---
+<!-- source: internal/handlers/media.go:1980 MediaHandler.DeleteMediaNote -->
+
 # Delete Note
 
 Delete a note.

docs/developer/api/notes/get_notes.md

@@ -1,3 +1,11 @@
+---
+method: GET
+path: /api/media-items/:id/notes
+auth: jwt
+area: media-items
+---
+<!-- source: internal/handlers/media.go:1851 MediaHandler.GetMediaNotes -->
+
 # Get Notes
 
 Retrieve all notes for a specific media item.
@@ -26,26 +34,34 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
 
 ## Response (200 OK)
 
-```json
-{
-  "notes": [
-    {
-      "id": "uuid",
-      "media_item_id": "uuid",
-      "user_id": "uuid",
-      "content": "This is an interesting passage...",
-      "position": "epubcfi(/6/4/2:15)",
-      "percentage_location": 0.45,
-      "character_start": 15432,
-      "character_end": 15480,
-      "epubcfi_location": "epubcfi(/6/4/2:15)",
-      "created_at": "2026-01-31T10:00:00Z",
-      "updated_at": "2026-01-31T10:00:00Z"
-    }
-  ]
-}
+```json example-response
+[
+  {
+    "id": "uuid",
+    "media_item_id": "uuid",
+    "user_id": "uuid",
+    "content": "This is an interesting passage...",
+    "position": "epubcfi(/6/4/2:15)",
+    "percentage_location": 0.45,
+    "character_start": 15432,
+    "character_end": 15480,
+    "epubcfi_location": "epubcfi(/6/4/2:15)",
+    "created_at": "2026-01-31T10:00:00Z",
+    "updated_at": "2026-01-31T10:00:00Z",
+    "chapter_reference": null,
+    "dedup_key": "",
+    "deleted": false,
+    "deleted_at": null,
+    "device_sync_data": "",
+    "last_modified_at": null,
+    "last_modified_source": "",
+    "paragraph_reference": null
+  }
+]
 ```
 
+Response is a bare JSON array of MediaNotes rows — no wrapper object.
+
 ## Error Responses
 
 | Code | Description              |

docs/developer/api/notes/update_note.md

@@ -1,3 +1,11 @@
+---
+method: PUT
+path: /api/media-items/:id/notes/:noteId
+auth: jwt
+area: media-items
+---
+<!-- source: internal/handlers/media.go:1932 MediaHandler.UpdateMediaNote -->
+
 # Update Note
 
 Update an existing note.
@@ -21,7 +29,7 @@ Update an existing note.
 
 ### Example Request
 
-```json
+```json example-request
 {
   "content": "Updated note content",
   "position": "epubcfi(/6/4/2:20)"
@@ -30,14 +38,27 @@ Update an existing note.
 
 ## Response (200 OK)
 
-```json
+```json example-response
 {
   "id": "uuid",
   "media_item_id": "uuid",
   "user_id": "uuid",
   "content": "Updated note content",
   "position": "epubcfi(/6/4/2:20)",
-  "updated_at": "2026-01-31T10:00:00Z"
+  "updated_at": "2026-01-31T10:00:00Z",
+  "chapter_reference": null,
+  "character_end": null,
+  "character_start": null,
+  "created_at": null,
+  "dedup_key": null,
+  "deleted": null,
+  "deleted_at": null,
+  "device_sync_data": null,
+  "epubcfi_location": null,
+  "last_modified_at": null,
+  "last_modified_source": null,
+  "paragraph_reference": null,
+  "percentage_location": null
 }
 ```