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.

internal/docs/drift_test.go

@@ -30,6 +30,7 @@ type extractedRoute struct {
 
 var (
 	groupRe      = regexp.MustCompile(`^(\w+)\s*:=\s*(\S+)\.Group\("([^"]*)"(?:,\s*(.+))?\)`)
+	useRe        = regexp.MustCompile(`^(\w+)\.Use\((.+)\)$`)
 	echoRouteRe  = regexp.MustCompile(`^(?:e|cfg\.Echo)\.(GET|POST|PUT|PATCH|DELETE)\("([^"]*)"(?:,\s*(.+))?\)`)
 	groupRouteRe = regexp.MustCompile(`^(\w+)\.(GET|POST|PUT|PATCH|DELETE)\("([^"]*)"(?:,\s*(.+))?\)`)
 )
@@ -94,6 +95,16 @@ func extractRoutesFromRouterSource(t *testing.T) map[string]extractedRoute {
 				continue
 			}
 
+			//opds-style middleware: `grp.Use(cfg.DeviceAuthMiddleware.Authenticate)`
+			//applies to every route registered on that group afterwards.
+			if m := useRe.FindStringSubmatch(s); m != nil {
+				if g, ok := groups[m[1]]; ok {
+					g.middleware = append(g.middleware, splitMW(m[2])...)
+					groups[m[1]] = g
+				}
+				continue
+			}
+
 			if m := echoRouteRe.FindStringSubmatch(s); m != nil {
 				add(m[1], m[2], splitMW(m[3]))
 				continue

internal/docs/schema.go

@@ -726,4 +726,48 @@ var Schemas = map[string]Schema{
 			"require_number": true, "require_special": true
 		}`),
 	},
+
+	// --- Beam batch 9: highlights, notes, progress delete, analytics, opds ---
+	"POST /api/media-items/:id/highlights": {
+		Request:  handlers.CreateMediaHighlightRequest{},
+		Response: database.MediaHighlights{},
+	},
+	"GET /api/media-items/:id/highlights": {
+		Response: []database.MediaHighlights{},
+	},
+	"PUT /api/media-items/:id/highlights/:highlightId": {
+		// LWW edit targeted by URL id (identity NOT re-derived from content).
+		Request:  handlers.UpdateMediaHighlightRequest{},
+		Response: database.MediaHighlights{},
+	},
+	"DELETE /api/media-items/:id/highlights/:highlightId": {
+		// Tombstone via sync service; 204 No Content.
+	},
+	"POST /api/media-items/:id/notes": {
+		Request:  handlers.CreateMediaNoteRequest{},
+		Response: database.MediaNotes{},
+	},
+	"GET /api/media-items/:id/notes": {
+		Response: []database.MediaNotes{},
+	},
+	"PUT /api/media-items/:id/notes/:noteId": {
+		Request:  handlers.UpdateMediaNoteRequest{},
+		Response: database.MediaNotes{},
+	},
+	"DELETE /api/media-items/:id/notes/:noteId": {
+		// Tombstone; 204 No Content.
+	},
+	"DELETE /api/media-items/:id/progress": {
+		Response: json.RawMessage(`{"message": ""}`),
+	},
+	"GET /api/analytics/reading-stats": {
+		// Query: start_date/end_date in MM-DD-YYYY, user-timezone buckets.
+		Response: handlers.ReadingStatsResponse{},
+	},
+
+	// OPDS: XML/Atom responses (content negotiated, not JSON) — response
+	// side intentionally unpinned.
+	"GET /opds/devices/:deviceId/catalog":          {},
+	"GET /opds/devices/:deviceId/download/:bookId": {},
+	"GET /opds/devices/:deviceId/cover/:bookId":    {},
 }