fix(ci): collapse multi-line Python to one-liner to fix YAML block scalar indentation error

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitea/workflows/android-release.yml

@@ -0,0 +1,109 @@
+name: Android Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+env:
+  APK_OUT: target/release/apk/ferrous-solitaire.apk
+  GITEA_URL: https://git.aleshym.co
+  REPO: funman300/Ferrous-Solitaire
+
+jobs:
+  build-apk:
+    runs-on: ubuntu-latest
+    container:
+      image: git.aleshym.co/funman300/android-builder:latest
+      credentials:
+        username: ${{ gitea.actor }}
+        password: ${{ secrets.CI_TOKEN }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Cache Cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            /usr/local/cargo/registry/index
+            /usr/local/cargo/registry/cache
+            /usr/local/cargo/git/db
+          key: cargo-registry-android-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: cargo-registry-android-
+
+      - name: Cache sccache
+        uses: actions/cache@v4
+        with:
+          path: /root/.cache/sccache
+          key: sccache-android-aarch64-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: sccache-android-aarch64-
+
+      - name: Get tag name
+        id: tag
+        run: echo "name=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+
+      - name: Decode release keystore
+        run: echo "${{ secrets.RELEASE_KEYSTORE_B64 }}" | base64 -d > release.jks
+
+      - name: Build release APK
+        env:
+          PROFILE: release
+          ABIS: arm64-v8a
+          KEYSTORE: ./release.jks
+          KEYSTORE_PASS: ${{ secrets.RELEASE_KEYSTORE_PASS }}
+          KEY_ALIAS: release
+          KEY_PASS: ${{ secrets.RELEASE_KEYSTORE_PASS }}
+          VERSION_NAME: ${{ steps.tag.outputs.name }}
+          RUSTC_WRAPPER: sccache
+          SCCACHE_DIR: /root/.cache/sccache
+        run: bash scripts/build_android_apk.sh
+
+      - name: sccache stats
+        if: always()
+        run: sccache --show-stats
+
+      - name: Create or get Gitea release
+        id: release
+        run: |
+          TAG="${{ steps.tag.outputs.name }}"
+          BASE="${{ env.GITEA_URL }}/api/v1/repos/${{ env.REPO }}"
+          AUTH="Authorization: token ${{ secrets.CI_TOKEN }}"
+
+          ID=$(curl -sf -H "$AUTH" "$BASE/releases/tags/$TAG" \
+               | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))" \
+               2>/dev/null || true)
+
+          if [ -z "$ID" ]; then
+            ID=$(curl -sf -X POST \
+                 -H "$AUTH" -H "Content-Type: application/json" \
+                 "$BASE/releases" \
+                 -d "{
+                   \"tag_name\": \"$TAG\",
+                   \"name\": \"$TAG\",
+                   \"body\": \"## Android release $TAG\n\n**Install / update with Obtainium** — add this source URL:\n\`\`\`\nhttps://git.aleshym.co/funman300/Ferrous-Solitaire\n\`\`\`\n\nOr download \`ferrous-solitaire.apk\` below and sideload it directly.\",
+                   \"draft\": false,
+                   \"prerelease\": false
+                 }" \
+                 | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+          fi
+          echo "id=$ID" >> "$GITHUB_OUTPUT"
+
+      - name: Upload APK to release
+        run: |
+          BASE="${{ env.GITEA_URL }}/api/v1/repos/${{ env.REPO }}"
+          AUTH="Authorization: token ${{ secrets.CI_TOKEN }}"
+          RELEASE_ID="${{ steps.release.outputs.id }}"
+
+          # Remove any existing APK assets so re-runs don't accumulate duplicates.
+          curl -sf -H "$AUTH" "$BASE/releases/$RELEASE_ID/assets" \
+            | python3 -c "import sys,json; [print(a['id']) for a in json.load(sys.stdin) if a['name'].endswith('.apk')]" \
+            | while read AID; do
+                curl -sf -X DELETE -H "$AUTH" "$BASE/releases/$RELEASE_ID/assets/$AID"
+              done
+
+          curl -sf -X POST \
+            -H "$AUTH" \
+            -F "attachment=@${{ env.APK_OUT }};type=application/vnd.android.package-archive" \
+            "$BASE/releases/$RELEASE_ID/assets"

.gitea/workflows/builder-image.yml

