docs(devices): Work Order 3 batch 1 — 6 missing device endpoints + gate entries

New frontmatter'd docs with handler-compatible examples:
- devices/get_device.md (DeviceInfo shape)
- devices/regenerate_device_token.md (token + sync_urls)
- devices/get_device_mappings.md (wrapper + DeviceMappingSummary)
- devices/update_device_mapping.md (UpdateDeviceMappingRequest)
- devices/download_sidecar_config.md (sidecar config JSON file)
- devices/link_book.md (LinkBookRequest; one UNVERIFIED marker on required-tag)

Schema registry: 6 new entries; DeviceMappingSummary hoisted to package
scope. Gate passes (the UNVERIFIED marker is logged, not a failure).

Excludes /api/devices-page (htmx page route, per ground rules).

internal/docs/schema.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 
 	"bookhoard/internal/handlers"
+	"bookhoard/internal/services"
 )
 
 // Schema pins the machine-checkable contract for one route. The drift gate
@@ -69,4 +70,53 @@ var Schemas = map[string]Schema{
 		}`),
 	},
 	"DELETE /api/collections/:id": {},
+	// --- devices (batch 1) ---
+	"GET /api/devices/:id": {
+		Response: handlers.DeviceInfo{},
+	},
+	"PUT /api/devices/:id/regenerate-token": {
+		Response: json.RawMessage(`{
+			"message": "", "auth_token": "",
+			"device": {
+				"id": "", "device_name": "", "device_type": "",
+				"last_sync": null, "last_seen": null,
+				"sync_enabled": false, "auto_sync": false,
+				"sync_frequency_minutes": 0, "created_at": "",
+				"device_metadata": null, "auth_token": ""
+			},
+			"sync_urls": {}
+		}`),
+	},
+	"GET /api/devices/:id/collections": {
+		Response: struct {
+			DeviceID string                                 `json:"device_id"`
+			Mappings []handlers.DeviceMappingSummary        `json:"mappings"`
+			Total    int                                    `json:"total"`
+		}{},
+	},
+	"PUT /api/devices/:id/collections/:collectionId": {
+		Request: handlers.UpdateDeviceMappingRequest{},
+		Response: json.RawMessage(`{
+			"id": "", "collection_id": "", "device_id": "",
+			"device_shelf_name": "", "sync_direction": "", "created_at": ""
+		}`),
+	},
+	"GET /api/devices/:id/sidecar/download": {
+		Response: json.RawMessage(`{
+			"version": "", "bookhoard": {}, "books": {},
+			"collections": [], "opds_enabled": false,
+			"sidecar_enabled": false, "last_updated": ""
+		}`),
+	},
+	"POST /api/devices/:deviceId/sync/link-book": {
+		Request: services.LinkBookRequest{},
+		Response: json.RawMessage(`{
+			"status": "",
+			"device_file_alias": {
+				"id": "", "media_item_id": "", "device_id": "",
+				"file_path": "", "file_sha256": "",
+				"confidence_score": 0.0
+			}
+		}`),
+	},
 }

internal/handlers/collections.go

@@ -75,6 +75,17 @@ type UpdateDeviceMappingRequest struct {
 	SyncDirection   string `json:"sync_direction" validate:"required,oneof=bidirectional book_to_device device_to_book none"`
 }
 
+// DeviceMappingSummary is one entry in GET /api/devices/:id/collections. Hoisted
+// to package scope so the docs schema registry can pin the response shape.
+type DeviceMappingSummary struct {
+	ID              uuid.UUID `json:"id"`
+	CollectionID    uuid.UUID `json:"collection_id"`
+	CollectionName  string    `json:"collection_name"`
+	DeviceShelfName string    `json:"device_shelf_name"`
+	SyncDirection   string    `json:"sync_direction"`
+	CreatedAt       string    `json:"created_at"`
+}
+
 // CollectionSummary is one entry in GET /api/collections. Package-level so
 // the docs schema registry (internal/docs) can pin the response shape.
 type CollectionSummary struct {
@@ -653,18 +664,9 @@ func (h *CollectionHandler) GetDeviceMappings(c *echo.Context) error {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
 	}
 
-	type MappingResponse struct {
-		ID              uuid.UUID `json:"id"`
-		CollectionID    uuid.UUID `json:"collection_id"`
-		CollectionName  string    `json:"collection_name"`
-		DeviceShelfName string    `json:"device_shelf_name"`
-		SyncDirection   string    `json:"sync_direction"`
-		CreatedAt       string    `json:"created_at"`
-	}
-
-	response := make([]MappingResponse, 0, len(mappings))
+	response := make([]DeviceMappingSummary, 0, len(mappings))
 	for _, m := range mappings {
-		response = append(response, MappingResponse{
+		response = append(response, DeviceMappingSummary{
 			ID:              m.ID.Bytes,
 			CollectionID:    m.CollectionID.Bytes,
 			CollectionName:  m.CollectionName,