feat(picker): mix similar, longest waiting and random picks

Picker slots rotate three sources: backlog games that share moods with
one of the top 5 played games, oldest first seen, and random. Each game
carries a reason (source, anchor game, first seen). Empty slots fall
back to random. Issue #28.

readme.md

@@ -21,9 +21,22 @@ To Be Played is split into three repositories:
   can be taken over; its own finish then changes nothing.
 - **Backlog**: status (`BACKLOG`, `PLAYING`, `FINISHED`, `COMPLETED` = 100 %, `DROPPED`), rating 1–5, notes, priority,
   filters and sorting. "Pile of Shame" summary with a random suggestion of what to play.
-- **Picker**: up to 10 random backlog games for a time budget (IGDB normal time to beat) and a mood, HIGH priority
-  first, then MEDIUM, then the rest. Games already shown can be excluded for a reroll. Moods `STORY`, `COOP`,
+- **Picker**: up to 10 backlog games for a time budget (IGDB normal time to beat) and a mood, mixed from three
+  sources, one per slot in turn: a game sharing moods with a random one of the user's 5 most played games (the
+  most shared moods first), the game waiting longest (oldest `firstSeenAt`), and a random one (HIGH priority first,
+  then MEDIUM, then the rest). A source with nothing left gives its slot to a random game; no game appears twice.
+  Every game carries a `reason` (`source`, plus the anchor game for `SIMILAR` or `firstSeenAt` for `LONGEST`).
+  Games already shown can be excluded for a reroll. Moods `STORY`, `COOP`,
   `CHILL`, `ACTION`, `SCARY` come from IGDB genres, themes and game modes; `SPEEDRUN` from speedrun.com.
+
+  ```mermaid
+  flowchart LR
+      A["anchor: random of top 5 played"] --> S[similar]
+      S --> M["PickMix: rotate, dedupe, random fallback"]
+      L[longest waiting] --> M
+      R[random] --> M
+      M --> O["games + reason"]
+  ```
 - **Speedrun games**: a backlog game counts as a speedrun game when speedrun.com has a game with the same name (and
   a release year at most one year off, when IGDB knows it) with at least one verified run. The game detail returns
   the speedrun.com link as `speedrunUrl`. speedrun.com has no Steam or IGDB link and no key, so one queue works for
@@ -168,7 +181,7 @@ ArchUnit role rules (`RoleAnnotationRules`) and `src/test/resources/contract/aut
 | `GET`, `DELETE` | `/api/library/imports/{id}/undo-check` (`{games, changed}`), `/api/library/imports/{id}/games` (undo; `204`, `409 IMPORT_NOT_SAVED`) | JWT |
 | `POST` | `/api/library/sync` | JWT |
 | `POST` | `/api/library/broken-images` (`{appid, kind}`, kind `COVER` or `ACHIEVEMENT_ICONS`; `204`) | JWT |
-| `GET` | `/api/library/picker?maxMinutes=&mood=&count=&exclude=` | JWT |
+| `GET` | `/api/library/picker?maxMinutes=&mood=&count=&exclude=` (each game has a `reason` object) | JWT |
 | `GET` | `/api/library/stats?groups=` (`OVERVIEW`, `PILE`, `TOP_GAMES`, `TASTE`, `HABITS`, `FINISHED`, `TREND`, `PLATFORMS`; none = all) | JWT |
 | `GET` | `/api/library/stats/games?key=&arg=&page=` (the games behind a stats number; `400 BAD_ARG`) | JWT |
 | `GET` | `/api/library/achievements/summary` | JWT |