feat(media): pagination

docs/api.md

@@ -97,10 +97,20 @@ try again."; the text of the error never reaches the event, the API or the CSV.
 codes, article bodies, file bytes, storage paths and asset urls are never recorded.
 
 Article routes accept `?format=markdown|html|json` (default `markdown`). `GET /v1/media/` accepts
-`q`, `hash`, `cursor`, `filter`, `sort` (`newest`, `oldest`, `name`, `largest` or `total_size`, the
-original plus its generated variants), `variants` (`with` or `without` generated variant files) and
-`limit`. Every item carries `variant_count` and `variant_size` (the index rows of the image and
-their bytes, 0 when none); `counts` stays library-wide. Any other `variants` or `sort` value is 400.
+`q`, `hash`, `filter` (`all`, `unused` or `duplicates`), `sort` (`newest`, `oldest`, `name`,
+`largest` or `total_size`, the original plus its generated variants), `variants` (`with` or
+`without` generated variant files), `page` (a whole number from 1, default 1) and `size` (5, 25, 50
+or 100, default 25). The body is `{ "items": [...], "total", "page", "size", "counts" }`: `total` is
+the number of images matching `q`, `hash`, `filter` and `variants` before paging, `page` and `size`
+echo the values applied, and `counts` (`all`, `unused`, `duplicates`) stays library-wide, ignoring
+every filter and the paging. Ordering is applied to the whole matching list before slicing, with the
+image id as the final tie-break, so pages never overlap or skip. A page past the last answers 200
+with `items: []` and the real `total`. Any invalid `page`, `size`, `filter`, `sort`, `variants` or
+`hash` is 400 "The media query is invalid.". Every item carries `variant_count` and `variant_size`
+(the index rows of the image and their bytes, 0 when none).
+
+Breaking change: `next_cursor` is gone and no `X-Total-Count` header is sent. `cursor` and `limit`
+are no longer parameters; they are ignored, never an error, and have no effect on paging.
 
 ## Image variants
 Owners and admins manage named variants of the stored images. These routes are session only (no API