fix(ci): fail fast on empty keystore before 7-min cargo build

If KEYSTORE_BASE64 is unset, base64 -d writes an empty file silently,
cargo ndk then spends ~7 min compiling all ABIs, and only then does
apksigner fail. Add a size check after decode so the job fails in
seconds with a clear error message instead of wasting a full build.

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

.gitea/workflows/android-build.yml

@@ -0,0 +1,131 @@
+name: Android Build
+
+on:
+  push:
+    branches: [master]
+    # Rebuild whenever app/engine/asset code changes.
+    # Skip server-only, deploy, and doc changes.
+    paths-ignore:
+      - 'deploy/**'
+      - 'argocd/**'
+      - 'solitaire_server/**'
+      - '**.md'
+
+env:
+  ANDROID_SDK: /opt/android-sdk
+  NDK_VERSION: "25.2.9519653"
+  BUILD_TOOLS_VERSION: "34.0.0"
+  PLATFORM: "android-34"
+
+jobs:
+  build-apk:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set short SHA
+        id: meta
+        run: echo "sha=${GITHUB_SHA::8}" >> "$GITHUB_OUTPUT"
+
+      # ── System dependencies ────────────────────────────────────────────
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y openjdk-17-jdk-headless unzip zip
+
+      # ── Android SDK (shared cache key with release workflow) ──────────
+      - name: Cache Android SDK
+        uses: actions/cache@v4
+        id: sdk-cache
+        with:
+          path: ${{ env.ANDROID_SDK }}
+          key: v2-android-sdk-ndk${{ env.NDK_VERSION }}-bt${{ env.BUILD_TOOLS_VERSION }}
+
+      - name: Install Android SDK + NDK
+        if: steps.sdk-cache.outputs.cache-hit != 'true'
+        run: |
+          sudo mkdir -p ${{ env.ANDROID_SDK }}/cmdline-tools
+          curl -sL \
+            "https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip" \
+            -o /tmp/cmdtools.zip
+          unzip -q /tmp/cmdtools.zip -d /tmp/cmdtools
+          sudo mv /tmp/cmdtools/cmdline-tools ${{ env.ANDROID_SDK }}/cmdline-tools/latest
+          yes | sudo ${{ env.ANDROID_SDK }}/cmdline-tools/latest/bin/sdkmanager \
+            --sdk_root=${{ env.ANDROID_SDK }} --licenses > /dev/null 2>&1 || true
+          sudo ${{ env.ANDROID_SDK }}/cmdline-tools/latest/bin/sdkmanager \
+            --sdk_root=${{ env.ANDROID_SDK }} \
+            "build-tools;${{ env.BUILD_TOOLS_VERSION }}" \
+            "platforms;${{ env.PLATFORM }}" \
+            "ndk;${{ env.NDK_VERSION }}"
+
+      # ── Rust toolchain ─────────────────────────────────────────────────
+      - name: Install Rust stable
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
+            | sh -s -- -y --default-toolchain stable --no-modify-path
+          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
+
+      - name: Add Android cross-compilation targets
+        run: |
+          rustup target add \
+            aarch64-linux-android \
+            armv7-linux-androideabi \
+            x86_64-linux-android
+
+      # ── Cargo caches ───────────────────────────────────────────────────
+      - name: Cache Cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry/index
+            ~/.cargo/registry/cache
+            ~/.cargo/git/db
+          key: cargo-registry-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: cargo-registry-
+
+      - name: Cache cargo-ndk binary
+        uses: actions/cache@v4
+        id: ndk-tool-cache
+        with:
+          path: ~/.cargo/bin/cargo-ndk
+          key: cargo-ndk-${{ runner.os }}-stable
+
+      - name: Cache build artifacts
+        uses: actions/cache@v4
+        with:
+          path: target
+          key: android-target-${{ hashFiles('**/Cargo.lock') }}-${{ github.sha }}
+          restore-keys: android-target-${{ hashFiles('**/Cargo.lock') }}-
+
+      - name: Install cargo-ndk
+        if: steps.ndk-tool-cache.outputs.cache-hit != 'true'
+        run: cargo install cargo-ndk --locked
+
+      # ── Build APK ──────────────────────────────────────────────────────
+      # Debug CI only builds arm64-v8a — full three-ABI debug builds blow
+      # past the runner's disk budget (~25 GB of target/ + intermediate
+      # APKs caused apksigner to OOM-on-disk in the previous run). Release
+      # CI still ships all three ABIs from android-release.yml.
+      - name: Build debug APK
+        env:
+          ANDROID_HOME: ${{ env.ANDROID_SDK }}
+          ANDROID_NDK_HOME: ${{ env.ANDROID_SDK }}/ndk/${{ env.NDK_VERSION }}
+          BUILD_TOOLS_VERSION: ${{ env.BUILD_TOOLS_VERSION }}
+          PLATFORM: ${{ env.PLATFORM }}
+          PROFILE: debug
+          ABIS: arm64-v8a
+        run: ./scripts/build_android_apk.sh
+
+      # ── Artifact ───────────────────────────────────────────────────────
+      # Pinned to v3 because Gitea Actions doesn't implement the github.com
+      # artifact service that upload-artifact@v4+ requires; v3 uses the
+      # older chunked HTTP API that Gitea's GHES-compatibility layer
+      # supports.
+      - name: Upload APK
+        uses: actions/upload-artifact@v3
+        with:
+          name: solitaire-quest-debug-${{ steps.meta.outputs.sha }}
+          path: target/debug/apk/solitaire-quest.apk
+          retention-days: 30

.gitea/workflows/android-release.yml