@@ -0,0 +1,41 @@
+name: Build Android Builder Image
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'docker/android-builder.Dockerfile'
+      - '.gitea/workflows/builder-image.yml'
+
+env:
+  IMAGE: git.aleshym.co/funman300/android-builder
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Log in to Gitea registry
+        uses: docker/login-action@v3
+        with:
+          registry: git.aleshym.co
+          username: ${{ gitea.actor }}
+          password: ${{ secrets.CI_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver-opts: network=host
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: docker/android-builder.Dockerfile
+          push: true
+          tags: ${{ env.IMAGE }}:latest
+          cache-from: type=registry,ref=${{ env.IMAGE }}:buildcache
+          cache-to: type=registry,ref=${{ env.IMAGE }}:buildcache,mode=max

.gitea/workflows/docker-build.yml

@@ -0,0 +1,78 @@
+name: Build and Deploy
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'solitaire_server/**'
+      - 'solitaire_sync/**'
+      - 'solitaire_core/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - '.gitea/workflows/docker-build.yml'
+
+env:
+  REGISTRY: git.aleshym.co
+  IMAGE: git.aleshym.co/funman300/solitaire-server
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Need full history so we can push the tag-update commit back.
+          fetch-depth: 0
+          token: ${{ secrets.CI_TOKEN }}
+
+      - name: Set image tag
+        id: meta
+        run: echo "sha=${GITHUB_SHA::8}" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Gitea registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ gitea.actor }}
+          password: ${{ secrets.CI_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver-opts: network=host
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: solitaire_server/Dockerfile
+          push: true
+          tags: |
+            ${{ env.IMAGE }}:${{ steps.meta.outputs.sha }}
+            ${{ env.IMAGE }}:latest
+          cache-from: type=registry,ref=${{ env.IMAGE }}:buildcache
+          cache-to: type=registry,ref=${{ env.IMAGE }}:buildcache,mode=max
+
+      - name: Install kustomize
+        run: |
+          curl -sL https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize%2Fv5.4.3/kustomize_v5.4.3_linux_amd64.tar.gz | tar xz
+          sudo mv kustomize /usr/local/bin/kustomize
+
+      - name: Pin image tag in deploy manifests
+        run: |
+          cd deploy
+          kustomize edit set image solitaire-server=${{ env.IMAGE }}:${{ steps.meta.outputs.sha }}
+
+      - name: Commit and push updated kustomization
+        run: |
+          git config user.email "ci@gitea.local"
+          git config user.name "Gitea CI"
+          git add deploy/kustomization.yaml
+          git diff --cached --quiet && exit 0  # nothing to commit — skip push
+          git commit -m "chore(deploy): bump image to ${{ steps.meta.outputs.sha }} [skip ci]"
+          for i in 1 2 3; do
+            git pull --rebase origin master && git push && break
+            sleep 5
+          done

.github/workflows/ci.yml

@@ -1,88 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [master]
-  pull_request:
-    branches: [master]
-
-env:
-  CARGO_TERM_COLOR: always
-  RUSTFLAGS: "-D warnings"
-
-jobs:
-  test:
-    name: Test & Lint
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
-        with:
-          components: clippy
-
-      - name: Install Linux audio/display dependencies
-        run: |
-          sudo apt-get update -qq
-          sudo apt-get install -y --no-install-recommends \
-            libasound2-dev \
-            libudev-dev \
-            libwayland-dev \
-            libxkbcommon-dev
-
-      - name: Cache cargo registry and build artifacts
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/registry
-            ~/.cargo/git
-            target
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-
-
-      - name: Clippy (all crates, zero warnings)
-        run: cargo clippy --workspace -- -D warnings
-
-      - name: Test (headless crates only — no display required)
-        run: |
-          cargo test -p solitaire_core
-          cargo test -p solitaire_sync
-          cargo test -p solitaire_data
-          cargo test -p solitaire_server
-
-  build:
-    name: Release Build
-    runs-on: ubuntu-latest
-    needs: test
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
-
-      - name: Install Linux audio/display dependencies
-        run: |
-          sudo apt-get update -qq
-          sudo apt-get install -y --no-install-recommends \
-            libasound2-dev \
-            libudev-dev \
-            libwayland-dev \
-            libxkbcommon-dev
-
-      - name: Cache cargo registry and build artifacts
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/registry
-            ~/.cargo/git
-            target
-          key: ${{ runner.os }}-cargo-release-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-release-
-
-      - name: Build release binaries
-        run: cargo build --workspace --release

.gitignore

@@ -7,3 +7,17 @@
 *.tmp
 data/
 .claude/
+
+# IDE project files
+.idea/
+
+# Android signing keystores — never commit
+*.jks
+*.jks.bak
+*.jks.bak*
+*.keystore
+
+# Kubernetes secrets — apply manually, never commit
+deploy/matomo-secret.yaml
+deploy/*-secret.yaml
+deploy/*-auth-secret.yaml

.sqlx/query-06c945e50567c6801f1346d436cdc86a82a4e13dd45d8286295ba37cdbdc045e.json

@@ -0,0 +1,20 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT username FROM users WHERE id = ?",
+  "describe": {
+    "columns": [
+      {
+        "name": "username",
+        "ordinal": 0,
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "06c945e50567c6801f1346d436cdc86a82a4e13dd45d8286295ba37cdbdc045e"
+}

.sqlx/query-0e199cafab7e71b0c7f28ede85a622e38649d2fe5a73a5c715f2319f5450f729.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "UPDATE leaderboard\n               SET best_score      = ?,\n                   best_time_secs  = ?,\n                   recorded_at     = ?\n               WHERE user_id = ?\n                 AND (\n                     best_score IS NULL\n                     OR ? > best_score\n                     OR (? = best_score AND (best_time_secs IS NULL OR ? < best_time_secs))\n                 )",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 7
+    },
+    "nullable": []
+  },
+  "hash": "0e199cafab7e71b0c7f28ede85a622e38649d2fe5a73a5c715f2319f5450f729"
+}

.sqlx/query-15d08e02b102147bc74848ec3692b99edbf4c33078191f0132991ee94d4507b1.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "UPDATE users SET avatar_url = ? WHERE id = ?",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": []
+  },
+  "hash": "15d08e02b102147bc74848ec3692b99edbf4c33078191f0132991ee94d4507b1"
+}

.sqlx/query-168e205e3eb832b78d085b48281a1bae74d5a0e64c4c793c18a6400605bacf76.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "DELETE FROM refresh_tokens WHERE jti = ?",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "168e205e3eb832b78d085b48281a1bae74d5a0e64c4c793c18a6400605bacf76"
+}

.sqlx/query-2b814989a6632ca930ae1e895f97a7fc3389c91d1d2abf6900a21fb0d6e94ef3.json

@@ -1,6 +1,6 @@
 {
   "db_name": "SQLite",
-  "query": "SELECT l.display_name, l.best_score, l.best_time_secs, l.recorded_at\n           FROM leaderboard l\n           JOIN users u ON u.id = l.user_id\n           WHERE u.leaderboard_opt_in = 1\n           ORDER BY\n               CASE WHEN l.best_score IS NULL THEN 1 ELSE 0 END ASC,\n               l.best_score DESC,\n               CASE WHEN l.best_time_secs IS NULL THEN 1 ELSE 0 END ASC,\n               l.best_time_secs ASC",
+  "query": "SELECT l.display_name, l.best_score, l.best_time_secs, l.recorded_at\n           FROM leaderboard l\n           JOIN users u ON u.id = l.user_id\n           WHERE u.leaderboard_opt_in = 1\n           ORDER BY\n               CASE WHEN l.best_score IS NULL THEN 1 ELSE 0 END ASC,\n               l.best_score DESC,\n               CASE WHEN l.best_time_secs IS NULL THEN 1 ELSE 0 END ASC,\n               l.best_time_secs ASC\n           LIMIT 100",
   "describe": {
     "columns": [
       {
@@ -34,5 +34,5 @@
       false
     ]
   },
-  "hash": "57c93a6acd7eea44d00412e62f0d3fed7ffbe4cd759353d29f38a8eb37f69112"
+  "hash": "2b814989a6632ca930ae1e895f97a7fc3389c91d1d2abf6900a21fb0d6e94ef3"
 }

.sqlx/query-40db0910531d4418d4d58d31f0f8ea3894248406cc016020a6e211ed66da91c0.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "DELETE FROM refresh_tokens WHERE user_id = ?",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "40db0910531d4418d4d58d31f0f8ea3894248406cc016020a6e211ed66da91c0"
+}

.sqlx/query-893c45c27854ba15ea611e8254ef980ced21dc64e6ca95fde56af513f86ffa46.json

@@ -0,0 +1,20 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT jti FROM refresh_tokens WHERE jti = ?",
+  "describe": {
+    "columns": [
+      {
+        "name": "jti",
+        "ordinal": 0,
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      true
+    ]
+  },
+  "hash": "893c45c27854ba15ea611e8254ef980ced21dc64e6ca95fde56af513f86ffa46"
+}

.sqlx/query-c9ee5c64ca547f0c730379919a642bd649cbf81fc1804159101a70efabf08b33.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "INSERT INTO refresh_tokens (jti, user_id, expires_at) VALUES (?, ?, ?)",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": []
+  },
+  "hash": "c9ee5c64ca547f0c730379919a642bd649cbf81fc1804159101a70efabf08b33"
+}

.sqlx/query-e4eb622073cbdf868ec1568a6bdb132e962480b0530d542102c05aa9e901463b.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "UPDATE users SET password_hash = ? WHERE id = ?",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": []
+  },
+  "hash": "e4eb622073cbdf868ec1568a6bdb132e962480b0530d542102c05aa9e901463b"
+}

.sqlx/query-ef7af925a8715c329dcafca5257c691e6bca31755eb5f54be47114f21fc04c8c.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "DELETE FROM refresh_tokens WHERE expires_at < ?",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "ef7af925a8715c329dcafca5257c691e6bca31755eb5f54be47114f21fc04c8c"
+}

.sqlx/query-fae33e7159b43c756131b1545360dcb0250988b43550881e3f0a336d9516dd45.json

@@ -0,0 +1,26 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT username, avatar_url FROM users WHERE id = ?",
+  "describe": {
+    "columns": [
+      {
+        "name": "username",
+        "ordinal": 0,
+        "type_info": "Text"
+      },
+      {
+        "name": "avatar_url",
+        "ordinal": 1,
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      true
+    ]
+  },
+  "hash": "fae33e7159b43c756131b1545360dcb0250988b43550881e3f0a336d9516dd45"
+}

ARCHITECTURE.md

@@ -1,9 +1,9 @@
-# Solitaire Quest — Architecture Document
+# Ferrous Solitaire — Architecture Document
 
-> **Version:** 1.1  
+> **Version:** 1.3  
 > **Language:** Rust (Edition 2024)  
 > **Engine:** Bevy (latest stable)  
-> **Last Updated:** 2026-04-29
+> **Last Updated:** 2026-05-12
 
 ---
 
@@ -34,7 +34,7 @@
 
 ## 1. Project Overview
 
-Solitaire Quest is a cross-platform Klondike Solitaire game written in Rust, targeting macOS, Windows, and Linux desktops. It features a full progression system with XP, levels, achievements, daily challenges, and an optional self-hosted sync server so statistics and progress are available across all of a player's devices.
+Ferrous Solitaire is a cross-platform Klondike Solitaire game written in Rust, targeting macOS, Windows, and Linux desktops. It features a full progression system with XP, levels, achievements, daily challenges, and an optional self-hosted sync server so statistics and progress are available across all of a player's devices.
 
 ### Sync Backend by Platform
 
@@ -43,6 +43,7 @@ Solitaire Quest is a cross-platform Klondike Solitaire game written in Rust, tar
 | macOS | Self-hosted server | Full feature set |
 | Windows | Self-hosted server | Full feature set |
 | Linux | Self-hosted server | Full feature set |
+| Android | Self-hosted server | Touch input; safe-area insets via JNI; `cargo-apk` build |
 
 ### Design Principles
 
@@ -57,7 +58,7 @@ Pure-core, no-panics-in-game-logic, and UI-first-interaction constraints are enf
 ## 2. Workspace Structure
 
 ```
-solitaire_quest/
+ferrous_solitaire/
 │
 ├── Cargo.toml                  # Workspace manifest
 ├── .env.example                # Server environment variable template
@@ -86,6 +87,7 @@ solitaire_quest/
 ├── solitaire_data/             # Persistence, sync client, settings
 ├── solitaire_engine/           # Bevy ECS systems, components, plugins
 ├── solitaire_server/           # Self-hosted sync server (Axum + SQLite)
+├── solitaire_wasm/             # WebAssembly bindings — browser-side replay player
 └── solitaire_app/              # Main binary entry point
 ```
 
@@ -160,6 +162,20 @@ Owns:
 - Daily challenge seed generation
 - Leaderboard management
 
+### `solitaire_wasm`
+**Dependencies:** `solitaire_core`, `serde`, `serde_json`, `chrono`, `wasm-bindgen`, `serde-wasm-bindgen`.
+
+WebAssembly bindings for browser-side replay playback. Compiled to `cdylib` via `wasm-pack build`; the output lives in `solitaire_server/web/pkg/` and is served statically by the server.
+
+Intentionally **does not** depend on `solitaire_data` (which pulls in `dirs`, `keyring`, `reqwest`, and other non-WASM crates). Instead it defines a minimal `Replay` mirror with the same serde shape as `solitaire_data::Replay` — the JSON wire format is the compatibility contract.
+
+Owns:
+- `ReplayPlayer` — WASM-exported state machine; steps through a replay's `Vec<ReplayMove>` against a live `GameState`
+- `StateSnapshot` — JS-facing pile snapshot returned by each `step()` call
+- `ReplayMove` / `Replay` mirrors — same serde shape as `solitaire_data` v2 equivalents
+
+Because `ReplayPlayer` uses the same `solitaire_core::GameState` as the desktop client, the two implementations cannot drift: the same seed + move list produces identical pile state at every step on both platforms.
+
 ### `solitaire_app`
 **Dependencies:** `bevy`, `solitaire_engine`.
 
@@ -261,6 +277,8 @@ The "Shortcut" column lists optional keyboard accelerators. Every action in this
 | `HomePlugin` | M | Main-menu overlay with keyboard shortcut reference |
 | `ProfilePlugin` | P | Player profile overlay: level, XP, achievements, sync status |
 | `SettingsPlugin` | O | Settings panel: audio, draw mode, theme, sync, cosmetics |
+| `ThemePlugin` | — | Owns `ActiveTheme` resource; registers the `CardTheme` SVG asset loader; rasterises themes once per (theme, target size) at load time and caches the resulting `Image`; handles the embedded default theme and user themes from `user_theme_dir()` |
+| `SyncSetupPlugin` | — | Sync setup modal (URL / username / password fields, "Log In" / "Register" buttons); account deletion confirm modal; re-auth trigger when `SyncError::Auth` is returned by a pull |
 | `LeaderboardPlugin` | L | Leaderboard overlay |
 | `HelpPlugin` | H | Help / controls overlay |
 | `PausePlugin` | Esc | Pause and resume |
@@ -305,6 +323,12 @@ struct FontResource(Handle<Font>);
 struct BackgroundImageSet {
     handles: Vec<Handle<Image>>,    // indices 0–4 match selected_background setting
 }
+
+// OS-reserved edge insets (physical px); zero on desktop
+struct SafeAreaInsets { top: f32, bottom: f32, left: f32, right: f32 }
+
+// Whether the HUD band is visible (auto-hide chrome feature)
+enum HudVisibility { Visible, Hidden }
 ```
 
 ### Key Bevy Events
@@ -342,12 +366,12 @@ Minimum window: 800×600. At this size cards are small but usable.
 
 ### Local Storage
 
-All files stored under `dirs::data_dir() / "solitaire_quest"/`:
+All files stored under `dirs::data_dir() / "ferrous_solitaire"/`:
 
 ```
-~/.local/share/solitaire_quest/   (Linux)
-~/Library/Application Support/solitaire_quest/   (macOS)
-%APPDATA%\solitaire_quest\   (Windows)
+~/.local/share/ferrous_solitaire/   (Linux)
+~/Library/Application Support/ferrous_solitaire/   (macOS)
+%APPDATA%\ferrous_solitaire\   (Windows)
 │
 ├── stats.json          # StatsSnapshot
 ├── progress.json       # PlayerProgress (XP, level, unlocks, daily challenge)
@@ -365,10 +389,22 @@ All sync backends implement a single trait in `solitaire_data`. The `SyncPlugin`
 ```rust
 #[async_trait]
 pub trait SyncProvider: Send + Sync {
+    // Required — must be implemented by every backend:
     async fn pull(&self) -> Result<SyncPayload, SyncError>;
     async fn push(&self, payload: &SyncPayload) -> Result<SyncResponse, SyncError>;
     fn backend_name(&self) -> &'static str;
     fn is_authenticated(&self) -> bool;
+
+    // Optional — all have default no-op / empty implementations:
+    async fn mirror_achievement(&self, _id: &str) -> Result<(), SyncError>;
+    async fn fetch_leaderboard(&self) -> Result<Vec<LeaderboardEntry>, SyncError>;
+    async fn fetch_daily_challenge(&self) -> Result<Option<ChallengeGoal>, SyncError>;
+    async fn opt_in_leaderboard(&self, _display_name: &str) -> Result<(), SyncError>;
+    async fn opt_out_leaderboard(&self) -> Result<(), SyncError>;
+    async fn delete_account(&self) -> Result<(), SyncError>;
+    // Returns the shareable web URL on success; defaults to Err(UnsupportedPlatform)
+    // so LocalOnlyProvider silently no-ops the push-on-win path.
+    async fn push_replay(&self, _replay: &Replay) -> Result<String, SyncError>;
 }
 ```
 
@@ -390,7 +426,7 @@ pub enum SyncBackend {
         url: String,
         username: String,
         // JWT access + refresh tokens stored in OS keychain
-        // key: "solitaire_quest_server_{username}"
+        // key: "ferrous_solitaire_server_{username}"
     },
 }
 ```
@@ -454,6 +490,24 @@ CREATE TABLE leaderboard (
     recorded_at     TEXT NOT NULL,
     PRIMARY KEY (user_id)
 );
+
+-- migrations/002_replays.sql
+
+CREATE TABLE IF NOT EXISTS replays (
+    id              TEXT PRIMARY KEY,                      -- UUID v4 minted server-side
+    user_id         TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    seed            INTEGER NOT NULL,
+    draw_mode       TEXT NOT NULL,                          -- "DrawOne" | "DrawThree"
+    mode            TEXT NOT NULL,                          -- "Classic" | "Zen" | "Challenge" | "TimeAttack"
+    time_seconds    INTEGER NOT NULL,
+    final_score     INTEGER NOT NULL,
+    recorded_at     TEXT NOT NULL,                          -- replay-side date (YYYY-MM-DD)
+    received_at     TEXT NOT NULL,                          -- server insert timestamp (ISO 8601)
+    replay_json     TEXT NOT NULL                           -- full Replay serialisation
+);
+
+CREATE INDEX IF NOT EXISTS replays_received_at_idx ON replays(received_at DESC);
+CREATE INDEX IF NOT EXISTS replays_user_id_idx     ON replays(user_id);
 ```
 
 ### Request Lifecycle
@@ -579,12 +633,25 @@ pub struct AchievementRecord {
 
 pub struct Settings {
     pub draw_mode: DrawMode,
-    pub sfx_volume: f32,           // 0.0–1.0
+    pub sfx_volume: f32,                       // 0.0–1.0
     pub music_volume: f32,
     pub animation_speed: AnimSpeed,
     pub theme: Theme,
-    pub sync_backend: SyncBackend, // Local | SolitaireServer
+    pub sync_backend: SyncBackend,             // Local | SolitaireServer
+    pub selected_card_back: usize,             // index into PlayerProgress::unlocked_card_backs
+    pub selected_background: usize,            // index into PlayerProgress::unlocked_backgrounds
     pub first_run_complete: bool,
+    pub color_blind_mode: bool,                // blue tint on red suits
+    pub high_contrast_mode: bool,              // boosted luminance for low-vision users
+    pub reduce_motion_mode: bool,              // WCAG reduce-motion — snaps instead of slides
+    pub window_geometry: Option<WindowGeometry>, // persisted size + position; None on first run
+}
+
+pub struct WindowGeometry {
+    pub width:  u32,   // logical pixels
+    pub height: u32,
+    pub x:      i32,   // physical pixels, top-left corner
+    pub y:      i32,
 }
 ```
 
@@ -600,7 +667,7 @@ All endpoints are under the base URL configured by the user (e.g., `https://soli
 |---|---|---|---|---|
 | POST | `/api/auth/register` | None | `{username, password}` | `{access_token, refresh_token}` |
 | POST | `/api/auth/login` | None | `{username, password}` | `{access_token, refresh_token}` |
-| POST | `/api/auth/refresh` | None | `{refresh_token}` | `{access_token}` |
+| POST | `/api/auth/refresh` | None | `{refresh_token}` | `{access_token, refresh_token}` (rotated) |
 
 ### Sync
 
@@ -617,6 +684,21 @@ All endpoints are under the base URL configured by the user (e.g., `https://soli
 | GET | `/api/leaderboard` | Bearer JWT | — | `Vec<LeaderboardEntry>` |
 | POST | `/api/leaderboard/opt-in` | Bearer JWT | — | `{ok: true}` |
 
+### Replays
+
+| Method | Path | Auth | Body | Response |
+|---|---|---|---|---|
+| POST | `/api/replays` | Bearer JWT | Replay JSON | `{id, share_url}` |
+| GET | `/api/replays/recent` | None | — (`?limit=N`) | `Vec<ReplaySummary>` |
+| GET | `/api/replays/:id` | None | — | Full Replay JSON |
+
+### Web Replay Player
+
+| Method | Path | Auth | Notes |
+|---|---|---|---|
+| GET | `/replays/:id` | None | Serves `web/index.html`; JS fetches `/api/replays/:id` and steps through via the `solitaire_wasm` WASM module |
+| GET | `/web/*` | None | Static assets served via `ServeDir` from `solitaire_server/web/` (includes `web/pkg/` with wasm-bindgen output) |
+
 ### Account Management
 
 | Method | Path | Auth | Body | Response |
@@ -825,7 +907,7 @@ All sound effect WAV files are embedded at compile time via `include_bytes!()` i
 | macOS | Primary | Self-hosted server | x86_64 + Apple Silicon (universal binary via `cargo-lipo`) |
 | Windows | Primary | Self-hosted server | x86_64, MSVC toolchain |
 | Linux | Primary | Self-hosted server | x86_64, tested on Ubuntu 22.04+ and Fedora 39+ |
-| Android | Stretch | Self-hosted server | `cargo-mobile2`, touch input |
+| Android | Active | Self-hosted server | `cargo-apk`; touch + long-press + double-tap; safe-area JNI; portrait layout |
 | iOS | Stretch | Self-hosted server | `cargo-mobile2`, touch input |
 
 Minimum Bevy window size enforced: 800×600. Desktop windows are freely resizable; layout recomputes on `WindowResized`.
@@ -898,8 +980,8 @@ Add `--features bevy/dynamic_linking` during development to dramatically reduce
 ### Docker Compose (Recommended)
 
 ```bash
-git clone https://github.com/yourname/solitaire_quest
-cd solitaire_quest
+git clone https://github.com/yourname/ferrous_solitaire
+cd ferrous_solitaire
 cp .env.example .env
 # Edit .env — set JWT_SECRET and SERVER_PORT
 docker compose up -d
@@ -945,6 +1027,7 @@ Migrations run automatically on startup via `sqlx::migrate!()`.
 | Password storage | bcrypt, cost factor 12 — never stored in plaintext |
 | Token security | JWTs signed with HS256, stored in OS keychain via `keyring` crate |
 | Token expiry | Access: 24h, Refresh: 30d |
+| Refresh token rotation | Each `/api/auth/refresh` call consumes the incoming refresh token (deletes its jti row) and issues a new one. Reuse of a consumed token returns 401. Expired rows are pruned inline. |
 | Brute force | `tower-governor`: 10 req/min per IP on `/api/auth/*` |
 | Payload abuse | 1MB max request body, enforced by Axum middleware |
 | Data deletion | `DELETE /api/account` removes all rows via `ON DELETE CASCADE` |

CHANGELOG.md

@@ -1,13 +1,955 @@
 # Changelog
 
-All notable changes to Solitaire Quest are documented here. The format is
+All notable changes to Ferrous Solitaire are documented here. The format is
 based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this
 project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
-No threads in flight. v0.21.1 cut on 2026-05-08; CHANGELOG accumulates
-the next cycle here.
+## [0.30.0] — 2026-05-16
+
+### Changed
+
+- **Tableau card spacing tightened.** Face-up card fan reduced from 25% to 18%
+  of card height; face-down from 20% to 14%. Cards on tableau piles sit closer
+  together while still showing enough of each card to read the pile depth.
+
+## [0.29.0] — 2026-05-16
+
+### Fixed
+
+- **APK versionCode hardcoded to 1** (`AndroidManifest.xml`, `build_android_apk.sh`).
+  Every release shipped with `versionCode="1"` / `versionName="1.0"`, so Android
+  silently refused upgrades and Obtainium permanently showed a false update
+  notification. The CI now derives the version code from the release tag
+  (e.g. v0.29.0 → 2900) and stamps it into the APK via `aapt2 link
+  --version-code / --version-name`.
+- **CI kustomize install flaky** (`.gitea/workflows/docker-build.yml`).
+  The `curl | bash install_kustomize.sh` pattern hit GitHub API rate limits
+  on the shared runner IP, causing a `tar: no such file` failure. Replaced
+  with a direct pinned tarball download (kustomize v5.4.3).
+
+## [0.28.0] — 2026-05-14
+
+### Changed
+
+- **Rename: Solitaire Quest → Ferrous Solitaire.** Android package id changed
+  from `com.solitairequest.app` to `com.ferrousapp.solitaire`; existing installs
+  must be uninstalled first (Android treats the new id as a new app).
+  Data directory renamed from `solitaire_quest/` to `ferrous_solitaire/`.
+
+### Fixed
+
+- **BUG-3: Multi-modal stacking** (`hud_plugin.rs`). `handle_menu_button`
+  now checks `scrims.is_empty()` — a `Query<(), With<ModalScrim>>` guard —
+  before calling `spawn_menu_popover`. Tapping ≡ while any modal (Stats,
+  Settings, Profile, Help) is open is now a no-op. Previously Stats + Profile
+  could be open simultaneously.
+- **UX-7: Help text single-line overflow** (`help_plugin.rs`). The HUD menu
+  button description "Menu: Stats, Settings, Profile, Achievements" wrapped to
+  two lines on Android. Shortened to "Open menu (Stats, Settings, Profile...)"
+  which fits on one line. Verified on device.
+- **UX-5b: Home mode glyph corruption** (`home_plugin.rs`). Mode selector icons
+  were using Geometric Shapes block (U+25xx) absent from the bundled FiraMono
+  font — rendered as missing-glyph rectangles on Android. Replaced with card
+  suits (U+2660–2666) which FiraMono covers: ♦ Daily, ♥ Zen, ♠ Challenge.
+- **UX-1: Modal Done button in gesture zone** (`safe_area.rs`). New
+  `apply_safe_area_to_modal_scrims` Bevy system pads every `ModalScrim` bottom
+  by `SafeAreaInsets.bottom / scale_factor`. Modal cards are now centred over
+  the safe area, not the full physical screen. The Settings / Help / Stats Done
+  buttons are reachable on gesture-nav Android devices. Verified on device.
+
+---
+
+## [0.23.0] — 2026-05-12
+
+Phase 8 sync UI: the self-hosted-server connection flow is now fully
+playable end-to-end. Players can open a Connect modal from Settings,
+enter a server URL + credentials, log in or register, and see the
+sync-status section update live. Token expiry auto-reopens the modal.
+Account deletion ships a two-click destroy flow. Server deployment
+artifacts (Dockerfile + docker-compose) let self-hosters spin up in one
+command.
+
+### Added
+
+- **Sync setup modal — Connect / Disconnect flow** (`432061c`).
+  New `SyncSetupPlugin` (`solitaire_engine/src/sync_setup_plugin.rs`)
+  provides the full server-connection UI. Three tab-stopped text fields
+  (URL, Username, Password) handle keyboard input via `MessageReader<KeyboardInput>`
+  with focus cycling on Tab. "Log In" and "Register" buttons each spawn an
+  async `AsyncComputeTaskPool` task that calls the new
+  `SolitaireServerClient::login()` / `::register()` methods; `poll_auth_task`
+  harvests the result, stores tokens via `store_tokens()`, hot-swaps
+  `SyncProviderResource` to the new server backend, fires
+  `ManualSyncRequestEvent` to pull immediately, and closes the modal.
+  An inline `SyncAuthError` label displays credential errors without a
+  toast. The modal is idempotent (`existing.is_empty()` guard) — safe
+  to open programmatically.
+- **`SyncConfigureRequestEvent`, `SyncLogoutRequestEvent`,
+  `DeleteAccountRequestEvent`** (`432061c`). Three new engine events
+  wire the Settings buttons → plugin handlers. `SyncConfigureRequestEvent`
+  opens the setup modal; `SyncLogoutRequestEvent` disconnects and resets
+  `SyncProviderResource` to `LocalOnlyProvider`; `DeleteAccountRequestEvent`
+  opens the deletion confirmation modal.
+- **Settings sync section — dynamic backend UI** (`432061c`).
+  `sync_row()` in `SettingsPlugin` now takes `backend: &SyncBackend` and
+  renders conditionally: `Local` → "Connect" button; `SolitaireServer` →
+  username label + "Sync Now" + "Disconnect" + "Delete Account". Three new
+  `SettingsButton` discriminants (`ConnectSync` tab 91, `DisconnectSync`
+  tab 92, `DeleteAccount` tab 93) feed into a new `handle_sync_buttons`
+  system extracted from `handle_settings_buttons` to stay within Bevy's
+  16-parameter system limit.
+- **`SolitaireServerClient::login()` and `::register()`** (`432061c`).
+  Both POST to `/api/auth/login` and `/api/auth/register` respectively.
+  Private helper `extract_auth_tokens` parses `{ access_token, refresh_token }`.
+  409 CONFLICT → "username already taken"; 401/403 → "invalid credentials";
+  400 → server message echoed to the player.
+- **Re-auth prompt on token expiry** (`6ce5564`).
+  `poll_pull_result` in `SyncPlugin` now fires `InfoToastEvent("Session
+  expired — please reconnect")` + `SyncConfigureRequestEvent` when the
+  pull task resolves to `SyncError::Auth(_)`. Because the modal is
+  idempotent the re-open is safe to trigger from any system path.
+- **Server deployment artifacts** (`6ce5564`).
+  `solitaire_server/Dockerfile`: multi-stage build (`rust:1.95-slim` →
+  `debian:bookworm-slim`); copies `.sqlx` offline cache so `SQLX_OFFLINE=true`
+  succeeds without a live database at build time; exposes port 8080.
+  `solitaire_server/docker-compose.yml`: single-service compose file;
+  `db-data` volume at `/app/data`; `DATABASE_URL` and `JWT_SECRET` from
+  environment; HTTP health-check via `wget`. `solitaire_server/.env.example`:
+  documents all required variables with generation hint (`openssl rand -hex 32`).
+- **Account deletion flow** (`272d31f`).
+  "Delete Account" in Settings fires `DeleteAccountRequestEvent` →
+  `SyncSetupPlugin::open_delete_confirm_modal` spawns a danger-red
+  confirmation modal with "Cancel" and "Delete Forever" buttons.
+  "Delete Forever" submits an async `PendingDeleteTask` that calls
+  `SyncProvider::delete_account()`; `poll_delete_task` on Ok fires
+  `SyncLogoutRequestEvent` + a success toast; on Err shows an error toast
+  and leaves the modal open. Two-click destroy pattern — no accidental
+  account deletion possible.
+
+### Removed
+
+- **`SyncAuthResultEvent`** (`432061c`). Defined but never emitted or
+  consumed; removed as dead code.
+
+### Stats
+
+- Tests: **1300+ passing** / 0 failing
+- Clippy: clean
+- Crates touched: `solitaire_data` (sync_client), `solitaire_engine`
+  (events, settings_plugin, sync_plugin, sync_setup_plugin [new], lib),
+  `solitaire_app` (lib.rs), `solitaire_server` (Dockerfile,
+  docker-compose.yml, .env.example [new])
+
+## [0.22.0] — 2026-05-08
+
+Adds difficulty-tier game selection, Android JNI bridges for keystore and
+clipboard, Play-by-Seed dialog, and double-tap auto-move on touch screens.
+Also closes the Prev/Next replay-selector spawn-site item carried since v0.19.0.
+
+### Added
+
+- **Difficulty-tier game mode** (this release).
+  `DifficultyLevel` enum (`Easy / Medium / Hard / Expert / Grandmaster /
+  Random`) added to `solitaire_core::game_state` alongside a new
+  `GameMode::Difficulty(DifficultyLevel)` variant. Five pre-verified seed
+  catalogs (40 seeds each, 200 total) are generated by the new
+  `gen_difficulty_seeds` binary in `solitaire_assetgen`; each catalog
+  contains seeds proven winnable at progressively larger solver budgets
+  (1 K → 200 K moves). `DifficultyPlugin` resolves `StartDifficultyRequestEvent`
+  → catalog seed → `NewGameRequestEvent`; the `Random` tier uses a
+  system-time seed and intentionally bypasses the winnable-only filter.
+  The home overlay gains an expandable `▶ Difficulty` section between the
+  Draw Mode row and the mode-card grid; the last-played tier is persisted
+  in `Settings::last_difficulty` and pre-expands/highlights on re-open.
+  Difficulty wins pool into Classic stats (no separate buckets).
+- **Prev/Next replay selector in the Stats overlay** (`a449f60`).
+  `ReplayPrevButton`, `ReplayNextButton`, `ReplaySelectorCaption`, and
+  `ReplaySelectorDetail` nodes now spawn inside `spawn_stats_screen`
+  as a flex row of two bordered chips flanking a `"Replay N / M"`
+  caption, with a detail line below showing the selected replay's
+  duration + date and an optional `"· Shareable"` badge. Both chips
+  carry `ModalButton(Secondary)` so the existing `repaint_modal_buttons`
+  paint loop gives them hover/press feedback at zero extra cost.
+  `repaint_replay_selector_detail` is wired into the existing
+  `.chain()` alongside `handle_replay_selector_buttons` and
+  `repaint_replay_selector_caption`. The click handler and repaint
+  systems have been registered (and dormant) since v0.19.0; this
+  commit is purely the missing spawn site.
+- **6 new selector unit tests** (`a449f60`). Covers: spawn-site
+  presence (Prev, Next, Caption, Detail all spawn with the screen),
+  caption initial text ("Replay 1 / 1"), detail initial text
+  ("{dur} win on {date}"), Shareable badge when `share_url` is set,
+  empty-history "No replays" caption, and ordinal wrapping.
+  `make_test_replay(time_seconds, share_url)` helper encapsulates
+  `Replay::new(...)` + `chrono::NaiveDate`.
+
+### Fixed
+
+- **`const { assert!() }` for dim-layer z-order test** (`a449f60`).
+  Converted `assert!(Z_REPLAY_DIM < Z_REPLAY_OVERLAY, …)` in
+  `replay_overlay` tests to `const { assert!(…) }` to satisfy
+  `clippy::assertions_on_constants` (constant-fold at compile time
+  rather than a runtime no-op).
+
+### Added (post-cut, same pending release)
+
+- **Double-tap auto-move on touch screens** (`395a322`).
+  `handle_double_tap` fires `MoveRequestEvent` (single card to
+  foundation/tableau, or a whole face-up stack via
+  `best_tableau_destination_for_stack`) when two `TouchPhase::Ended`
+  events on the same card arrive within `DOUBLE_TAP_WINDOW` (0.5 s,
+  slightly wider than the mouse `DOUBLE_CLICK_WINDOW` to account for
+  touch latency). If no legal destination exists, fires
+  `MoveRejectedEvent` (audio + visual rejection feedback).  The system
+  is inserted into the touch drag chain immediately before
+  `touch_end_drag` so `DragState.active_touch_id` and `committed` are
+  still readable; the tap timestamp is tracked in a `Local<HashMap<u32,
+  f32>>` keyed by card ID.
+- **Play-by-Seed dialog** (`0cb1587`).
+  `PlayBySeedPlugin` adds a numeric-input modal that accepts a decimal
+  seed, runs a solver preview in the background (debounced 500 ms via
+  `AsyncComputeTaskPool`), and shows a win/no-win verdict before
+  dealing.  A new `HomeMode::PlayBySeed` card in the home overlay fires
+  `StartPlayBySeedRequestEvent`; the handler in `PlayBySeedPlugin`
+  spawns the dialog.  Digit, Backspace, Enter (confirm), and Escape
+  (cancel) are handled via `ButtonInput<KeyCode>`.  Five unit tests
+  cover spawn, digit append, buffer read, confirm, and cancel paths.
+- **75 new challenge seeds** (`2062bd0`).
+  New `gen_seeds` binary in `solitaire_assetgen` brute-searches seeds
+  in the `0xCAFEBABE…` namespace and filters for hands solvable in
+  ≤250 moves via the core solver.  The 75 confirmed-win seeds are
+  appended to `CHALLENGE_SEEDS` in `solitaire_data::challenge`.
+
+### Fixed (post-cut, same pending release)
+
+- **Gate `handle_fullscreen` to non-Android** (`45436d0`).
+  F11 fullscreen toggle makes no sense on Android (the OS owns window
+  sizing); the fn and its `MonitorSelection`/`WindowMode` imports are
+  now `#[cfg(not(target_os = "android"))]`-gated.  The `add_systems`
+  call is extracted as a separate statement so `#[cfg]` can annotate it
+  (attributes cannot appear mid-chain in Rust).
+- **Android APK launch: export `android_main`** (`202a64d`).
+  `NativeActivity` dlopen-s `libsolitaire_app.so` and calls
+  `android_main` as its entry point. Without the symbol the app
+  crashed immediately with `UnsatisfiedLinkError`. The new function
+  sets `bevy::android::ANDROID_APP` (required by `WinitPlugin`) then
+  delegates to `run()` — equivalent to what `#[bevy_main]` would
+  generate, but usable on an arbitrary entry point name.
+- **Android APK launch: gate `resize_constraints` to non-Android**
+  (`202a64d`). On Android `max_width/max_height` default to `0.0`;
+  Bevy's clamp panicked with `min=800 > max=0`.
+- **Android APK launch: gate `apply_smart_default_window_size` to
+  non-Android** (`202a64d`). The system calls `.clamp(800.0,
+  logical_w)` which panics when the emulator reports zero window
+  dimensions during early Android lifecycle events. The OS controls
+  window size on Android; the system is irrelevant there.
+- **Ignore `.idea/` IDE project files** (`16242e6`). Android Studio
+  created `.idea/` when the project was opened during APK
+  verification; added to `.gitignore` and removed the accidentally-
+  committed files.
+
+### Android verification result
+
+APK boots on `x86_64-linux-android` in a Pixel_7 AVD (Android 14 /
+API 34, SwiftShader Vulkan). App runs for 2+ minutes without crashing.
+Bevy renderer initialises, splash screen loads. This is the first
+confirmed end-to-end device run.
+
+### Stats
+
+- Tests: **1300+ passing** / 0 failing
+- Clippy: clean
+- Crates touched: `solitaire_core` (game_state), `solitaire_data`
+  (settings, stats, difficulty_seeds, challenge), `solitaire_engine`
+  (events, difficulty_plugin, home_plugin, hud_plugin, win_summary_plugin,
+  input_plugin, play_by_seed_plugin, lib), `solitaire_app` (lib.rs),
+  `solitaire_assetgen` (gen_difficulty_seeds + gen_seeds binaries)
+
+## [0.21.8] — 2026-05-08
+
+Patch release for replay-overlay polish. Through-line:
+**notch-label centering + WIN MOVE HC legibility + HC system extension**.
+All three items were "optional polish" flagged in the v0.21.7 handoff;
+all three ship in two commits.
+
+### Added
+
+- **`STATE_SUCCESS_HC` constant** (`c50eaf8`). Brighter lime
+  (`#c8e862`, L≈0.73) in `ui_theme` for use wherever the
+  standard `STATE_SUCCESS` (`#acc267`, L≈0.51) needs extra
+  luminance under HC mode. Sits above the bumped notch ticks
+  (`BORDER_SUBTLE_HC` gray, L≈0.60) so a WIN MOVE marker at
+  this colour is unambiguous.
+- **`HighContrastBackground::with_hc(default, hc)` constructor**
+  (`c50eaf8`). Extends `HighContrastBackground` with an
+  `hc_color: Color` field (default = `BORDER_SUBTLE_HC` via
+  `with_default()`). `update_high_contrast_backgrounds` now
+  reads `marker.hc_color` instead of the hardcoded constant —
+  backwards-compatible; all existing `with_default()` usages
+  continue to bump to gray.
+- **WIN MOVE scrub-bar marker HC bump** (`c50eaf8`). Marker
+  now carries `HighContrastBackground::with_hc(STATE_SUCCESS,
+  STATE_SUCCESS_HC)` so the lime stays lime under HC (brighter
+  lime rather than gray). Pin test locks both the default and
+  HC colour fields on the spawned entity.
+
+### Fixed
+
+- **Scrub-bar notch-label centering** (`b44d277`). Middle
+  three labels ("25%", "50%", "75%") previously had their
+  left edge at the notch; now their text centre coincides
+  with the notch tick. Implemented using the CSS
+  `translateX(-50%)` pattern for Bevy 0.18 UI: a fixed
+  `SCRUB_LABEL_CENTER_WIDTH = 36 px` container with
+  `margin.left = -18 px` is placed at `left: Percent(pct)`,
+  and `Justify::Center` centres the text within it. Endpoint
+  labels ("0%", "100%") keep their flush-left / flush-right
+  anchoring. `with_default()` remains one-argument.
+
+### Stats
+
+- Tests: 1276 passing / 0 failing (engine: 831)
+- Clippy: clean
+- Crates touched: `solitaire_engine` (replay_overlay.rs,
+  ui_theme.rs, settings_plugin.rs)
+
+## [0.21.7] — 2026-05-08
+
+Patch release closing the last major B-2 sub-piece. Through-line:
+**mini-tableau preview dim layer**. The mockup's "Game Peek Band at
+50 % opacity" is now implemented as a full-screen UI scrim that darkens
+the card world during replay so the chrome (banner + move-log panel)
+reads clearly against the scene.
+
+### Added
+
+- **Full-screen tableau dim layer** (`da3e542`). Spawns a
+  `ReplayTableauDimLayer` UI node (100 % × 100 %, 50 % opacity
+  black) at `Z_REPLAY_DIM = Z_REPLAY_OVERLAY − 1 = 54` whenever
+  a replay starts; despawned alongside the banner and move-log
+  panel when the replay ends. Bevy's UI/world compositor means
+  no changes to `card_plugin` are needed — UI nodes always
+  render above world-space sprites regardless of `Transform.z`.
+  The dim layer carries no `Interaction` component (purely
+  visual; pointer events pass through). Adds `Z_REPLAY_DIM`
+  and `TABLEAU_DIM_ALPHA` constants plus two new tests:
+  lifecycle (spawn/despawn mirrors the floating-chip pattern)
+  and z-ordering invariant (`Z_REPLAY_DIM < Z_REPLAY_OVERLAY`
+  pinned). 1275 tests pass / 0 failing.
+
+### Stats
+
+- Tests: 1275 passing / 0 failing
+- Clippy: clean
+- Crates touched: `solitaire_engine` (replay_overlay.rs)
+
+## [0.21.6] — 2026-05-08
+
+Patch release for the post-v0.21.5 work. Through-line:
+**Move Log panel + scrub-UX polish**. v0.21.5 closed out the
+keyboard-accelerator surface (Space / Esc / ← / →) and the
+keybind footer; v0.21.6 builds on that with two parallel
+threads — accessibility + scrub-on-hold polish for the v0.21.5
+surfaces, plus a brand-new Move Log panel anchored to the
+viewport's bottom edge that gives players a 5-row recent-and-
+upcoming move history alongside the existing top-edge banner.
+
+The Move Log panel is the first replay-overlay surface that
+*isn't* attached to the banner — it lives at a separate screen
+anchor (bottom: 0) with its own spawn/despawn lifecycle.
+Establishes the pattern for "multi-anchor replay UI" that the
+remaining B-2 sub-piece (mini-tableau preview) will inherit.
+
+### Added
+
+- **HC-mode coverage for the scrub track + quarter-mark notch
+  ticks** (`d3cb1a5`). Adds parallel primitive
+  `HighContrastBackground` to `ui_theme` and a paint system
+  `update_high_contrast_backgrounds` in `settings_plugin` that
+  mirrors the existing border-marker pattern but targets
+  `BackgroundColor` instead of `BorderColor`. Tags the 1 px
+  scrub track Node and all five quarter-mark notch ticks so
+  they bump from `BORDER_SUBTLE` (`#505050`) →
+  `BORDER_SUBTLE_HC` (`#a0a0a0`) under HC mode. Scrub fill
+  (`ACCENT_PRIMARY`) and WIN MOVE marker (`STATE_SUCCESS`)
+  don't get the marker — accent and state colours are already
+  saturated and don't need an HC luminance variant.
+- **Continuous scrub on key-held arrow keys** (`2e25476`).
+  Holding ← or → triggers continuous step at 100 ms cadence
+  (10 steps/sec) — matches the mockup's `[← →] scrub`
+  terminology while keeping single-press = single-step
+  semantics. Per-key accumulators in a new
+  `ReplayScrubKeyHold` resource; `just_pressed` events bypass
+  the accumulator and fire immediately. Release resets to 0
+  so the next fresh press fires immediately rather than at
+  half-interval.
+- **Move Log panel** (`d6f32d3` + `140251b` + `e7345ae` +
+  `4437a1a`). New bottom-edge UI panel showing a 5-row window
+  onto recent + upcoming moves: 2 prev rows above the active
+  row + active row highlighted in `ACCENT_PRIMARY` + 2 next
+  rows below. Header reads `▌ MOVE LOG · N/M` (or
+  `▌ MOVE LOG · COMPLETE` when finished). Active row carries
+  a `▶` focus prefix and `TEXT_PRIMARY_HC` text colour for
+  legible contrast against the brick-red highlight. Prev /
+  next rows render in `TEXT_SECONDARY` so the active row
+  stays the focal point.
+  - Sibling-of-banner pattern (separate root entity anchored
+    at viewport bottom, not a banner child) — same
+    spawn/despawn lifecycle as `ReplayFloatingProgressChip`,
+    different screen anchor.
+  - Five pure helpers handle the formatting:
+    `format_pile`, `format_move_body`,
+    `format_move_log_header`, `format_kth_recent_row` (active
+    + prev), `format_kth_next_row` (next). 1-indexed display
+    numbers throughout (`Foundation(2)` reads as "foundation
+    3" rather than the enum's 0-index).
+  - Panel grows from 56 → 84 → 112 px across the four
+    move-log commits. `MOVE_LOG_PREV_ROWS` and
+    `MOVE_LOG_NEXT_ROWS` constants (both = 2) parameterise
+    the row count; `format_kth_recent_row` and
+    `format_kth_next_row` return empty for out-of-range k so
+    panels gracefully under-fill at the start (cursor=1) and
+    end (cursor=N-1) of a replay.
+  - HC marker on the panel's top border so the 1 px edge
+    bumps under HC mode (same pattern as the keybind footer).
+
+### Changed
+
+- **`react_to_state_change` despawns the Move Log panel** on
+  `Playing → Inactive` alongside the banner root and floating
+  progress chip. Third query in the same defer-and-despawn
+  cycle.
+- **Move Log panel height grew 56 → 84 → 112 px** across the
+  prev-rows and next-rows commits. The panel is sized to fit
+  the chosen row count + header + padding; tunable via the
+  `MOVE_LOG_PANEL_HEIGHT` const.
+- **`format_active_move_row` now prefixes the `▶` focus
+  marker** (`e7345ae`). Wraps `format_kth_recent_row(state, 1)`
+  and prepends the prefix when the body is non-empty. Empty
+  case still returns empty — cursor=0 doesn't paint a stray
+  `▶` on an otherwise-empty row.
+
+### Documentation
+
+- `SESSION_HANDOFF.md` refreshed twice this cycle — once
+  recording the HC paint + continuous-scrub polish, then
+  again as the Move Log arc shipped commit-by-commit. The
+  Resume menu's B option now traces the full arc:
+  notches → labels → footer → ESC → HC → arrow keys →
+  HC paint → continuous scrub → move log.
+
+### Stats
+
+- **1273 passing tests / 0 failing** across the workspace
+  (net +23 from v0.21.5's 1250 baseline):
+  - 2 from `d3cb1a5` (HC marker on track + notches).
+  - 2 from `2e25476` (continuous-scrub repeat-while-held +
+    release-resets-accumulator).
+  - 8 from `d6f32d3` (move-log panel init + 5 helpers + 3
+    spawn / lifecycle scenarios).
+  - 4 from `140251b` (prev rows: helper k coverage + spawn
+    cardinality + spawn texts + repaint on cursor advance).
+  - 3 from `e7345ae` (active row highlight: wrapper bg +
+    text colour + focus prefix + cursor=0 stays empty).
+  - 4 from `4437a1a` (next rows: helper k coverage + spawn
+    cardinality + spawn texts + under-fill at replay end).
+- Clippy clean across the workspace.
+
+## [0.21.5] — 2026-05-08
+
+Patch release for the post-v0.21.4 work. One through-line:
+**replay-overlay scrubbing affordances + accessibility**. v0.21.4
+shipped pause / resume / step + the WIN MOVE marker as the first
+*scrubbing-shaped* additions to the replay overlay; v0.21.5
+fills out the rest of the scrubbing UX so the player has both
+visual anchor points (notches + labels) and a complete keyboard
+control surface (Space / Esc / ← / →) for navigating a paused
+replay.
+
+Two of the six commits in this cycle are layout-changing — they
+grow the banner height from 60 px → 76 px → 92 px to make room
+for the notch labels and keybind footer. Banner geometry was
+fixed for every prior B-2 commit; this release establishes the
+"grow the container, add a flex-column child" pattern that the
+remaining B-2 sub-pieces (move-log scroller, mini-tableau
+preview) will inherit when they land.
+
+### Added
+
+- **Quarter-mark scrub-bar notches** (`fe68861`). Five 1 px
+  vertical ticks at 0 / 25 / 50 / 75 / 100 % give the player
+  visual anchor points without needing to mentally bisect the
+  bar. Pure helper `scrub_notch_positions()` returns the fixed
+  array; spawn loop sits next to the WIN MOVE marker spawn so
+  the lifecycles match. Notches paint in `BORDER_SUBTLE` (same
+  as the unfilled track) and rely on extending past the 1 px
+  track (5 px tall, anchored 2 px above the track top) for
+  visibility — same trick the WIN MOVE marker uses. Spawned
+  *after* the WIN MOVE marker so a notch and the marker
+  landing on the same percentage paint the marker on top.
+- **Percentage labels under each notch** (`d322abf`). Five
+  `0%` / `25%` / `50%` / `75%` / `100%` labels in a new 16 px
+  row beneath the 1 px scrub track give the player explicit
+  quarter-mark readouts. Banner grew from 60 → 76 px to
+  accommodate the row — first **layout-changing** commit in
+  the B-2 arc. Pure helper `scrub_notch_labels()` returns the
+  fixed array, paired index-for-index with
+  `scrub_notch_positions()`. Spawn loop applies an "endpoints
+  flush, middle three percent-anchored" positioning pattern:
+  leftmost label gets `left: 0`, rightmost gets `right: 0`,
+  middle three anchor at `left: Val::Percent(p)` since Bevy
+  0.18 UI lacks a clean CSS-style `translate-x: -50%`
+  centering primitive. Label colour is `TEXT_SECONDARY`
+  rather than the mockup's `BORDER_SUBTLE` (the latter would
+  match the notches but is too low-contrast against
+  `BG_ELEVATED_HI` to read at 12 px).
+- **Keybind-hint footer** (`1873b3f`). Vim-style mode line on
+  the left (`▌ NORMAL │ replay`) plus a keybind hint on the
+  right at the bottom edge of the banner. Banner grew from
+  76 → 92 px to fit the 16 px footer row. Surfaces every
+  wired keyboard accelerator visually so CLAUDE.md §3.3's
+  UI-first contract holds for keyboard accelerators too. The
+  footer lists *only* keybinds that are actually wired —
+  the only-wired-keybinds discipline means each release
+  cycle's hint string is a precise honest contract with the
+  player. Two pure helpers (`keybind_footer_mode_text`,
+  `keybind_footer_hint_text`) keep the static text testable.
+  1 px top border in `BORDER_SUBTLE` separates the footer
+  from the labels row.
+- **ESC keyboard accelerator for replay-stop** (`90e24d9`).
+  New `handle_stop_keyboard` system parallels
+  `handle_pause_keyboard` in shape — fires only when state
+  is `Playing`, calls `stop_replay_playback`. Cross-plugin
+  coordination via `pause_plugin::toggle_pause`: added a
+  fourth defer-if check
+  (`replay_state.is_some_and(|s| s.is_playing())`) right
+  after the existing `other_modal_scrims` check so ESC
+  during active replay belongs to the replay overlay, not
+  the pause modal.
+- **HC-mode coverage for the keybind-footer top border**
+  (`23902cd`).
+  `HighContrastBorder::with_default(BORDER_SUBTLE)` marker
+  on the footer's border-carrying Node so the existing
+  `apply_high_contrast_borders` system bumps the 1 px top
+  border from `#505050` → `#a0a0a0` when
+  `Settings::high_contrast_mode` is on. Without the marker
+  the footer reads as floating loose under HC because the
+  border that anchors it to the labels row is
+  near-invisible.
+- **← / → keyboard accelerators for paused stepping**
+  (`e5c4f51`). New `step_backwards_replay_playback` in
+  `replay_playback.rs` decrements the cursor and dispatches
+  `UndoRequestEvent`; the game's `handle_undo` reads it
+  next frame to reverse its most-recent move. Hooks the
+  existing undo system rather than replaying-forward-from-
+  zero — every replay-applied move pushes to the undo stack
+  the same way a player move would, so undo is the right
+  reversal primitive. Both arrow keys are paused-only via
+  the same destructure-gate pattern the forward step uses.
+  The mockup labels these `[← →] scrub`; single-move step
+  is the closest behaviour shippable today, so the footer
+  hint reads `[← →] step` — only-wired-keybinds discipline.
+
+### Changed
+
+- **Banner height grew 60 → 76 → 92 px** across two
+  layout-changing commits (`d322abf` then `1873b3f`). Top
+  row's `flex_grow: 1.0` still consumes 59 px so the
+  existing content (label / progress chip / buttons) has
+  the same vertical space; the new rows (16 px labels +
+  16 px footer) extend the banner downward into the
+  gameplay area. Banner geometry is now mutable — every
+  prior B-2 commit fit inside fixed 60 px space.
+- **Keybind-footer hint text grew alongside the wirings**:
+  `[SPACE] pause/resume` →
+  `[SPACE] pause/resume · [ESC] stop` →
+  `[SPACE] pause/resume · [ESC] stop · [← →] step`.
+- **`pause_plugin::toggle_pause` now defers when a replay
+  is active** (`90e24d9`). Adds a fourth defer-if check to
+  the existing modal-stack pattern.
+- **`ReplayOverlayPlugin` registers
+  `add_message::<UndoRequestEvent>()`** (`e5c4f51`).
+  Defensive registration so the plugin runs cleanly under
+  `MinimalPlugins` without `GamePlugin` attached.
+
+### Documentation
+
+- `SESSION_HANDOFF.md` refreshed five times this cycle.
+  The B option in the Resume menu now traces the full arc:
+  notches → labels → footer → ESC → HC → arrow keys.
+- The pre-existing `daily_challenge` warning test that
+  fails when wall-clock UTC is within 30 minutes of
+  midnight is documented in this cycle's handoff. Same
+  shape as the earlier `winnable_seed_search` flake —
+  time-dependent, deterministically passes outside the
+  trigger window.
+
+### Stats
+
+- **1250 total tests / 1249 passing / 1 pre-existing
+  time-dependent flake** across the workspace (net +22 from
+  v0.21.4's 1228 baseline):
+  - 4 from `fe68861` (scrub-notch coverage)
+  - 4 from `d322abf` (notch-label coverage)
+  - 4 from `1873b3f` (keybind-footer coverage)
+  - 3 from `90e24d9` (ESC-accelerator coverage)
+  - 1 from `23902cd` (HC-marker coverage)
+  - 6 from `e5c4f51` (arrow-keyboard coverage)
+- **Pre-existing flake**:
+  `daily_challenge_plugin::tests::check_system_fires_warning_event_only_once_per_day`
+  fails when wall-clock UTC is within 30 minutes of
+  midnight. Verified pre-existing by stash-and-retest
+  before each commit. Will pass deterministically outside
+  the trigger window. Not introduced by this release.
+- Clippy clean across the workspace.
+
+## [0.21.4] — 2026-05-08
+
+Patch release for the post-v0.21.3 work. One through-line:
+**replay-scrubbing accessibility**. The replay overlay used to be
+pure-passive — the player started a replay, watched it execute,
+and waited for it to end. v0.21.4 adds the scaffolding for
+*navigating within* a replay: a WIN MOVE marker on the scrub bar
+so the player can see at a glance where the winning move sits,
+and pause / resume / step controls so they can stop on any move
+and inspect the board.
+
+The work is also the first three commits on the B-2 replay
+screen-takeover redesign arc. The remaining pieces (screen-
+takeover layout, move-log scroller, mini-tableau preview) are
+deferred to a future cycle because they need a layout reflow
+that the existing banner-only overlay can't carry.
+
+### Added
+
+- **`Replay::win_move_index: Option<usize>` data field**
+  (`ab857bb`). Additive optional field on the persisted
+  `Replay` shape. `#[serde(default)]` keeps older
+  `latest_replay.json` / `replays.json` files loadable without
+  bumping `REPLAY_SCHEMA_VERSION` — this is purely additive.
+  Populated at the live recording site
+  (`game_plugin::handle_game_won`) via a new builder-style
+  setter `Replay::with_win_move_index`. For fresh recordings
+  the value is always `Some(moves.len() - 1)` because recording
+  freezes on win, but storing it explicitly lets the playback
+  UI read the WIN MOVE position directly without re-deriving
+  on every render.
+- **WIN MOVE scrub-bar marker** (`52befa6`). New
+  `ReplayOverlayWinMoveMarker` component spawned as a sibling
+  to `ReplayOverlayScrubFill` under the 1px scrub track,
+  absolute-positioned at `replay.win_move_index / total %` of
+  the bar. Painted in `STATE_SUCCESS` (green) so the marker
+  reads as "this is where the win lives." Pure helper
+  `win_move_marker_pct` returns `None` for any state where the
+  marker shouldn't draw (Inactive, Completed, replay missing
+  the field, empty move list); percentage clamps to `[0, 100]`
+  defensively. Spawn-time only — the position never changes
+  during a single playback because the underlying `Replay` is
+  immutable while `Playing`.
+- **Pause / Resume / Step playback controls** (`fbe48ac`). New
+  `paused: bool` field on `ReplayPlaybackState::Playing`.
+  `tick_replay_playback` skips the `secs_to_next` decrement
+  entirely while paused so cursor and timer freeze together;
+  resuming starts the next move from a full interval. New
+  public API: `toggle_pause_replay_playback` and
+  `step_replay_playback` (the latter hard-gated to `Playing {
+  paused: true }` via the destructure pattern itself, so
+  manual stepping can't race the tick loop). On-screen Pause
+  and Step buttons sit alongside the existing Stop button;
+  `Space` keyboard accelerator toggles pause / resume.
+- **`Replay::with_win_move_index` builder** (`ab857bb`).
+  Chainable setter so the recording site can write
+  `Replay::new(...).with_win_move_index(idx)`. Keeps
+  `Replay::new`'s signature stable across the 13+ existing
+  test-fixture call sites that don't care about the field.
+
+### Changed
+
+- **`Replay::new` writes `win_move_index: None`** (`ab857bb`).
+  Existing canonical constructor stays signature-compatible
+  with all existing callers. The field is opt-in via the
+  builder.
+- **`game_plugin::handle_game_won` populates the new field**
+  (`ab857bb`). The recording site computes
+  `recording.moves.len().checked_sub(1)` as the win-move
+  index. `checked_sub` rather than direct subtraction guards
+  the unreachable empty-recording branch (which is also
+  guarded earlier in the function).
+- **`tick_replay_playback` honors the new `paused` flag**
+  (`fbe48ac`). Skipping the timer decrement is the only
+  behavior change; the loop body and Completed-detection are
+  unchanged. Stepping fires moves directly via
+  `step_replay_playback`, bypassing the tick path entirely.
+- **Pause / Resume button label is reactive** (`fbe48ac`).
+  `update_pause_button_label` walks `Children` from the
+  marked button to its inner `Text` and repaints the label
+  whenever `ReplayPlaybackState` changes. Pure helper
+  `pause_button_label` covers all four state arms (running,
+  paused, inactive, completed).
+- **25 existing `Playing { ... }` construction sites gained
+  `paused: false`** (`fbe48ac`). Mechanical edit across
+  `replay_overlay`, `achievement_plugin`, and
+  `replay_playback` tests to satisfy the new field
+  requirement. No behavioral change.
+
+### Documentation
+
+- `SESSION_HANDOFF.md` refreshed three times this cycle —
+  once after each post-cut feature commit. The B-2 entry in
+  the Visual-identity follow-ups list now points at the
+  remaining sub-pieces (screen-takeover layout, move-log
+  scroller, mini-tableau preview) as a single multi-session
+  arc rather than three independent ones, since they share a
+  layout-reflow prerequisite.
+
+### Stats
+
+- **1228 passing tests / 0 failing** across the workspace
+  (net +21 from v0.21.3's 1207 baseline):
+  - 5 from `ab857bb`'s `win_move_index` coverage: default
+    constructor, builder set / set-None, on-disk round-trip,
+    legacy-JSON-loads-with-None backward-compat. The last
+    test pins the no-schema-bump claim — if a future refactor
+    drops the `#[serde(default)]`, that test catches it.
+  - 8 from `52befa6`'s WIN MOVE marker: pure-helper truth
+    table (Inactive / Completed / no-field / correct-position
+    / clamp) + spawn-presence-with-field /
+    spawn-absence-without / despawn-with-overlay observables.
+  - 8 from `fbe48ac`'s playback controls: label truth table,
+    label repaint on state change, click-toggles-paused,
+    step advances cursor by exactly one with paused
+    preserved, step-while-running no-op, Space toggles
+    paused.
+- Zero clippy warnings under `cargo clippy --workspace
+  --all-targets -- -D warnings`.
+- `cargo test --workspace` clean.
+
+## [0.21.3] — 2026-05-08
+
+Patch release for the post-v0.21.2 work. One through-line:
+**accessibility arc closure**. v0.21.2 explicitly carved out
+"dynamic-paint sites" (HUD action buttons, modal buttons, radial
+menu rim) on the assumption that their existing paint cycles would
+race the central `update_high_contrast_borders` system. v0.21.3
+walks the actual code, finds the carve-out was over-cautious, and
+closes it. Bonus: the first real consumer of `ToastVariant::Warning`
+also lands here, making the `ToastVariant` enum fully load-bearing
+(every variant has at least one driver).
+
+### Added
+
+- **`WarningToastEvent(String)` — first `ToastVariant::Warning`
+  consumer** (`279e23d`). Generic carrier message that any system
+  can fire to spawn a 4 s amber-bordered fire-and-forget toast.
+  Mirrors the v0.21.2 `MoveRejectedEvent` → `Error` toast wiring:
+  domain message crosses the plugin boundary, the animation
+  plugin's `handle_warning_toast` system reads it and spawns. Not
+  queued (Warning is alert-shaped, not info-shaped — should never
+  block on a queue).
+- **Daily-challenge-expiry warning** (`279e23d`). First in-engine
+  driver of `WarningToastEvent`. New
+  `daily_challenge_plugin::check_daily_expiry_warning` system
+  fires at most once per `DailyChallengeResource::date` when the
+  player is within 30 min of UTC midnight reset and today's
+  challenge isn't yet complete. Suppression decided by a pure
+  helper (`compute_expiry_warning_minutes`) covering: already-
+  completed-today, already-shown-for-this-date, outside the
+  threshold window, post-midnight rollover. Pure-helper-plus-
+  thin-system shape because `Utc::now()` can't be pinned without
+  injecting a clock resource — overkill for one consumer.
+- **`radial_rim_outline` pure helper** (`c153363`). Decision
+  logic for the radial-menu rim outline colour. Resting outlines
+  always carry `BORDER_SUBTLE`; focused outlines carry
+  `BORDER_STRONG` normally and `BORDER_SUBTLE_HC` under HC. Naive
+  marker substitution would invert the focused-vs-resting
+  hierarchy because `BORDER_SUBTLE_HC` (`#a0a0a0`) is *lighter*
+  than `BORDER_STRONG` (`#505050`); folding the choice in here
+  keeps the focused rim more visible under HC, not less.
+
+### Changed
+
+- **HC marker pattern extended to HUD action buttons + modal
+  buttons** (`c153363`). Re-reading the code revealed both sites'
+  paint systems (`paint_action_buttons`, `paint_modal_buttons`)
+  only mutate `BackgroundColor` — `BorderColor` is set once at
+  spawn and never touched. So the existing
+  `HighContrastBorder::with_default(BORDER_SUBTLE)` marker
+  pattern works cleanly for both, no race. v0.21.2's carve-out
+  comment was based on assumed-but-not-actual race risk; this
+  cycle treats it as the doc-vs-implementation drift pattern in
+  the wild and verifies before trusting.
+- **Radial menu rim folds HC into per-frame respawn**
+  (`c153363`). The rim is the only true dynamic-painter of the
+  three carved-out sites — `radial_redraw_overlay` despawns and
+  respawns all rim sprites every frame the radial is `Active`.
+  The `HighContrastBorder` marker can't apply (entities don't
+  persist across frames) so HC is read directly in the system
+  via `Option<Res<SettingsResource>>` and routed through
+  `radial_rim_outline`. The `Option<Res<...>>` shape preserves
+  test compatibility under `MinimalPlugins`.
+- **Animation plugin registers `WarningToastEvent`** (`279e23d`).
+  Joins `InfoToastEvent`, `MoveRejectedEvent` etc. in
+  `AnimationPlugin::build`. Daily-challenge plugin also
+  registers it (idempotent) so the message exists when running
+  the daily plugin under `MinimalPlugins` without the animation
+  plugin attached.
+
+### Documentation
+
+- `SESSION_HANDOFF.md` refreshed twice this cycle — once after
+  the Toast Warning wiring (menu trimmed 5 → 4 options), and
+  again after the HC dynamic-paint rollout (menu trimmed 4 → 3,
+  with all remaining options now flagged as multi-session). The
+  `High-contrast accessibility mode` entry in the Visual-identity
+  follow-ups list is updated to reflect that no "un-tagged
+  because race-risk" surfaces remain.
+
+### Stats
+
+- **1207 passing tests / 0 failing** across the workspace
+  (net +12 from v0.21.2's 1195 baseline):
+  - 7 tests for `compute_expiry_warning_minutes` (`279e23d`)
+    covering each suppression rule + the inclusive boundary at
+    exactly 30 min remaining.
+  - 1 in-Bevy test (`check_system_fires_warning_event_only_once_per_day`)
+    pinning `DailyExpiryWarningShown`'s once-per-date
+    suppression and the symmetric "already-completed-today"
+    suppression.
+  - 4 truth-table tests for `radial_rim_outline` (`c153363`):
+    focused × HC. The "resting stays subtle under HC" test
+    explicitly documents *why* — it's the hierarchy-preservation
+    invariant a future refactor might be tempted to break.
+- Zero clippy warnings under `cargo clippy --workspace
+  --all-targets -- -D warnings`.
+- `cargo test --workspace` clean.
+
+## [0.21.2] — 2026-05-08
+
+Patch release for the post-v0.21.1 polish work. Three through-
+lines: **accessibility extensions** (reduce-motion gating for
+splash animations, full HC chrome rollout across 8 surfaces),
+**replay polish** (floating MOVE chip above the focused card
+during playback), and the **first real consumer of
+`ToastVariant::Error`** (invalid-move feedback as the third leg
+of the existing audio + visual rejection-feedback stool).
+
+The accessibility extensions close two threads v0.21.1 left
+explicitly open: reduce-motion was previously gated only on card
+slide_secs, and HC borders had `BORDER_SUBTLE_HC` defined but no
+consumers. v0.21.2 finishes both — non-essential motion in the
+splash boot screen now respects reduce-motion, and every static-
+border chrome surface (modal scaffold, tooltip, help / stats /
+home / settings panels) boosts to the HC variant under high-
+contrast mode. Dynamic-paint sites (HUD action buttons, modal
+buttons, radial menu rim) intentionally stay un-tagged because
+their existing paint cycles would race the HC system; they
+remain open for a future iteration that needs a different shape.
+
+### Added
+
+- **`sync_pile_marker_visibility` system precursor was v0.21.1's;
+  this cycle adds**: `update_high_contrast_borders` system in
+  `settings_plugin` (`c9af1ea`). Walks all entities tagged with
+  `HighContrastBorder` each Update tick, swaps `BorderColor` to
+  `BORDER_SUBTLE_HC` when high-contrast mode is on. Compares
+  current colour and only mutates when different so Bevy's
+  change-detection doesn't trigger repaints every frame. New
+  `HighContrastBorder { default_color: Color }` component carries
+  the off-state colour at each tagged site so the system can
+  revert correctly.
+- **HC chrome rollout — 8 tagged surfaces** (`c9af1ea` modal
+  scaffold; `d87761d` tooltip + onboarding key chips + help
+  panel key chips + stats panel cells; `ec804d5` home Level/XP/
+  Score row + home mode-selector buttons + home mode-hotkey
+  chips + 4 settings panel surfaces). Each tagging is one line
+  on the spawn tuple. The marker-component architecture pays
+  back proportionally to the number of consumers — the per-
+  commit cost dropped from ~75 lines (foundation + first
+  surface) to ~13 lines (4 surfaces) to ~9 lines (7 surfaces).
+- **Floating MOVE chip during replay** (`2fb2d63`). New
+  `ReplayFloatingProgressChip` marker on a `Text2d` entity
+  rendered in 2D world space above the destination pile of the
+  most-recently-applied move. Sibling of the banner overlay (not
+  a child) because it lives in world-space coordinates, not the
+  UI tree. Lifecycle matches the banner: `spawn_overlay` spawns
+  the chip alongside the banner when a replay starts;
+  `react_to_state_change` despawns it when the replay ends.
+  World-space placement (rather than UI-space + camera projection)
+  uses the same `LayoutResource` pile coordinates that drive
+  every other piece of pile geometry — stays correctly positioned
+  through window resizes for free. Hidden when cursor=0 (no
+  moves applied yet) or when the last applied move was a
+  `StockClick` (no destination pile to follow).
+- **`handle_move_rejected_toast` system + first real
+  `ToastVariant::Error` consumer** (`68d50b5`). When
+  `MoveRejectedEvent` fires (illegal placement attempt), spawns
+  a 2-second pink-bordered "Invalid move" toast. Joins the
+  existing `card_invalid.wav` (audio cue) and destination-pile
+  shake (visual cue) as the accessibility-focused readable text
+  channel — covers deaf players (no audio reliance) and
+  reduce-motion players (no shake reliance) with a persistent
+  ~2 s text cue. Drops the `#[allow(dead_code)]` from
+  `ToastVariant::Error` and updates its doc to point at the new
+  consumer.
+
+### Changed
+
+- **Splash scanline overlay skipped under reduce-motion**
+  (`ed152e2`). `spawn_splash` reads `Settings::reduce_motion_mode`
+  and skips the scanline texture / overlay node entirely when
+  on. Without the scanlines the boot screen still reads as
+  terminal-themed (foreground content, borders, palette swatches
+  unchanged); the scanlines are decorative.
+- **Splash cursor pulse held under reduce-motion** (`ed152e2`).
+  `pulse_splash_cursor` reads `Settings::reduce_motion_mode` and
+  skips the per-frame sine-pulse multiplier when on — the cursor
+  still fades in / out with the global splash alpha (essential
+  timing) but doesn't blink. Spec calls out non-essential motion
+  as the reduce-motion target; the global fade is essential
+  (otherwise the splash would hard-cut on/off, which is
+  jarring), and the cursor blink is decorative.
+- **`AnimationPlugin::build` registers
+  `MoveRejectedEvent`** (`68d50b5`). Bevy's `add_message` is
+  idempotent, so the duplicate registration with
+  `feedback_anim_plugin` (which already registered the message)
+  coexists cleanly. Required for the new
+  `handle_move_rejected_toast` system to run under
+  MinimalPlugins (tests).
+
+### Documentation
+
+- `docs/ui-mockups/design-system.md` and `SESSION_HANDOFF.md`
+  refreshed in lockstep with the rollouts. The handoff's
+  Resume-prompt menu trimmed twice this cycle as Options A and F
+  closed in v0.21.1, then this commit cycle's accessibility
+  extensions implicitly closed the "future scope" footnotes
+  v0.21.1 left on F's documentation.
+
+### Stats
+
+- **1195 passing tests / 0 failing** across the workspace
+  (net +3 from v0.21.1's 1192 baseline). New tests added by
+  this cycle:
+  - `splash_skips_scanline_overlay_under_reduce_motion`
+    (`ed152e2`) pins the reduce-motion gate on the splash
+    scanline overlay. Discovered an asset-fixture bootstrapping
+    detail along the way: under `MinimalPlugins`,
+    `Assets<Image>` isn't auto-inserted; the test had to add
+    `bevy::asset::AssetPlugin::default()` and
+    `init_asset::<bevy::image::Image>()`. Pattern flagged for
+    future asset-using tests.
+  - `floating_chip_spawns_and_despawns_with_overlay`
+    (`2fb2d63`) pins the floating MOVE chip's lifecycle:
+    absent on Inactive, exactly one on Playing, absent again
+    on return to Inactive.
+  - `move_rejected_event_spawns_error_toast` (`68d50b5`) pins
+    the new toast wiring: firing a `MoveRejectedEvent` spawns
+    exactly one `ToastOverlay` on the next tick.
+- Zero clippy warnings under `cargo clippy --workspace
+  --all-targets -- -D warnings`.
+- `cargo test --workspace` clean.
 
 ## [0.21.1] — 2026-05-08
 
@@ -521,7 +1463,7 @@ candidate — the app-icon round — stays open.
 - **Android build target — first working APK** (`fb8b2ac`).
   `cargo apk build -p solitaire_app --target x86_64-linux-android`
   now produces a 54 MB debug-signed APK at
-  `target/debug/apk/solitaire-quest.apk`. Five gating points
+  `target/debug/apk/ferrous-solitaire.apk`. Five gating points
   resolved end-to-end:
   - **`solitaire_app` split into bin + lib.** cargo-apk needs a
     `cdylib` to bundle as `libmain.so`; pure-bin crates panic
@@ -638,7 +1580,7 @@ candidate — the app-icon round — stays open.
   achievements, replays, game-state, time-attack sessions, user
   themes). New `solitaire_data::platform::data_dir()` shim falls
   through to `dirs::data_dir()` on desktop and returns the per-app
-  sandbox at `/data/data/com.solitairequest.app/files` on Android
+  sandbox at `/data/data/com.ferrousapp.solitaire/files` on Android
   — no JNI needed, since the package id is pinned in
   `[package.metadata.android]`. Six call sites across
   `solitaire_data` plus `solitaire_engine/assets/user_dir.rs`
@@ -780,7 +1722,7 @@ fully reverted and is not part of this release.
   The test's single-frame `app.update()` was sensitive to
   first-frame `Time::delta_secs()` variance under heavy parallel
   cargo-test load, and to production-disk
-  `~/.local/share/solitaire_quest/game_state.json` state leaking
+  `~/.local/share/ferrous_solitaire/game_state.json` state leaking
   into the test world via `GamePlugin::build`'s load path.
   `test_app` now resets `PendingRestoredGame(None)` after plugin
   build (preventing the dev machine's saved-game state from
@@ -1476,7 +2418,7 @@ the binary shipped with bundled artwork.
   patterns.
 - **Ambient audio loop** wired through the kira mixer.
 - **Arch Linux PKGBUILDs** for the game client and sync server (under
-  the separate `solitaire-quest-pkgbuild` directory).
+  the separate `ferrous-solitaire-pkgbuild` directory).
 - **Workspace README, CI workflow, migration guide.**
 
 ### Changed

CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-version: unified-3.0
+version: unified-4.0
 
 ---
 
@@ -29,8 +29,9 @@ solitaire_sync/    # Shared API + merge logic
 solitaire_data/    # Persistence + sync client
 solitaire_engine/  # Bevy ECS + UI + gameplay orchestration
 solitaire_server/  # Axum backend (optional sync layer)
+solitaire_wasm/    # WASM bindings for browser-side replay player
 solitaire_app/     # Entry binary
-assets/            # Runtime assets (except audio)
+assets/            # Runtime assets (except audio + default theme)
 ```
 
 ---
@@ -72,12 +73,16 @@ These override all other instructions.
 
 * NO `unwrap()`
 * NO `panic!()` in runtime/game logic
-* All state transitions:
+* Core game state mutations MUST return:
 
 ```rust id="err_model"
 Result<T, MoveError>
 ```
 
+* Engine / UI state changes follow ECS patterns (Resources, Events) —
+  they do not return `MoveError`
+* Use `thiserror`-derived types for any new error enums outside `solitaire_core`
+
 ---
 
 ## 2.4 Threading Rules
@@ -126,10 +131,15 @@ trait SyncProvider
 ## 3.1 ECS Design
 
 * systems = single responsibility
-* communication = Events only
-* shared state = Resources only
+* cross-system communication = Events (fire-and-forget triggers)
+* persistent shared state = Resources (polled every frame or on change)
 * per-entity state = Components only
 
+Events and Resources are both valid communication paths — use Events when
+the receiver needs to react once; use Resources when the receiver polls
+or when multiple systems read the same value (e.g. `SafeAreaInsets`,
+`HudVisibility`, `LayoutResource`).
+
 ---
 
 ## 3.2 Game State Authority
@@ -149,11 +159,22 @@ Every player action MUST:
 Keyboard shortcuts are:
 → optional accelerators only
 
+**Exception — UI chrome gestures:**
+Tap-to-toggle visibility of UI chrome (e.g. auto-hiding HUD band) is
+permitted without a visible button. The gesture MUST:
+* affect only chrome visibility, never game state
+* restore chrome automatically when any modal opens
+* be purely additive (game remains fully playable with chrome always visible)
+
 ---
 
 ## 3.4 Layout System
 
 * recompute on `WindowResized`
+* recompute on `SafeAreaInsets` changed
+* recompute on `HudVisibility` changed
+* `compute_layout` MUST accept `hud_visible: bool`; pass `HUD_BAND_HEIGHT`
+  when `true`, `0.0` when `false`
 * no fixed resolution assumptions
 
 ---
@@ -178,11 +199,18 @@ Includes:
 
 ## 4.2 Embedded Assets
 
-Only audio:
+Embed via `include_bytes!()` only when ALL of the following are true:
 
-```text id="audio_rule"
-include_bytes!()
-```
+* the asset is small (< 500 KB uncompressed)
+* it changes rarely (not user-customisable)
+* a missing file would be a hard crash, not a graceful degradation
+
+Currently embedded:
+* **Audio** — all `.wav` files in `audio_plugin.rs`
+* **Default card theme** — shipped via `embedded://` scheme in `ThemePlugin`
+
+Do NOT embed card face PNGs, background images, or user fonts —
+these are loaded via `AssetServer` so art can be swapped without recompile.
 
 ---
 
@@ -210,7 +238,9 @@ Must degrade gracefully under `MinimalPlugins`.
 ## 5.2 Public API Rules
 
 * prefer `Into<T>` over concrete types
-* all public items require doc comments
+* publicly exported functions, traits, and non-trivial types require doc comments
+* simple marker components, newtype wrappers, and internal `pub` items
+  used only within the same crate are exempt from doc comment requirements
 
 ---
 
@@ -276,11 +306,13 @@ NEVER commit otherwise
 
 Claude must request confirmation before:
 
-* adding dependencies
-* modifying `solitaire_sync`
-* changing DB schema
+* adding dependencies to `solitaire_core` or `solitaire_sync`
+  (engine/server crates may add deps without confirmation)
+* modifying `solitaire_sync` types or the `SyncProvider` trait
+* changing DB schema (migrations are append-only)
 * introducing `unsafe`
-* changing merge strategy
+* changing the merge strategy in `solitaire_sync::merge`
+* changing the `SyncPayload` wire format (breaking change for existing servers)
 
 ---
 
@@ -304,10 +336,29 @@ Core is always the source of truth.
 
 Must always be handled explicitly:
 
+**All platforms**
 * Bevy `Time` uses `f32`
 * `sqlx::migrate!()` path is crate-relative
 * `dirs::data_dir()` may return `None`
-* Linux may lack keyring backend
+* Linux may lack keyring backend — handle `keyring::Error` gracefully
+
+**Android (active target — not stretch)**
+* Safe-area insets arrive in frames 1–3 via JNI polling, not at startup;
+  UI that depends on them must handle the zero-inset initial state
+* Physical pixels ≠ logical pixels: `SafeAreaInsets` values are physical
+  (from `WindowInsets` API); divide by `window.scale_factor()` before
+  passing to Bevy `Val::Px`
+* `adb shell input tap` uses physical pixel coordinates
+* FiraMono (bundled font) covers: ASCII, card suits U+2660–2666,
+  Arrows U+2190–21FF. It does NOT cover Geometric Shapes (U+25xx) —
+  those render as missing-glyph rectangles on Android
+* The gesture/navigation bar at the bottom (≈132px physical on common
+  devices) is inside the Bevy viewport; use `SafeAreaInsets.bottom` to
+  avoid placing interactive elements in that zone
+* `HUD_BAND_HEIGHT` is 128px on Android (two-row wrap) vs 64px on desktop;
+  layout constants are `#[cfg(target_os = "android")]` gated
+* JNI calls must use `attach_current_thread_permanently` — not
+  `attach_current_thread` — to avoid detach-on-drop panics
 
 ---
 
@@ -318,6 +369,12 @@ Must always be handled explicitly:
 * blocking async calls in ECS
 * insecure credential storage
 * bypassing core logic layer
+* hardcoded pixel coordinates in layout — always derive from `compute_layout`
+* Unicode Geometric Shapes block (U+25xx) in UI text — not in FiraMono
+* spawning a second `ModalScrim` while one already exists without first
+  dismissing the existing one (use `scrims.is_empty()` guard)
+* reading `SafeAreaInsets` physical values directly into `Val::Px` without
+  dividing by `window.scale_factor()`
 
 ---
 
@@ -345,9 +402,74 @@ If unclear:
 | Both combined   | full system understanding |
 
 ---
-# 14. Context Injection System (AUTOMATIC SCOPE FILTER)
+# 14. Modal System Conventions
 
-## 14.1 Purpose
+All full-screen overlay panels MUST use the `spawn_modal` / `ModalScrim` pattern
+from `solitaire_engine::ui_modal`.
+
+## 14.1 Spawn pattern
+
+```rust
+let scrim = spawn_modal(commands, MyScreenMarker, Z_MODAL_PANEL, |card| {
+    spawn_modal_header(card, "Title", font_res);
+    // ... body nodes ...
+    spawn_modal_actions(card, |actions| {
+        spawn_modal_button(actions, MyCloseButton, "Done", None,
+                           ButtonVariant::Primary, font_res);
+    });
+});
+// Optional: allow clicking the scrim outside the card to dismiss
+commands.entity(scrim).insert(ScrimDismissible);
+```
+
+## 14.2 Guard rule
+
+Before spawning a new modal, check `scrims: Query<(), With<ModalScrim>>`
+and return early if `!scrims.is_empty()` — unless the new modal is
+explicitly replacing the current one (despawn first, then spawn).
+
+## 14.3 Safe area
+
+Every `ModalScrim` automatically receives `padding.bottom` equal to the
+logical gesture-bar height via `apply_safe_area_to_modal_scrims` in
+`SafeAreaInsetsPlugin`. Do not manually add bottom padding to scrim nodes.
+
+## 14.4 Z-ordering
+
+Use `Z_MODAL_PANEL` from `ui_theme` for all modal scrims. Do not use
+raw `z_index` values — they drift and cause ordering bugs.
+
+---
+
+# 15. Android Build & Verification
+
+## 15.1 Build command
+
+```bash
+cargo apk build --package solitaire_app --lib
+adb install -r target/debug/apk/ferrous-solitaire.apk
+```
+
+## 15.2 Coordinate system reminder
+
+Device physical: 1080×2400. Bevy logical: 900×2000. Scale factor: 1.20.
+`adb shell input tap X Y` takes PHYSICAL coordinates.
+To convert from what you see on screen (logical): multiply by 1.20.
+
+## 15.3 Android-specific test checklist
+
+Before shipping any Android build:
+- [ ] Safe area insets arrive and shift HUD correctly (check after 3s)
+- [ ] All modal Done buttons are above the gesture bar
+- [ ] No Geometric Shapes glyphs in UI text
+- [ ] HUD band does not overlap the top status bar
+- [ ] Touch drag-and-drop works on all pile types
+
+---
+
+# 16. Context Injection System (AUTOMATIC SCOPE FILTER)
+
+## 16.1 Purpose
 
 Before generating any response, Claude MUST construct a **minimal relevant context set**.
 
@@ -360,7 +482,7 @@ This prevents:
 
 ---
 
-## 14.2 Input Classification Step (MANDATORY)
+## 16.2 Input Classification Step (MANDATORY)
 
 Every request MUST be classified into exactly one task type:
 
@@ -381,13 +503,13 @@ If uncertain → ask clarification.
 
 ---
 
-## 14.3 Context Selection Engine
+## 16.3 Context Selection Engine
 
 After classification, Claude MUST include ONLY the relevant sections below.
 
 ---
 
-## 14.4 Context Map (CORE RULESET)
+## 16.4 Context Map (CORE RULESET)
 
 ### feature
 
@@ -495,7 +617,7 @@ Include:
 
 ---
 
-## 14.5 Context Compression Rules
+## 16.5 Context Compression Rules
 
 Claude MUST obey:
 
@@ -506,7 +628,7 @@ Claude MUST obey:
 
 ---
 
-## 14.6 Context Priority Order
+## 16.6 Context Priority Order
 
 When space is limited:
 
@@ -517,7 +639,7 @@ When space is limited:
 
 ---
 
-## 14.7 “No Context Pollution” Rule
+## 16.7 “No Context Pollution” Rule
 
 Claude must NOT include:
 
@@ -529,7 +651,7 @@ Claude must NOT include:
 
 ---
 
-## 14.8 Self-Check Before Execution
+## 16.8 Self-Check Before Execution
 
 Before writing code, Claude MUST verify:
 
@@ -542,7 +664,7 @@ If any fail → revise context selection.
 
 ---
 
-## 14.9 Injection Output Format (Internal Model)
+## 16.9 Injection Output Format (Internal Model)
 
 Claude should behave as if it constructed:
 
@@ -560,7 +682,7 @@ Claude should behave as if it constructed:
 
 ---
 
-## 14.10 Relationship to ARCHITECTURE.md
+## 16.10 Relationship to ARCHITECTURE.md
 
 * ARCHITECTURE.md = source of truth
 * CLAUDE.md = execution constraints

CLAUDE_PROMPT_PACK.md

@@ -1,497 +0,0 @@
-# CLAUDE_PROMPT_PACK.md
-
-version: 1.0
-
----
-
-# 0. GLOBAL INSTRUCTION (prepend to every prompt)
-
-```
-You must follow CLAUDE_SPEC.md strictly.
-
-Rules:
-- Do not expand scope beyond what is defined
-- Do not refactor unrelated code
-- Do not introduce new dependencies
-- Prefer minimal, surgical changes
-- Use existing patterns in the codebase
-- Return minimal diffs or changed functions only
-
-Before writing code:
-1. List relevant constraints from CLAUDE_SPEC.md
-2. Identify risks
-3. Then implement
-```
-
----
-
-# 1. FEATURE IMPLEMENTATION
-
-```
-# TASK: Feature Implementation
-
-feature: "<name>"
-
-goal:
-"<clear outcome>"
-
-scope:
-crates: []
-systems: []
-files: []
-
-non_goals:
-- ""
-
-constraints:
-- must follow CLAUDE_SPEC.md
-- event-driven architecture required
-- no blocking operations
-- no cross-crate leakage
-
-acceptance_criteria:
-- ""
-- ""
-
-edge_cases:
-- ""
-
----
-
-## Required Patterns
-
-Use this pattern for systems:
-<PASTE EXISTING SYSTEM SNIPPET HERE>
-
----
-
-## Output Format
-
-intent:
-plan:
-constraints_used:
-risks:
-
-code_changes:
-(minimal diffs only)
-
-notes:
-```
-
----
-
-# 2. BUGFIX
-
-```
-# TASK: Bug Fix
-
-bug_description:
-"<what is broken>"
-
-expected_behavior:
-"<correct behavior>"
-
-root_cause_hint (optional):
-""
-
-scope:
-crates: []
-files: []
-
-constraints:
-- minimal fix only
-- no refactors unless required
-- must add regression protection if applicable
-
----
-
-## Requirements
-
-1. Identify root cause
-2. Fix it minimally
-3. Preserve all invariants
-4. Do not change unrelated logic
-
----
-
-## Output Format
-
-analysis:
-root_cause:
-fix_strategy:
-
-code_changes:
-(minimal diff)
-
-regression_test (only if high-value):
-
-notes:
-```
-
----
-
-# 3. REFACTOR
-
-```
-# TASK: Refactor
-
-target:
-"<what is being improved>"
-
-goal:
-"<what improves>"
-
-scope:
-crates: []
-files: []
-
-non_goals:
-- no behavior changes
-- no new features
-
-constraints:
-- must preserve behavior exactly
-- must respect crate boundaries
-- must not duplicate logic
-
----
-
-## Refactor Type
-
-- [ ] simplify logic
-- [ ] reduce duplication
-- [ ] improve readability
-- [ ] performance (non-invasive)
-
----
-
-## Output Format
-
-analysis:
-issues_found:
-
-refactor_plan:
-
-code_changes:
-(diff only)
-
-verification:
-- behavior unchanged: yes/no
-- invariants preserved: yes/no
-
-notes:
-```
-
----
-
-# 4. SYSTEM DESIGN (NEW FEATURE)
-
-```
-# TASK: System Design
-
-feature:
-"<name>"
-
-goal:
-"<what problem it solves>"
-
-constraints:
-- must fit existing architecture
-- must follow plugin + event model
-- must not violate crate boundaries
-
----
-
-## Required Output
-
-design:
-
-components:
-- plugins:
-- systems:
-- events:
-- resources:
-
-data_flow:
-(step-by-step)
-
-integration_points:
-- where it connects to existing systems
-
-risks:
-- ""
-
-tradeoffs:
-- ""
-
----
-
-## DO NOT
-
-- write full implementation
-- modify unrelated systems
-```
-
----
-
-# 5. NEW BEVY SYSTEM
-
-```
-# TASK: Add Bevy System
-
-system_name:
-""
-
-trigger:
-(event or condition)
-
-reads:
-[Resources]
-
-writes:
-[Resources]
-
-emits:
-[Events]
-
-constraints:
-- must be event-driven
-- must not directly mutate unrelated state
-- must be single responsibility
-
----
-
-## Output Format
-
-system_signature:
-
-implementation:
-(code only)
-
-notes:
-```
-
----
-
-# 6. CORE LOGIC FUNCTION (solitaire_core)
-
-```
-# TASK: Core Logic Implementation
-
-function:
-"<name>"
-
-goal:
-"<what it does>"
-
-rules:
-- no IO
-- no async
-- no Bevy
-- deterministic
-
-invariants:
-- ""
-- ""
-
-errors:
-- ""
-
----
-
-## Output Format
-
-constraints_checked:
-
-implementation:
-(code only)
-
-edge_case_handling:
-
-notes:
-```
-
----
-
-# 7. SYNC / MERGE LOGIC
-
-```
-# TASK: Sync Logic
-
-goal:
-"<what is being merged or synced>"
-
-constraints:
-- must be deterministic
-- must be idempotent
-- must be lossless
-- must not delete data
-
-rules:
-- counters → max
-- times → min
-- collections → union
-
----
-
-## Output Format
-
-analysis:
-
-merge_logic:
-
-code_changes:
-
-invariants_verified:
-- deterministic
-- idempotent
-- lossless
-
-notes:
-```
-
----
-
-# 8. PERFORMANCE OPTIMIZATION
-
-```
-# TASK: Optimization
-
-target:
-"<what is slow>"
-
-constraints:CLAUDE_WORKFLOW.md
-- no behavior change
-- no architecture change
-- minimal code changes
-
----
-
-## Output Format
-
-analysis:
-bottleneck:
-
-optimization_strategy:
-
-code_changes:
-
-impact_estimate:
-
-notes:
-```
-
----
-
-# 9. TEST GENERATION (STRICT MODE)
-
-```
-# TASK: Test Generation
-
-target:
-"<function/system>"
-
-reason:
-- bugfix | complex logic | invariant protection
-
-constraints:
-- no redundant tests
-- must test real behavior
-- must fail if logic breaks
-
----
-
-## Output Format
-
-test_cases:
-- ""
-
-test_code:
-
-notes:
-```
-
----
-
-# 10. DEBUGGING / INVESTIGATION
-
-```
-# TASK: Debug
-
-problem:
-"<symptom>"
-
-context:
-"<relevant code or system>"
-
----
-
-## Required Steps
-
-1. List possible causes
-2. Narrow down most likely
-3. Suggest verification steps
-4. Provide minimal fix
-
----
-
-## Output Format
-
-hypotheses:
-
-most_likely:
-
-verification_steps:
-
-fix:
-
-notes:
-```
-
----
-
-# 11. HARD CONSTRAINT OVERRIDE (RARE)
-
-```
-# TASK: Exception Handling
-
-reason:
-"<why constraints must be bent>"
-
-requested_exception:
-"<rule being broken>"
-
-justification:
-"<why unavoidable>"
-
----
-
-## Output Format
-
-analysis:
-
-alternatives_considered:
-
-final_decision:
-
-risk:
-```
-
----
-
-# 12. STOP CONDITIONS (always append)
-
-```
-Stop when:
-- acceptance criteria are met
-- code is minimal and correct
-
-Do NOT:
-- expand scope
-- refactor unrelated code
-- optimize prematurely
-```
-
----
-
-# END

CLAUDE_SPEC.md

@@ -1,292 +0,0 @@
-# CLAUDE_SPEC.md
-
-version: 1.0
-
----
-
-## 0. Global Rules
-
-(Core determinism, panic policy, and event-driven engine constraints live in CLAUDE.md §2.1, §2.3, §3.1. Listed here only when they add information CLAUDE.md doesn't carry.)
-
-rules:
-
-* id: single_source_of_truth
-  description: "GameStateResource is the only mutable game state in runtime"
-
-* id: sync_is_additive
-  description: "Remote data must never destructively overwrite local data"
-
----
-
-## 1. Crate Graph
-
-crates:
-solitaire_core:
-depends_on: [rand, serde, chrono]
-forbidden_deps: [bevy, reqwest, tokio, std::fs]
-
-solitaire_sync:
-depends_on: [serde, serde_json, uuid, chrono]
-role: "shared_types"
-
-solitaire_data:
-depends_on: [solitaire_core, solitaire_sync, reqwest, tokio, keyring]
-role: "persistence_and_sync"
-
-solitaire_engine:
-depends_on: [bevy, kira, solitaire_core, solitaire_data]
-role: "runtime_engine"
-
-solitaire_server:
-depends_on: [solitaire_sync, axum, sqlx, jsonwebtoken]
-role: "backend"
-
-solitaire_app:
-depends_on: [solitaire_engine]
-role: "entrypoint"
-
----
-
-## 2. Data Ownership
-
-ownership:
-GameState:
-owner: solitaire_core
-mutable_in: solitaire_engine
-access_pattern: "via GameStateResource only"
-
-StatsSnapshot:
-owner: solitaire_data
-
-PlayerProgress:
-owner: solitaire_data
-
-AchievementRecord:
-owner: solitaire_data
-
-SyncPayload:
-owner: solitaire_sync
-
----
-
-## 3. State Transitions
-
-state_machine:
-GameState:
-transitions:
-- action: move_cards
-returns: Result<GameState, MoveError>
-
-```
-  - action: draw
-    returns: Result<GameState, MoveError>
-
-  - action: undo
-    returns: Result<GameState, MoveError>
-
-invariants:
-  - "52 cards always exist"
-  - "no duplicate card IDs"
-  - "all cards belong to exactly one pile"
-```
-
----
-
-## 4. Event System
-
-events:
-
-input:
-- MoveRequestEvent
-- DrawRequestEvent
-- UndoRequestEvent
-- NewGameRequestEvent
-
-state:
-- StateChangedEvent
-- GameWonEvent
-
-meta:
-- AchievementUnlockedEvent
-- SyncCompleteEvent
-
-rules:
-
-* "Input events trigger core logic"
-* "Core logic emits state events"
-* "UI reacts to state events only"
-
----
-
-## 5. Sync Contract
-
-sync:
-
-provider_trait:
-methods:
-- pull() -> SyncPayload
-- push(payload) -> SyncResponse
-
-guarantees:
-- "non-blocking during gameplay"
-- "blocking allowed on exit only"
-
-merge:
-rules:
-counters: "max"
-best_times: "min"
-collections: "union"
-achievements: "never removed"
-
-```
-properties:
-  - deterministic
-  - idempotent
-  - lossless
-```
-
----
-
-## 6. Persistence
-
-storage:
-
-format: json
-
-files:
-- stats.json
-- progress.json
-- achievements.json
-- settings.json
-- game_state.json
-
-guarantees:
-- atomic_write: true
-- crash_safe: true
-
----
-
-## 7. Engine Rules
-
-engine:
-
-mutation_rules:
-- "Only GameLogicSystem mutates GameState"
-- "UI systems are read-only"
-
-threading:
-- "sync runs on AsyncComputeTaskPool"
-- "main thread must never block"
-
-plugins:
-pattern: "feature_isolation"
-communication: "events"
-
----
-
-## 8. Server Contract
-
-server:
-
-auth:
-method: jwt
-access_expiry: 24h
-refresh_expiry: 30d
-
-endpoints:
-- POST /api/auth/register
-- POST /api/auth/login
-- GET /api/sync/pull
-- POST /api/sync/push
-
-limits:
-payload_max: 1MB
-rate_limit: "10 req/min auth routes"
-
----
-
-## 9. Achievement System
-
-achievements:
-
-definition_location: solitaire_core
-state_location: solitaire_data
-
-types:
-- condition_based
-- event_driven
-
-rule:
-- "achievements cannot be revoked"
-
----
-
-## 10. Testing Rules
-
-testing:
-
-philosophy:
-- "test real failures"
-- "avoid redundant tests"
-
-required_coverage:
-solitaire_core:
-- move_validation
-- undo_integrity
-- win_detection
-
-```
-solitaire_sync:
-  - merge_correctness
-  - idempotency
-```
-
----
-
-## 11. Prohibited Patterns
-
-(See CLAUDE.md §11 for the canonical forbidden-patterns list.)
-
----
-
-## 12. Extension Points
-
-extensibility:
-
-sync_backends:
-pattern: "implement SyncProvider"
-
-game_modes:
-location: solitaire_core::GameMode
-
-plugins:
-rule: "new feature = new plugin"
-
----
-
-## 13. Validation Checklist (for Claude)
-
-validation:
-
-* check: "crate dependency rules respected"
-* check: "no panics in core"
-* check: "events used for cross-system communication"
-* check: "GameState mutations centralized"
-* check: "merge function properties preserved"
-* check: "no blocking operations in main loop"
-
----
-
-## 14. Mental Model
-
-model:
-
-layers:
-- core
-- engine
-- data
-- server
-
-flow:
-- input -> engine -> core -> engine -> ui
-- data <-> sync <-> server

CLAUDE_WORKFLOW.md

@@ -1,335 +0,0 @@
-# CLAUDE_WORKFLOW.md
-
-version: 1.0
-
----
-
-## 0. Overview
-
-This workflow defines a **two-agent system**:
-
-* **Builder Agent** → writes and modifies code
-* **Guardian Agent** → enforces architecture + rejects invalid changes
-
-No code is considered valid unless it passes Guardian validation.
-
----
-
-## 1. Agent Roles
-
-### 1.1 Builder Agent
-
-role: "code_generation"
-
-responsibilities:
-
-* implement features
-* refactor code
-* generate tests (only when justified)
-* follow CLAUDE_SPEC.md
-
-constraints:
-
-* cannot bypass validation
-* must declare intent before writing code
-
-output_contract:
-must_produce:
-- change_summary
-- files_modified
-- reasoning (short)
-- code_diff
-
----
-
-### 1.2 Guardian Agent
-
-role: "architecture_enforcement"
-
-responsibilities:
-
-* validate against CLAUDE_SPEC.md
-* detect violations
-* reject or approve changes
-* suggest minimal fixes (not full rewrites)
-
-constraints:
-
-* no feature implementation
-* no large rewrites
-* must be deterministic
-
-output_contract:
-must_produce:
-- status: APPROVED | REJECTED
-- violations[]
-- required_fixes[]
-- optional_improvements[]
-
----
-
-## 2. Workflow Pipeline
-
-```text
-User Request
-    ↓
-Builder Agent (proposal + code)
-    ↓
-Guardian Agent (validation)
-    ↓
-IF approved → commit
-IF rejected → feedback → Builder retry
-```
-
----
-
-## 3. Builder Protocol
-
-### Step 1 — Intent Declaration
-
-Builder MUST start with:
-
-```yaml
-intent:
-  feature: "<name>"
-  crates_touched: []
-  systems_affected: []
-  risk_level: low|medium|high
-```
-
----
-
-### Step 2 — Plan
-
-```yaml
-plan:
-  - step: "..."
-  - step: "..."
-```
-
----
-
-### Step 3 — Implementation
-
-* Only modify declared crates
-* Follow ownership rules
-* Use events for cross-system communication
-
----
-
-### Step 4 — Output
-
-```yaml
-change_summary: "..."
-
-files_modified:
-  - path: ...
-    change: "..."
-
-violations_self_check:
-  - none | list
-
-notes: "short reasoning"
-```
-
----
-
-## 4. Guardian Protocol
-
-### Step 1 — Spec Validation
-
-Check against:
-
-* crate boundaries
-* mutation rules
-* event system usage
-* sync guarantees
-* forbidden patterns
-
----
-
-### Step 2 — Invariant Validation
-
-Must verify:
-
-* GameState invariants preserved
-* no new panic paths
-* no blocking calls in engine
-* merge properties unchanged
-
----
-
-### Step 3 — Output Decision
-
-#### APPROVED
-
-```yaml
-status: APPROVED
-
-notes:
-  - "no violations"
-```
-
----
-
-#### REJECTED
-
-```yaml
-status: REJECTED
-
-violations:
-  - id: core_purity_violation
-    file: "solitaire_core/src/..."
-    reason: "uses std::fs"
-
-required_fixes:
-  - "move IO to solitaire_data"
-
-optional_improvements:
-  - "simplify event naming"
-```
-
----
-
-## 5. Enforcement Rules
-
-### Hard Fail (automatic rejection)
-
-* core crate uses IO / Bevy / network
-* GameState mutated outside GameLogicSystem
-* blocking async on main thread
-* duplicate logic across crates
-* merge function altered incorrectly
-
----
-
-### Soft Fail (allowed but flagged)
-
-* unnecessary complexity
-* redundant tests
-* minor architectural drift
-
----
-
-## 6. Iteration Loop
-
-Max attempts per task: **3**
-
-```text
-Attempt 1 → Reject → Fix
-Attempt 2 → Reject → Fix
-Attempt 3 → Final decision
-```
-
-If still failing:
-→ escalate to user
-
----
-
-## 7. Diff Strategy
-
-Builder MUST produce:
-
-* minimal diffs
-* no unrelated refactors
-* no formatting-only changes
-
----
-
-## 8. Test Strategy Integration
-
-Builder rules:
-
-* only add tests if:
-
-  * fixing a bug
-  * protecting complex logic
-  * validating invariants
-
-Guardian rejects:
-
-* redundant tests
-* no-op tests
-
----
-
-## 9. Optional Extensions
-
-### 9.1 Third Agent (Optimizer)
-
-role: performance + cleanup
-
-runs AFTER approval:
-
-* reduce allocations
-* simplify logic
-* improve ECS scheduling
-
----
-
-### 9.2 CI Integration
-
-Pipeline:
-
-```text
-Builder → Guardian → cargo check → clippy → tests
-```
-
-Guardian runs BEFORE compilation to catch structural issues early.
-
----
-
-## 10. Example Interaction
-
-### Builder
-
-```yaml
-intent:
-  feature: "undo stack limit fix"
-  crates_touched: [solitaire_core]
-  risk_level: low
-```
-
-```yaml
-change_summary: "limit undo stack to 64 entries"
-
-files_modified:
-  - solitaire_core/src/game_state.rs
-
-notes: "prevents unbounded memory growth"
-```
-
----
-
-### Guardian
-
-```yaml
-status: APPROVED
-
-notes:
-  - "respects core constraints"
-  - "no invariant violations"
-```
-
----
-
-## 11. Mental Model
-
-* Builder = **creative**
-* Guardian = **strict**
-
-Builder explores
-Guardian enforces
-
-Neither replaces the other.
-
----
-
-## 12. Success Criteria
-
-System is working if:
-
-* architectural violations go to ~0
-* code stays consistent across features
-* refactors become safe
-* complexity grows sub-linearly

CREDITS.md

@@ -1,6 +1,6 @@
 # Credits
 
-Solitaire Quest is MIT-licensed (see [LICENSE](LICENSE)). It is built on top of
+Ferrous Solitaire is MIT-licensed (see [LICENSE](LICENSE)). It is built on top of
 the work of many open-source projects and a small handful of third-party
 assets. This file lists every component that ships in the binary or in the
 `assets/` directory.
@@ -43,7 +43,7 @@ copyleft code is statically linked into the game binary.
 | File(s) | Source | License |
 |---|---|---|
 | `solitaire_engine/assets/themes/default/{suit}_{rank}.svg` (52 SVGs) | [hayeah/playing-cards-assets](https://github.com/hayeah/playing-cards-assets) | MIT |
-| `solitaire_engine/assets/themes/default/back.svg` | Original — Solitaire Quest | MIT (this project) |
+| `solitaire_engine/assets/themes/default/back.svg` | Original — Ferrous Solitaire | MIT (this project) |
 | `assets/cards/faces/{RANK}{SUIT}.png` (52 PNGs) | Pre-rendered from the same `playing-cards-assets` SVGs | MIT (passed through from hayeah) |
 | `assets/cards/backs/back_0.png` – `back_4.png` | Original — generated by `solitaire_assetgen::gen_art` | MIT (this project) |
 
@@ -107,6 +107,6 @@ Audio files are MIT-licensed alongside the rest of this project.
   backs, every audio file) are original work covered by this project's MIT
   license.
 
-If you redistribute Solitaire Quest, you must ship this `CREDITS.md` and the
+If you redistribute Ferrous Solitaire, you must ship this `CREDITS.md` and the
 `LICENSE` file alongside the binary so the MIT (project + hayeah card art)
 and OFL (FiraMono) notices remain visible to end users.

Cargo.lock

@@ -4034,9 +4034,14 @@ checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104"
 dependencies = [
  "bytemuck",
  "byteorder-lite",
+ "color_quant",
+ "gif",
+ "image-webp",
  "moxcms",
  "num-traits",
  "png 0.18.1",
+ "zune-core",
+ "zune-jpeg",
 ]
 
 [[package]]
@@ -6967,6 +6972,8 @@ version = "0.1.0"
 dependencies = [
  "ab_glyph",
  "png 0.17.16",
+ "solitaire_core",
+ "solitaire_data",
 ]
 
 [[package]]
@@ -6984,8 +6991,10 @@ version = "0.1.0"
 dependencies = [
  "async-trait",
  "axum",
+ "bevy",
  "chrono",
  "dirs",
+ "jni 0.21.1",
  "jsonwebtoken",
  "keyring-core",
  "reqwest",
@@ -7009,10 +7018,14 @@ dependencies = [
  "bevy",
  "chrono",
  "dirs",
+ "image",
+ "jni 0.21.1",
  "kira",
+ "reqwest",
  "resvg",
  "ron",
  "serde",
+ "serde_json",
  "solitaire_core",
  "solitaire_data",
  "solitaire_sync",

Cargo.toml

@@ -31,6 +31,7 @@ keyring     = "4"
 keyring-core = "1"
 reqwest     = { version = "0.13", features = ["json", "rustls", "rustls-native-certs"], default-features = false }
 arboard     = { version = "3", default-features = false }
+jni         = { version = "0.21", default-features = false }
 
 solitaire_core   = { path = "solitaire_core" }
 solitaire_sync   = { path = "solitaire_sync" }
@@ -109,6 +110,9 @@ ron = "0.12"
 # only `deflate` is needed because the importer rejects other
 # compression methods anyway (see Phase 7 spec).
 zip = { version = "8.6", default-features = false, features = ["deflate"] }
+# Image decoding for avatar bytes received from the server.
+# Features mirror what Bevy already enables via bevy_image.
+image = { version = "0.25", default-features = false, features = ["png", "jpeg", "webp", "gif"] }
 
 # Importer-only test dependency: tests build zip archives in a
 # scratch directory so they don't pollute the real user themes path

README.md

@@ -1,4 +1,4 @@
-# Solitaire Quest
+# Ferrous Solitaire
 
 A cross-platform Klondike Solitaire game written in Rust, with a card-theme
 system, full progression (XP / levels / achievements / daily challenges), and
@@ -31,6 +31,23 @@ optional self-hosted sync so your stats follow you across machines.
 - **Color-blind mode** — blue tint on red-suit cards alongside the suit
   glyph
 
+## Android Install
+
+### Obtainium (recommended — automatic updates)
+
+1. Install [Obtainium](https://github.com/ImranR98/Obtainium/releases) on your device
+2. Tap the badge below on your Android device — the source type is pre-configured, no manual selection needed:
+
+   [<img src="https://raw.githubusercontent.com/ImranR98/Obtainium/main/assets/graphics/badge_obtainium.png" alt="Get it on Obtainium" height="40">](https://apps.obtainium.imranr.dev/redirect?r=obtainium://app/%7B%22id%22%3A%22com.ferrousapp.solitaire%22%2C%22url%22%3A%22https%3A//git.aleshym.co/funman300/Ferrous-Solitaire%22%2C%22author%22%3A%22funman300%22%2C%22name%22%3A%22Ferrous%20Solitaire%22%2C%22installedVersion%22%3Anull%2C%22latestVersion%22%3Anull%2C%22apkUrls%22%3A%22%5B%5D%22%2C%22preferredApkIndex%22%3A0%2C%22additionalSettings%22%3A%22%7B%7D%22%2C%22lastUpdateCheck%22%3Anull%2C%22pinned%22%3Afalse%2C%22categories%22%3A%5B%5D%2C%22releaseDate%22%3Anull%2C%22changeLog%22%3Anull%2C%22overrideSource%22%3A%22Codeberg%22%2C%22allowIdChange%22%3Afalse%2C%22otherAssetUrls%22%3A%22%5B%5D%22%7D)
+
+3. Tap **Install** to download the current release — Obtainium will notify you when updates are available.
+
+### Direct APK
+
+Download the latest `ferrous-solitaire.apk` from the
+[Releases](https://git.aleshym.co/funman300/Ferrous-Solitaire/releases) page,
+enable **Install from unknown sources** in your device settings, and open the file.
+
 ## Building
 
 **Prerequisites**

README_SERVER.md

@@ -1,4 +1,4 @@
-# Solitaire Quest — Self-Hosting Guide
+# Ferrous Solitaire — Self-Hosting Guide
 
 ## Prerequisites
 
@@ -42,3 +42,29 @@ git pull
 docker compose build
 docker compose up -d
 ```
+
+
+## Admin — Password Reset
+
+If a player loses access to their account, the server binary includes a
+built-in password reset command. Run it on the host (or inside the container)
+with `DATABASE_URL` pointing at your database:
+
+```bash
+# Interactive (prompts for the new password):
+DATABASE_URL=sqlite://./data/solitaire.db \
+  ./solitaire_server --reset-password <username>
+
+# Non-interactive (piped from a script or password manager):
+echo "new_password" | \
+  DATABASE_URL=sqlite://./data/solitaire.db \
+    ./solitaire_server --reset-password <username>
+
+# Inside a running Docker container:
+docker compose exec server sh -c \
+  'echo "new_password" | ./solitaire_server --reset-password alice'
+```
+
+On success the user's `password_hash` is updated and **all active refresh
+tokens are deleted**, so every open session must log in again with the new
+password. `JWT_SECRET` does not need to be set for this command.

SESSION_HANDOFF.md

@@ -1,313 +0,0 @@
-# Solitaire Quest — Session Handoff
-
-**Last updated:** 2026-05-08 — **v0.21.0 cut and tagged at `04f9bf9`**,
-working tree clean, all post-tag work pushed to origin.
-
-v0.21.0 closes the visual-identity arc opened in v0.20.0. Three
-through-lines landed in this cycle: the **card-face / suit /
-card-back artwork migration** that v0.20.0 deliberately deferred
-(both rendering paths in lockstep — `assets/cards/*.png` fallback
-plus the bundled-default theme SVGs at
-`solitaire_engine/assets/themes/default/*.svg` that
-`include_bytes!()`-embed into the binary), the **splash boot-
-screen + replay-overlay polish** that closed Resume-prompt
-Options B and C, and a late-cycle **`ACCENT_PRIMARY` palette
-swap** from cyan `#6fc2ef` to brick red `#a54242` after a quick
-stakeholder review of the shipped art.
-
-Full v0.21.0 detail lives in `CHANGELOG.md` § [0.21.0]. This
-file from here on focuses on what's *open* post-cut and how to
-resume.
-
-## Status at pause
-
-- **HEAD locally:** see `git rev-parse HEAD`. The cut commit is
-  `04f9bf9`; any post-cut docs edits ride on top of that.
-- **HEAD on origin:** matches local. v0.21.0 is fully on origin.
-- **Working tree:** clean. No WIP outstanding.
-- **`artwork/` directory:** still untracked. Intentional.
-- **Build:** `cargo clippy --workspace --all-targets -- -D warnings`
-  clean.
-- **Tests:** **1184 passing / 0 failing** across the workspace
-  (net +8 from v0.20.0's 1176 baseline). Detail in
-  `CHANGELOG.md` § [0.21.0] § Stats.
-- **Tags on origin:** `v0.9.0` through `v0.21.0`. v0.21.0 is on
-  `04f9bf9`; v0.20.0 stays on `41a009a`.
-
-## Since the v0.21.0 cut
-
-Two Resume-prompt options closed post-tag (2026-05-08):
-
-- **Option A — App icon round** (`3eb3a26` + `716a025`). 9-size
-  PNG hierarchy in `assets/icon/` (16/24/32/48/64/128/256/512/
-  1024 px), generated by a new `icon_generator` example from a
-  shared `icon_svg` builder (Terminal `▌RS` mark on dark
-  `#151515` with brick-red accent). Runtime `Window::icon`
-  wired via `WinitWindows` on desktop only (Android draws its
-  launcher icon from the APK manifest). The follow-up fix
-  `716a025` wraps `NonSend<WinitWindows>` in `Option<...>`
-  to satisfy Bevy 0.18's stricter system-param validation —
-  the resource doesn't exist on the first few frames before
-  winit's `Resumed` event fires. New deps (target-gated
-  non-Android): direct `winit = "0.30"` for `Icon`
-  construction, direct `tiny-skia` for PNG → RGBA decode.
-  Pin test `icon_svg_pin` guards future rasteriser drift.
-- **Option F — Accessibility modes** (`c5787c6` + `07e0357`).
-  High-contrast and reduce-motion settings flags wired through
-  the engine and surfaced as Settings panel toggles. HC boosts
-  `RED_SUIT_COLOUR` to `#ff8aa0` and `BLACK_SUIT_COLOUR` to
-  `#f5f5f5` for card text rendering; reduce-motion forces
-  `effective_slide_secs` to 0 regardless of `AnimSpeed`. CBM
-  and HC compose: lime CBM wins on red when both are on; HC
-  still applies to black suits when both are on. Six new
-  tests pin the truth tables. UI toggles sit alongside the
-  Color-blind row in Settings → Cosmetic; tab-walk visits
-  all three accessibility flags in one vertical run.
-
-Three Resume-prompt options remain live: B (APK launch
-verification), C (replay-overlay extensions), D (Toast
-Warning/Error wiring), E (Phase 8 sync). The visible-payoff
-pieces of the post-v0.21.0 menu have shipped; what's left is
-Android runtime work, replay-overlay polish, sync infrastructure,
-and toast-event sourcing.
-
-## Open punch list
-
-### Phase Android (build + persistence shipped; runtime gaps remain)
-
-- **APK launch verification on AVD / device.** `adb install` then
-  `adb logcat` against the `bevy_test` AVD or an x86_64 device.
-  The build works and persistence is wired, but no end-to-end
-  device run has been logged. Shakes out runtime bugs the build +
-  unit tests can't catch.
-- **JNI ClipboardManager bridge.** Replaces the Android stub for
-  the Stats "Copy share link" toast. `arboard` doesn't ship an
-  Android backend; small custom JNI call.
-- **Android Keystore for credentials.** `keyring` is target-gated
-  to a stub returning `KeychainUnavailable`; replace with Android
-  Keystore via JNI when sync auth ships on mobile.
-- **Google Play Games (gpgs) integration.** Listed as a
-  Phase-Android target since Phase 1; now unblocked by the build
-  target.
-- **Cosmetic `cargo apk build --lib` workaround.** Post-sign
-  panic doesn't affect the APK on disk but produces noisy stderr.
-  Either upstream a cargo-apk fix or document `--lib` as
-  canonical in the runbook.
-
-### Visual-identity follow-ups (post-v0.21.0)
-
-The visual-identity arc is effectively complete: token system,
-chrome migration, splash boot screen, replay-overlay banner,
-card-face artwork (both rendering paths), and the `ACCENT_PRIMARY`
-palette refresh all shipped in v0.20.0 + v0.21.0. What stays open:
-
-- **Replay-overlay screen-takeover redesign.** The full mockup
-  (`docs/ui-mockups/replay-overlay-mobile.html`) calls for a
-  mini-tableau preview, playback controls, move-log scroll, and
-  a WIN MOVE marker on the scrub bar. Banner-local pieces all
-  shipped in v0.21.0 (`c84d9f4` + `6204db8` + `54005d5` +
-  `e080b49`); the screen-takeover is a multi-session redesign
-  with data-layer impact (move-log scroller; WIN MOVE needs a
-  `win_move_index` field on `Replay` that doesn't yet exist).
-- **Floating `MOVE N/M` chip above the focused card during
-  playback.** Cross-plugin work — `update_progress_text` writes
-  the banner chip but the card-position lookup belongs in
-  `card_plugin`. Smaller scope than the screen-takeover.
-- **Toast Warning / Error variants.** `ToastVariant` has slots
-  for `Warning` (gold) and `Error` (pink) but no in-engine
-  event uses them yet. Wire when a warning- or error-flavoured
-  toast event materialises.
-- *High-contrast accessibility mode — closed 2026-05-08 by
-  `c5787c6` + `07e0357`.* Card text rendering picks up
-  `TEXT_PRIMARY_HC` (`#f5f5f5`) and `RED_SUIT_COLOUR_HC`
-  (`#ff8aa0`); Settings panel has a toggle. Future scope:
-  extend HC through chrome borders (`BORDER_SUBTLE_HC` already
-  defined, not yet consumed), buttons, popover edges.
-- *Reduced-motion mode — closed 2026-05-08 by the same pair.*
-  `effective_slide_secs` forces 0 when on, regardless of the
-  `AnimSpeed` setting. Future scope: gate splash scanline
-  overlay + cursor pulse animation on the same flag, gate
-  warning-chip pulse, gate any future card-lift z-bump
-  animation.
-
-### Carried forward from v0.19.0
-
-- *App icon round — closed 2026-05-08 by `3eb3a26` + `716a025`.*
-  Runtime `Window::icon` wired (Linux/macOS/Windows); 9-size
-  PNG hierarchy at `assets/icon/icon_<size>.png` covers Linux
-  hicolor + downstream `.icns`/`.ico` packaging needs. The
-  `.ico` and `.icns` bundle-format files themselves are *not*
-  generated — both would need new crate deps (`ico` and
-  `icns` respectively) and only matter at app-bundle time
-  (cargo-bundle / packaging), not at `cargo run`. Open if the
-  project later ships as a packaged macOS / Windows app.
-
-### Other small candidates
-
-- **Prev/Next selector chips spawn site.** v0.19.0's `9b065e5`
-  noted Prev/Next markers exist in `stats_plugin` but no spawn
-  site renders them today — the Shareable badge therefore lands
-  on the single-replay caption. If/when Prev/Next is plumbed,
-  the badge will need to follow.
-- **Toast queue / immediate unification.** The two toast paths
-  (`spawn_queued_toast` for `InfoToastEvent` queue; `spawn_toast`
-  for fire-and-forget) now share visual treatment but remain
-  separate functions because they serve different temporal
-  needs (sequential vs. parallel). If overlap becomes a UX
-  issue, merge into one queue with priority lanes.
-
-### Process notes
-
-- **The desktop-adaptation spec is the canonical reference for
-  geometry decisions** when porting any future plugin. Read
-  `docs/ui-mockups/desktop-adaptation.md` first; apply the
-  universal rules to every surface; consult the per-screen
-  table for the priority surfaces. The 9 missing-plugin screens
-  (splash now ported; eight remaining) inherit the universal
-  rules without dedicated guidance.
-- **Stitch `generate_variants` is unreliable for layout-only
-  adaptation prompts** as of 2026-05-07. The first call timed
-  out and no variant ever landed in `list_screens`. If a future
-  session wants visual desktop mockups, prefer
-  `generate_screen_from_text` with a fresh narrow prompt per
-  screen rather than `generate_variants` against existing
-  mobile screens.
-- **Token-port pattern.** v0.20.0's chrome-migration commits
-  set a reusable shape for "centralised design system applied
-  across N plugins":
-  1. Constants module (`ui_theme.rs`) is the source of truth.
-  2. Const sites that can't call `Alpha::with_alpha` (not yet
-     `const` on stable) use a literal RGB matching the token,
-     with a unit test pinning the RGB to the token (e.g.
-     `MARKER_VALID`, `HINT_PILE_HIGHLIGHT_COLOUR`,
-     `RIGHT_CLICK_HIGHLIGHT_COLOUR`).
-  3. Cross-plugin duplication (e.g. `MARKER_DEFAULT` ↔
-     `PILE_MARKER_DEFAULT_COLOUR`) collapses to a single
-     promoted const re-exported from one plugin and imported
-     by the other — replaces "kept in sync" doc comments with a
-     compile-time invariant.
-  4. Domain colours (suit pips, card faces, lerp helpers) stay
-     as literals with a comment naming the rationale; only UI
-     chrome routes through tokens.
-- **`SplashFadable` scaffolding pattern** (introduced in
-  `cacb19c`). Any future overlay that needs to fade `N >> 3`
-  elements together should follow the same shape: one tiny
-  marker carrying the full-alpha base colour, one global query
-  that lerps every marker's alpha each frame, no per-element
-  query plumbing. Cleanly outscales the `Without<X>, Without<Y>`
-  query exclusion pattern that the old splash was hitting at
-  three siblings.
-
-### Canonical remote
-
-`github.com/funman300/Rusty_Solitaire` is the canonical repo.
-Always push there. As of v0.21.0 origin matches local; the next
-push happens when post-cut work accumulates and is ready to roll
-into a v0.21.1 / v0.22.0 cut.
-
-### Design direction (Terminal — base16-eighties)
-
-- **Tone:** retro-terminal / synthwave — flat depth (no box-shadows),
-  monospaced-forward typography (JetBrains Mono / FiraMono), tight
-  16 px edge margins, 8 px card radius.
-- **Palette:** near-black surface ramp (`#151515` / `#202020` /
-  `#2a2a2a` / `#353535`), brick-red primary CTA (`#a54242` —
-  swapped from cyan `#6fc2ef` in v0.21.0 commit `a292a7e`), lime
-  success (`#acc267`), gold warning (`#ddb26f`), pink error /
-  suit-red (`#fb9fb1`), lavender celebration (`#e1a3ee`), teal
-  info (`#12cfc0`).
-- **Two-color suits.** Red = `#fb9fb1`, black = `#d0d0d0`.
-  Outlined glyphs for diamonds & clubs are *always on*; the
-  Settings "color-blind mode" toggle swaps red → lime `#acc267`
-  (was red → cyan pre-v0.21.0; lime is the next-best non-red
-  base16-eighties accent now that the primary itself is red).
-- **Card glyphs render upright in both corners** — no 180°
-  inverted-corner-indicator rotation. Single-orientation
-  digital play doesn't benefit from the traditional flip-
-  readback convention. `design-system.md` § Game Cards
-  documents this deliberate deviation.
-
-## Resume prompt
-
-```
-You are a senior Rust + Bevy developer working on Solitaire Quest.
-Working directory: <Rusty_Solitaire clone path on this machine>.
-Branch: master. v0.21.0 is tagged at 04f9bf9 (cut 2026-05-08).
-Working tree clean. v0.21.0 closed the visual-identity arc that
-v0.20.0 deferred — full Terminal cards on both rendering paths
-(asset PNGs + bundled-default theme SVGs), splash boot screen,
-replay-overlay banner enrichments, and a project-wide ACCENT_PRIMARY
-swap from cyan to brick red `#a54242`. See CHANGELOG.md § [0.21.0]
-for full detail.
-
-State: HEAD locally — see `git rev-parse HEAD`. All workspace tests
-pass (1184+; check with `cargo test --workspace`), clippy clean.
-
-READ FIRST (in order, before doing anything):
-  1. SESSION_HANDOFF.md  — this file
-  2. CHANGELOG.md        — [0.21.0] section is the most recent cut
-  3. CLAUDE.md           — unified-3.0 rule set
-  4. CLAUDE_SPEC.md      — formal architecture spec
-  5. ARCHITECTURE.md     — crate responsibilities + data flow
-  6. docs/ui-mockups/    — design system + 24-mockup library +
-                           desktop-adaptation.md (the rules-based
-                           companion to the mockups; read this
-                           before any plugin port)
-  7. docs/android/*      — Android setup + build runbook
-  8. ~/.claude/projects/<this-project>/memory/MEMORY.md
-                         — saved feedback / project context
-                           (machine-local; may be missing on a
-                           fresh machine)
-
-DECISION TO ASK THE PLAYER FIRST:
-  A. *Closed 2026-05-08 by `3eb3a26` + `716a025`.* App icon
-     round — runtime `Window::icon` wired plus a 9-size PNG
-     hierarchy at `assets/icon/`. `.ico` / `.icns` bundle
-     formats stay open if the project later ships as a
-     packaged macOS / Windows app.
-  B. APK launch verification on AVD / device — `adb install` +
-     `adb logcat` to shake out runtime bugs the build / unit
-     tests can't catch. Likely surfaces JNI ClipboardManager
-     and Android Keystore stubs that need real bridges. Larger
-     scope; needs an Android device or emulator running.
-  C. Replay-overlay extensions — either the floating `MOVE N/M`
-     chip above the focused card (smaller, cross-plugin; needs
-     cursor → card-position plumbing in `card_plugin`) or the
-     full screen-takeover redesign (multi-session: move-log
-     scroll, mini tableau preview, WIN MOVE marker, data-layer
-     impact for `Replay::win_move_index`).
-  D. Toast Warning / Error variant wiring. UI infrastructure
-     exists in `ToastVariant`; no in-engine event uses Warning
-     (gold) or Error (pink) yet. Wire when a real warning- or
-     error-flavoured event materialises.
-  E. Phase 8 (sync) — local storage scaffolding, self-hosted
-     Axum server, `SolitaireServerClient` impl, GPGS stub
-     wired into Settings. The biggest open arc by scope; rolls
-     up several Phase Android dependencies (Keystore,
-     ClipboardManager).
-  F. *Closed 2026-05-08 by `c5787c6` + `07e0357`.* High-contrast
-     and reduced-motion accessibility modes — Settings flags
-     + UI toggles + engine wiring. Card text rendering uses
-     HC variants when on; card slide_secs forces to 0 when
-     reduce-motion is on. Future scope: extend HC through
-     chrome borders, buttons; gate splash + warning-chip
-     animations on reduce-motion.
-
-WORKFLOW NOTES:
-  - Use the system git config (already correct).
-  - When attributing playtester feedback in commits/docs, use
-    "Quat" not "Rhys" (saved feedback memory).
-  - Sub-agents stage + verify only; orchestrator commits.
-  - Every commit must pass build / clippy / test before pushing.
-  - Push to GitHub (origin) — gh auth setup-git wired on
-    primary dev box; verify on laptop before first push.
-  - Token-port pattern: when migrating tokens, walk every
-    concrete artifact downstream of the token (PNG textures,
-    embedded SVGs, hardcoded literals, comment color names),
-    not just the token name. v0.21.0 surfaced three "the
-    migration walked past this" follow-ups that all matched
-    this shape — codified here so future similar work can
-    pattern-match instead of rediscovering.
-
-OPEN AT THE START: ask which of A–F. Don't pick unilaterally.
-```

argocd/application.yaml

@@ -0,0 +1,28 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: solitaire-server
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://git.aleshym.co/funman300/Ferrous-Solitaire.git
+    targetRevision: master
+    path: deploy
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: solitaire
+  # Secrets are applied manually and must not be pruned by ArgoCD.
+  ignoreDifferences:
+    - group: ""
+      kind: Secret
+      name: matomo-secret
+      namespace: solitaire
+      jsonPointers:
+        - /data
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true