feat(library): let auditors merge duplicate games

An auditor merges a game added by hand into its Steam game or another
game added by hand (V21). Every user's row moves; a user with both rows
keeps one, with the status, rating and notes set by hand. game_alias
sends later adds to the kept key, and admin_audit logs who merged what.
The game search shows games already in ToBePlayed first.

readme.md

@@ -96,6 +96,7 @@ method calling another service's method that needs more.
 | `GET` | `/api/library/games`, `/api/library/games/{appid}` | JWT |
 | `PUT` | `/api/library/games/{appid}/backlog` | JWT |
 | `PUT`, `DELETE` | `/api/library/games/{appid}/corrections/{field}` (`{value}`; `name`, `image`, `speedrun`, `moods`, `endless`, `genres`; `204`, `400 INVALID_CORRECTION`) | JWT, AUDITOR |
+| `POST` | `/api/library/games/{appid}/merge` (`{otherAppid}`; `200 {appid}` = the key that stays, `400 SAME_GAME` / `STEAM_GAMES`, `404 GAME_NOT_FOUND`) | JWT, AUDITOR |
 | `PUT` | `/api/library/games/{appid}/status` (status only, keeps rating, notes, priority) | JWT |
 | `PUT` | `/api/library/games/{appid}/finished-hint` (`{dismissed: ENDING\|PLAYTIME}`, "Not yet"; `204`) | JWT |
 | `PUT` | `/api/library/games/{appid}/hidden` (`{hidden}`; `409 MANUAL_GAME` for a game added by hand) | JWT |
@@ -218,6 +219,24 @@ lets the next refresh ask IGDB or speedrun.com again. An image must be on a host
 Known limit: a mood or speedrun refresh that waits on the row lock while an auditor saves can still write the
 source value once (its guard sees the state from before the save); the auditor saves again.
 
+### Merging duplicates
+
+One game can have two keys: a Steam appid and minus its IGDB id, or two IGDB ids. An AUDITOR merges them for every
+user (`GameMergeService`, V21). The key off Steam always goes into the other one; two Steam appids are refused,
+since the sync would bring both back. In one transaction:
+
+- A user with only the old row: the row moves to the new key with its status history (FK `ON UPDATE CASCADE`).
+- A user with both rows: one row stays on the new key. Status, rating, notes and priority come from the row whose
+  current status the user chose (both: the one chosen last); a gap is filled from the other row. Source, platform and playtime stay, unless the
+  Steam copy is no longer owned. Both status histories stay; the merge itself logs no status change.
+- The shared rows of the old key (catalog row, moods, speedrun, time to beat, corrections, broken images) are
+  deleted.
+- `game_alias` points the old key to the new one (kept flat), so a later add of the old IGDB game lands on the new
+  key. `admin_audit` gets one `GAME_MERGE` row: who, both keys, both names and how many rows moved or were combined.
+
+There is no undo. The game search shows games already in ToBePlayed first, with their catalog name and image, and
+games other users added by hand that IGDB did not return; `inCatalog` marks both (only those can be merged).
+
 ### Deleted accounts
 
 Auth drives it (see Auth's readme). `POST /internal/accounts/deleted` adds a tombstone in `deleted_user`: the user
@@ -240,7 +259,8 @@ one exception: when the user later owns the game on Steam under the same appid,
 `STEAM`, and status, rating and notes stay. Only `MANUAL` rows can be edited (`PUT /api/library/games/{appid}/manual`)
 or deleted (`DELETE /api/library/games/{appid}`). Time to beat uses the Steam appid for positive keys and the IGDB
 id for negative keys. Search and add check both keys of a game. A game added under minus its IGDB id can still get
-a second row when IGDB learns its Steam appid later and the user owns it on Steam.
+a second row when IGDB learns its Steam appid later and the user owns it on Steam; an auditor then merges the two
+(see "Merging duplicates").
 
 ## Run locally