@@ -0,0 +1,154 @@
+name: Android Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+env:
+  ANDROID_SDK: /opt/android-sdk
+  NDK_VERSION: "25.2.9519653"
+  BUILD_TOOLS_VERSION: "34.0.0"
+  PLATFORM: "android-34"
+  GITEA_API: https://git.aleshym.co/api/v1
+  REPO: funman300/Rusty_Solitare
+
+jobs:
+  build-release-apk:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: meta
+        run: echo "tag=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
+
+      # ── System dependencies ────────────────────────────────────────────
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y openjdk-17-jdk-headless unzip zip jq
+
+      # ── Android SDK (shared cache key with debug workflow) ─────────────
+      - name: Cache Android SDK
+        uses: actions/cache@v4
+        id: sdk-cache
+        with:
+          path: ${{ env.ANDROID_SDK }}
+          key: v2-android-sdk-ndk${{ env.NDK_VERSION }}-bt${{ env.BUILD_TOOLS_VERSION }}
+
+      - name: Install Android SDK + NDK
+        if: steps.sdk-cache.outputs.cache-hit != 'true'
+        run: |
+          sudo mkdir -p ${{ env.ANDROID_SDK }}/cmdline-tools
+          curl -sL \
+            "https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip" \
+            -o /tmp/cmdtools.zip
+          unzip -q /tmp/cmdtools.zip -d /tmp/cmdtools
+          sudo mv /tmp/cmdtools/cmdline-tools ${{ env.ANDROID_SDK }}/cmdline-tools/latest
+          yes | sudo ${{ env.ANDROID_SDK }}/cmdline-tools/latest/bin/sdkmanager \
+            --sdk_root=${{ env.ANDROID_SDK }} --licenses > /dev/null 2>&1 || true
+          sudo ${{ env.ANDROID_SDK }}/cmdline-tools/latest/bin/sdkmanager \
+            --sdk_root=${{ env.ANDROID_SDK }} \
+            "build-tools;${{ env.BUILD_TOOLS_VERSION }}" \
+            "platforms;${{ env.PLATFORM }}" \
+            "ndk;${{ env.NDK_VERSION }}"
+
+      # ── Rust toolchain ─────────────────────────────────────────────────
+      - name: Install Rust stable
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
+            | sh -s -- -y --default-toolchain stable --no-modify-path
+          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
+
+      - name: Add Android cross-compilation targets
+        run: |
+          rustup target add \
+            aarch64-linux-android \
+            armv7-linux-androideabi \
+            x86_64-linux-android
+
+      # ── Cargo caches ───────────────────────────────────────────────────
+      - name: Cache Cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry/index
+            ~/.cargo/registry/cache
+            ~/.cargo/git/db
+          key: cargo-registry-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: cargo-registry-
+
+      - name: Cache cargo-ndk binary
+        uses: actions/cache@v4
+        id: ndk-tool-cache
+        with:
+          path: ~/.cargo/bin/cargo-ndk
+          key: cargo-ndk-${{ runner.os }}-stable
+
+      - name: Cache build artifacts
+        uses: actions/cache@v4
+        with:
+          path: target
+          key: android-release-target-${{ hashFiles('**/Cargo.lock') }}-${{ github.sha }}
+          restore-keys: android-release-target-${{ hashFiles('**/Cargo.lock') }}-
+
+      - name: Install cargo-ndk
+        if: steps.ndk-tool-cache.outputs.cache-hit != 'true'
+        run: cargo install cargo-ndk --locked
+
+      # ── Build & sign with release keystore ─────────────────────────────
+      - name: Decode keystore
+        run: |
+          echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 -d > /tmp/solitaire-release.jks
+          size=$(wc -c < /tmp/solitaire-release.jks)
+          echo "Keystore size: ${size} bytes"
+          [ "$size" -gt 0 ] || { echo "ERROR: KEYSTORE_BASE64 secret is empty or unset"; exit 1; }
+
+      - name: Build signed release APK
+        env:
+          ANDROID_HOME: ${{ env.ANDROID_SDK }}
+          ANDROID_NDK_HOME: ${{ env.ANDROID_SDK }}/ndk/${{ env.NDK_VERSION }}
+          BUILD_TOOLS_VERSION: ${{ env.BUILD_TOOLS_VERSION }}
+          PLATFORM: ${{ env.PLATFORM }}
+          PROFILE: release
+          KEYSTORE: /tmp/solitaire-release.jks
+          KEYSTORE_PASS: ${{ secrets.KEYSTORE_PASS }}
+          KEY_ALIAS: ${{ secrets.KEY_ALIAS }}
+          KEY_PASS: ${{ secrets.KEY_PASS }}
+          APK_OUT: ferrous-solitaire-${{ steps.meta.outputs.tag }}.apk
+        run: ./scripts/build_android_apk.sh
+
+      # ── Publish to Gitea release ───────────────────────────────────────
+      - name: Create Gitea release
+        id: release
+        run: |
+          TAG="${{ steps.meta.outputs.tag }}"
+          RESPONSE=$(curl -s -o /tmp/release.json -w "%{http_code}" \
+            -X POST "$GITEA_API/repos/$REPO/releases" \
+            -H "Authorization: token ${{ secrets.CI_TOKEN }}" \
+            -H "Content-Type: application/json" \
+            -d "{\"tag_name\":\"$TAG\",\"name\":\"$TAG\",\"draft\":false,\"prerelease\":false}")
+          if [ "$RESPONSE" = "409" ]; then
+            curl -sf "$GITEA_API/repos/$REPO/releases/tags/$TAG" \
+              -H "Authorization: token ${{ secrets.CI_TOKEN }}" \
+              > /tmp/release.json
+          elif [ "$RESPONSE" != "201" ]; then
+            echo "Release creation failed with HTTP $RESPONSE"
+            cat /tmp/release.json
+            exit 1
+          fi
+          RELEASE_ID=$(jq -r '.id' /tmp/release.json)
+          echo "release_id=$RELEASE_ID" >> "$GITHUB_OUTPUT"
+
+      - name: Upload signed APK
+        run: |
+          TAG="${{ steps.meta.outputs.tag }}"
+          APK="ferrous-solitaire-${TAG}.apk"
+          curl -sf -X POST \
+            "$GITEA_API/repos/$REPO/releases/${{ steps.release.outputs.release_id }}/assets?name=$APK" \
+            -H "Authorization: token ${{ secrets.CI_TOKEN }}" \
+            -H "Content-Type: application/octet-stream" \
+            --data-binary @"$APK"

.gitea/workflows/docker-build.yml

@@ -0,0 +1,73 @@
+name: Build and Deploy
+
+on:
+  push:
+    branches: [master]
+    # Only run when server code changes, not when CI itself updates deploy/.
+    paths-ignore:
+      - 'deploy/**'
+      - 'argocd/**'
+      - '**.md'
+
+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://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
+          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 commit -m "chore(deploy): bump image to ${{ steps.meta.outputs.sha }} [skip ci]" || true
+          git pull --rebase origin master
+          git push

.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-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-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-f23630e78ae88e72d7930184f7cd8fc67e71f3930609f1cf14061d35d6de8ec3.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "INSERT OR IGNORE INTO analytics_events\n               (id, user_id, session_id, event_type, payload, client_time, received_at)\n               VALUES (?, ?, ?, ?, ?, ?, ?)",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 7
+    },
+    "nullable": []
+  },
+  "hash": "f23630e78ae88e72d7930184f7cd8fc67e71f3930609f1cf14061d35d6de8ec3"
+}

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,15 +43,15 @@ 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
 
 - **Offline first.** The local file is always the source of truth. Sync is additive, never destructive.
-- **Pure core.** All game logic lives in a dependency-free Rust crate with no Bevy, no network, and no I/O. This keeps it fully unit-testable and portable.
-- **No panics in game logic.** Every state transition returns `Result<_, MoveError>`. Panics are only acceptable in startup/configuration code.
 - **One language, one repo.** The game client, sync client, shared types, and sync server are all Rust crates in a single Cargo workspace.
 - **Plugin-based Bevy architecture.** Each major feature is a Bevy `Plugin`. Systems are small and single-purpose. Cross-system communication uses Bevy `Event`s.
-- **UI-first interaction.** Every player-triggered action — new game, undo, draw, pause, open stats / settings / help / profile / leaderboard, etc. — must be reachable from a visible UI control. Keyboard shortcuts exist only as optional accelerators for power users; they are never the sole entry point. A player using only mouse or touch must be able to perform every action. New gameplay features ship with the UI control alongside the system that backs it.
+
+Pure-core, no-panics-in-game-logic, and UI-first-interaction constraints are enforced by CLAUDE.md §2.1, §2.3, and §3.3 respectively — those are the canonical statements; this file describes the design that motivates them.
 
 ---
 
@@ -87,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
 ```
 
@@ -161,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`.
 
@@ -262,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 |
@@ -306,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
@@ -366,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>;
 }
 ```
 
@@ -455,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
@@ -585,7 +638,20 @@ pub struct Settings {
     pub animation_speed: AnimSpeed,
     pub theme: Theme,
     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,
 }
 ```
 
@@ -601,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
 
@@ -618,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 |
@@ -826,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`.
@@ -946,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` |

CLAUDE.md

@@ -1,114 +1,693 @@
-# Solitaire Quest — Claude Code Instructions
+# CLAUDE.md
 
-See @ARCHITECTURE.md for full project design, crate responsibilities, data models, and API reference.
+version: unified-4.0
 
 ---
 
-## Project Layout
+# 0. Role of This File
 
