Update API and spec for linked voting

API.md

@@ -1,38 +1,39 @@
-# API Contract (Auth-enabled)
+# API Contract (auth-enabled)
 
-All endpoints are JSON. Most routes require the HttpOnly cookie `player`, which is issued after successful register/login. Legacy player rows are given `legacy-xxxxxxxx` usernames during migration; they must register/login to get a valid auth cookie.
+All endpoints are JSON. Most routes require the HttpOnly `player` cookie issued after register/login. Admin access is granted via authenticated admin user or `X-Admin-Key`/`key` matching `ADMIN_PASSWORD`.
 
 ## Auth
-POST /api/auth/register  
+POST /api/auth/register — accepts optional `adminKey` to set `IsAdmin=true`  
 POST /api/auth/login  
 POST /api/auth/logout
 
-- Register accepts optional `adminKey`; when it matches `ADMIN_PASSWORD`, the account is marked `IsAdmin=true` and can use admin APIs. If an `adminKey` is supplied but wrong (or ADMIN_PASSWORD unset), registration returns 400.
-
-## State
-GET /api/state (public)
+## State (requires auth)
+GET /api/state — returns currentPhase (for caller), votesFinal, resultsOpen, updatedAt, counts (players/suggestions/votes)  
+GET /api/me — id, displayName, username, isAdmin, currentPhase, votesFinal
 
 ## Player (requires auth)
-GET /api/me  (returns id, displayName, username, isAdmin)  
-POST /api/me/name
+POST /api/me/name — set display name (max 16 chars)  
+POST /api/me/phase/next — advance caller to next phase (Suggest→Vote→Results; Results gated by resultsOpen)  
+POST /api/me/phase/prev — admin-only move caller backward (Results→Vote→Suggest)
 
 ## Suggestions (requires auth + phase gating)
-GET /api/suggestions/mine  
-POST /api/suggestions  
-DELETE /api/suggestions/{id}  
-PUT /api/suggestions/{id} (non-admin: own suggestion, Suggest phase only; admin: any time, any suggestion)  
-GET /api/suggestions/all
+GET /api/suggestions/mine — own suggestions (Suggest phase)  
+POST /api/suggestions — create (name required ≤100; max 5 per player; validates screenshot URL)  
+PUT /api/suggestions/{id} — update (non-admin: own suggestion; title locked after Suggest)  
+DELETE /api/suggestions/{id} — delete (non-admin only in Suggest; admin any time)  
+GET /api/suggestions/all — all suggestions (from Vote onward), includes author, link metadata
 
-## Votes (requires auth + phase gating)
+## Votes (requires auth + Vote phase)
 GET /api/votes/mine  
-POST /api/votes
+POST /api/votes — upsert vote; if suggestion is in a linked group, applies the same score to all linked siblings  
+POST /api/votes/finalize — `{ final: bool }` toggles caller’s finalized status (blocks further vote edits when true)
 
-## Results (requires auth + phase gating)
-GET /api/results
+## Results (requires auth + Results phase + resultsOpen)
+GET /api/results — leaderboard with totals, counts, averages, caller’s vote, media/links, link metadata
 
-## Admin (requires admin account or admin key)
-POST /api/admin/phase  
-POST /api/admin/reset  
-POST /api/admin/factory-reset  
-
-Admin APIs accept either an authenticated admin user (cookie) or, for compatibility, `X-Admin-Key`/`key` matching `ADMIN_PASSWORD`.
+## Admin (admin auth or admin key)
+POST /api/admin/results — `{ resultsOpen: bool }` locks/unlocks results and aligns player phases  
+GET  /api/admin/vote-status — readiness overview (who finalized)  
+POST /api/admin/link-suggestions — `{ sourceSuggestionId, targetSuggestionId }`; merges vote groups during Vote, clears votes in the linked group, unfinalizes affected players  
+POST /api/admin/reset — clear suggestions/votes; keep players; reset phases/vote-final flags  
+POST /api/admin/factory-reset — wipe players, suggestions, votes, state