fix(engine): resolve all clippy warnings introduced by PNG asset pipeline

- Collapse nested-if patterns into let-chains across 13 plugins (42 instances)
- Add #[allow(clippy::too_many_arguments)] to 5 Bevy systems in card_plugin
  and input_plugin where ECS parameter count exceeds the lint threshold
- Gate Theme import in table_plugin under #[cfg(test)] — only used by
  test-only colour helpers; removing the unconditional import silences the
  unused-import lint without breaking the test suite
- Wrap ButtonInput<MouseButton> in Option<> in update_input_platform so that
  tests using MinimalPlugins (no InputPlugin) no longer panic on startup

All 789 tests pass; cargo clippy --workspace -- -D warnings is clean.

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

.env.example

@@ -1,4 +1,16 @@
-DATABASE_URL=sqlite://solitaire.db
-JWT_SECRET=replace_with_64_char_hex_from_openssl_rand_hex_32
+# Copy to .env and fill in the values before running docker compose up.
+
+# SQLite database path inside the container.
+# When using docker-compose, leave as-is — the volume handles persistence.
+DATABASE_URL=sqlite:///data/solitaire.db
+
+# HS256 signing secret for JWT tokens.
+# Generate with: openssl rand -hex 32
+JWT_SECRET=replace_me_with_a_64_char_hex_secret
+
+# TCP port the server listens on inside the container.
 SERVER_PORT=8080
-ADMIN_USERNAME=admin
+
+# Public domain name used by Caddy for automatic HTTPS.
+# Example: solitaire.example.com
+SOLITAIRE_DOMAIN=solitaire.example.com

.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+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

@@ -4,3 +4,5 @@
 *.db-wal
 .env
 *.tmp
+data/
+.claude/

.sqlx/query-04d8dced0cc309bc0d968ab8f542a7f6c504ce7c2f682c0bef35dfe441ffb6e8.json

@@ -0,0 +1,20 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT goal_json FROM daily_challenges WHERE date = ?",
+  "describe": {
+    "columns": [
+      {
+        "name": "goal_json",
+        "ordinal": 0,
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "04d8dced0cc309bc0d968ab8f542a7f6c504ce7c2f682c0bef35dfe441ffb6e8"
+}

.sqlx/query-2e61cd30a6cd3e0937dd096b4f94493e8bcb8c10687d0f8c0592fe38ed956fa6.json

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

.sqlx/query-2f12541a6b99acf6d9e8f7ad13438df4ab92edcbfa01f38930aae63f1554b534.json

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

.sqlx/query-36bab3ca8f126c66a6f4865d2699702689518bd3a796c374f932aba0434a4c94.json

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

.sqlx/query-57c93a6acd7eea44d00412e62f0d3fed7ffbe4cd759353d29f38a8eb37f69112.json

@@ -0,0 +1,38 @@
+{
+  "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",
+  "describe": {
+    "columns": [
+      {
+        "name": "display_name",
+        "ordinal": 0,
+        "type_info": "Text"
+      },
+      {
+        "name": "best_score",
+        "ordinal": 1,
+        "type_info": "Integer"
+      },
+      {
+        "name": "best_time_secs",
+        "ordinal": 2,
+        "type_info": "Integer"
+      },
+      {
+        "name": "recorded_at",
+        "ordinal": 3,
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Right": 0
+    },
+    "nullable": [
+      false,
+      true,
+      true,
+      false
+    ]
+  },
+  "hash": "57c93a6acd7eea44d00412e62f0d3fed7ffbe4cd759353d29f38a8eb37f69112"
+}

.sqlx/query-5e9e61cae887a08e4224fbea43a047c093bf5a4413499bfec858e302efa91bc3.json

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

.sqlx/query-720edc3b85eec90744179f2c73ed9798814b734a2f3d57405ef95772ae66a24d.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "INSERT INTO sync_state (user_id, stats_json, achievements_json, progress_json, last_modified)\n           VALUES (?, ?, ?, ?, ?)\n           ON CONFLICT(user_id) DO UPDATE SET\n               stats_json        = excluded.stats_json,\n               achievements_json = excluded.achievements_json,\n               progress_json     = excluded.progress_json,\n               last_modified     = excluded.last_modified",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 5
+    },
+    "nullable": []
+  },
+  "hash": "720edc3b85eec90744179f2c73ed9798814b734a2f3d57405ef95772ae66a24d"
+}

.sqlx/query-73ffdf5be39aa5c4c160c2f77d6634a6970eeb4e1d3395f045ded747f0ce9d2a.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "DELETE FROM users WHERE id = ?",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "73ffdf5be39aa5c4c160c2f77d6634a6970eeb4e1d3395f045ded747f0ce9d2a"
+}

.sqlx/query-765c87463905b2edbf37f7416d5bc38e639c7e4c5feb0f5a9d8d6fb724e7a0a8.json

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

.sqlx/query-8697100790ebcdf4058812cf6debad8f9a13ac91c2d0ef20cff3bd4bb9385360.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "INSERT INTO leaderboard (user_id, display_name, recorded_at)\n           VALUES (?, ?, ?)\n           ON CONFLICT(user_id) DO UPDATE SET\n               display_name = excluded.display_name,\n               recorded_at  = excluded.recorded_at",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": []
+  },
+  "hash": "8697100790ebcdf4058812cf6debad8f9a13ac91c2d0ef20cff3bd4bb9385360"
+}

.sqlx/query-a908d8d19647494f2ac2f801dc9c977f7ce23b44779da1567049856eab922645.json

@@ -0,0 +1,32 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT stats_json, achievements_json, progress_json FROM sync_state WHERE user_id = ?",
+  "describe": {
+    "columns": [
+      {
+        "name": "stats_json",
+        "ordinal": 0,
+        "type_info": "Text"
+      },
+      {
+        "name": "achievements_json",
+        "ordinal": 1,
+        "type_info": "Text"
+      },
+      {
+        "name": "progress_json",
+        "ordinal": 2,
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "a908d8d19647494f2ac2f801dc9c977f7ce23b44779da1567049856eab922645"
+}

.sqlx/query-a931c228c46dc06a5657d419cd5dfa5a810bbce9501845c92c6619d29806d70c.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "UPDATE leaderboard\n           SET best_score     = MAX(COALESCE(best_score, 0), ?),\n               best_time_secs = CASE\n                   WHEN ? IS NULL THEN best_time_secs\n                   WHEN best_time_secs IS NULL THEN ?\n                   ELSE MIN(best_time_secs, ?)\n               END,\n               recorded_at = ?\n           WHERE user_id = ?",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 6
+    },
+    "nullable": []
+  },
+  "hash": "a931c228c46dc06a5657d419cd5dfa5a810bbce9501845c92c6619d29806d70c"
+}

.sqlx/query-ab537795ba39fdd28c502a8b9e615f53e7cb08f3eddd8f0574f4dc8156436de5.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "INSERT OR IGNORE INTO daily_challenges (date, seed, goal_json) VALUES (?, ?, ?)",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": []
+  },
+  "hash": "ab537795ba39fdd28c502a8b9e615f53e7cb08f3eddd8f0574f4dc8156436de5"
+}

.sqlx/query-cc1e091bf5e46e6d98baf94bac6d9ac1ca1845eff7c4b8196dd2efb93fd9e0dd.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "INSERT INTO users (id, username, password_hash, created_at) VALUES (?, ?, ?, ?)",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 4
+    },
+    "nullable": []
+  },
+  "hash": "cc1e091bf5e46e6d98baf94bac6d9ac1ca1845eff7c4b8196dd2efb93fd9e0dd"
+}

ARCHITECTURE.md

@@ -1,9 +1,9 @@
 # Solitaire Quest — Architecture Document
 
 > **Version:** 1.1  
-> **Language:** Rust (Edition 2021)  
+> **Language:** Rust (Edition 2024)  
 > **Engine:** Bevy (latest stable)  
-> **Last Updated:** 2026-04-20
+> **Last Updated:** 2026-04-29
 
 ---
 