-```text
-solitaire_core/    # Pure Rust game logic — NO Bevy, NO network, NO I/O
-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_app/     # Thin binary entry point
-assets/            # Source assets — embedded at compile time via include_bytes!()
+This document defines:
+
+* **Execution rules (what Claude must do)**
+* **System constraints (what Claude must never violate)**
+* **Operational architecture (how code is structured)**
+
+For full system design details:
+→ `ARCHITECTURE.md` (authoritative source of truth)
+
+This file overrides all conversational assumptions.
+
+---
+
+# 1. System Architecture (Authoritative Mapping)
+
+## 1.1 Crates
+
+```text id="crate_map"
+solitaire_core/    # PURE logic (no IO, no Bevy, deterministic)
+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 + default theme)
 ```
 
 ---
 
-## Build & Test Commands
+## 1.2 Architecture Source of Truth
+
+* Full system design: `ARCHITECTURE.md`
+* This file NEVER redefines system design
+* This file ONLY enforces behavior
+
+---
+
+# 2. Hard Global Constraints (NON-NEGOTIABLE)
+
+These override all other instructions.
+
+## 2.1 Core Determinism
+
+* `solitaire_core` MUST:
+
+  * be deterministic
+  * be side-effect free
+  * never depend on Bevy / IO / async
+
+---
+
+## 2.2 Sync Isolation
+
+* `solitaire_sync`:
+
+  * no Bevy
+  * no IO
+  * no engine dependencies
+* merge logic must be pure functions only
+
+---
+
+## 2.3 Error Policy
+
+* NO `unwrap()`
+* NO `panic!()` in runtime/game logic
+* 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
+
+* Sync must run on `AsyncComputeTaskPool`
+* NEVER block Bevy main thread
+
+---
+
+## 2.5 Persistence Rules
+
+* atomic writes only:
+
+  * write `.tmp`
+  * rename atomically
+* no partial state writes allowed
+
+---
+
+## 2.6 Security Rules
+
+* credentials ONLY via `keyring`
+* NEVER store secrets in:
+
+  * files
+  * logs
+  * source code
+
+---
+
+## 2.7 Sync System Rules
+
+* All sync backends implement:
+
+```rust id="sync_trait"
+trait SyncProvider
+```
+
+* `SyncPlugin` MUST be backend-agnostic
+* NEVER match on backend inside ECS systems
+
+---
+
+# 3. Engine Rules (Bevy Layer)
+
+## 3.1 ECS Design
+
+* systems = single responsibility
+* 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
+
+* ONLY `GameStateResource` can mutate game state
+* UI systems MUST NOT directly modify core logic
+
+---
+
+## 3.3 UI-First Constraint (CRITICAL)
+
+Every player action MUST:
+
+* have a visible UI control
+* NOT rely solely on keyboard shortcuts
+
+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
+
+---
+
+# 4. Asset System Rules
+
+## 4.1 Runtime Assets (AssetServer)
+
+Loaded via:
+
+* `CardImageSet`
+* `BackgroundImageSet`
+* `FontResource`
+
+Includes:
+
+* cards
+* backgrounds
+* fonts
+
+---
+
+## 4.2 Embedded Assets
+
+Embed via `include_bytes!()` only when ALL of the following are true:
+
+* 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.
+
+---
+
+## 4.3 Test Compatibility Rule
+
+All asset loaders MUST accept:
+
+```rust id="asset_fallback"
+Option<Res<AssetServer>>
+```
+
+Must degrade gracefully under `MinimalPlugins`.
+
+---
+
+# 5. Code Standards
+
+## 5.1 Error Handling
+
+* use `thiserror`
+* no `Box<dyn Error>` in libraries
+
+---
+
+## 5.2 Public API Rules
+
+* prefer `Into<T>` over concrete types
+* 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
+
+---
+
+## 5.3 Derive Order
+
+```rust id="derive_order"
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+```
+
+---
+
+## 5.4 Performance Rules
+
+* NO `clone()` in hot paths
+* profile before optimizing
+
+---
+
+## 5.5 SQL Rules
+
+* ONLY `sqlx::query!`
+* NO raw SQL strings
+
+---
+
+# 6. Build & Verification Rules
+
+These are mandatory before ANY commit.
+
+```bash id="build_rules"
+cargo test --workspace
+cargo clippy --workspace -- -D warnings
+```
+
+---
+
+# 7. Git Workflow Rules
+
+## Commit format
+
+```text id="commit_fmt"
+type(scope): description
+```
+
+Examples:
+
+* feat(core): add draw-three rules
+* fix(engine): correct drag z-order
+* test(core): undo boundary cases
+
+---
+
+## Commit conditions
+
+* tests must pass
+* clippy must be clean
+
+NEVER commit otherwise
+
+---
+
+# 8. Change Control (ASK BEFORE DOING)
+
+Claude must request confirmation before:
+
+* 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 the merge strategy in `solitaire_sync::merge`
+* changing the `SyncPayload` wire format (breaking change for existing servers)
+
+---
+
+# 9. System Mental Model (IMPORTANT)
+
+```text id="mental_model"
+Core (rules + deterministic logic)
+    ↓
+Engine (Bevy orchestration)
+    ↓
+Data layer (persistence + sync)
+    ↓
+Server (optional external system)
+```
+
+Core is always the source of truth.
+
+---
+
+# 10. Known Platform Pitfalls
+
+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 — 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
+
+---
+
+# 11. Forbidden Patterns
+
+* game logic inside Bevy systems
+* duplication across crates
+* 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()`
+
+---
+
+# 12. Execution Rules for Claude
+
+When generating code:
+
+1. respect crate boundaries
+2. minimize diff size
+3. do not expand scope
+4. follow existing patterns
+5. preserve invariants
+
+If unclear:
+→ ask before acting
+
+---
+
+# 13. Relationship to ARCHITECTURE.md
+
+| File            | Role                      |
+| --------------- | ------------------------- |
+| CLAUDE.md       | execution + constraints   |
+| ARCHITECTURE.md | system design truth       |
+| Both combined   | full system understanding |
+
+---
+# 14. Modal System Conventions
+
+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
-# Dev run (fast compile via dynamic linking)
-cargo run -p solitaire_app --features bevy/dynamic_linking
+cargo apk build --package solitaire_app --lib
+adb install -r target/debug/apk/solitaire-quest.apk
+```
 
-# Release build
-cargo build --workspace --release
+## 15.2 Coordinate system reminder
 
-# All tests — MUST pass before any commit
-cargo test --workspace
+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.
 
-# Lint — MUST pass clean (zero warnings)
-cargo clippy --workspace -- -D warnings
+## 15.3 Android-specific test checklist
 
-# Run sync server locally
-cargo run -p solitaire_server
+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
 
-# Check a single crate
-cargo test -p solitaire_core
-cargo clippy -p solitaire_core -- -D warnings
+---
+
+# 16. Context Injection System (AUTOMATIC SCOPE FILTER)
+
+## 16.1 Purpose
+
+Before generating any response, Claude MUST construct a **minimal relevant context set**.
+
+This prevents:
+
+* architectural drift
+* irrelevant spec loading
+* over-engineering
+* cross-crate confusion
+
+---
+
+## 16.2 Input Classification Step (MANDATORY)
+
+Every request MUST be classified into exactly one task type:
+
+```text id="task_types"
+feature
+bugfix
+refactor
+system_design
+bevy_system
+core_logic
+sync
+optimization
+test
+debug
+```
+
+If uncertain → ask clarification.
+
+---
+
+## 16.3 Context Selection Engine
+
+After classification, Claude MUST include ONLY the relevant sections below.
+
+---
+
+## 16.4 Context Map (CORE RULESET)
+
+### feature
+
+Include:
+
+* §2 Hard Global Constraints
+* §3 Engine Rules
+* ARCHITECTURE.md (crate of target feature only)
+* relevant data models (GameState, SyncPayload if needed)
+
+---
+
+### bugfix
+
+Include:
+
+* §2 Hard Global Constraints
+* §5 Code Standards
+* affected crate boundaries
+* relevant system (engine/core/sync only)
+
+---
+
+### refactor
+
+Include:
+
+* §3 Engine Rules
+* §5 Code Standards
+* §11 Forbidden Patterns
+* target crate boundaries
+
+---
+
+### system_design
+
+Include:
+
+* ARCHITECTURE.md (FULL)
+* §9 Mental Model
+* §1 System Architecture Mapping
+
+---
+
+### core_logic
+
+Include:
+
+* solitaire_core rules only
+* GameState model
+* MoveError model
+* §2.1–2.3 constraints
+
+---
+
+### bevy_system
+
+Include:
+
+* §3 Engine Rules
+* ECS rules (Events/Resources/Components)
+* UI-first constraint
+* relevant plugin system only
+
+---
+
+### sync
+
+Include:
+
+* SyncProvider trait
+* merge strategy rules
+* solitaire_sync models
+* §2.6 Sync Rules
+
+---
+
+### optimization
+
+Include:
+
+* target crate only
+* §5.4 Performance Rules
+* hot path constraints
+
+---
+
+### test
+
+Include:
+
+* §6 Build Rules
+* relevant module
+* expected invariants
+
+---
+
+### debug
+
+Include:
+
+* target file/module only
+* §2.3 Error Policy
+* runtime assumptions relevant to failure
+
+---
+
+## 16.5 Context Compression Rules
+
+Claude MUST obey:
+
+* never include full ARCHITECTURE.md unless system_design
+* max 2 crates per response unless explicitly required
+* prefer function-level context over file-level context
+* exclude unrelated plugins/systems
+
+---
+
+## 16.6 Context Priority Order
+
+When space is limited:
+
+1. Hard Constraints (§2)
+2. Target crate rules
+3. Data models
+4. Only then: architecture snippets
+
+---
+
+## 16.7 “No Context Pollution” Rule
+
+Claude must NOT include:
+
+* unrelated crates
+* unrelated plugins
+* unused data models
+* full architecture dumps
+* speculative systems
+
+---
+
+## 16.8 Self-Check Before Execution
+
+Before writing code, Claude MUST verify:
+
+* [ ] Is only relevant context included?
+* [ ] Is at least one hard constraint present?
+* [ ] Am I touching more than one crate unnecessarily?
+* [ ] Am I duplicating ARCHITECTURE.md content?
+
+If any fail → revise context selection.
+
+---
+
+## 16.9 Injection Output Format (Internal Model)
+
+Claude should behave as if it constructed:
+
+```text id="ctx_format"
+[SELECTED TASK TYPE]
+
+[MINIMAL REQUIRED RULES]
+
+[MINIMAL ARCHITECTURE SLICES]
+
+[RELEVANT MODELS]
+
+[REQUEST]
 ```
 
 ---
 
-## Hard Rules
+## 16.10 Relationship to ARCHITECTURE.md
 
-- `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>`.
-- Audio assets are embedded at compile time using `include_bytes!()` in `audio_plugin.rs`.
-- Card faces (52 PNGs in `assets/cards/faces/`), card backs (`assets/cards/backs/back_N.png`), board backgrounds (`assets/backgrounds/bg_N.png`), and the UI font (`assets/fonts/main.ttf`) are loaded at runtime via `AssetServer::load()` and stored as `Handle<Image>`/`Handle<Font>` in the `CardImageSet`, `BackgroundImageSet`, and `FontResource` resources. The `assets/` directory must ship alongside the binary.
-- Asset-loading systems take `Option<Res<AssetServer>>` so they degrade cleanly under `MinimalPlugins` (tests). When `CardImageSet` is absent, `card_plugin` falls back to a `Text2d` rank+suit overlay; when `BackgroundImageSet` is absent, the board falls back to a solid colour.
-- 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.
-- `cargo clippy --workspace -- -D warnings` must pass clean after every change.
-- `cargo test --workspace` must pass after every change.
+* ARCHITECTURE.md = source of truth
+* CLAUDE.md = execution constraints
+* THIS SECTION = filtering layer between them
 
 ---
 
-## Code Style
-
-- Use `thiserror` for error types. Never `Box<dyn Error>` in library crates.
-- Prefer `Into<T>` over concrete types in public API function parameters.
-- All public items must have doc comments (`///`). Private items: comment only when non-obvious.
-- Derive order convention: `#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]`
-- Bevy systems: one responsibility per system. Use `Events` for cross-system communication, never shared mutable state.
-- SQL queries: use `sqlx::query!` macros (compile-time checked), not raw string queries.
-- No `clone()` calls in hot paths (game loop systems). Profile before optimising elsewhere.
-
----
-
-## Bevy Conventions
-
-- One `Plugin` per major feature: `CardPlugin`, `AudioPlugin`, `AchievementPlugin`, `UIPlugin`, `SyncPlugin`.
-- Resources own shared state. Events communicate between systems. Components own per-entity data.
-- All UI screens are built with Bevy UI (`bevy::ui`). Never mix UI layout and game logic in the same system.
-- Layout is recomputed on `WindowResized` — never assume a fixed window size.
-- **UI-first.** Every player-triggered action (new game, undo, draw, pause, open stats / settings / help / profile / leaderboard, switch mode, etc.) must be reachable from a visible UI control. Keyboard shortcuts are optional accelerators — never the sole entry point. New gameplay features ship with the UI control alongside the system that backs it; do not merge a feature that is keyboard-only.
-
----
-
-## Git Workflow
-
-- Commit after each passing phase, not after every file change.
-- Commit message format: `type(scope): description`
-  - `feat(core): add draw-three mode validation`
-  - `fix(engine): card z-order during drag`
-  - `test(core): undo stack boundary conditions`
-  - `chore(server): add sqlx migration 002`
-- Never commit with failing tests or clippy warnings.
-- Never commit secrets, `.env` files, or `*.db` files.
-
----
-
-## Ask Before Doing
-
-- Adding a new crate dependency (discuss alternatives first).
-- Changing a type in `solitaire_sync` (breaking change on both client and server).
-- Altering the database schema (requires a new sqlx migration).
-- Introducing `unsafe` code anywhere.
-- Changing the merge strategy in `solitaire_sync::merge()`.
-
----
-
-## Lessons Learned
-
-> Add entries here when Claude makes a mistake so it isn't repeated.
-
-- Bevy's `Time` resource uses `f32` seconds; convert to `u64` only when writing to `StatsSnapshot`.
-- `sqlx::migrate!()` macro path is relative to the crate root, not the workspace root.
-- `keyring` on Linux requires a running secret service (e.g. GNOME Keyring or KWallet) — handle `Error::NoStorageAccess` gracefully and fall back to prompting the user.
-- `dirs::data_dir()` returns `None` on some minimal Linux environments — always handle the `None` case explicitly, do not unwrap.
+# END CONTEXT INJECTION SYSTEM

