feat(docs): drift gate — docs frontmatter validated against real routes

Every API doc that declares frontmatter (method/path/auth/area) is now
checked by a unit test against three sources of truth:

1. Route registration: internal/router/*.go is parsed the way echo resolves
   it (group prefixes concatenate; scanner.go's parameterized groups seeded).
   Doc paths that no longer exist fail. (This is the check that would have
   caught the /api/api/admin/hash-conflicts split.)
2. Auth: frontmatter auth label must match the middleware chain
   (none|jwt|jwt+admin|device-token|optional-jwt).
3. Shapes: internal/docs/schema.go registry — example-request decoded with
   unknown fields DISALLOWED (typo guard), required-by-validate fields must
   appear (staleness guard), example-response top-level key set compared
   both directions against the marshaled handler type (or a RawMessage pin
   for hand-built map responses).

Five collections docs are the pilots with real handler shapes; notable
corrections they pin: update returns 201 (not 200), list excludes smart
collections unless include_auto=true, rule priority is 1-10 higher-wins
(docs claimed 1=highest), created_at is Go time.String() not RFC3339,
hide_finished/show_up_next toggles documented. CollectionResponse hoisted
out of GetCollections/GetBookCollections as CollectionSummary /
BookCollectionSummary so the registry can pin real types.

The gate fails on missing registry entries by design — that is the
maintenance contract. Known pre-existing (not this commit): vet copy-lock
warnings in media.go.

internal/docs/drift_test.go

@@ -0,0 +1,386 @@
+package docs
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"reflect"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+// The drift gate: every doc that declares an endpoint in frontmatter must
+// (1) match a real route registration, (2) match its middleware-derived auth
+// label, and (3) have request/response examples compatible with the schema
+// registry. Docs without frontmatter (overviews, contracts) are out of scope.
+//
+// Run verbose to see UNVERIFIED markers left by drafting passes:
+//
+//	go test ./internal/docs/ -run TestDocsMatchRoutes -v
+
+// ---------- route extraction ----------
+
+type extractedRoute struct {
+	method     string
+	path       string
+	middleware []string
+}
+
+var (
+	groupRe      = regexp.MustCompile(`^(\w+)\s*:=\s*(\S+)\.Group\("([^"]*)"(?:,\s*(.+))?\)`)
+	echoRouteRe  = regexp.MustCompile(`^(?:e|cfg\.Echo)\.(GET|POST|PUT|PATCH|DELETE)\("([^"]*)"(?:,\s*(.+))?\)`)
+	groupRouteRe = regexp.MustCompile(`^(\w+)\.(GET|POST|PUT|PATCH|DELETE)\("([^"]*)"(?:,\s*(.+))?\)`)
+)
+
+// extractRoutesFromRouterSource parses internal/router/*.go the way the echo
+// router resolves them: group prefixes concatenate, and some files receive
+// their group as a function parameter (registerScannerRoutes(protected, ...)).
+// This is a test — if it drifts from reality, a doc vs route mismatch shows up
+// in live behavior; treat failures here as "the parser needs updating", never
+// as license to edit docs to match the parser.
+func extractRoutesFromRouterSource(t *testing.T) map[string]extractedRoute {
+	t.Helper()
+	type group struct {
+		prefix     string
+		middleware []string
+	}
+	groups := map[string]group{
+		"e":        {},
+		"cfg.Echo": {},
+	}
+
+	files, err := filepath.Glob("../router/*.go")
+	if err != nil || len(files) == 0 {
+		t.Fatalf("cannot read router sources: %v", err)
+	}
+
+	routes := map[string]extractedRoute{}
+	add := func(method, path string, mw []string) {
+		routes[method+" "+path] = extractedRoute{method, path, mw}
+	}
+
+	for _, file := range files {
+		base := filepath.Base(file)
+		if strings.HasSuffix(base, "_test.go") {
+			continue
+		}
+		// registerScannerRoutes receives its groups as parameters; seed the
+		// names the call site actually passes (router.go: protected=/api jwt,
+		// admin=/api jwt+admin).
+		if base == "scanner.go" {
+			groups["protected"] = group{prefix: "/api", middleware: []string{"jwt"}}
+			groups["admin"] = group{prefix: "/api", middleware: []string{"jwt", "admin"}}
+		}
+		raw, err := os.ReadFile(file)
+		if err != nil {
+			t.Fatalf("read %s: %v", file, err)
+		}
+		for _, line := range strings.Split(string(raw), "\n") {
+			s := strings.TrimSpace(line)
+
+			if m := groupRe.FindStringSubmatch(s); m != nil {
+				varname, parent, prefix, mwArg := m[1], m[2], m[3], m[4]
+				parentInfo := groups[parent]
+				g := group{
+					prefix:     strings.TrimSuffix(parentInfo.prefix+prefix, "/"),
+					middleware: append(append([]string{}, parentInfo.middleware...), splitMW(mwArg)...),
+				}
+				groups[varname] = g
+				continue
+			}
+
+			if m := echoRouteRe.FindStringSubmatch(s); m != nil {
+				add(m[1], m[2], splitMW(m[3]))
+				continue
+			}
+
+			if m := groupRouteRe.FindStringSubmatch(s); m != nil {
+				g, ok := groups[m[1]]
+				if !ok {
+					continue
+				}
+				full := strings.TrimSuffix(g.prefix+m[3], "/")
+				add(m[2], full, append(append([]string{}, g.middleware...), splitMW(m[4])...))
+			}
+		}
+	}
+	return routes
+}
+
+func splitMW(s string) []string {
+	if strings.TrimSpace(s) == "" {
+		return nil
+	}
+	var out []string
+	for _, part := range strings.Split(s, ",") {
+		out = append(out, strings.TrimSpace(part))
+	}
+	return out
+}
+
+// authLabel reduces a middleware chain to the frontmatter auth vocabulary.
+func authLabel(chain []string) string {
+	has := func(needle string) bool {
+		for _, c := range chain {
+			if strings.Contains(c, needle) {
+				return true
+			}
+		}
+		return false
+	}
+	switch {
+	case has("AdminMiddleware"):
+		return "jwt+admin"
+	case has("DeviceAuthMiddleware"):
+		return "device-token"
+	case has("createOptionalAuthMiddleware"):
+		return "optional-jwt"
+	case has("jwt"):
+		return "jwt"
+	default:
+		return "none"
+	}
+}
+
+// parseHandlerMiddleware extracts per-route middleware markers from the
+// registration's argument list (wrappers like rateLimitMiddleware(handler)).
+func parseHandlerMiddleware(rest string) []string {
+	if rest == "" {
+		return nil
+	}
+	var mw []string
+	if strings.HasPrefix(strings.TrimSpace(rest), "rateLimitMiddleware") {
+		mw = append(mw, "rateLimit")
+	}
+	if strings.Contains(rest, "AdminMiddleware") {
+		mw = append(mw, "admin")
+	}
+	if strings.Contains(rest, "DeviceAuthMiddleware") {
+		mw = append(mw, "device-token")
+	}
+	if strings.Contains(rest, "createJWTMiddleware") {
+		mw = append(mw, "jwt")
+	}
+	return mw
+}
+
+// ---------- the gate ----------
+
+func TestDocsMatchRoutes(t *testing.T) {
+	routes := extractRoutesFromRouterSource(t)
+
+	docsDir := "../../docs/developer/api"
+	docs, err := LoadAPIDocs(docsDir)
+	if err != nil {
+		t.Fatalf("walk %s: %v", docsDir, err)
+	}
+	if len(docs) == 0 {
+		t.Fatal("no frontmatter'd endpoint docs found — the gate is checking nothing")
+	}
+
+	for _, doc := range docs {
+		key := doc.Frontmatter.Method + " " + doc.Frontmatter.Path
+
+		route, ok := routes[key]
+		if !ok {
+			t.Errorf("%s: frontmatter declares %q but no such route is registered (wrong path, method, or the route moved)", doc.RelPath, key)
+			continue
+		}
+
+		if want := authLabel(route.middleware); doc.Frontmatter.Auth != want {
+			t.Errorf("%s: frontmatter auth=%q but route middleware resolves to %q", doc.RelPath, doc.Frontmatter.Auth, want)
+		}
+
+		for _, marker := range doc.Unverified {
+			t.Logf("UNVERIFIED in %s: %s", doc.RelPath, marker)
+		}
+
+		schema, registered := Schemas[key]
+		if !registered {
+			t.Errorf("%s: route %q has no internal/docs schema registry entry — add one in the same change", doc.RelPath, key)
+			continue
+		}
+
+		validateRequestExample(t, &doc, schema)
+		validateResponseExample(t, &doc, schema)
+	}
+}
+
+func validateRequestExample(t *testing.T, doc *APIDoc, schema Schema) {
+	t.Helper()
+	if schema.Request == nil {
+		if len(doc.ExampleRequest) > 0 {
+			t.Errorf("%s: route takes no request body but the doc has an example-request block", doc.RelPath)
+		}
+		return
+	}
+	if len(doc.ExampleRequest) == 0 {
+		t.Errorf("%s: no example-request block — required for routes with a body", doc.RelPath)
+		return
+	}
+
+	// Typo guard: field names must exist on the bind struct.
+	dec := json.NewDecoder(bytes.NewReader(doc.ExampleRequest))
+	dec.DisallowUnknownFields()
+	v := reflect.New(reflect.TypeOf(schema.Request)).Interface()
+	if err := dec.Decode(v); err != nil {
+		t.Errorf("%s: example-request is not compatible with %T: %v", doc.RelPath, schema.Request, err)
+		return
+	}
+
+	// Staleness guard: required fields must be present in the example.
+	for _, field := range requiredJSONFields(reflect.TypeOf(schema.Request)) {
+		if !jsonHasKey(doc.ExampleRequest, field) {
+			t.Errorf("%s: example-request missing required field %q", doc.RelPath, field)
+		}
+	}
+}
+
+func validateResponseExample(t *testing.T, doc *APIDoc, schema Schema) {
+	t.Helper()
+	if schema.Response == nil {
+		if doc.HasExampleResponse {
+			t.Errorf("%s: route returns no JSON body but the doc has an example-response block", doc.RelPath)
+		}
+		return
+	}
+	if !doc.HasExampleResponse {
+		t.Errorf("%s: no example-response block — required for JSON routes", doc.RelPath)
+		return
+	}
+
+	want := responseTopLevelKeys(t, schema.Response)
+	got := topLevelKeys(doc.ExampleResponse)
+
+	for _, k := range sortedKeys(want) {
+		if !got[k] {
+			t.Errorf("%s: example-response missing key %q (the handler emits it)", doc.RelPath, k)
+		}
+	}
+	for _, k := range sortedKeys(got) {
+		if !want[k] {
+			t.Errorf("%s: example-response has key %q but the handler does not emit it", doc.RelPath, k)
+		}
+	}
+}
+
+// requiredJSONFields lists json field names of struct type whose validate tag
+// marks them required.
+func requiredJSONFields(rt reflect.Type) []string {
+	if rt.Kind() == reflect.Ptr {
+		rt = rt.Elem()
+	}
+	var out []string
+	for i := 0; i < rt.NumField(); i++ {
+		f := rt.Field(i)
+		jsonTag := strings.Split(f.Tag.Get("json"), ",")[0]
+		if jsonTag == "" || jsonTag == "-" {
+			continue
+		}
+		for _, rule := range strings.Split(f.Tag.Get("validate"), ",") {
+			if strings.TrimSpace(rule) == "required" {
+				out = append(out, jsonTag)
+				break
+			}
+		}
+	}
+	return out
+}
+
+func jsonHasKey(data []byte, key string) bool {
+	var m map[string]json.RawMessage
+	if err := json.Unmarshal(data, &m); err != nil {
+		return false
+	}
+	_, ok := m[key]
+	return ok
+}
+
+func topLevelKeys(data []byte) map[string]bool {
+	var m map[string]json.RawMessage
+	if err := json.Unmarshal(data, &m); err != nil {
+		return nil
+	}
+	out := make(map[string]bool, len(m))
+	for k := range m {
+		out[k] = true
+	}
+	return out
+}
+
+// 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 {
+	t.Helper()
+	if raw, ok := resp.(json.RawMessage); ok {
+		return topLevelKeys(raw)
+	}
+	rt := reflect.TypeOf(resp)
+	if rt == nil {
+		return nil
+	}
+	if rt.Kind() == reflect.Slice {
+		if rt.Elem().Kind() == reflect.Uint8 {
+			return topLevelKeys(reflect.ValueOf(resp).Bytes()) // []byte payloads
+		}
+		rt = rt.Elem()
+	}
+	if rt.Kind() == reflect.Ptr {
+		rt = rt.Elem()
+	}
+	if rt.Kind() != reflect.Struct {
+		t.Fatalf("schema response %T: unsupported kind %s (use a struct, slice of struct, or json.RawMessage)", resp, rt.Kind())
+	}
+	b, err := json.Marshal(reflect.New(rt).Interface())
+	if err != nil {
+		t.Fatalf("marshal schema response %T: %v", resp, err)
+	}
+	return topLevelKeys(b)
+}
+
+func sortedKeys(m map[string]bool) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	// deterministic order for stable failure messages
+	for i := 1; i < len(out); i++ {
+		for j := i; j > 0 && out[j] < out[j-1]; j-- {
+			out[j], out[j-1] = out[j-1], out[j]
+		}
+	}
+	return out
+}
+
+// Sanity: the extraction itself must find the pilot routes, otherwise the
+// gate would pass vacuously if the parser ever broke.
+func TestRouteExtractionFindsPilots(t *testing.T) {
+	routes := extractRoutesFromRouterSource(t)
+	for _, key := range []string{
+		"POST /api/collections",
+		"GET /api/collections",
+		"GET /api/collections/:id",
+		"PUT /api/collections/:id",
+		"DELETE /api/collections/:id",
+		"GET /api/admin/hash-conflicts",
+		"POST /api/admin/hash-conflicts/:id/resolve",
+		"POST /api/sync/kobo/:token/markup",
+		"POST /api/auth/login",
+	} {
+		if _, ok := routes[key]; !ok {
+			t.Errorf("route extraction missing %q (parser drift — fix extractRoutesFromRouterSource, do not edit docs to match)", key)
+		}
+	}
+	if label := authLabel(routes["GET /api/admin/hash-conflicts"].middleware); label != "jwt+admin" {
+		t.Errorf("hash-conflicts auth label = %q, want jwt+admin", label)
+	}
+	if label := authLabel(routes["POST /api/sync/kobo/:token/markup"].middleware); label != "device-token" {
+		t.Errorf("kobo markup auth label = %q, want device-token", label)
+	}
+	if label := authLabel(routes["POST /api/auth/login"].middleware); label != "none" {
+		t.Errorf("login auth label = %q, want none (public, rate-limited)", label)
+	}
+}

internal/docs/frontmatter.go

@@ -0,0 +1,146 @@
+package docs
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// DocFrontmatter is the machine-readable identity header of an API doc page.
+// It is the contract the drift gate (drift_test.go) checks against the real
+// router registrations and the schema registry (schema.go).
+type DocFrontmatter struct {
+	Method string // GET|POST|PUT|PATCH|DELETE
+	Path   string // Echo syntax, e.g. /api/collections/:id
+	Auth   string // none|jwt|jwt+admin|device-token|optional-jwt
+	Area   string // sidebar area, e.g. collections
+}
+
+// APIDoc is one endpoint doc file: its frontmatter plus the labeled example
+// blocks extracted from the body.
+type APIDoc struct {
+	RelPath            string
+	Frontmatter        DocFrontmatter
+	ExampleRequest     []byte
+	ExampleResponse    []byte
+	HasExampleResponse bool
+	Unverified         []string // UNVERIFIED markers found in the body
+}
+
+// parseFrontmatter splits a leading "---" delimited block of flat key:value
+// lines off content. Recognized keys: method, path, auth, area. Returns the
+// frontmatter and the remaining body; hasFM is false when no well-formed
+// block is present (prose pages like overviews have none and are skipped by
+// the gate).
+func parseFrontmatter(content string) (fm DocFrontmatter, body string, hasFM bool) {
+	lines := strings.Split(content, "\n")
+	if len(lines) == 0 || strings.TrimSpace(lines[0]) != "---" {
+		return fm, content, false
+	}
+	end := -1
+	for i := 1; i < len(lines); i++ {
+		if strings.TrimSpace(lines[i]) == "---" {
+			end = i
+			break
+		}
+	}
+	if end == -1 {
+		return fm, content, false
+	}
+
+	for _, line := range lines[1:end] {
+		key, value, ok := strings.Cut(line, ":")
+		if !ok {
+			continue
+		}
+		key = strings.ToLower(strings.TrimSpace(key))
+		value = strings.TrimSpace(value)
+		switch key {
+		case "method":
+			fm.Method = strings.ToUpper(value)
+		case "path":
+			fm.Path = value
+		case "auth":
+			fm.Auth = strings.ToLower(value)
+		case "area":
+			fm.Area = strings.ToLower(value)
+		}
+	}
+	if fm.Method == "" || fm.Path == "" {
+		return fm, content, false // identity is the minimum for a gateable doc
+	}
+	return fm, strings.Join(lines[end+1:], "\n"), true
+}
+
+// extractExampleBlocks pulls fenced code blocks tagged
+// "json example-request" / "json example-response" out of a doc body, and
+// counts UNVERIFIED markers.
+func extractExampleBlocks(body string, doc *APIDoc) {
+	lines := strings.Split(body, "\n")
+	for i := 0; i < len(lines); i++ {
+		fence := strings.TrimSpace(lines[i])
+		switch {
+		case fence == "```json example-request":
+			doc.ExampleRequest = extractUntilClose(lines, i+1)
+			i = skipBlock(lines, i+1)
+		case fence == "```json example-response":
+			doc.ExampleResponse = extractUntilClose(lines, i+1)
+			doc.HasExampleResponse = true
+			i = skipBlock(lines, i+1)
+		}
+		if strings.Contains(lines[i], "UNVERIFIED:") {
+			doc.Unverified = append(doc.Unverified, strings.TrimSpace(lines[i]))
+		}
+	}
+}
+
+func extractUntilClose(lines []string, start int) []byte {
+	var b strings.Builder
+	for i := start; i < len(lines); i++ {
+		if strings.TrimSpace(lines[i]) == "```" {
+			break
+		}
+		b.WriteString(lines[i])
+		b.WriteString("\n")
+	}
+	return []byte(b.String())
+}
+
+// skipBlock returns the index of the closing fence line so the outer loop
+// resumes after it.
+func skipBlock(lines []string, start int) int {
+	for i := start; i < len(lines); i++ {
+		if strings.TrimSpace(lines[i]) == "```" {
+			return i
+		}
+	}
+	return len(lines) - 1
+}
+
+// LoadAPIDocs walks dir recursively and returns every markdown file carrying
+// well-formed endpoint frontmatter. Prose pages (overviews, contracts) are
+// skipped: the gate only checks docs that claim to describe an endpoint.
+func LoadAPIDocs(dir string) ([]APIDoc, error) {
+	var docs []APIDoc
+	err := filepath.WalkDir(dir, func(path string, d os.DirEntry, err error) error {
+		if err != nil || d.IsDir() || !strings.HasSuffix(path, ".md") {
+			return err
+		}
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return err
+		}
+		fm, body, hasFM := parseFrontmatter(string(raw))
+		if !hasFM {
+			return nil
+		}
+		doc := APIDoc{
+			RelPath:     path,
+			Frontmatter: fm,
+		}
+		extractExampleBlocks(body, &doc)
+		docs = append(docs, doc)
+		return nil
+	})
+	return docs, err
+}

internal/docs/schema.go

@@ -0,0 +1,72 @@
+package docs
+
+import (
+	"encoding/json"
+
+	"bookhoard/internal/handlers"
+)
+
+// Schema pins the machine-checkable contract for one route. The drift gate
+// (drift_test.go) validates every frontmatter'd doc against the entry for its
+// "METHOD path" key.
+//
+// MAINTENANCE CONTRACT: every doc with frontmatter MUST have a registry
+// entry, and every new/changed route that ships a frontmatter'd doc updates
+// its entry in the same commit. The gate fails loudly on a missing entry —
+// that is the discipline, not an inconvenience.
+//
+// Request: the struct the handler Binds into (nil for bodyless routes).
+//   - example-request is decoded with unknown fields DISALLOWED (typo guard)
+//   - fields whose validate tag contains "required" must appear in the
+//     example (staleness guard)
+//
+// Response: what the handler passes to c.JSON.
+//   - struct / slice of struct: marshaled and its TOP-LEVEL key set compared
+//     against example-response in both directions
+//   - json.RawMessage: hand-built map responses pin their key set as a
+//     sample; promote to a struct when the endpoint is next touched
+//   - zero value (Schema{}): no JSON body expected (e.g. 204) — the doc must
+//     not carry an example-response block
+type Schema struct {
+	Request  any
+	Response any
+}
+
+// Schemas is keyed by "METHOD path" in Echo syntax. Sample values inside
+// RawMessage pins use empty strings / zero values — only the KEY SET is
+// checked, never the values.
+var Schemas = map[string]Schema{
+	// --- collections (pilot area) ---
+	"POST /api/collections": {
+		Request: handlers.CreateCollectionRequest{},
+		Response: json.RawMessage(`{
+			"id": "", "user_id": "", "name": "", "description": "",
+			"color": "", "icon": "", "collection_type": "",
+			"auto_assign_rules": null, "view_settings": {},
+			"book_count": 0, "created_at": ""
+		}`),
+	},
+	"GET /api/collections": {
+		Response: struct {
+			Collections []handlers.CollectionSummary `json:"collections"`
+			Total       int                          `json:"total"`
+		}{},
+	},
+	"GET /api/collections/:id": {
+		Response: json.RawMessage(`{
+			"id": "", "user_id": "", "name": "", "description": "",
+			"color": "", "icon": "", "auto_assign_rules": null,
+			"view_settings": {}, "books": [], "book_count": 0,
+			"is_smart": false, "up_next": [], "created_at": ""
+		}`),
+	},
+	"PUT /api/collections/:id": {
+		Request: handlers.UpdateCollectionRequest{},
+		Response: json.RawMessage(`{
+			"id": "", "user_id": "", "name": "", "description": "",
+			"color": "", "icon": "", "auto_assign_rules": null,
+			"view_settings": {}, "created_at": ""
+		}`),
+	},
+	"DELETE /api/collections/:id": {},
+}

internal/handlers/collections.go

@@ -75,6 +75,30 @@ type UpdateDeviceMappingRequest struct {
 	SyncDirection   string `json:"sync_direction" validate:"required,oneof=bidirectional book_to_device device_to_book none"`
 }
 
+// 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 {
+	ID              uuid.UUID       `json:"id"`
+	Name            string          `json:"name"`
+	Description     string          `json:"description"`
+	Color           string          `json:"color"`
+	Icon            string          `json:"icon"`
+	AutoAssignRules json.RawMessage `json:"auto_assign_rules"`
+	CreatedAt       string          `json:"created_at"`
+	BookCount       int             `json:"book_count"`
+	IsSmart         bool            `json:"is_smart"`
+}
+
+// BookCollectionSummary is one entry in GET /api/collections/:id/books —
+// the collections a book belongs to (list view: no rules/count fields).
+type BookCollectionSummary struct {
+	ID          uuid.UUID `json:"id"`
+	Name        string    `json:"name"`
+	Description string    `json:"description"`
+	Color       string    `json:"color"`
+	Icon        string    `json:"icon"`
+}
+
 type SectionData struct {
 	ID           string     `json:"id"`
 	CollectionID string     `json:"collection_id"`
@@ -160,19 +184,7 @@ func (h *CollectionHandler) GetCollections(c *echo.Context) error {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
 	}
 
-	type CollectionResponse struct {
-		ID              uuid.UUID       `json:"id"`
-		Name            string          `json:"name"`
-		Description     string          `json:"description"`
-		Color           string          `json:"color"`
-		Icon            string          `json:"icon"`
-		AutoAssignRules json.RawMessage `json:"auto_assign_rules"`
-		CreatedAt       string          `json:"created_at"`
-		BookCount       int             `json:"book_count"`
-		IsSmart         bool            `json:"is_smart"`
-	}
-
-	response := make([]CollectionResponse, 0, len(collections))
+	response := make([]CollectionSummary, 0, len(collections))
 	for _, col := range collections {
 		isSmart := h.collectionService.IsSmartCollection(col.AutoAssignRules)
 		if !includeAuto && isSmart {
@@ -211,7 +223,7 @@ func (h *CollectionHandler) GetCollections(c *echo.Context) error {
 			}
 		}
 
-		response = append(response, CollectionResponse{
+		response = append(response, CollectionSummary{
 			ID:              col.ID.Bytes,
 			Name:            col.Name,
 			Description:     utils.PgTextString(col.Description),
@@ -768,17 +780,9 @@ func (h *CollectionHandler) GetBookCollections(c *echo.Context) error {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
 	}
 
-	type CollectionResponse struct {
-		ID          uuid.UUID `json:"id"`
-		Name        string    `json:"name"`
-		Description string    `json:"description"`
-		Color       string    `json:"color"`
-		Icon        string    `json:"icon"`
-	}
-
-	response := make([]CollectionResponse, 0, len(collections))
+	response := make([]BookCollectionSummary, 0, len(collections))
 	for _, col := range collections {
-		response = append(response, CollectionResponse{
+		response = append(response, BookCollectionSummary{
 			ID:          col.ID.Bytes,
 			Name:        col.Name,
 			Description: utils.PgTextString(col.Description),