fix: note the library-list scan cap; preset-cap note only with presets (M-11, M-12)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

src/Integrations/Divi/Library/LibraryListAbility.php

@@ -105,6 +105,7 @@ final class LibraryListAbility implements Ability
                 'affected' => ['type' => 'array', 'items' => ['type' => 'object']],
                 'affected_count' => ['type' => 'integer'],
                 'hidden_count' => ['type' => 'integer'],
+                'notes' => ['type' => 'array', 'items' => ['type' => 'string']],
             ],
             'required' => ['items', 'next_cursor'],
         ];
@@ -174,7 +175,7 @@ final class LibraryListAbility implements Ability
      * null when no readable entry follows (or the scan cap is reached with nothing found).
      *
      * @param array<string, string|int> $filters
-     * @return array{items: list<array<string, mixed>>, next_cursor: ?string}
+     * @return array{items: list<array<string, mixed>>, next_cursor: ?string, notes?: list<string>}
      */
     private function page(array $filters, int $limit, int $skip): array
     {
@@ -199,7 +200,19 @@ final class LibraryListAbility implements Ability
             }
         }
 
-        return ['items' => $items, 'next_cursor' => $items === [] ? null : Cursor::encode($skip + count($items))];
+        // Review M-12: say why the page is short, so the client neither thinks the list ended nor loops.
+        return [
+            'items' => $items,
+            'next_cursor' => $items === [] ? null : Cursor::encode($skip + count($items)),
+            'notes' => [sprintf(
+                'Nach %d gelesenen Bibliothekseinträgen abgebrochen (Einträge ohne Bearbeitungsrecht werden '
+                    . 'übersprungen); %s',
+                self::MAX_SCAN,
+                $items === []
+                    ? 'weitere Einträge mit Filtern (layout_type, scope, search, category) eingrenzen.'
+                    : 'mit next_cursor weiterblättern oder mit Filtern eingrenzen.'
+            )],
+        ];
     }
 
     /**