CLAUDE_PROMPT_PACK.md

@@ -0,0 +1,497 @@
+# 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 to solitaire_core or solitaire_sync without confirmation
+- 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:
+- 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

@@ -0,0 +1,296 @@
+# 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_wasm:
+depends_on: [solitaire_core, wasm-bindgen, serde-wasm-bindgen]
+role: "wasm_replay_player"
+
+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 and resources"
+
+---
+
+## 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

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

@@ -44,7 +44,7 @@ dependencies = [
  "accesskit_consumer",
  "hashbrown 0.15.5",
  "objc2 0.5.2",
- "objc2-app-kit",
+ "objc2-app-kit 0.2.2",
  "objc2-foundation 0.2.2",
 ]
 
@@ -126,6 +126,19 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if",
+ "getrandom 0.3.4",
+ "once_cell",
+ "version_check",
+ "zerocopy",
+]
+
 [[package]]
 name = "aho-corasick"
 version = "1.1.4"
@@ -313,6 +326,23 @@ dependencies = [
  "num-traits",
 ]
 
+[[package]]
+name = "arboard"
+version = "3.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0348a1c054491f4bfe6ab86a7b6ab1e44e45d899005de92f58b3df180b36ddaf"
+dependencies = [
+ "clipboard-win",
+ "log",
+ "objc2 0.6.4",
+ "objc2-app-kit 0.3.2",
+ "objc2-foundation 0.3.2",
+ "parking_lot",
+ "percent-encoding",
+ "windows-sys 0.60.2",
+ "x11rb",
+]
+
 [[package]]
 name = "arc-swap"
 version = "1.9.1"
