docs(libraries): Work Order 3 batch 2 — 10 missing endpoints + array-response gate support

New frontmatter'd docs with handler-compatible shapes:
- get_library_types.md (public; []LibraryTypes)
- list_libraries.md (admin; {data: ListLibrariesRow})
- get_library_folders.md (admin; []LibraryFolders)
- list/get stats/resolve/delete processing issues (admin; family-lens 403s
  documented)
- scan_library.md (202 + 409 coalescing with active_job_id)
- get/update scan-settings (ScanSettingsResponse)

Gate improvements forced by this batch:
- Array responses: registered slice -> doc example must be a JSON array; key
  set compared against the element type
- RawMessage pins may now be arrays
- update scan-settings uses a RawMessage pin: handler always sets Message but
  the struct's omitempty would reject correct docs via zero-value marshal

Registry: sqlc models pinned directly (LibraryTypes, LibraryFolders,
ListLibrariesRow — json tags verified in the generated code).

internal/docs/drift_test.go

@@ -251,8 +251,24 @@ func validateResponseExample(t *testing.T, doc *APIDoc, schema Schema) {
 		return
 	}
 
-	want := responseTopLevelKeys(t, schema.Response)
-	got := topLevelKeys(doc.ExampleResponse)
+	want, isSlice := responseTopLevelKeys(t, schema.Response)
+
+	var got map[string]bool
+	if isSlice {
+		// Array responses: compare the first sample element's keys.
+		var arr []json.RawMessage
+		if err := json.Unmarshal(doc.ExampleResponse, &arr); err != nil {
+			t.Errorf("%s: example-response must be a JSON array for this route (handler returns a slice)", doc.RelPath)
+			return
+		}
+		if len(arr) == 0 {
+			t.Errorf("%s: example-response array needs at least one sample element to check keys", doc.RelPath)
+			return
+		}
+		got = topLevelKeys(arr[0])
+	} else {
+		got = topLevelKeys(doc.ExampleResponse)
+	}
 
 	for _, k := range sortedKeys(want) {
 		if !got[k] {
@@ -312,21 +328,25 @@ func topLevelKeys(data []byte) map[string]bool {
 
 // responseTopLevelKeys derives the expected top-level key set from the
 // registered Response: marshal a struct (or its element for slices), or use a
-// RawMessage pin verbatim.
-func responseTopLevelKeys(t *testing.T, resp any) map[string]bool {
+// RawMessage pin verbatim. The second return reports that the handler emits a
+// JSON ARRAY (slice response) — the doc's example must then be an array too.
+func responseTopLevelKeys(t *testing.T, resp any) (map[string]bool, bool) {
 	t.Helper()
 	if raw, ok := resp.(json.RawMessage); ok {
-		return topLevelKeys(raw)
+		trimmed := bytes.TrimLeft(raw, " \t\r\n")
+		return topLevelKeys(raw), len(trimmed) > 0 && trimmed[0] == '['
 	}
 	rt := reflect.TypeOf(resp)
 	if rt == nil {
-		return nil
+		return nil, false
 	}
+	isSlice := false
 	if rt.Kind() == reflect.Slice {
 		if rt.Elem().Kind() == reflect.Uint8 {
-			return topLevelKeys(reflect.ValueOf(resp).Bytes()) // []byte payloads
+			return topLevelKeys(reflect.ValueOf(resp).Bytes()), false // []byte payloads
 		}
 		rt = rt.Elem()
+		isSlice = true
 	}
 	if rt.Kind() == reflect.Ptr {
 		rt = rt.Elem()
@@ -338,7 +358,7 @@ func responseTopLevelKeys(t *testing.T, resp any) map[string]bool {
 	if err != nil {
 		t.Fatalf("marshal schema response %T: %v", resp, err)
 	}
-	return topLevelKeys(b)
+	return topLevelKeys(b), isSlice
 }
 
 func sortedKeys(m map[string]bool) []string {

internal/docs/schema.go

@@ -3,6 +3,7 @@ package docs
 import (
 	"encoding/json"
 
+	"bookhoard/internal/database"
 	"bookhoard/internal/handlers"
 	"bookhoard/internal/services"
 )
@@ -89,9 +90,9 @@ var Schemas = map[string]Schema{
 	},
 	"GET /api/devices/:id/collections": {
 		Response: struct {
-			DeviceID string                                 `json:"device_id"`
-			Mappings []handlers.DeviceMappingSummary        `json:"mappings"`
-			Total    int                                    `json:"total"`
+			DeviceID string                          `json:"device_id"`
+			Mappings []handlers.DeviceMappingSummary `json:"mappings"`
+			Total    int                             `json:"total"`
 		}{},
 	},
 	"PUT /api/devices/:id/collections/:collectionId": {
@@ -119,4 +120,47 @@ var Schemas = map[string]Schema{
 			}
 		}`),
 	},
+
+	// --- libraries (batch 2) ---
+	"GET /api/libraries/types": {
+		Response: []database.LibraryTypes{},
+	},
+	"GET /api/libraries": {
+		Response: struct {
+			Data []database.ListLibrariesRow `json:"data"`
+		}{},
+	},
+	"GET /api/libraries/:id/folders": {
+		Response: []database.LibraryFolders{},
+	},
+	"GET /api/libraries/:id/issues/list": {
+		Response: []handlers.ProcessingIssueResponse{},
+	},
+	"GET /api/libraries/:id/issues/stats": {
+		Response: handlers.ProcessingIssueStats{},
+	},
+	"POST /api/libraries/:id/issues/:issueId/:mediaItemId/resolve": {
+		Response: json.RawMessage(`{"success": false, "message": ""}`),
+	},
+	"DELETE /api/libraries/:id/issues/:issueId": {
+		Response: json.RawMessage(`{"success": false, "message": ""}`),
+	},
+	"POST /api/libraries/:id/scan": {
+		Request:  nil, // library_id injected from the path; no body used
+		Response: json.RawMessage(`{"message": "", "job_id": "", "status": ""}`),
+	},
+	"GET /api/libraries/scan-settings": {
+		Response: handlers.ScanSettingsResponse{},
+	},
+	"PUT /api/libraries/scan-settings": {
+		Request: handlers.UpdateScanSettingsRequest{},
+		// RawMessage pin (not the struct): the update handler ALWAYS sets
+		// Message, but the struct's omitempty would drop it from a
+		// zero-value marshal and the gate would reject correct docs.
+		Response: json.RawMessage(`{
+			"scan_poll_interval_seconds": 0,
+			"auto_scan_enabled": false,
+			"message": ""
+		}`),
+	},
 }