@@ -16,28 +16,25 @@
 5. [Game Engine Architecture](#5-game-engine-architecture)
 6. [Persistence & Sync Architecture](#6-persistence--sync-architecture)
 7. [Sync Server Architecture](#7-sync-server-architecture)
-8. [Google Play Games Services (Android Future)](#8-google-play-games-services-android-future)
-9. [Data Models](#9-data-models)
-10. [API Reference](#10-api-reference)
-11. [Merge Strategy](#11-merge-strategy)
-12. [Achievement System](#12-achievement-system)
-13. [Progression System](#13-progression-system)
-14. [Audio System](#14-audio-system)
-15. [Asset Pipeline](#15-asset-pipeline)
-16. [Platform Targets](#16-platform-targets)
-17. [Build & Development Guide](#17-build--development-guide)
-18. [Deployment Guide](#18-deployment-guide)
-19. [Security Model](#19-security-model)
-20. [Testing Strategy](#20-testing-strategy)
-21. [Decision Log](#21-decision-log)
+8. [Data Models](#8-data-models)
+9. [API Reference](#9-api-reference)
+10. [Merge Strategy](#10-merge-strategy)
+11. [Achievement System](#11-achievement-system)
+12. [Progression System](#12-progression-system)
+13. [Audio System](#13-audio-system)
+14. [Asset Pipeline](#14-asset-pipeline)
+15. [Platform Targets](#15-platform-targets)
+16. [Build & Development Guide](#16-build--development-guide)
+17. [Deployment Guide](#17-deployment-guide)
+18. [Security Model](#18-security-model)
+19. [Testing Strategy](#19-testing-strategy)
+20. [Decision Log](#20-decision-log)
 
 ---
 
 ## 1. Project Overview
 
-Solitaire Quest is a cross-platform Klondike Solitaire game written in Rust, targeting macOS, Windows, and Linux desktops (iOS/Android as a stretch goal). 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.
-
-On Android (stretch goal), sync is enhanced with Google Play Games Services (GPGS) for native achievement popups, leaderboards, and cloud saves — sitting on top of the same underlying sync payload so data stays consistent regardless of which backend was used last.
+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.
 
 ### Sync Backend by Platform
 
@@ -46,8 +43,6 @@ On Android (stretch goal), sync is enhanced with Google Play Games Services (GPG
 | macOS | Self-hosted server | Full feature set |
 | Windows | Self-hosted server | Full feature set |
 | Linux | Self-hosted server | Full feature set |
-| Android (stretch) | Google Play Games Services | + server as fallback |
-| iOS (stretch) | Self-hosted server | GPGS not supported on iOS |
 
 ### Design Principles
 
@@ -72,26 +67,25 @@ solitaire_quest/
 ├── Dockerfile                  # Multi-stage server build
 ├── docker-compose.yml          # Server + Caddy reverse proxy
 │
-├── assets/                     # All runtime assets (loaded via Bevy AssetServer)
+├── assets/                     # Assets embedded at compile time via include_bytes!()
 │   ├── cards/
-│   │   ├── faces/              # Card face sprites (suit + rank)
-│   │   └── backs/              # Card back designs (back_0.png … back_4.png)
-│   ├── backgrounds/            # Table backgrounds (bg_0.png … bg_4.png)
-│   ├── fonts/                  # .ttf font files
+│   │   ├── faces/{rank}_{suit}.png  # 52 individual card faces (120×168, generated by solitaire_assetgen)
+│   │   └── backs/back_0.png – back_4.png    # placeholder patterns
+│   ├── backgrounds/bg_0.png – bg_4.png      # placeholder textures
+│   ├── fonts/main.ttf          # FiraMono-Medium (170K, OFL)
 │   └── audio/
-│       ├── card_deal.ogg
-│       ├── card_flip.ogg
-│       ├── card_place.ogg
-│       ├── card_invalid.ogg
-│       ├── win_fanfare.ogg
-│       └── ambient_loop.ogg
+│       ├── card_deal.wav
+│       ├── card_flip.wav
+│       ├── card_place.wav
+│       ├── card_invalid.wav
+│       ├── win_fanfare.wav
+│       └── ambient_loop.wav
 │
 ├── solitaire_core/             # Pure Rust game logic — zero external deps beyond rand/serde
 ├── solitaire_sync/             # Shared API types — used by client and server
 ├── solitaire_data/             # Persistence, sync client, settings
 ├── solitaire_engine/           # Bevy ECS systems, components, plugins
 ├── solitaire_server/           # Self-hosted sync server (Axum + SQLite)
-├── solitaire_gpgs/             # Google Play Games Services bridge (Android only, stub until stretch goal)
 └── solitaire_app/              # Main binary entry point
 ```
 
@@ -135,25 +129,10 @@ Owns:
 - `SyncBackend` enum and backend selection
 - Solitaire Server sync client (JWT auth, auto-refresh)
 - OS keychain integration (`keyring`)
-- `SyncProvider` trait — implemented by both `SolitaireServerClient` and `GpgsClient` (Android)
-
-### `solitaire_gpgs` *(stub — implement when targeting Android)*
-**Dependencies:** `solitaire_sync`, `jni` (Android only), `solitaire_data` trait impls.
-
-Android-only crate, compiled only when `target_os = "android"`. Bridges the Google Play Games Services Java SDK via JNI.
-
-Owns:
-- `GpgsClient` implementing the `SyncProvider` trait from `solitaire_data`
-- GPGS Saved Games API calls (load/save cloud save slot)
-- GPGS Achievements API calls (unlock, reveal, increment)
-- GPGS Leaderboards API calls (submit score, load scores)
-- Google Sign-In token management (via JNI into Android SDK)
-- Conversion between GPGS cloud save blob ↔ `SyncPayload`
-
-> **Note:** This crate contains only a trait stub and compile-time stub implementations until Android support is actively developed. Do not implement JNI bindings until Phase: Android.
+- `SyncProvider` trait — implemented by `SolitaireServerClient`
 
 ### `solitaire_engine`
-**Dependencies:** `bevy`, `bevy_egui`, `bevy_kira_audio`, `solitaire_core`, `solitaire_data`.
+**Dependencies:** `bevy`, `bevy_kira_audio`, `solitaire_core`, `solitaire_data`.
 
 All Bevy-specific code. Structured as a collection of Plugins that `solitaire_app` registers.
 
@@ -162,9 +141,10 @@ Owns:
 - Rendering systems (card sprites, table, backgrounds)
 - Drag-and-drop input handling
 - Animation systems (slide, flip, win cascade, toast)
-- All egui screens (Home, Stats, Achievements, Settings, Profile)
+- All Bevy UI screens (Home, Stats, Achievements, Settings, Profile)
 - Audio playback systems
 - Sync status display
+- Card, background, and font asset loading (embedded via `include_bytes!()` — no `AssetServer` dependency)
 
 ### `solitaire_server`
 **Dependencies:** `solitaire_sync`, `axum`, `sqlx`, `jsonwebtoken`, `bcrypt`, `tower-governor`, `tracing`, `tokio`, `dotenvy`.
@@ -209,7 +189,7 @@ RenderSystem          ScoreSystem          AchievementSystem
                                                 │
                                                 │ fires AchievementUnlockedEvent
                                                 ▼
-                                          ToastSystem (egui popup)
+                                          ToastSystem (Bevy UI popup)
                                           PersistenceSystem (write to disk)
 ```
 
@@ -223,8 +203,7 @@ SyncPlugin::on_startup()
     │  spawns AsyncComputeTask
     ▼
 solitaire_data::sync_pull()          ← dispatches to active SyncProvider
-    │                                    SolitaireServerClient  (desktop / iOS)
-    │                                    GpgsClient             (Android, future)
+    │                                    SolitaireServerClient
     ▼
 solitaire_sync::merge(local, remote)
     │
@@ -245,7 +224,7 @@ SyncPlugin::on_exit()
     │  blocking push (acceptable on exit, not on main loop)
     ▼
 active SyncProvider::push(local)
-    │  POST to server  — or —  GPGS Saved Games PUT (Android)
+    │  POST to server
     ▼
 Done
 ```
@@ -256,16 +235,36 @@ Done
 
 ### Bevy Plugins
 
-| Plugin | Responsibility |
-|---|---|
-| `CardPlugin` | Card entity spawning, sprite management, drag-and-drop |
-| `TablePlugin` | Pile markers, background, layout calculation |
-| `AnimationPlugin` | Slide, flip, win cascade, toast animations |
-| `AudioPlugin` | Sound effect and music playback via bevy_kira_audio |
-| `UIPlugin` | All egui screens: Home, Stats, Achievements, Settings, Profile |
-| `AchievementPlugin` | Listens for game events, evaluates unlock conditions, fires toasts |
-| `SyncPlugin` | Manages sync lifecycle (pull on start, push on exit, status display) |
-| `GamePlugin` | Core game state resource, input routing, win detection |
+| Plugin | Key | Responsibility |
+|---|---|---|
+| `CardPlugin` | — | Card entity spawning, sprite management, drag-and-drop |
+| `TablePlugin` | — | Pile markers, background, layout calculation |
+| `FontPlugin` | — | Embeds FiraMono-Medium font at compile time; exposes `FontResource` handle |
+| `AnimationPlugin` | — | Slide, flip, win cascade, toast animations |
+| `FeedbackAnimPlugin` | — | Shake, settle, and deal-stagger animations |
+| `AutoCompletePlugin` | Enter | Executes auto-complete when the HUD badge is lit |
+| `AudioPlugin` | — | Sound effect and music playback via bevy_kira_audio |
+| `InputPlugin` | — | Keyboard and mouse input routing |
+| `CursorPlugin` | — | Custom cursor sprite during drag |
+| `SelectionPlugin` | — | Keyboard-driven card selection |
+| `GamePlugin` | N | Core game state resource, new-game flow, win/game-over overlays |
+| `HudPlugin` | — | Score, move counter, timer, auto-complete badge |
+| `StatsPlugin` | S | Stats overlay and persistence |
+| `ProgressPlugin` | — | XP/level system, persistence |
+| `AchievementPlugin` | A | Unlock evaluation, toast events, persistence |
+| `DailyChallengePlugin` | — | Daily challenge resource and completion tracking |
+| `WeeklyGoalsPlugin` | — | Weekly goal progress and completion events |
+| `ChallengePlugin` | — | Challenge mode progression (seeded hard deals) |
+| `TimeAttackPlugin` | — | 10-minute time-attack mode timer |
+| `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 |
+| `LeaderboardPlugin` | L | Leaderboard overlay |
+| `HelpPlugin` | H | Help / controls overlay |
+| `PausePlugin` | Esc | Pause and resume |
+| `OnboardingPlugin` | — | First-run welcome screen |
+| `SyncPlugin` | — | Async sync lifecycle (pull on start, push on exit, status display) |
+| `WinSummaryPlugin` | — | Win cascade overlay and screen-shake effect |
 
 ### Key Bevy Resources
 
@@ -290,6 +289,20 @@ struct StatsResource(StatsSnapshot);
 struct ProgressResource(PlayerProgress);
 struct AchievementsResource(Vec<AchievementRecord>);
 struct SettingsResource(Settings);
+
+// Pre-loaded card face and back PNG handles
+struct CardImageSet {
+    faces: [[Handle<Image>; 13]; 4], // [suit][rank]: Clubs=0..Spades=3, Ace=0..King=12
+    backs: [Handle<Image>; 5],       // indexed by selected_card_back setting
+}
+
+// Project-wide font handle (FiraMono-Medium embedded at compile time)
+struct FontResource(Handle<Font>);
+
+// Pre-loaded background PNG handles
+struct BackgroundImageSet {
+    handles: Vec<Handle<Image>>,    // indices 0–4 match selected_background setting
+}
 ```
 
 ### Key Bevy Events
@@ -363,7 +376,6 @@ Implementations:
 |---|---|---|
 | `LocalOnlyProvider` | No-op (default) | All |
 | `SolitaireServerClient` | Self-hosted server | All |
-| `GpgsClient` *(future)* | Google Play Games Services | Android only |
 
 Sync always runs on `bevy::tasks::AsyncComputeTaskPool` — the game thread is never blocked.
 
@@ -378,9 +390,6 @@ pub enum SyncBackend {
         // JWT access + refresh tokens stored in OS keychain
         // key: "solitaire_quest_server_{username}"
     },
-    GooglePlayGames,
-    // No credentials stored locally — auth managed by Google Sign-In SDK via JNI
-    // Android only; selecting this on non-Android falls back to Local silently
 }
 ```
 
@@ -392,10 +401,6 @@ On exit: `POST /api/sync/push` with payload
 On 401: automatically attempt `POST /api/auth/refresh`, retry once, then surface error to user.
 Credentials stored in OS keychain via `keyring` — never in plaintext on disk.
 
-### Google Play Games Sync *(Android — future, see Section 8)*
-
-Implemented in `solitaire_gpgs` crate. Uses the GPGS Saved Games API with named slot `"solitaire_quest_sync"`. The `GpgsClient` struct implements `SyncProvider` — the `SyncPlugin` treats it identically to `SolitaireServerClient`. The same `solitaire_sync::merge()` function applies regardless of which provider returned the remote data.
-
 ---
 
 ## 7. Sync Server Architecture
@@ -482,89 +487,7 @@ This ensures all players worldwide get the same challenge for a given date, rega
 
 ---
 
-## 8. Google Play Games Services (Android Future)
-
-> **Status: Stub only.** Do not implement JNI bindings until Android is actively targeted. The `solitaire_gpgs` crate exists in the workspace with a trait stub so the compiler enforces the interface contract from day one.
-
-### Why GPGS on Android
-
-Google Play Games Services provides first-class Android features that would otherwise require significant backend work:
-
-| Feature | GPGS Provides | Our Alternative |
-|---|---|---|
-| Cloud saves | Saved Games API | Self-hosted server |
-| Achievements | Native popups + Play profile | In-game toasts only |
-| Leaderboards | Hosted by Google, visible in Play app | Server leaderboard |
-| Auth | Google Sign-In, no registration | Username + password |
-
-On Android, GPGS is the **primary** sync provider. The self-hosted server is the **fallback** if the player is not signed in or has no server configured. Both can be active simultaneously — a win pushes to both, pull merges from whichever responded last.
-
-### Compatibility Reality
-
-| Platform | GPGS Support |
-|---|---|
-| Android | ✅ Full |
-| Windows | ✅ GPGS for PC (optional, separate SDK) |
-| macOS | ❌ Not supported |
-| Linux | ❌ Not supported |
-| iOS | ❌ Not supported |
-
-macOS, Linux, and iOS users always use the self-hosted server. This is why the server is the primary design and GPGS is an enhancement layer.
-
-### `solitaire_gpgs` Crate Design
-
-The crate is compiled only on Android (`#[cfg(target_os = "android")]`). On all other platforms the crate exports only the stub.
-
-```rust
-// solitaire_gpgs/src/lib.rs
-
-#[cfg(target_os = "android")]
-mod android;
-
-#[cfg(not(target_os = "android"))]
-mod stub;
-
-pub use stub::GpgsClient;   // stub on desktop
-#[cfg(target_os = "android")]
-pub use android::GpgsClient; // real impl on Android
-```
-
-### JNI Bridge (Android implementation — future)
-
-The real `GpgsClient` uses the `jni` crate to call into the GPGS Android SDK:
-
-```
-Rust GpgsClient
-    │  jni::JNIEnv
-    ▼
-Java: com.google.android.gms.games.PlayGames
-    ├── getSnapshotsClient()   → Saved Games (sync payload)
-    ├── getAchievementsClient() → unlock / reveal
-    └── getLeaderboardsClient() → submit score
-```
-
-Steps required when Android work begins:
-1. Add `cargo-mobile2` to the build toolchain
-2. Implement `GpgsClient` with `jni` bindings in `solitaire_gpgs/src/android.rs`
-3. Add `GpgsClient: SyncProvider` impl — pull/push map to Saved Games load/save
-4. Mirror achievement unlocks: on `AchievementUnlockedEvent`, call GPGS unlock API alongside in-game toast
-5. Submit scores to GPGS leaderboard on `GameWonEvent`
-6. Add Google Sign-In button to the Settings screen (Android build only, `#[cfg]` gated)
-
-### Dual-Sync on Android
-
-When both GPGS and the self-hosted server are configured, the `SyncPlugin` runs both providers concurrently and merges all three payloads (local + GPGS + server) using the same `solitaire_sync::merge()` function applied twice:
-
-```
-local ──────┐
-             ├── merge() ──► intermediate ──┐
-gpgs ────────┘                               ├── merge() ──► final
-                                server ──────┘
-```
-
----
-
-## 9. Data Models
+## 8. Data Models
 
 ### Core Game Models (`solitaire_core`)
 
@@ -588,6 +511,9 @@ pub enum PileType {
 
 pub enum DrawMode { DrawOne, DrawThree }
 
+/// Active game mode. Classic is the default; others unlock at level 5.
+pub enum GameMode { Classic, Zen, Challenge, TimeAttack }
+
 pub enum MoveError {
     InvalidSource,
     InvalidDestination,
@@ -600,13 +526,16 @@ pub enum MoveError {
 pub struct GameState {
     pub piles: HashMap<PileType, Vec<Card>>,
     pub draw_mode: DrawMode,
+    pub mode: GameMode,
     pub score: i32,
     pub move_count: u32,
+    pub undo_count: u32,        // number of undos used in this game
+    pub recycle_count: u32,     // number of stock recycles
     pub elapsed_seconds: u64,
     pub seed: u64,
     pub is_won: bool,
     pub is_auto_completable: bool,
-    undo_stack: Vec<StateSnapshot>,   // private, max 64
+    undo_stack: VecDeque<StateSnapshot>,   // private, max 64 (VecDeque for O(1) pop_front)
 }
 ```
 
@@ -652,14 +581,14 @@ pub struct Settings {
     pub music_volume: f32,
     pub animation_speed: AnimSpeed,
     pub theme: Theme,
-    pub sync_backend: SyncBackend, // Local | SolitaireServer | GooglePlayGames
+    pub sync_backend: SyncBackend, // Local | SolitaireServer
     pub first_run_complete: bool,
 }
 ```
 
 ---
 
-## 10. API Reference
+## 9. API Reference
 
 All endpoints are under the base URL configured by the user (e.g., `https://solitaire.example.com`).
 
@@ -702,9 +631,9 @@ All endpoints are under the base URL configured by the user (e.g., `https://soli
 
 ---
 
-## 11. Merge Strategy
+## 10. Merge Strategy
 
-Used identically by the `SolitaireServerClient`, `GpgsClient`, and server-side handler. Lives in `solitaire_sync` as a pure function with no I/O. Called once per provider when multiple backends are active simultaneously (e.g. GPGS + server on Android).
+Used by both `SolitaireServerClient` and the server-side handler. Lives in `solitaire_sync` as a pure function with no I/O.
 
 ```rust
 pub fn merge(local: &SyncPayload, remote: &SyncPayload) -> SyncPayload {
@@ -744,7 +673,7 @@ pub fn merge(local: &SyncPayload, remote: &SyncPayload) -> SyncPayload {
 
 ---
 
-## 12. Achievement System
+## 11. Achievement System
 
 ### Definition Structure
 
@@ -789,13 +718,9 @@ pub struct AchievementDef {
 
 Achievement conditions are evaluated by `AchievementPlugin` on every `GameWonEvent` and `StateChangedEvent`. The plugin calls `solitaire_core::check_achievements()` which returns a `Vec<AchievementDef>` of newly unlocked achievements. The plugin then fires `AchievementUnlockedEvent` for each, which the toast and persistence systems handle independently.
 
-### GPGS Mirroring *(Android, future)*
-
-When the `GpgsClient` is active, every `AchievementUnlockedEvent` also triggers a GPGS `achievements.unlock()` call via JNI so the achievement appears in the player's Google Play profile. A static map in `solitaire_gpgs` maps our achievement IDs to GPGS achievement IDs (assigned in the Google Play Console). Mirroring is fire-and-forget — failures are logged but never block the in-game toast.
-
 ---
 
-## 13. Progression System
+## 12. Progression System
 
 ### XP Sources
 
@@ -824,18 +749,18 @@ Levels 11+:   level = 10 + floor((total_xp - 5000) / 1000)
 
 ---
 
-## 14. Audio System
+## 13. Audio System
 
-Audio uses `bevy_kira_audio`. All sound files are `.ogg` (good compression, cross-platform, royalty-free).
+Audio uses `bevy_kira_audio`. All sound files are `.wav`.
 
 | File | Trigger |
 |---|---|
-| `card_deal.ogg` | New game deal animation |
-| `card_flip.ogg` | Card flips face-up |
-| `card_place.ogg` | Valid card placement |
-| `card_invalid.ogg` | Invalid move attempt |
-| `win_fanfare.ogg` | Game won |
-| `ambient_loop.ogg` | Looping background music (restarts seamlessly) |
+| `card_deal.wav` | New game deal animation |
+| `card_flip.wav` | Card flips face-up |
+| `card_place.wav` | Valid card placement |
+| `card_invalid.wav` | Invalid move attempt |
+| `win_fanfare.wav` | Game won |
+| `ambient_loop.wav` | Looping background music |
 
 Volume is controlled by two independent sliders in Settings (`sfx_volume`, `music_volume`), each stored in `Settings` and applied as `bevy_kira_audio` channel volumes.
 
@@ -843,43 +768,64 @@ Audio systems listen for Bevy events and never block the game thread.
 
 ---
 
-## 15. Asset Pipeline
+## 14. Asset Pipeline
 
-All assets are loaded through Bevy's `AssetServer`. No bytes are hardcoded in source.
+### Rendering approach
 
-### Card Sprites
+Cards are Bevy `Sprite` entities with `Handle<Image>` from `CardImageSet`. Face-up cards use one of 52 individual face PNGs selected by `faces[suit][rank]` — rank and suit are baked into each image and no `Text2d` overlay is spawned. Face-down cards use `backs/back_N.png` indexed by `settings.selected_card_back`. `Text2d` labels are only used as a fallback when `CardImageSet` is absent (e.g. tests with `MinimalPlugins`). `CardImageSet` is populated at startup from `include_bytes!()` — no `AssetServer`.
 
-Card faces can be either:
-- A texture atlas (`assets/cards/atlas.png` + `atlas.ron` layout) — faster to load, preferred
-- Individual files (`assets/cards/faces/2_of_clubs.png`, etc.) — easier to author
+Backgrounds are Bevy `Sprite` entities with `Handle<Image>` from `BackgroundImageSet`. `BackgroundImageSet` is populated at startup from `include_bytes!()`.
 
-Card backs: `assets/cards/backs/back_0.png` through `back_4.png`. Additional backs unlocked via achievements are in the same folder, gated by `PlayerProgress::unlocked_card_backs`.
+The font `FiraMono-Medium` is embedded via `include_bytes!()` at startup by `FontPlugin` and exposed as `FontResource` for use by all UI and text systems.
 
-### Backgrounds
+The `assets/` directory layout:
 
-`assets/backgrounds/bg_0.png` through `bg_4.png`. Same unlock gating as card backs.
+```
+assets/
+├── cards/
+│   ├── faces/{rank}_{suit}.png  # 52 individual card faces (120×168, generated by solitaire_assetgen)
+│   └── backs/back_0.png – back_4.png    # placeholder patterns
+├── backgrounds/bg_0.png – bg_4.png      # placeholder textures
+├── fonts/main.ttf              # FiraMono-Medium (170K, OFL)
+└── audio/
+    ├── card_deal.wav
+    ├── card_flip.wav
+    ├── card_place.wav
+    ├── card_invalid.wav
+    ├── win_fanfare.wav
+    └── ambient_loop.wav
+```
 
-### Fonts
+### Audio
 
-`assets/fonts/main.ttf` — used for card rank/suit text and all egui overrides.
+All sound effect WAV files are embedded at compile time via `include_bytes!()` in `audio_plugin.rs`. There is no runtime asset loading — the binary is fully self-contained.
+
+| File | Trigger |
+|---|---|
+| `card_deal.wav` | New game deal animation |
+| `card_flip.wav` | Card flips face-up |
+| `card_place.wav` | Valid card placement |
+| `card_invalid.wav` | Invalid move attempt |
+| `win_fanfare.wav` | Game won |
+| `ambient_loop.wav` | Looping background music |
 
 ---
 
-## 16. Platform Targets
+## 15. Platform Targets
 
 | Platform | Status | Primary Sync | Notes |
 |---|---|---|---|
 | macOS | Primary | Self-hosted server | x86_64 + Apple Silicon (universal binary via `cargo-lipo`) |
-| Windows | Primary | Self-hosted server | x86_64, MSVC toolchain; optional GPGS for PC (future) |
+| 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 | Google Play Games + server | `cargo-mobile2`, touch input, GPGS via JNI |
-| iOS | Stretch | Self-hosted server | `cargo-mobile2`, touch input; GPGS unavailable on iOS |
+| Android | Stretch | Self-hosted server | `cargo-mobile2`, touch input |
+| 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`.
 
 ---
 
-## 17. Build & Development Guide
+## 16. Build & Development Guide
 
 ### Prerequisites
 
@@ -940,7 +886,7 @@ Add `--features bevy/dynamic_linking` during development to dramatically reduce
 
 ---
 
-## 18. Deployment Guide
+## 17. Deployment Guide
 
 ### Docker Compose (Recommended)
 
@@ -985,7 +931,7 @@ Migrations run automatically on startup via `sqlx::migrate!()`.
 
 ---
 
-## 19. Security Model
+## 18. Security Model
 
 | Concern | Mitigation |
 |---|---|
@@ -1001,7 +947,7 @@ Migrations run automatically on startup via `sqlx::migrate!()`.
 
 ---
 
-## 20. Testing Strategy
+## 19. Testing Strategy
 
 ### Unit Tests (`solitaire_core`)
 
@@ -1040,12 +986,10 @@ Using `axum::test` and an in-memory SQLite database:
 - [ ] Achievement toast appears and dismisses
 - [ ] Server sync: register, login, push, pull on second machine
 - [ ] Server sync: JWT refresh on 401 works transparently
-- [ ] GPGS sync (Android only): sign in, unlock achievement, verify appears in Play Games app
-- [ ] Dual sync (Android only): GPGS + server both configured, payloads merge correctly
 
 ---
 
-## 21. Decision Log
+## 20. Decision Log
 
 | Decision | Rationale | Date |
 |---|---|---|
@@ -1057,7 +1001,8 @@ Using `axum::test` and an in-memory SQLite database:
 | bcrypt cost 12 | Balances security and registration latency (~300ms on modern hardware); higher than default 10 | 2026-04-19 |
 | No email required for server accounts | Reduces PII collected; simplifies self-hosted deployments; password reset handled by server admin if needed | 2026-04-19 |
 | Self-hosted server as primary sync (not WebDAV) | A proper Rust server gives us auth, leaderboards, and daily challenge seeding for minimal extra effort over WebDAV, and removes a redundant backend | 2026-04-20 |
-| `SyncProvider` trait, not `SyncBackend` match arms | Allows adding Google Play Games Services cleanly; `SyncPlugin` stays backend-agnostic and testable | 2026-04-20 |
-| GPGS as Android enhancement, not replacement | GPGS has no macOS/Linux support; the server must remain universal, with GPGS layered on top for Android players | 2026-04-20 |
+| `SyncProvider` trait, not `SyncBackend` match arms | `SyncPlugin` stays backend-agnostic and testable; new backends can be added without touching the plugin | 2026-04-20 |
 | Dropped WebDAV backend | Redundant once the self-hosted server exists; removing it reduces surface area and simplifies settings UI | 2026-04-20 |
-| `solitaire_gpgs` crate stubbed from day one | Enforces the `SyncProvider` interface contract at compile time even before Android work begins; avoids architectural rework later | 2026-04-20 |
+| Dropped GPGS backend | Redundant with the self-hosted server; adds JNI complexity for no user-visible benefit on the target platforms | 2026-04-28 |
+| PNG assets embedded via `include_bytes!()` | Using `Image::from_buffer()` in startup systems rather than `AssetServer::load()` keeps the binary self-contained and eliminates runtime file-not-found errors | 2026-04-29 |
+| FiraMono-Medium font embedded via `include_bytes!()` | Exposed through `FontResource`; avoids runtime font loading errors on headless systems and ensures consistent text rendering across all platforms | 2026-04-29 |

CLAUDE.md

@@ -12,7 +12,6 @@ solitaire_sync/    # Shared API types — NO Bevy, serde/uuid/chrono only
 solitaire_data/    # Persistence + SyncProvider trait + server client
 solitaire_engine/  # Bevy ECS systems, components, plugins
 solitaire_server/  # Axum sync server binary
-solitaire_gpgs/    # Google Play Games bridge — STUB ONLY until Android phase
 solitaire_app/     # Thin binary entry point
 assets/            # Source assets — embedded at compile time via include_bytes!()
 ```
@@ -48,12 +47,11 @@ cargo clippy -p solitaire_core -- -D warnings
 
 - `solitaire_core` and `solitaire_sync` must never gain Bevy or network dependencies.
 - No `unwrap()` or `panic!()` in game logic. All state transitions return `Result<_, MoveError>`.
-- Assets are embedded at compile time using `include_bytes!()`. No runtime asset loading via `AssetServer`.
+- Audio assets are embedded at compile time using `include_bytes!()` in `audio_plugin.rs`. Cards and backgrounds are rendered procedurally (colored `Sprite` entities + text) — no image files are used and no `AssetServer` is needed.
 - Atomic file writes only: write to `filename.json.tmp`, then `rename()`.
 - Passwords and tokens are stored in the OS keychain via the `keyring` crate — never in plaintext files or logs.
 - Sync runs on `AsyncComputeTaskPool` — never block the Bevy main thread.
 - All sync backends implement the `SyncProvider` trait. The `SyncPlugin` is backend-agnostic — never `match` on `SyncBackend` inside a Bevy system.
-- `solitaire_gpgs` is a stub until Android work begins. Do not write JNI bindings yet; keep the compile-time stub so the trait contract is enforced from day one.
 - `cargo clippy --workspace -- -D warnings` must pass clean after every change.
 - `cargo test --workspace` must pass after every change.
 

Caddyfile

@@ -0,0 +1,3 @@
+{$SOLITAIRE_DOMAIN} {
+    reverse_proxy server:{$SERVER_PORT:-8080}
+}

Cargo.toml

@@ -5,42 +5,44 @@ members = [
     "solitaire_data",
     "solitaire_engine",
     "solitaire_server",
-    "solitaire_gpgs",
     "solitaire_app",
     "solitaire_assetgen",
 ]
 resolver = "2"
 
 [workspace.package]
-edition = "2021"
+edition = "2024"
 version = "0.1.0"
+license = "MIT"
+rust-version = "1.95"
 
 [workspace.dependencies]
 serde       = { version = "1", features = ["derive"] }
 serde_json  = "1"
 uuid        = { version = "1", features = ["v4", "serde"] }
 chrono      = { version = "0.4", features = ["serde"] }
-thiserror   = "1"
-rand        = "0.8"
+thiserror   = "2"
+rand        = "0.9"
 async-trait = "0.1"
 tokio       = { version = "1", features = ["full"] }
-dirs        = "5"
-keyring     = "2"
-reqwest     = { version = "0.12", features = ["json", "rustls-tls"], default-features = false }
+dirs        = "6"
+keyring     = "4"
+keyring-core = "1"
+reqwest     = { version = "0.13", features = ["json", "rustls", "rustls-native-certs"], default-features = false }
 
 solitaire_core   = { path = "solitaire_core" }
 solitaire_sync   = { path = "solitaire_sync" }
 solitaire_data   = { path = "solitaire_data" }
 solitaire_engine = { path = "solitaire_engine" }
 
-bevy = "0.15"
-kira = "0.9"
+bevy = "0.18"
+kira = "0.12"
 
-axum               = "0.7"
+axum               = "0.8"
 sqlx               = { version = "0.8", features = ["runtime-tokio-rustls", "sqlite", "macros", "migrate"] }
-jsonwebtoken       = "9"
-bcrypt             = "0.15"
-tower_governor     = "0.4"
+jsonwebtoken       = { version = "10", default-features = false, features = ["rust_crypto"] }
+bcrypt             = "0.19"
+tower_governor     = "0.8"
 tracing            = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 dotenvy            = "0.15"

Dockerfile

@@ -0,0 +1,28 @@
+# Stage 1 — builder
+# Compiles the solitaire_server binary in release mode.
+# Requires a pre-generated .sqlx/ query cache (run `cargo sqlx prepare --workspace`
+# before building the image so sqlx macros work without a live database).
+FROM rust:slim AS builder
+
+WORKDIR /app
+
+COPY . .
+
+# Tell sqlx to use the cached query metadata instead of a live database.
+ENV SQLX_OFFLINE=true
+
+RUN cargo build --release -p solitaire_server
+
+# Stage 2 — runtime
+# Minimal image that only contains the compiled binary and its runtime deps.
+FROM debian:bookworm-slim
+
+RUN apt-get update \
+    && apt-get install -y ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /app/target/release/solitaire_server /usr/local/bin/solitaire_server
+
+EXPOSE ${SERVER_PORT:-8080}
+
+ENTRYPOINT ["/usr/local/bin/solitaire_server"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 funman300
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,73 @@
+# Solitaire Quest
+
+A cross-platform Klondike Solitaire game written in Rust, featuring a full progression system with XP, levels, achievements, daily challenges, and optional self-hosted sync so your stats follow you across machines.
+
+## Features
+
+- **Klondike Solitaire** — Draw One and Draw Three modes
+- **Progression** — XP, levels, unlockable card backs and backgrounds
+- **18 Achievements** — including secret ones
+- **Daily Challenge** — server-seeded so every player worldwide gets the same deal
+- **Leaderboard** — opt-in, powered by your own self-hosted server
+- **Special Modes** (unlocked at level 5): Zen, Time Attack, Challenge
+- **Sync** — pull/push stats across devices via a self-hosted server
+- **Color-blind mode** — blue tint on red-suit cards
+
+## Building
+
+**Prerequisites**
+
+- Rust stable toolchain (`rustup install stable`)
+- Linux: `libasound2-dev libudev-dev libxkbcommon-dev`
+- macOS: Xcode Command Line Tools
+
+```bash
+# Fast development build
+cargo run -p solitaire_app --features bevy/dynamic_linking
+
+# Release build
+cargo build -p solitaire_app --release
+./target/release/solitaire_app
+```
+
+## Controls
+
+| Key | Action |
+|---|---|
+| Left click / drag | Move cards |
+| Right click | Highlight legal moves for a card |
+| Space / D | Draw from stock |
+| Z / Ctrl+Z | Undo |
+| N | New game |
+| S | Stats overlay |
+| A | Achievements overlay |
+| P | Profile overlay |
+| O | Settings |
+| L | Leaderboard |
+| H | Help / controls |
+| Enter | Auto-complete (when badge is lit) |
+| Escape | Pause / clear selection |
+| Arrow keys | Navigate card selection |
+
+## Sync Server (optional)
+
+To sync stats across machines, run the self-hosted server. See [README_SERVER.md](README_SERVER.md) for setup instructions.
+
+Once the server is running, open **Settings → Sync Backend**, enter the server URL and your username, and register an account from within the game.
+
+## Running Tests
+
+```bash
+# All tests
+cargo test --workspace
+
+# Just game logic (no display required)
+cargo test -p solitaire_core -p solitaire_sync -p solitaire_data -p solitaire_server
+
+# Lint
+cargo clippy --workspace -- -D warnings
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

README_SERVER.md

@@ -0,0 +1,44 @@
+# Solitaire Quest — Self-Hosting Guide
+
+## Prerequisites
+
+- Docker and Docker Compose
+- `openssl` for generating a JWT secret
+
+## Quick start
+
+1. Clone the repo and enter it.
+2. Copy the example environment file and fill in your values:
+   ```bash
+   cp .env.example .env
+   # Edit .env: set JWT_SECRET and SOLITAIRE_DOMAIN
+   ```
+3. (First time only) Generate the sqlx query cache so the server builds without a live database:
+   ```bash
+   cargo install sqlx-cli --no-default-features --features rustls,sqlite
+   export DATABASE_URL=sqlite://solitaire.db
+   sqlx database create
+   sqlx migrate run --source solitaire_server/migrations
+   cargo sqlx prepare --workspace
+   rm solitaire.db   # the real DB lives in ./data/ at runtime
+   ```
+4. Start everything:
+   ```bash
+   docker compose up -d
+   ```
+5. The server is now reachable at `https://<SOLITAIRE_DOMAIN>`.
+
+## Backups
+
+The entire server state is one SQLite file at `./data/solitaire.db`. Back it up with:
+```bash
+sqlite3 ./data/solitaire.db ".backup backup_$(date +%Y%m%d).db"
+```
+
+## Updating
+
+```bash
+git pull
+docker compose build
+docker compose up -d
+```

docker-compose.yml

@@ -0,0 +1,30 @@
+services:
+  server:
+    build: .
+    env_file: .env
+    environment:
+      # Override DATABASE_URL so the DB always lands in the persistent volume,
+      # regardless of what .env contains.
+      DATABASE_URL: sqlite:///data/solitaire.db
+    volumes:
+      - ./data:/data
+    restart: unless-stopped
+    expose:
+      - "${SERVER_PORT:-8080}"
+
+  caddy:
+    image: caddy:2-alpine
+    depends_on:
+      - server
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    restart: unless-stopped
+
+volumes:
+  caddy_data:
+  caddy_config:

docs/android_investigation.md

@@ -0,0 +1,247 @@
+# Android Port Investigation
+
+> **Date:** 2026-04-28  
+> **Author:** Claude Code  
+> **Scope:** Feasibility analysis for porting Solitaire Quest to Android using cargo-mobile2
+
+---
+
+## Summary
+
+A working Android port is feasible but not trivial. The core game logic (`solitaire_core`, `solitaire_sync`) compiles to Android without changes. Every other crate requires at least minor surgery. The biggest blockers are the `keyring` crate (no Android backend), the `kira`/`AudioManager` audio stack (`DefaultBackend` uses CPAL which targets desktop), and the `dirs` crate returning `None` on Android in its current usage. Touch input already has a solid foundation in `input_plugin.rs`. Estimated effort from a clean Android toolchain is **12–18 developer-days** to reach a playable-but-rough state.
+
+---
+
+## 1. Bevy on Android — Current Status
+
+Bevy's Android support is community-maintained via the `winit` backend and is usable but carries known rough edges as of the 0.15/0.16 generation.
+
+**What works:**
+- Basic rendering via Vulkan (through `wgpu`). OpenGL ES fallback is available for older devices.
+- Touch input events: Bevy's `TouchInput` events and the `Touches` resource are populated from Android `MotionEvent`s via `winit`. The existing `touch_start_drag`, `touch_follow_drag`, `touch_end_drag`, and `handle_touch_stock_tap` systems in `input_plugin.rs` will function correctly — this was already written with multi-touch in mind and uses `TouchPhase::Started/Moved/Ended/Canceled` cleanly.
+- Bevy UI (the `bevy::ui` module used for all overlays).
+- `WindowResized` events fire correctly, so the layout system will recompute for any screen size.
+
+**What does not work / needs attention:**
+- **`bevy/dynamic_linking`**: The dynamic linking feature must be stripped from any Android build profile. Dynamic linking is a desktop-only development shortcut; Android requires static linking.
+- **Fixed window size**: `main.rs` sets `resolution: (1280u32, 800u32)`. On Android the window is always the full display. This value is harmlessly overridden by the OS, but `min_width`/`min_height` constraints should be removed or set to 0 for Android to avoid Winit warnings.
+- **`F11` fullscreen toggle** (`handle_fullscreen` in `input_plugin.rs`): `WindowMode::BorderlessFullscreen` is desktop-only. On Android it should be a no-op.
+- **Keyboard shortcuts**: The entire `handle_keyboard_core`, `handle_keyboard_hint`, `handle_keyboard_forfeit` systems are desktop-only workflows. They will not crash, but they are dead code on Android. No touchscreen replacement for Undo (U), New Game (N), Draw (D/Space), Hint (H), Forfeit (G) exists yet — these need an on-screen UI.
+- **`CursorPlugin`**: The custom cursor sprite plugin is irrelevant on Android (no cursor). Harmless to leave registered, but it uses `PrimaryWindow` cursor APIs that may panic or warn on Android.
+
+**cargo-mobile2 integration for Bevy:**
+The standard path is:
+1. Install `cargo-mobile2`: `cargo install --locked cargo-mobile2`
+2. Run `cargo mobile init` in the workspace root. This generates an `android/` directory with the Gradle project, `AndroidManifest.xml`, and JNI glue.
+3. cargo-mobile2 targets the `solitaire_app` binary crate (the thin entry point). The generated `lib.rs` shim calls `android_main` via `bevy::winit`'s Android entry point.
+4. The `solitaire_app` crate needs a `[lib]` target added alongside the existing `[[bin]]`, with `crate-type = ["cdylib"]`, used only when building for Android.
+
+**Required `Cargo.toml` changes (workspace level):**
+```toml
+[target.'cfg(target_os = "android")'.dependencies]
+# android_logger and ndk-glue wiring are handled by cargo-mobile2's generated shim.
+# No direct ndk-glue dependency is needed in app code when using Bevy + cargo-mobile2.
+```
+
+**NDK version:** Android NDK r25c or r26 LTS is the tested range for `wgpu`/Vulkan on Android. NDK r27+ may work but has had compatibility reports with CPAL. Set `ANDROID_NDK_ROOT` to the NDK root; the minimum API level should be 26 (Android 8.0) for Vulkan stability.
+
+---
+
+## 2. Audio — `kira` + `DefaultBackend`
+
+**The problem:**  
+`solitaire_engine/src/audio_plugin.rs` creates an `AudioManager<DefaultBackend>`. `kira`'s `DefaultBackend` is an alias for `CpalBackend`, which wraps CPAL. CPAL's Android backend uses OpenSL ES and is functional but historically fragile. As of kira 0.9+, `kira` no longer bundles its own CPAL backend by default in the same way — the `DefaultBackend` feature must be enabled explicitly and requires `cpal` with the Android feature.
+
+**Current code behavior:**  
+The `AudioPlugin::build` already handles the "no audio device" case gracefully:
+```rust
+let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default()).ok();
+if manager.is_none() {
+    warn!("audio device unavailable; SFX disabled");
+}
+```
+This means if the audio manager fails to initialise on Android, the game continues silently. This is acceptable as a first-pass fallback.
+
+**What is needed for working audio on Android:**
+- Add `kira` dependency with `cpal` backend enabled for Android: The `kira` workspace dependency currently specifies `version = "0.12"`. Verify that `kira/Cargo.toml` exposes a `cpal` feature (or that `DefaultBackend` compiles on Android targets with NDK). If not, a `CpalBackend` with `cpal = { features = ["oboe"] }` may be needed.
+- The `NonSend` resource `AudioState` should compile fine — `NonSend` is legal in Bevy Android builds.
+- `include_bytes!` for the WAV assets is compile-time and unaffected by platform.
+
+**Recommendation:** Defer full audio verification to a device test. The graceful fallback means a silent-but-working first build is achievable without resolving this.
+
+---
+
+## 3. `keyring` Crate — No Android Backend
+
+**The problem:**  
+`keyring = "2"` is used in `solitaire_data/src/auth_tokens.rs` to store JWT access and refresh tokens in the OS keychain. The `keyring` crate's Android backend does not exist — as of v2.x, supported backends are: macOS Keychain, Windows Credential Manager, Linux Secret Service (D-Bus), and iOS Keychain. There is no Android KeyStore backend.
+
+On Android, `Entry::new(...)` will return `keyring::Error::NoStorageAccess`, which the existing code already maps to `TokenError::KeychainUnavailable`. So the code will not crash — it will simply fail every token store/load operation.
+
+**Current failure mode:**  
+Every call to `store_tokens`, `load_access_token`, `load_refresh_token`, or `delete_tokens` will return `Err(TokenError::KeychainUnavailable(...))`. The sync client in `sync_client.rs` needs to be verified to handle this gracefully rather than propagating an error that disables sync entirely.
+
+**Options for Android credential storage:**
+
+| Option | Security | Effort | Notes |
+|---|---|---|---|
+| **In-memory only (prompt re-login each session)** | N/A | 1 day | Simplest. On `TokenError::KeychainUnavailable`, the `SyncProvider` returns `SyncError::Auth`, user is prompted to log in. Already architecturally supported. |
+| **Encrypted `SharedPreferences` equivalent via JNI** | Good | 4–6 days | Call Android's `EncryptedSharedPreferences` (Jetpack Security) via JNI. Significant JNI boilerplate. |
+| **AES-256 file encryption using Android Keystore via JNI** | Excellent | 5–8 days | Proper Android keychain equivalent. Complex JNI. |
+| **Store in app-private file, unencrypted** | Poor | 0.5 days | Only acceptable during development. Never ship. |
+
+**Recommended approach (first pass):** Use the in-memory / re-login-each-session path. The existing `TokenError::KeychainUnavailable` variant already exists for exactly this reason (Linux without a running secret service). The `SyncPlugin` should detect this on startup and present a "Sync unavailable — please log in" message rather than a hard error. This requires:
+1. Conditional compilation: when `cfg(target_os = "android")`, replace the `keyring` calls with a no-op in-memory store (a simple `Mutex<HashMap<String, String>>`).
+2. A `#[cfg(not(target_os = "android"))]` guard on the `keyring` import/dependency in `solitaire_data/Cargo.toml`.
+
+**Required `solitaire_data/Cargo.toml` change:**
+```toml
+[target.'cfg(not(target_os = "android"))'.dependencies]
+keyring = { workspace = true }
+
+[target.'cfg(target_os = "android")'.dependencies]
+# keyring is replaced by in-memory storage; no dependency needed
+```
+
+---
+
+## 4. `dirs` Crate — Data Directory on Android
+
+**The problem:**  
+`storage.rs` and other persistence modules use `dirs::data_dir()` to locate `~/.local/share/solitaire_quest/` (or platform equivalent). On Android, `dirs::data_dir()` returns `None` because there is no `XDG_DATA_HOME` and the `dirs` crate does not implement an Android-specific path.
+
+**Current code behavior:**  
+All persistence functions already handle `None` gracefully (returning default values or `Err`), consistent with the CLAUDE.md lesson about `dirs::data_dir()`. Stats and progress will silently not persist across sessions if `data_dir()` returns `None`.
+
+**Fix required:**  
+Android apps should store private data in the app's internal storage directory, obtained via JNI: `context.getFilesDir()`. This requires either:
+- A thin JNI helper (via `jni` crate) called once on startup to obtain the path and store it as a global.
+- Or passing the path in via the `android_main` entry point using `cargo-mobile2`'s `AndroidApp` handle, which exposes `internal_data_path()`.
+
+The `cargo-mobile2` + Bevy path exposes an `AndroidApp` via `bevy::winit`'s Android entry point. Bevy 0.13+ passes `AndroidApp` through `WinitPlugin`, and it is accessible via a Bevy resource. A startup system can extract `app.internal_data_path()` and insert a `PlatformDataDirResource` that the storage functions read instead of calling `dirs::data_dir()`.
+
+**Effort:** 1–2 days to implement the override and thread it through all `storage.rs` / `progress.rs` / `settings.rs` / `achievements.rs` call sites.
+
+---
+
+## 5. Touch Input — Current State and Gaps
+
+**What already exists (strong foundation):**
+
+The `InputPlugin` in `input_plugin.rs` has a complete parallel touch pipeline:
+
+| System | Purpose | Status |
+|---|---|---|
+| `handle_touch_stock_tap` | Tap the stock pile to draw | Complete |
+| `touch_start_drag` | Begin a touch drag on a face-up card | Complete |
+| `touch_follow_drag` | Move card(s) with the active finger | Complete |
+| `touch_end_drag` | Resolve the drag (move or reject) | Complete |
+
+The touch systems use `TouchInput` events and the `Touches` resource, map touch IDs to `DragState.active_touch_id` to prevent multi-finger conflicts, and share the same `DragState`, `MoveRequestEvent`, `MoveRejectedEvent`, and `StateChangedEvent` infrastructure as the mouse pipeline. The drag threshold (`tuning.drag_threshold_px`) applies identically.
+
+**Gaps for a production Android experience:**
+
+1. **No double-tap equivalent for auto-move**: `handle_double_click` is mouse-only. Android users need a double-tap to trigger the same "move to best destination" logic. The `handle_double_click` system checks `buttons.just_pressed(MouseButton::Left)` and will be inert on Android. Estimated: 1 day.
+
+2. **No touch equivalent for keyboard actions**: Undo, New Game, Draw (when stock is visible but tapping it is awkward), Hint, and Forfeit have no on-screen buttons. These need an Android-specific UI bar or gesture (e.g. two-finger tap for undo). Estimated: 2–3 days for a minimal floating action button strip.
+
+3. **Drag threshold tuning**: The threshold is in `AnimationTuning` (`tuning.drag_threshold_px`). Touch screens typically need a larger threshold than mouse (physical screens have more accidental movement during a tap). The current value should be evaluated on a real device and likely increased for touch.
+
+4. **No long-press for right-click equivalent**: The right-click highlight/hint glow (`HintHighlightTimer`) is triggered via right mouse button. Long-press detection is not yet implemented. This is a missing feature but not a blocker for basic play.
+
+5. **`handle_double_click` uses `LocalDateTime`-based timing via `Time`**: This will work on Android, but `DOUBLE_CLICK_WINDOW = 0.35s` may feel too tight on touch. Should be configurable.
+
+---
+
+## 6. Additional Issues Not in Scope of the Four Research Areas
+
+**`CursorPlugin`:** Uses Bevy's cursor APIs which are desktop-only. Should be conditionally compiled out on Android with `#[cfg(not(target_os = "android"))]`.
+
+**`reqwest` with `rustls-native-certs`:** The `reqwest` dependency uses `rustls` with native root certificates. On Android, `rustls-native-certs` reads system certificates differently (via the `android_system_properties` crate internally). This generally works but should be tested; Android's certificate store is in a non-standard location vs Linux.
+
+**App lifecycle (suspend/resume):** Android can suspend the process at any time. Bevy handles `WindowEvent::Suspended` and `WindowEvent::Resumed` via `winit`, pausing the render loop. The `SyncPlugin`'s "push on exit" path (`AppExit` event) should also trigger on `WindowEvent::Suspended` to avoid data loss when the user backgrounds the app. This is a separate feature (1 day).
+
+**No `sqlx` on Android:** `solitaire_server` is a server binary and is never built for Android. The `sqlx` dependency only exists in `solitaire_server/Cargo.toml` and will not affect Android builds of the client crates.
+
+**`solitaire_assetgen`:** The asset generation tool is desktop-only and not part of the client build. Unaffected.
+
+---
+
+## 7. Required Changes Per Crate
+
+### `solitaire_core` and `solitaire_sync`
+No changes required. Both are pure Rust with no platform dependencies.
+
+### `solitaire_data`
+| Change | Effort |
+|---|---|
+| Gate `keyring` dependency on `#[cfg(not(target_os = "android"))]` | 0.5 days |
+| Implement `auth_tokens.rs` in-memory fallback for Android | 1 day |
+| Add `internal_data_path()` override for `dirs::data_dir()` on Android | 1.5 days |
+| Audit all `dirs::data_dir()` / `settings_file_path()` call sites to accept injected path | 0.5 days |
+
+### `solitaire_engine`
+| Change | Effort |
+|---|---|
+| Conditionally disable `CursorPlugin` on Android | 0.5 days |
+| Disable `handle_fullscreen` on Android (or make it a no-op) | 0.25 days |
+| Implement double-tap for auto-move (touch equivalent of `handle_double_click`) | 1 day |
+| On-screen action bar for Undo, New Game, Hint (minimal floating buttons) | 2.5 days |
+| Tune drag threshold for touch; expose as a platform-specific tuning constant | 0.5 days |
+| Trigger sync push on `WindowEvent::Suspended` in `SyncPlugin` | 1 day |
+| Verify `kira` audio on Android (test `DefaultBackend` / CPAL; implement fallback if needed) | 1–2 days |
+
+### `solitaire_app`
+| Change | Effort |
+|---|---|
+| Add `[lib]` target with `crate-type = ["cdylib"]` for Android builds | 0.25 days |
+| Create `src/lib.rs` (or `src/android.rs`) Android entry point calling `android_main` | 0.5 days |
+| Remove or guard fixed `resolution` / `resize_constraints` for Android | 0.25 days |
+| Pass `AndroidApp::internal_data_path()` to a startup resource | 0.5 days |
+
+### Build / Toolchain
+| Change | Effort |
+|---|---|
+| Install cargo-mobile2, Android NDK r25c/r26, `aarch64-linux-android` target | 1 day |
+| Run `cargo mobile init`, configure `android/` Gradle project | 0.5 days |
+| Get a first build compiling (resolve linker / NDK issues) | 1–2 days |
+
+---
+
+## 8. Estimated Effort
+
+| Phase | Description | Days |
+|---|---|---|
+| Toolchain setup | NDK, cargo-mobile2, first compile | 2–3 |
+| `solitaire_data` Android adaptations | keyring fallback, data dir | 3 |
+| `solitaire_app` Android entry point | cdylib, AndroidApp wiring | 1 |
+| `solitaire_engine` guards and fixes | cursor, fullscreen, audio verify | 2–3 |
+| Touch UX improvements | double-tap, action bar, threshold tuning | 4–5 |
+| Testing on real device / emulator | iteration, lifecycle edge cases | 2–3 |
+| **Total** | | **14–17 days** |
+
+This produces a playable, functionally complete Android build. It does not include Play Store preparation (signing keys, metadata, icon set, permissions manifest tuning) which would add 1–2 more days.
+
+---
+
+## 9. Recommended First Step
+
+**Get the workspace to compile for `aarch64-linux-android` without running.**
+
+This surfaces all the real linker and dependency errors before writing any gameplay code:
+
+```bash
+# Install toolchain
+rustup target add aarch64-linux-android
+cargo install --locked cargo-mobile2
+
+# In the workspace root:
+cargo mobile init   # generates android/ directory
+
+# Attempt a library build targeting Android
+cargo build -p solitaire_app --target aarch64-linux-android 2>&1 | head -60
+```
+
+The first build will fail on `keyring` (no Android backend) and likely on `dirs`. Fixing those two in `solitaire_data` — gate `keyring` behind `cfg(not(target_os = "android"))` and stub the data directory — will probably get the workspace to a clean compile. From there, the path to a running APK is incremental.
+
+Do not attempt to resolve audio or touch UX until the build compiles cleanly. Compile errors are the only true blockers; the rest are feature gaps.

docs/sync_test_runbook.md

@@ -0,0 +1,318 @@
+# Sync Subsystem Manual Test Runbook
+
+**Version:** 1.0  
+**Last Updated:** 2026-04-28  
+**Scope:** Cross-machine sync, JWT refresh, conflict resolution, account deletion
+
+---
+
+## Prerequisites
+
+### Infrastructure
+
+- Two machines (or VMs) referred to as **Machine A** and **Machine B** throughout this runbook. Both must be able to reach the sync server over the network.
+- A running Solitaire Quest sync server reachable at a known URL, e.g. `https://solitaire.example.com`. See `README_SERVER.md` for setup.
+- Verify the server is live before starting:
+
+  ```bash
+  curl -s https://solitaire.example.com/health
+  # Expected: {"status":"ok","version":"..."}
+  ```
+
+### Accounts
+
+- You will register two separate accounts (`alice` and `bob`) during the tests. You do not need to create them in advance.
+
+### Tooling
+
+- `curl` or a REST client (Insomnia/Postman) for manual API calls.
+- `sqlite3` CLI if you need to inspect the server database directly.
+- The game binary built in release mode on both machines:
+
+  ```bash
+  cargo build -p solitaire_app --release
+  ```
+
+### Baseline: Clear local data on both machines
+
+Before starting, delete any existing local save files to ensure a clean state:
+
+```
+# Linux
+rm -rf ~/.local/share/solitaire_quest/
+
+# macOS
+rm -rf ~/Library/Application\ Support/solitaire_quest/
+
+# Windows
+rmdir /s %APPDATA%\solitaire_quest\
+```
+
+---
+
+## Test 1 — Full Sync Round-Trip (register, play, push, verify on second machine)
+
+**Goal:** Confirm that stats played on Machine A appear on Machine B after sync.
+
+### Step 1 — Register on Machine A
+
+1. Launch the game on Machine A.
+2. Open **Settings** (key: `O`) and locate the **Sync** section.
+3. Enter the server URL and choose a username: `alice`.
+4. Choose a password (at least 12 characters).
+5. Tap **Register** (or **Login** if the account already exists).
+6. The Settings screen should show **Status: syncing…** briefly, then **Status: last synced at HH:MM**.
+7. Close the game.
+
+Verify the registration succeeded directly:
+
+```bash
+curl -s -X POST https://solitaire.example.com/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"alice","password":"<your-password>"}' | jq .
+# Expected: {"access_token":"...","refresh_token":"..."}
+```
+
+### Step 2 — Play games on Machine A
+
+1. Launch the game on Machine A.
+2. Win at least **three games** (Draw One or Draw Three — note which mode).
+3. Check the Stats overlay (key: `S`) and note:
+   - `games_played`
+   - `games_won`
+   - `win_streak_current`
+   - `fastest_win_seconds`
+4. Close the game normally (this triggers the push-on-exit path).
+
+### Step 3 — Verify the push reached the server
+
+```bash
+# Log in to get a fresh token
+TOKEN=$(curl -s -X POST https://solitaire.example.com/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"alice","password":"<your-password>"}' | jq -r .access_token)
+
+# Pull the server's stored state
+curl -s -H "Authorization: Bearer $TOKEN" \
+  https://solitaire.example.com/api/sync/pull | jq .merged.stats
+```
+
+Confirm `games_won` matches what you recorded in Step 2.
+
+### Step 4 — Pull on Machine B
+
+1. Launch the game on **Machine B** (clean local data).
+2. Open **Settings**, enter the same server URL, and log in as `alice` with the same password.
+3. The plugin will pull on startup. Wait for **Status: last synced at HH:MM**.
+4. Open the Stats overlay (key: `S`) and confirm the numbers from Step 2 are present.
+
+**Pass criterion:** `games_won`, `games_played`, and `fastest_win_seconds` on Machine B match Machine A.
+
+---
+
+## Test 2 — JWT Refresh on 401
+
+**Goal:** Confirm that an expired access token is refreshed transparently without user interaction.
+
+### Step 1 — Shorten the access token TTL on the server (test environment only)
+
+Edit the server `.env` and set a short expiry, then restart:
+
+```
+JWT_ACCESS_EXPIRY_SECS=5
+```
+
+> If you cannot modify the server config, skip to the manual token corruption method in Step 1b.
+
+### Step 1b (alternative) — Corrupt the stored access token directly
+
+On the machine where you want to test (Linux example):
+
+```bash
+# List keychain entries (uses secret-tool on GNOME)
+secret-tool search service solitaire_quest_server
+
+# Overwrite alice's access token with a deliberately invalid value
+secret-tool store --label="alice_access" service solitaire_quest_server account alice_access <<< "invalid.token.value"
+```
+
+### Step 2 — Trigger a sync with the expired/invalid token
+
+1. Launch the game.
+2. Either wait for the startup pull (for the short-TTL method), or open **Settings** and tap **Sync Now**.
+3. Observe the **Status** field.
+
+**Pass criterion (transparent refresh):** Status briefly shows "syncing…" and then shows "last synced at HH:MM" — no auth error is displayed. The access token in the keychain has been silently replaced.
+
+**Verify the new token is valid:**
+
+```bash
+# Extract the new token from the keychain
+secret-tool lookup service solitaire_quest_server account alice_access | head -c 50
+# Should look like a valid JWT (three base64 segments separated by dots)
+```
+
+### Step 3 — Test failed refresh (both tokens expired)
+
+1. Corrupt both the access token and the refresh token in the keychain:
+
+   ```bash
+   secret-tool store --label="alice_access" service solitaire_quest_server account alice_access <<< "bad"
+   secret-tool store --label="alice_refresh" service solitaire_quest_server account alice_refresh <<< "bad"
+   ```
+
+2. Launch the game and trigger a sync.
+
+**Pass criterion:** The Settings screen shows an error message matching: "Login expired — tap Sync Now after re-logging in". The game must not crash. No data must be lost (local files are untouched).
+
+3. Restore: log in again via Settings to get fresh tokens.
+
+---
+
+## Test 3 — Conflict Scenario (offline play on both machines, then sync)
+
+**Goal:** Confirm that progress made on both devices offline is merged correctly, with no data silently discarded.
+
+### Step 1 — Take both machines offline
+
+Disable network on both Machine A and Machine B (e.g. airplane mode, or block the server URL in `/etc/hosts`).
+
+### Step 2 — Play on Machine A (offline)
+
+1. Win 5 games. Note the resulting streak and `games_won`.
+2. Close the game.
+
+### Step 3 — Play on Machine B (offline)
+
+1. Win 3 different games. Note the resulting streak and `games_won`.
+2. Close the game.
+
+At this point Machine A and Machine B have divergent state.
+
+### Step 4 — Re-enable network, sync Machine A first
+
+1. Restore network.
+2. Launch the game on Machine A. The push-on-exit from Step 2 did not reach the server, so:
+   - Open Settings, tap **Sync Now** to force a pull.
+   - Close the game (triggers push-on-exit).
+3. Verify the server has Machine A's state:
+
+   ```bash
+   curl -s -H "Authorization: Bearer $TOKEN" \
+     https://solitaire.example.com/api/sync/pull | jq '.merged.stats.games_won'
+   ```
+
+### Step 5 — Sync Machine B
+
+1. Launch the game on Machine B.
+2. The startup pull fetches the server's merged state (which now contains Machine A's wins).
+3. Open Settings — wait for **Status: last synced at HH:MM**.
+4. Open the Stats overlay.
+
+**Pass criteria:**
+- `games_won` = max(Machine A wins, Machine B wins) — at minimum the higher of the two counts.
+- No games are lost — both machines' win counts contribute.
+- If the two machines had different `win_streak_current` values, a conflict should be recorded (visible if you inspect the server response directly):
+
+  ```bash
+  curl -s -H "Authorization: Bearer $TOKEN" \
+    https://solitaire.example.com/api/sync/pull | jq '.conflicts'
+  ```
+
+- The `win_streak_current` conflict entry will show `local_value` and `remote_value`. The higher value is used as the best-effort resolution.
+
+---
+
+## Test 4 — Account Deletion
+
+**Goal:** Confirm that `DELETE /api/account` removes all server-side data and that a subsequent authenticated request is rejected.
+
+### Step 1 — Confirm data exists before deletion
+
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" \
+  https://solitaire.example.com/api/sync/pull | jq '.merged.stats.games_played'
+# Expected: a non-zero number
+```
+
+### Step 2 — Delete the account via the API
+
+```bash
+curl -s -X DELETE \
+  -H "Authorization: Bearer $TOKEN" \
+  https://solitaire.example.com/api/account | jq .
+# Expected: {"ok":true}
+```
+
+### Step 3 — Verify all data is gone from the server
+
+```bash
+# Try to pull with the (now-invalid) token
+curl -s -H "Authorization: Bearer $TOKEN" \
+  https://solitaire.example.com/api/sync/pull
+# Expected: HTTP 401 Unauthorized
+
+# Try to log in again with the same credentials
+curl -s -X POST https://solitaire.example.com/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"alice","password":"<your-password>"}' | jq .
+# Expected: HTTP 401 or error body indicating invalid credentials
+```
+
+### Step 4 — Verify local data is NOT deleted
+
+1. Open the game. The local files (`stats.json`, `progress.json`, etc.) must still be present and intact — account deletion only affects the server.
+2. Check the Stats overlay and confirm local game history is visible.
+3. The Settings screen may show an auth error on next sync attempt, which is expected.
+
+### Step 5 — Re-register with the same username (optional)
+
+```bash
+curl -s -X POST https://solitaire.example.com/api/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"username":"alice","password":"<new-password>"}' | jq .
+# Expected: {"access_token":"...","refresh_token":"..."} — fresh empty account
+```
+
+**Pass criterion:** Re-registration succeeds, and a subsequent pull returns a payload with all-zero stats (completely fresh account, no residual data from the deleted account).
+
+---
+
+## Test 5 — Server Errors Do Not Show "Login Expired"
+
+**Goal:** Verify that a 500 Internal Server Error or 429 Too Many Requests shows a network error, not an auth error, to the user.
+
+### Step 1 — Simulate a 500 with a reverse proxy rule
+
+Add a temporary nginx/Caddy rule to return 500 for `/api/sync/*`:
+
+```nginx
+location /api/sync/ {
+    return 500;
+}
+```
+
+Or use a local proxy like `mitmproxy` to intercept and rewrite responses.
+
+### Step 2 — Trigger a sync
+
+Open Settings and tap **Sync Now**.
+
+**Pass criterion:** The Status field shows "Can't reach server — check your connection" (network error message), NOT "Login expired — tap Sync Now after re-logging in" (auth error message).
+
+Remove the nginx rule after this test.
+
+---
+
+## Regression Checklist
+
+After running all tests above, confirm:
+
+- [ ] No crash occurred during any test on either machine.
+- [ ] Local save files (`stats.json`, `progress.json`, `achievements.json`) are present and valid JSON after all tests.
+- [ ] The game launches and plays normally after all sync operations (sync is additive — never blocks gameplay).
+- [ ] The Stats overlay shows correct numbers on both machines after a successful sync round-trip.
+- [ ] An expired token is refreshed transparently without the user having to log in again.
+- [ ] A doubly-expired token surfaces a clear error message to the user.
+- [ ] Account deletion removes all server data; local data is preserved.
+- [ ] HTTP 5xx and 429 responses show a network error, not an auth error.

pkg/solitaire-quest-server/PKGBUILD

@@ -0,0 +1,63 @@
+# Maintainer: funman300 <funman300@gmail.com>
+
+pkgname=solitaire-quest-server
+pkgver=0.1.0
+pkgrel=1
+pkgdesc='Self-hosted sync server for Solitaire Quest (stats, achievements, leaderboards)'
+url='https://github.com/funman300/solitaire-quest'
+license=('MIT')
+arch=('x86_64')
+makedepends=('cargo' 'rust')
+depends=(
+    'gcc-libs'
+    'glibc'
+)
+backup=('etc/solitaire-quest-server/server.env')
+
+# Build from the local workspace (two levels above this PKGBUILD).
+_srcdir="$startdir/../.."
+source=(
+    'solitaire-quest-server.service'
+    'server.env'
+)
+b2sums=('SKIP'
+        'SKIP')
+
+prepare() {
+    export RUSTUP_TOOLCHAIN=stable
+    cd "$_srcdir"
+    cargo fetch --locked --target "$(rustc -Vv | grep host | cut -d' ' -f2)"
+}
+
+build() {
+    export RUSTUP_TOOLCHAIN=stable
+    export CARGO_TARGET_DIR=target
+    cd "$_srcdir"
+    cargo build --frozen --release -p solitaire_server
+}
+
+check() {
+    export RUSTUP_TOOLCHAIN=stable
+    cd "$_srcdir"
+    cargo test --frozen -p solitaire_server -p solitaire_sync
+}
+
+package() {
+    cd "$_srcdir"
+
+    # Binary
+    install -Dm0755 -t "$pkgdir/usr/bin/" "target/release/solitaire_server"
+
+    # systemd service
+    install -Dm0644 "$srcdir/solitaire-quest-server.service" \
+        "$pkgdir/usr/lib/systemd/system/solitaire-quest-server.service"
+
+    # Environment file (contains JWT_SECRET, DATABASE_URL, SERVER_PORT)
+    install -Dm0640 "$srcdir/server.env" \
+        "$pkgdir/etc/solitaire-quest-server/server.env"
+
+    # License and docs
+    install -Dm0644 LICENSE "$pkgdir/usr/share/licenses/$pkgname/LICENSE"
+    install -Dm0644 README_SERVER.md \
+        "$pkgdir/usr/share/doc/$pkgname/README_SERVER.md"
+}

pkg/solitaire-quest-server/server.env

@@ -0,0 +1,15 @@
+# Solitaire Quest Server — environment configuration
+# This file is installed to /etc/solitaire-quest-server/server.env (mode 0640).
+# Edit these values before starting the service.
+
+# Path to the SQLite database file.
+# The directory must be writable by the solitaire-quest service user.
+DATABASE_URL=sqlite:///var/lib/solitaire-quest-server/solitaire.db
+
+# HS256 signing secret for JWT tokens.
+# Generate a strong secret with: openssl rand -hex 32
+# REQUIRED — server will refuse to start if unset.
+JWT_SECRET=changeme_generate_with_openssl_rand_hex_32
+
+# TCP port the server listens on.
+SERVER_PORT=8080

pkg/solitaire-quest-server/solitaire-quest-server.service

@@ -0,0 +1,23 @@
+[Unit]
+Description=Solitaire Quest Sync Server
+Documentation=https://github.com/funman300/solitaire-quest/blob/main/README_SERVER.md
+After=network.target
+
+[Service]
+Type=simple
+User=solitaire-quest
+Group=solitaire-quest
+EnvironmentFile=/etc/solitaire-quest-server/server.env
+ExecStart=/usr/bin/solitaire_server
+Restart=on-failure
+RestartSec=5s
+
+# Harden the service
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/solitaire-quest-server
+
+[Install]
+WantedBy=multi-user.target

pkg/solitaire-quest/PKGBUILD

@@ -0,0 +1,48 @@
+# Maintainer: funman300 <funman300@gmail.com>
+
+pkgname=solitaire-quest
+pkgver=0.1.0
+pkgrel=1
+pkgdesc='Cross-platform Klondike Solitaire with progression, achievements, and optional sync'
+url='https://github.com/funman300/solitaire-quest'
+license=('MIT')
+arch=('x86_64')
+makedepends=('cargo' 'rust')
+depends=(
+    'gcc-libs'
+    'glibc'
+    'alsa-lib'
+    'libxkbcommon'
+    'systemd-libs'   # libudev.so — required by Bevy input
+)
+
+# Build from the local workspace (two levels above this PKGBUILD).
+_srcdir="$startdir/../.."
+source=()
+b2sums=()
+
+prepare() {
+    export RUSTUP_TOOLCHAIN=stable
+    cd "$_srcdir"
+    cargo fetch --locked --target "$(rustc -Vv | grep host | cut -d' ' -f2)"
+}
+
+build() {
+    export RUSTUP_TOOLCHAIN=stable
+    export CARGO_TARGET_DIR=target
+    cd "$_srcdir"
+    cargo build --frozen --release -p solitaire_app
+}
+
+check() {
+    export RUSTUP_TOOLCHAIN=stable
+    cd "$_srcdir"
+    # Only test non-Bevy crates — Bevy integration tests require a GPU/display.
+    cargo test --frozen -p solitaire_core -p solitaire_sync
+}
+
+package() {
+    cd "$_srcdir"
+    install -Dm0755 -t "$pkgdir/usr/bin/" "target/release/solitaire_app"
+    install -Dm0644 LICENSE "$pkgdir/usr/share/licenses/$pkgname/LICENSE"
+}

rust-toolchain.toml

@@ -0,0 +1,2 @@
+[toolchain]
+channel = "stable"

solitaire_app/Cargo.toml

@@ -1,6 +1,7 @@
 [package]
 name    = "solitaire_app"
 version.workspace = true
+license.workspace = true
 edition.workspace = true
 
 [[bin]]
@@ -10,3 +11,5 @@ path = "src/main.rs"
 [dependencies]
 bevy             = { workspace = true }
 solitaire_engine = { workspace = true }
+solitaire_data   = { workspace = true }
+keyring          = { workspace = true }

solitaire_app/src/main.rs

@@ -1,27 +1,60 @@
 use bevy::prelude::*;
+use solitaire_data::{load_settings_from, provider_for_backend, settings_file_path, Settings};
 use solitaire_engine::{
-    AchievementPlugin, AnimationPlugin, AudioPlugin, CardPlugin, ChallengePlugin,
-    DailyChallengePlugin, GamePlugin, HelpPlugin, InputPlugin, OnboardingPlugin, PausePlugin,
-    ProgressPlugin, SettingsPlugin, StatsPlugin, TablePlugin, TimeAttackPlugin, WeeklyGoalsPlugin,
+    AchievementPlugin, AnimationPlugin, AudioPlugin, AutoCompletePlugin, CardAnimationPlugin,
+    CardPlugin, ChallengePlugin, CursorPlugin, DailyChallengePlugin, FeedbackAnimPlugin,
+    FontPlugin, GamePlugin, HelpPlugin, HomePlugin, HudPlugin, InputPlugin, LeaderboardPlugin,
+    OnboardingPlugin, PausePlugin, ProfilePlugin, ProgressPlugin, SelectionPlugin, SettingsPlugin,
+    StatsPlugin, SyncPlugin, TablePlugin, TimeAttackPlugin, WeeklyGoalsPlugin, WinSummaryPlugin,
 };
 
 fn main() {
+    // Initialise the platform keyring store before any token operations.
+    // On Linux this uses the Secret Service (GNOME Keyring / KWallet); on
+    // macOS it uses the Keychain; on Windows it uses the Credential store.
+    // If the platform has no OS keyring (e.g. a headless CI box), keyring
+    // operations will fail gracefully with TokenError::KeychainUnavailable.
+    if let Err(e) = keyring::use_native_store(true) {
+        eprintln!(
+            "warn: could not initialise OS keyring ({e}); \
+             server sync login will be unavailable"
+        );
+    }
+
+    // Load settings before building the app so we can construct the right
+    // sync provider. Falls back to defaults if no settings file exists yet.
+    let settings: Settings = settings_file_path()
+        .map(|p| load_settings_from(&p))
+        .unwrap_or_default();
+    let sync_provider = provider_for_backend(&settings.sync_backend);
+
     App::new()
         .add_plugins(
             DefaultPlugins.set(WindowPlugin {
                 primary_window: Some(Window {
                     title: "Solitaire Quest".into(),
-                    resolution: (1280.0, 800.0).into(),
+                    resolution: (1280u32, 800u32).into(),
+                    resize_constraints: bevy::window::WindowResizeConstraints {
+                        min_width: 800.0,
+                        min_height: 600.0,
+                        ..default()
+                    },
                     ..default()
                 }),
                 ..default()
             }),
         )
+        .add_plugins(FontPlugin)
         .add_plugins(GamePlugin)
         .add_plugins(TablePlugin)
         .add_plugins(CardPlugin)
+        .add_plugins(CursorPlugin)
         .add_plugins(InputPlugin)
+        .add_plugins(SelectionPlugin)
         .add_plugins(AnimationPlugin)
+        .add_plugins(FeedbackAnimPlugin)
+        .add_plugins(CardAnimationPlugin)
+        .add_plugins(AutoCompletePlugin)
         .add_plugins(StatsPlugin::default())
         .add_plugins(ProgressPlugin::default())
         .add_plugins(AchievementPlugin::default())
@@ -29,10 +62,16 @@ fn main() {
         .add_plugins(WeeklyGoalsPlugin)
         .add_plugins(ChallengePlugin)
         .add_plugins(TimeAttackPlugin)
+        .add_plugins(HudPlugin)
         .add_plugins(HelpPlugin)
+        .add_plugins(HomePlugin)
+        .add_plugins(ProfilePlugin)
         .add_plugins(PausePlugin)
         .add_plugins(SettingsPlugin::default())
         .add_plugins(AudioPlugin)
         .add_plugins(OnboardingPlugin)
+        .add_plugins(SyncPlugin::new(sync_provider))
+        .add_plugins(LeaderboardPlugin)
+        .add_plugins(WinSummaryPlugin)
         .run();
 }