@@ -702,7 +732,7 @@ dependencies = [
  "cfg-if",
  "console_error_panic_hook",
  "ctrlc",
- "downcast-rs",
+ "downcast-rs 2.0.2",
  "log",
  "thiserror 2.0.18",
  "variadics_please",
@@ -736,7 +766,7 @@ dependencies = [
  "crossbeam-channel",
  "derive_more",
  "disqualified",
- "downcast-rs",
+ "downcast-rs 2.0.2",
  "either",
  "futures-io",
  "futures-lite",
@@ -784,7 +814,7 @@ dependencies = [
  "bevy_utils",
  "bevy_window",
  "derive_more",
- "downcast-rs",
+ "downcast-rs 2.0.2",
  "serde",
  "smallvec",
  "thiserror 2.0.18",
@@ -1183,7 +1213,7 @@ dependencies = [
  "bevy_utils",
  "derive_more",
  "disqualified",
- "downcast-rs",
+ "downcast-rs 2.0.2",
  "erased-serde",
  "foldhash 0.2.0",
  "glam 0.30.10",
@@ -1242,7 +1272,7 @@ dependencies = [
  "bitflags 2.11.1",
  "bytemuck",
  "derive_more",
- "downcast-rs",
+ "downcast-rs 2.0.2",
  "encase",
  "fixedbitset",
  "glam 0.30.10",
@@ -1837,6 +1867,18 @@ dependencies = [
  "thiserror 1.0.69",
 ]
 
+[[package]]
+name = "calloop-wayland-source"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95a66a987056935f7efce4ab5668920b5d0dac4a7c99991a67395f13702ddd20"
+dependencies = [
+ "calloop",
+ "rustix 0.38.44",
+ "wayland-backend",
+ "wayland-client",
+]
+
 [[package]]
 name = "cbc"
 version = "0.1.2"
@@ -1972,6 +2014,15 @@ version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
 
+[[package]]
+name = "clipboard-win"
+version = "5.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bde03770d3df201d4fb868f2c9c59e66a3e4e2bd06692a0fe701e7103c7e84d4"
+dependencies = [
+ "error-code",
+]
+
 [[package]]
 name = "cmake"
 version = "0.1.58"
@@ -2683,6 +2734,12 @@ version = "0.15.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1aaf95b3e5c8f23aa320147307562d361db0ae0d51242340f558153b4eb2439b"
 
+[[package]]
+name = "downcast-rs"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75b325c5dbd37f80359721ad39aca5a29fb04c89279657cffdda8736d0c0b9d2"
+
 [[package]]
 name = "downcast-rs"
 version = "2.0.2"
@@ -2882,6 +2939,12 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "error-code"
+version = "3.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dea2df4cf52843e0452895c455a1a2cfbb842a1e7329671acf418fdc53ed4c59"
+
 [[package]]
 name = "etcetera"
 version = "0.8.0"
@@ -4968,6 +5031,18 @@ dependencies = [
  "objc2-quartz-core",
 ]
 
+[[package]]
+name = "objc2-app-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d49e936b501e5c5bf01fda3a9452ff86dc3ea98ad5f283e1455153142d97518c"
+dependencies = [
+ "bitflags 2.11.1",
+ "objc2 0.6.4",
+ "objc2-core-graphics",
+ "objc2-foundation 0.3.2",
+]
+
 [[package]]
 name = "objc2-audio-toolbox"
 version = "0.3.2"
@@ -5065,6 +5140,19 @@ dependencies = [
  "objc2 0.6.4",
 ]
 
+[[package]]
+name = "objc2-core-graphics"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e022c9d066895efa1345f8e33e584b9f958da2fd4cd116792e15e07e4720a807"
+dependencies = [
+ "bitflags 2.11.1",
+ "dispatch2",
+ "objc2 0.6.4",
+ "objc2-core-foundation",
+ "objc2-io-surface",
+]
+
 [[package]]
 name = "objc2-core-image"
 version = "0.2.2"
@@ -5121,6 +5209,17 @@ dependencies = [
  "objc2-core-foundation",
 ]
 
+[[package]]
+name = "objc2-io-surface"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "180788110936d59bab6bd83b6060ffdfffb3b922ba1396b312ae795e1de9d81d"
+dependencies = [
+ "bitflags 2.11.1",
+ "objc2 0.6.4",
+ "objc2-core-foundation",
+]
+
 [[package]]
 name = "objc2-link-presentation"
 version = "0.2.2"
@@ -5129,7 +5228,7 @@ checksum = "a1a1ae721c5e35be65f01a03b6d2ac13a54cb4fa70d8a5da293d7b0020261398"
 dependencies = [
  "block2 0.5.1",
  "objc2 0.5.2",
- "objc2-app-kit",
+ "objc2-app-kit 0.2.2",
  "objc2-foundation 0.2.2",
 ]
 
@@ -5724,6 +5823,15 @@ version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
 
+[[package]]
+name = "quick-xml"
+version = "0.39.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "958f21e8e7ceb5a1aa7fa87fab28e7c75976e0bfe7e23ff069e0a260f894067d"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "quinn"
 version = "0.11.9"
@@ -6097,7 +6205,7 @@ dependencies = [
  "pico-args",
  "rgb",
  "svgtypes",
- "tiny-skia",
+ "tiny-skia 0.12.0",
  "usvg",
  "zune-jpeg",
 ]
@@ -6434,6 +6542,19 @@ version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
+[[package]]
+name = "sctk-adwaita"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6277f0217056f77f1d8f49f2950ac6c278c0d607c45f5ee99328d792ede24ec"
+dependencies = [
+ "ab_glyph",
+ "log",
+ "memmap2",
+ "smithay-client-toolkit",
+ "tiny-skia 0.11.4",
+]
+
 [[package]]
 name = "sec1"
 version = "0.7.3"
@@ -6778,6 +6899,31 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "smithay-client-toolkit"
+version = "0.19.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3457dea1f0eb631b4034d61d4d8c32074caa6cd1ab2d59f2327bd8461e2c0016"
+dependencies = [
+ "bitflags 2.11.1",
+ "calloop",
+ "calloop-wayland-source",
+ "cursor-icon",
+ "libc",
+ "log",
+ "memmap2",
+ "rustix 0.38.44",
+ "thiserror 1.0.69",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-csd-frame",
+ "wayland-cursor",
+ "wayland-protocols",
+ "wayland-protocols-wlr",
+ "wayland-scanner",
+ "xkeysym",
+]
+
 [[package]]
 name = "smol_str"
 version = "0.2.2"
@@ -6811,6 +6957,8 @@ dependencies = [
  "keyring",
  "solitaire_data",
  "solitaire_engine",
+ "tiny-skia 0.12.0",
+ "winit",
 ]
 
 [[package]]
@@ -6819,6 +6967,8 @@ version = "0.1.0"
 dependencies = [
  "ab_glyph",
  "png 0.17.16",
+ "solitaire_core",
+ "solitaire_data",
 ]
 
 [[package]]
@@ -6836,8 +6986,10 @@ version = "0.1.0"
 dependencies = [
  "async-trait",
  "axum",
+ "bevy",
  "chrono",
  "dirs",
+ "jni 0.21.1",
  "jsonwebtoken",
  "keyring-core",
  "reqwest",
@@ -6856,20 +7008,23 @@ dependencies = [
 name = "solitaire_engine"
 version = "0.1.0"
 dependencies = [
+ "arboard",
  "async-trait",
  "bevy",
  "chrono",
  "dirs",
+ "jni 0.21.1",
  "kira",
  "resvg",
  "ron",
  "serde",
+ "serde_json",
  "solitaire_core",
  "solitaire_data",
  "solitaire_sync",
  "tempfile",
  "thiserror 2.0.18",
- "tiny-skia",
+ "tiny-skia 0.12.0",
  "tokio",
  "usvg",
  "uuid",
@@ -7456,7 +7611,7 @@ dependencies = [
  "crc32fast",
  "crossbeam-channel",
  "datasketches",
- "downcast-rs",
+ "downcast-rs 2.0.2",
  "fastdivide",
  "fnv",
  "fs4",
@@ -7508,7 +7663,7 @@ version = "0.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c57166f5bcfd478f370ab8445afb4678dce44801fa5ce5c451aaf8595583c5dc"
 dependencies = [
- "downcast-rs",
+ "downcast-rs 2.0.2",
  "fastdivide",
  "itertools 0.14.0",
  "serde",
@@ -7696,6 +7851,20 @@ dependencies = [
  "time-core",
 ]
 
+[[package]]
+name = "tiny-skia"
+version = "0.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83d13394d44dae3207b52a326c0c85a8bf87f1541f23b0d143811088497b09ab"
+dependencies = [
+ "arrayref",
+ "arrayvec",
+ "bytemuck",
+ "cfg-if",
+ "log",
+ "tiny-skia-path 0.11.4",
+]
+
 [[package]]
 name = "tiny-skia"
 version = "0.12.0"
@@ -7708,7 +7877,18 @@ dependencies = [
  "cfg-if",
  "log",
  "png 0.18.1",
- "tiny-skia-path",
+ "tiny-skia-path 0.12.0",
+]
+
+[[package]]
+name = "tiny-skia-path"
+version = "0.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c9e7fc0c2e86a30b117d0462aa261b72b7a99b7ebd7deb3a14ceda95c5bdc93"
+dependencies = [
+ "arrayref",
+ "bytemuck",
+ "strict-num",
 ]
 
 [[package]]
@@ -8479,7 +8659,7 @@ dependencies = [
  "siphasher",
  "strict-num",
  "svgtypes",
- "tiny-skia-path",
+ "tiny-skia-path 0.12.0",
  "ttf-parser",
  "unicode-bidi",
  "unicode-script",
@@ -8685,6 +8865,114 @@ dependencies = [
  "semver",
 ]
 
+[[package]]
+name = "wayland-backend"
+version = "0.3.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2857dd20b54e916ec7253b3d6b4d5c4d7d4ca2c33c2e11c6c76a99bd8744755d"
+dependencies = [
+ "cc",
+ "downcast-rs 1.2.1",
+ "rustix 1.1.4",
+ "scoped-tls",
+ "smallvec",
+ "wayland-sys",
+]
+
+[[package]]
+name = "wayland-client"
+version = "0.31.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "645c7c96bb74690c3189b5c9cb4ca1627062bb23693a4fad9d8c3de958260144"
+dependencies = [
+ "bitflags 2.11.1",
+ "rustix 1.1.4",
+ "wayland-backend",
+ "wayland-scanner",
+]
+
+[[package]]
+name = "wayland-csd-frame"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "625c5029dbd43d25e6aa9615e88b829a5cad13b2819c4ae129fdbb7c31ab4c7e"
+dependencies = [
+ "bitflags 2.11.1",
+ "cursor-icon",
+ "wayland-backend",
+]
+
+[[package]]
+name = "wayland-cursor"
+version = "0.31.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4a52d18780be9b1314328a3de5f930b73d2200112e3849ca6cb11822793fb34d"
+dependencies = [
+ "rustix 1.1.4",
+ "wayland-client",
+ "xcursor",
+]
+
+[[package]]
+name = "wayland-protocols"
+version = "0.32.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "563a85523cade2429938e790815fd7319062103b9f4a2dc806e9b53b95982d8f"
+dependencies = [
+ "bitflags 2.11.1",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-scanner",
+]
+
+[[package]]
+name = "wayland-protocols-plasma"
+version = "0.3.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b6d8cf1eb2c1c31ed1f5643c88a6e53538129d4af80030c8cabd1f9fa884d91"
+dependencies = [
+ "bitflags 2.11.1",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-protocols",
+ "wayland-scanner",
+]
+
+[[package]]
+name = "wayland-protocols-wlr"
+version = "0.3.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eb04e52f7836d7c7976c78ca0250d61e33873c34156a2a1fc9474828ec268234"
+dependencies = [
+ "bitflags 2.11.1",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-protocols",
+ "wayland-scanner",
+]
+
+[[package]]
+name = "wayland-scanner"
+version = "0.31.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c324a910fd86ebdc364a3e61ec1f11737d3b1d6c273c0239ee8ff4bc0d24b4a"
+dependencies = [
+ "proc-macro2",
+ "quick-xml",
+ "quote",
+]
+
+[[package]]
+name = "wayland-sys"
+version = "0.31.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8eab23fefc9e41f8e841df4a9c707e8a8c4ed26e944ef69297184de2785e3be"
+dependencies = [
+ "dlib",
+ "log",
+ "pkg-config",
+]
+
 [[package]]
 name = "web-sys"
 version = "0.3.97"
@@ -9500,6 +9788,7 @@ version = "0.30.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a6755fa58a9f8350bd1e472d4c3fcc25f824ec358933bba33306d0b63df5978d"
 dependencies = [
+ "ahash",
  "android-activity",
  "atomic-waker",
  "bitflags 2.11.1",
@@ -9514,9 +9803,10 @@ dependencies = [
  "dpi",
  "js-sys",
  "libc",
+ "memmap2",
  "ndk",
  "objc2 0.5.2",
- "objc2-app-kit",
+ "objc2-app-kit 0.2.2",
  "objc2-foundation 0.2.2",
  "objc2-ui-kit",
  "orbclient",
@@ -9525,11 +9815,17 @@ dependencies = [
  "raw-window-handle",
  "redox_syscall 0.4.1",
  "rustix 0.38.44",
+ "sctk-adwaita",
+ "smithay-client-toolkit",
  "smol_str",
  "tracing",
  "unicode-segmentation",
  "wasm-bindgen",
  "wasm-bindgen-futures",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-protocols",
+ "wayland-protocols-plasma",
  "web-sys",
  "web-time",
  "windows-sys 0.52.0",
@@ -9697,6 +9993,12 @@ version = "0.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd"
 
+[[package]]
+name = "xcursor"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bec9e4a500ca8864c5b47b8b482a73d62e4237670e5b5f1d6b9e3cae50f28f2b"
+
 [[package]]
 name = "xkbcommon-dl"
 version = "0.4.2"

Cargo.toml

@@ -30,6 +30,8 @@ dirs        = "6"
 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" }
@@ -53,12 +55,24 @@ bevy = { version = "0.18", default-features = false, features = [
     "bevy_window",
     "custom_cursor",
     "reflect_auto_register",
-    # default_platform (desktop subset; no android/wayland/webgl/gilrs/sysinfo)
+    # default_platform (desktop subset)
     "std",
     "bevy_winit",
     "default_font",
     "multi_threaded",
+    # winit prefers Wayland when WAYLAND_DISPLAY is set on the
+    # session and falls through to X11 otherwise. Without `wayland`,
+    # winit-on-Wayland-session falls back to XWayland which renders
+    # the game in an X11 frame inside the Wayland compositor.
+    "wayland",
     "x11",
+    # Android: NativeActivity glue. The feature is target-gated inside
+    # bevy_internal — desktop builds compile it out, so leaving it on
+    # the always-on list is harmless on Linux/macOS/Windows. Pairs with
+    # cargo-apk's NativeActivity wrapper (cargo-apk 0.10+ uses this by
+    # default). Switch to `android-game-activity` later if we want
+    # AndroidX GameActivity for Google Play Games integration.
+    "android-native-activity",
     # common_api
     "bevy_color",
     "bevy_image",

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

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,107 +1,177 @@
-# Solitaire Quest — Session Handoff
+# Ferrous Solitaire — Session Handoff
 
-**Last updated:** 2026-05-06 (post-v0.16.0) — Modal-feel polish round shipped: every overlay scrolls when it overflows, every button shows a pointer cursor on hover, modal focus lands on the same frame, and read-only modals dismiss on scrim click. Direction now opens.
+**Last updated:** 2026-05-12 — Leaderboard display name shipped (`03be4fc`). All commits pushed to origin.
 
-## Status at pause
+Phase 8 closes the self-hosted-server connection arc end-to-end: login/register
+modal, re-auth on token expiry, account deletion flow, server deployment
+artifacts (Dockerfile + docker-compose), replay upload on win, web replay
+player (WASM + HTML/CSS/JS served by the server), leaderboard opt-in/out,
+and full server integration tests.
 
-- **HEAD on origin:** v0.16.0's tag commit.
-- **Working tree:** clean apart from untracked `CARD_PLAN.md` (intentional).
+---
+
+## Current state
+
+- **HEAD locally:** `03be4fc` (feat: leaderboard custom display name).
+- **HEAD on origin:** `03be4fc` (fully pushed).
+- **Working tree:** clean (only `solitaire-release.jks.bak2` untracked — intentional).
 - **Build:** `cargo clippy --workspace --all-targets -- -D warnings` clean.
-- **Tests:** **1196 passed / 0 failed** across the workspace.
-- **Tags on origin:** `v0.9.0` through `v0.16.0`.
+- **Tests:** **1300+ passing / 0 failing** across the workspace.
+- **Tags on origin:** `v0.9.0` through `v0.22.0`.
 
-## Where we are
+---
 
-v0.16.0 is the smallest meaningful release in a while — a focused round on how modals feel rather than what they contain. The originating bug was "I can't scroll on the Achievements list"; the sweep that followed found four other modals with the same problem plus three smaller modal-feel gaps (no pointer cursor on buttons, focus arriving a frame late, no click-outside-to-dismiss).
+## What shipped in Phase 8 (432061c – bd388fe)
 
-Every overlay screen now: scrolls if its content can overflow at 800×600, shows a hand cursor when you hover any button, has its primary auto-focused the moment the modal appears so the very first Tab/Enter is meaningful, and (for read-only screens) dismisses when you click outside the card.
+| Commit | Summary |
+|--------|---------|
+| `432061c` | Sync setup modal (login/register/connect/disconnect) |
+| `6ce5564` | Re-auth on expired session + server deployment artifacts |
+| `272d31f` | Account deletion flow + `handle_sync_buttons` refactor |
+| `bd388fe` | CHANGELOG v0.23.0 documentation |
 
-The post-v0.15.0 next-round candidates are still mostly open — solver-driven hints, replay-rate slider, solver progress overlay, async solver, "won previously" indicator, replay sharing. Direction is open.
+Also shipped (pre-Phase 8 but post-v0.22.0, already in CHANGELOG):
+- `solitaire_wasm` crate: WASM ReplayPlayer bindings for browser-side replay playback
+- Server replay API: `POST /api/replays`, `GET /api/replays/recent`, `GET /api/replays/:id`
+- Server web UI: `/replays/:id` HTML route + `ServeDir /web` static assets
+- DB migration 002: `replays` table + two indexes
+- Full server integration tests for replay endpoints
+- `push_replay` in `sync_plugin` (uploads on win, writes share URL into replay history)
+- Stats panel "Copy Share Link" button reads `share_url` from replay history
 
-### Design direction (unchanged)
+---
 
-- **Tone:** Balatro — chunky readable type, theatrical hierarchy, satisfying micro-interactions.
-- **Palette:** Midnight Purple base + Balatro yellow primary + warm magenta secondary.
-- See `~/.claude/projects/-home-manage-Rusty-Solitare/memory/project_ux_overhaul_2026-04.md` (machine-local).
+## Open punch list (ordered by priority)
 
-### Canonical remote
+### 1. Documentation debt (no code)
+- [x] CHANGELOG [Unreleased] → v0.23.0 — done this session
+- [x] ARCHITECTURE.md update — all 8 gaps closed, bumped to v1.3
+- [x] SESSION_HANDOFF.md update — this file
 
-`github.com/funman300/Rusty_Solitaire` is the canonical repo. Always push there.
+### 2. Leaderboard wiring gaps
+- [x] **Best-score auto-post.** Done (`303c78a`): `update_leaderboard_if_opted_in`
+  called from both first-push and merge paths in `sync.rs`; uses SQLite `MIN`/`MAX`
+  in the UPDATE so scores never regress on stale data.
+- [x] **Display name = username.** Done (`03be4fc`): `leaderboard_display_name:
+  Option<String>` added to `Settings`; editor modal in leaderboard panel; persists
+  to `settings.json`; `handle_opt_in_button` prefers custom name over username.
 
-## v0.16.0 (shipped 2026-05-06)
+### 3. Security hardening
+- [x] **Refresh token rotation.** Done (`b129664`): `refresh_tokens` table
+  (migration 003); jti embedded in JWT; rotate-on-use pattern; 3 integration
+  tests.
+- [x] **Sync endpoint rate limiting.** Done (`6e6f3ef`): `UserIdKeyExtractor`
+  decodes JWT for per-user identity; falls back to IP; burst 10 / 6 min
+  steady-state; integration test passes.
 
-| Area | Commit | What landed |
-|---|---|---|
-| Modal scroll | `7a3032b` | Achievements / Help / Stats / Profile / Leaderboard bodies now carry `Overflow::scroll_y()` + a `max_height` constraint + a per-plugin `*Scrollable` marker. Sibling `scroll_*_panel` systems route `MouseWheel` into the body's `ScrollPosition`. Mirrors the existing `SettingsPanelScrollable` pattern. Home modal not scrolled — five mode cards + Cancel are sized to fit by design. |
-| Pointer cursor | `cd54ce1` | `update_cursor_icon` gains a fourth branch: `SystemCursorIcon::Pointer` whenever any `Interaction::Hovered`/`Pressed` button is detected and no card drag is active. Branch order Grabbing → Pointer → Grab → Default. Pure `pick_cursor_icon(is_dragging, any_button_hovered, any_card_hovered)` helper unit-tests the priority. |
-| Same-frame focus | `48e4121` | `attach_focusable_to_modal_buttons` and `auto_focus_on_modal_open` moved from `Update` to `PostUpdate`. The schedule boundary supplies the sync point so a click-handler in `Update` that spawns a modal has its `Commands` materialised before attach runs. `FocusedButton` is populated before `app.update()` returns; the very first Tab/Enter after open lands on a populated resource. |
-| Scrim dismiss core | `a54201e` | New `ScrimDismissible` marker on `ModalScrim` opts a modal into click-outside-to-close. `dismiss_modal_on_scrim_click` system in `ui_modal` despawns the topmost dismissible scrim on a left-mouse press whose cursor lands on the scrim and outside every `ModalCard`. Stats / Achievements / Help opted in. |
-| Scrim dismiss tail | `cbf2483` | One-line opt-in (capture scrim + insert marker) for Profile / Leaderboard / Home, completing all six read-only modals. |
+### 4. Android validation
+- [x] **Android Keystore functional test.** Done (2026-05-11, Pixel 7 AVD,
+  Android 14): `load_access_token()` exercised via `start_pull`; logcat confirmed
+  `NotFound` returned cleanly — no JNI panic. See `docs/android/PLAYABILITY_TODO.md` P4.
+- [x] **JNI clipboard functional test.** Done (2026-05-11): temporary `KEYCODE_C`
+  hook confirmed `ClipboardManager.setPrimaryClip()` succeeds on Android 14.
+  Hook reverted. Production path requires Interaction::Pressed + non-null `share_url`.
+  Note: `adb shell input tap` doesn't deliver touch events on headless AVD (documented).
+- [x] **`cargo apk build --lib` noisy stderr** — upstream cargo-apk bug; `--lib`
+  is the canonical command (CLAUDE.md §15.1, docs/ANDROID.md). No in-repo fix possible.
 
-## Open punch list
+### 5. Feature completeness
+- [x] **Theme importer UI.** Done (`613bbf8`): "Scan for new themes" button in
+  Settings Appearance section. Shows import path label, scans user_theme_dir()
+  for .zip archives, fires InfoToastEvent per file, refreshes ThemeRegistry.
+- [x] **`mirror_achievement` removed.** Done (`549a817`): method was a no-op
+  default never overridden and never called; achievements already sync via
+  `SyncPayload` push. Deleted from trait and blanket impl.
+- [x] **WASM build script.** Done (`40d0712`): `build_wasm.sh` at repo root
+  documents `wasm-pack build --target web`, cleans up pkg metadata files,
+  includes dependency guard + install instructions.
+- [x] **Server password reset.** Done (`7514684`): `--reset-password <username>`
+  subcommand reads new password from stdin, bcrypt-hashes it, invalidates all
+  active sessions for the user.
 
-### Release prep
+### 5b. Android UX polish (2026-05-12)
 
-1. **Smoke-test on a real game**: confirm scroll feels right on Achievements (the original bug), pointer cursor changes on every interactive surface, the very first Tab in a modal already activates the primary, and clicking the dimmed area dismisses the read-only modals while NOT dismissing Settings/Pause.
-2. **Desktop packaging** per `ARCHITECTURE.md §17`. Arch PKGBUILD exists in `/home/manage/solitaire-quest-pkgbuild/` (separate repo). Pending: app icon, macOS `.icns` + notarisation cert, Windows `.ico` + Authenticode cert, AppImage recipe.
+- [x] **UX-1 — Modal Done button in gesture zone.** `apply_safe_area_to_modal_scrims` system
+  added to `SafeAreaInsetsPlugin` (`safe_area.rs`). Pads every `ModalScrim` bottom by
+  `insets.bottom / scale`. Fires on resource change + `Added<ModalScrim>`. Verified on device.
+- [x] **UX-5b — Home mode glyph corruption.** Geometric Shapes (U+25xx, absent from FiraMono)
+  replaced with card suits U+2660–2666 in `home_plugin.rs`. Affects Zen/Challenge/Daily mode
+  selector buttons at level 5+.
+- [x] **UX-7 — Help text wrap.** Android HUD entry shortened to
+  `"Open menu (Stats, Settings, Profile...)"` in `help_plugin.rs` — fits one line.
+- [x] **BUG-3 — Multi-modal stacking.** `handle_menu_button` now checks
+  `scrims: Query<(), With<ModalScrim>>` and guards `spawn_menu_popover` with `scrims.is_empty()`.
+  Verified on device: ≡ tap while Stats open does nothing.
 
-### Carryover from v0.15.0 next-round candidates
+  **Note:** These 4 fixes are implemented and verified but not yet committed.
 
-Still open — would each be ~50–200 LOC:
+### 6. Testing gaps
+- [x] **Server 401 → refresh → retry path.** Done (`198df75`): both
+  `jwt_refresh_on_401_succeeds` (pull) and
+  `push_retries_after_401_on_expired_access_token` (push) in
+  `solitaire_data/tests/sync_round_trip.rs`.
+- [x] **WASM winning-replay step-through.** Done (`b4ada2a`): greedy solver
+  searches seeds 1–200 at test time; steps every move through `ReplayPlayer`;
+  asserts `is_won = true` on the final `StateSnapshot`.
 
-- **Solver-driven hints** — the existing hint system uses a heuristic; promote it to ask `try_solve` for the actual best move. Now that the solver is in place this is mostly plumbing.
-- **Replay-playback rate slider** — the 0.45 s/move pace is hardcoded; a Settings slider in the same row as tooltip-delay / time-bonus would let power users speed up older replays.
-- **Solver progress overlay** — when "Winnable deals only" is on, a brief "checking deal…" toast surfaces after ~500 ms so the player isn't confused by the rare worst-case stall.
-- **Solver-on-AsyncComputeTaskPool** — current solver runs synchronously on the main thread. Worst-case 50 attempts × 120 ms = 6 s of UI stall on pathological seeds. Async + cancel button would be safer.
-- **Per-deal "won previously" indicator** — the rolling replay history's seeds make this easy: when a new game starts on a seed the player has already won, surface a tiny indicator on the HUD.
-- **Replay sharing** — `replays.json` is per-machine. Allow a player to copy a replay's URL (already wired via `solitaire_server`) and post it elsewhere. The web-viewer already exists.
+---
+
+## ARCHITECTURE.md gaps (for the update pass)
+
+Items missing from the doc:
+1. `solitaire_wasm` crate (§2 workspace + §3 responsibilities)
+2. Replay API endpoints (§9 API Reference — 3 new routes)
+3. Web replay player route (`/replays/:id` + `ServeDir /web`)
+4. `SyncProvider` trait: 6 added methods
+5. Theme system in Bevy plugin table (§5)
+6. `Settings` new fields: `color_blind_mode`, `high_contrast_mode`,
+   `reduce_motion_mode`, `window_geometry`, `selected_card_back`,
+   `selected_background`
+7. DB migration 002 (§7)
+8. Update "Last Updated" date
+
+---
+
+## Process notes
+
+- **Commit attribution:** use `funman300` as git user. Co-author line:
+  `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
+- **Commit format:** `type(scope): description` per CLAUDE.md §7.
+- **Never commit without:** `cargo test --workspace` passing + clippy clean.
+- **Sub-agents** stage/verify only; orchestrator commits.
+- **`CARD_PLAN.md`** referenced in `theme/` module comments but not present in
+  repo. Clean up references or commit the file.
+- **Token-port pattern** (v0.20.0): when migrating tokens, walk every concrete
+  artifact downstream — PNGs, SVGs, literals, comments. Three "walked past this"
+  follow-ups in v0.21.0 all had this shape.
+
+---
 
 ## Resume prompt
 
 ```
-You are a senior Rust + Bevy developer working on Solitaire Quest.
-Working directory: <Rusty_Solitaire clone path on this machine — local
-directory may still be named Rusty_Solitare from earlier; that's fine>.
-Branch: master. Direction is OPEN — v0.16.0 just shipped covering
-modal scroll fixes, pointer cursor, same-frame focus, and scrim-click
-dismiss across all six read-only modals.
+You are a senior Rust + Bevy developer working on Ferrous Solitaire.
+Working directory: <Rusty_Solitaire clone path>.
+Branch: master. v0.23.0 is the current version (HEAD: 03be4fc). Fully pushed.
 
-State: HEAD at v0.16.0. Working tree clean apart from untracked
-CARD_PLAN.md (intentional).
-Build: cargo clippy --workspace --all-targets -- -D warnings clean.
-Tests: 1196 passed / 0 failed.
+READ FIRST (in order):
+  1. SESSION_HANDOFF.md  — this file
+  2. CHANGELOG.md        — [0.23.0] section has full Phase 8 detail
+  3. CLAUDE.md           — unified-4.0 rule set
+  4. ARCHITECTURE.md     — v1.3, fully up to date
+  5. docs/ui-mockups/    — design system + mockup library
+  6. docs/android/       — Android setup + build runbook
+  7. ~/.claude/projects/<this-project>/memory/MEMORY.md
 
-READ FIRST (in order, before doing anything):
-  1. SESSION_HANDOFF.md  — v0.16.0 changelog + open punch list
-  2. CHANGELOG.md        — release-by-release record
-  3. CLAUDE.md           — hard rules (UI-first, no panics, etc.)
-  4. ARCHITECTURE.md     — crate responsibilities + data flow
-  5. ~/.claude/projects/<this-project>/memory/MEMORY.md
-                         — saved feedback / project context (machine-local;
-                           may be missing on a fresh machine)
+OPEN WORK:
+  Phase 8 punch list is fully closed. All items verified complete.
+  Remaining nuisance: `cargo apk build --lib` noisy stderr (cosmetic, non-blocking).
 
-DECISION TO ASK THE PLAYER FIRST:
-  A. Smoke-test v0.16.0. Scroll on Achievements, pointer cursor on
-     buttons, first Tab in a modal activates rather than advances,
-     scrim click dismisses Stats/Achievements/Help/Profile/
-     Leaderboard/Home but NOT Settings/Pause/etc.
-  B. Solver-driven hints — replace heuristic with try_solve's
-     best-move suggestion. ~100 LOC.
-  C. Solver-on-AsyncComputeTaskPool with progress toast + cancel.
-     Eliminates the worst-case 6 s stall.
-  D. Pick from the remaining "next-round candidates" in this doc.
-  E. Take the deferred desktop-packaging item (needs artwork +
-     signing certs from the user).
+  4 Android UX fixes are implemented and verified but NOT YET COMMITTED:
+    - BUG-3 (hud_plugin.rs): multi-modal stacking guard
+    - UX-7 (help_plugin.rs): help text wrap on Android
+    - UX-5b (home_plugin.rs): FiraMono glyph corruption in mode selector
+    - UX-1 (safe_area.rs): modal Done button in gesture zone
 
-WORKFLOW NOTES:
-  - Commits use:
-      git -c user.name=funman300 -c user.email=root@vscode.infinity \
-          commit -m "..."
-  - 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) — that is the canonical remote.
-
-OPEN AT THE START: ask which of A–E. Don't pick unilaterally.
+  Commit those first, then suggest Phase 9 planning.
 ```

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/Rusty_Solitare.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

build_wasm.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Rebuild the solitaire_wasm crate and install the output into
+# solitaire_server/web/pkg/ so the server can serve the replay viewer.
+#
+# Prerequisites:
+#   cargo install wasm-pack
+#   rustup target add wasm32-unknown-unknown
+#
+# Run from the repo root:
+#   ./build_wasm.sh
+#
+# The generated files (solitaire_wasm.js + solitaire_wasm_bg.wasm) are
+# committed to git so self-hosters who don't touch the WASM crate can
+# skip this step.  Regenerate after any change to solitaire_wasm/ or
+# solitaire_core/.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUT_DIR="$REPO_ROOT/solitaire_server/web/pkg"
+
+if ! command -v wasm-pack &> /dev/null; then
+    echo "error: wasm-pack not found." >&2
+    echo "  Install with: cargo install wasm-pack" >&2
+    exit 1
+fi
+
+echo "Building solitaire_wasm (target: web)..."
+wasm-pack build \
+    --target web \
+    --out-dir "$OUT_DIR" \
+    --no-typescript \
+    "$REPO_ROOT/solitaire_wasm"
+
+# wasm-pack writes a package.json and .gitignore into the output dir.
+# Remove them — we manage the output directory ourselves.
+rm -f "$OUT_DIR/package.json" "$OUT_DIR/.gitignore"
+
+echo "Done. Output:"
+ls -lh "$OUT_DIR"

deploy/deployment.yaml

@@ -0,0 +1,62 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: solitaire-server
+  namespace: solitaire
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: solitaire-server
+  # SQLite is single-writer; Recreate avoids two pods owning the PVC at once.
+  strategy:
+    type: Recreate
+  template:
+    metadata:
+      labels:
+        app: solitaire-server
+    spec:
+      imagePullSecrets:
+        - name: gitea-registry
+      containers:
+        - name: server
+          image: solitaire-server
+          imagePullPolicy: Always
+          ports:
+            - containerPort: 8080
+          env:
+            - name: DATABASE_URL
+              value: sqlite:///data/sol.db
+            - name: JWT_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: solitaire-secrets
+                  key: jwt-secret
+            - name: SERVER_PORT
+              value: "8080"
+          volumeMounts:
+            - name: db-data
+              mountPath: /data
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: 8080
+            initialDelaySeconds: 5
+            periodSeconds: 30
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: 8080
+            initialDelaySeconds: 3
+            periodSeconds: 10
+          resources:
+            requests:
+              cpu: 50m
+              memory: 64Mi
+            limits:
+              cpu: 500m
+              memory: 256Mi
+      volumes:
+        - name: db-data
+          persistentVolumeClaim:
+            claimName: solitaire-db