docs: describe the themed login pages and messages

AGENTS.md

@@ -24,8 +24,8 @@ Online Mancala (the Turkish *Mangala* rules) with a web app, an Android/iOS app
 Specs that exist: `keycloak-auth` (login, guests, tokens), `game-history` (saved games, live games, replay),
 `game-clock` (5 minutes per player, ending games on time), `web-redesign` (the web app's look: themes, board,
 pages), `quarkus-backend` (the backend's move from Node to Java and Quarkus), `game-bot` (playing against a bot
-at four levels), `tutorial` (rules page, lessons, hints in bot games) and `rematch` (rematches, alternating first
-moves, the series strip).
+at four levels), `tutorial` (rules page, lessons, hints in bot games), `rematch` (rematches, alternating first
+moves, the series strip) and `theme-polish` (the login pages in the app's themes, the web app's messages).
 
 ## Running locally
 
@@ -142,9 +142,11 @@ which helps to check what the server holds.
 - The guest authenticator uses an internal Keycloak SPI: keep the version in `extension/pom.xml` and `Dockerfile` in
   sync and run `mvn test` when upgrading.
 - Keycloak sets `Secure` cookies; browsers send them to `http://localhost`, simple HTTP clients do not.
-- The login theme (`apps/keycloak/themes/mancala`) is only CSS on top of `keycloak.v2`. Keycloak in `start` mode caches
-  themes and keeps gzipped resources in `data/tmp/kc-gzip-cache` across restarts; see `apps/keycloak/README.md` for
-  reloading it in a running container.
+- The login theme (`apps/keycloak/themes/mancala`) is CSS and one script on top of `keycloak.v2`. The script takes the
+  theme from the `mancala_theme` cookie the web app writes (`saveThemeCookie`); the three themes' colors are copied
+  from `apps/frontend/src/styles/app.css`, so change both. Keycloak in `start` mode caches themes and keeps gzipped
+  resources in `data/tmp/kc-gzip-cache` across restarts; see `apps/keycloak/README.md` for reloading it in a running
+  container.
 
 **Mobile**
 - `apps/mobile/release_android.sh` contains signing passwords (see `TODO.md`); do not copy them anywhere.

TODO.md

@@ -35,7 +35,6 @@ The web app has game history (see `docs/specs/game-history`); the mobile app nee
 - [ ] Statistics for logged in users (wins, losses), now that games are saved
 - [ ] Social logins (Keycloak identity providers)
 - [ ] Keycloak email theme in the game's look (password reset emails still use Keycloak's)
-- [ ] Login pages follow the system color scheme; they could follow the theme chosen in the app instead
 - [ ] Restrict the Keycloak admin console in production
 
 ## Game history

apps/keycloak/README.md

@@ -35,11 +35,18 @@ console too, or delete the realm and restart Keycloak.
 
 ## Login theme
 
-`themes/mancala/login` gives the login, registration and password reset pages the game's look: its app bar and logo,
-the board's colors and a board with stones on top of the card. It extends Keycloak's `keycloak.v2` theme and only
-adds `resources/css/mancala.css`, so its templates and behaviour stay Keycloak's own and upgrades need no template
-changes. The colors come from `LightTheme` and `DarkTheme` in `packages/core/src/theme`; the dark ones are used when
-the system prefers a dark color scheme. The realm turns the theme on (`loginTheme`) and offers English and Turkish;
+`themes/mancala/login` gives the login, registration and password reset pages the web app's look in its three themes
+(Ceviz, Gece, Yeşim): its header, logo and name, font, cards, fields, pill buttons and a board with stones on top of
+the card (`docs/specs/theme-polish`). It extends Keycloak's `keycloak.v2` theme and only adds
+`resources/css/mancala.css` and `resources/js/theme.js`, so its templates and behaviour stay Keycloak's own and
+upgrades need no template changes.
+
+The script runs in the page's head and puts the theme's class (`t-ceviz`, `t-gece`, `t-yesim`) on `<html>`: the
+theme the player chose in the web app, which the app keeps in the `mancala_theme` cookie (shared by `localhost`'s
+ports, and set for `playmancala.app` so `auth.playmancala.app` gets it), or else Ceviz for a dark system color scheme
+and Yeşim for a light one. Keycloak's own dark mode is off (`darkMode=false`); the script adds PatternFly's
+`pf-v5-theme-dark` for the dark themes. The themes' colors are copied from `apps/frontend/src/styles/app.css`; the logo
+and the board are masks (`img/*-mask.svg`) filled with them. The realm turns the theme on (`loginTheme`) and offers English and Turkish;
 the web app passes its language as `ui_locales`.
 
 To try a change without rebuilding the image, copy the theme into the running container, clear Keycloak's gzip cache

docs/specs/theme-polish/requirements.md

@@ -1,6 +1,6 @@
 # Theme polish: requirements
 
-Status: in progress, on branch `feature/theme-polish` (based on `develop`).
+Status: implemented on branch `feature/theme-polish` (based on `develop`); checked in Chrome against the local stack.
 Scope: the Keycloak login theme and the web app's short messages. Follows `web-redesign`.
 
 ## Goals

docs/specs/theme-polish/tasks.md

@@ -7,4 +7,4 @@ Work through the tasks in order; each ends with its checks passing and a commit.
 - [x] 3. **Theme cookie**: the web app saves the chosen theme for the login pages.
 - [x] 4. **Login theme**: the script, the three themes' styles, logo and board masks; checked in Chrome in all three
       themes, at desktop and phone width, with and without the cookie.
-- [ ] 5. **Docs**: `AGENTS.md` (specs list, the cookie), `apps/keycloak/README.md`, `TODO.md`.
+- [x] 5. **Docs**: `AGENTS.md` (specs list, the cookie), `apps/keycloak/README.md`, `TODO.md`.