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>
fix(ci): restore 3-ABI release build now that LXC has 106 GB disk
2026-05-14 15:12:25 -07:00 · 2026-05-14 14:04:09 -07:00 · 2026-05-14 21:00:48 +00:00 · 2026-05-14 13:53:48 -07:00 · 2026-05-14 13:47:43 -07:00 · 2026-05-14 20:20:49 +00:00
241 changed files with 10719 additions and 1605 deletions
@@ -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
@@ -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"
@@ -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
@@ -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@v5
      - 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@v5
        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@v5
      - 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@v5
        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
@@ -1,174 +0,0 @@
 name: Release
 # Triggered by pushing a version tag, e.g. `git tag v0.22.0 && git push origin v0.22.0`.
 # Builds a Linux x86_64 tarball and a signed Android APK, then publishes
 # both as assets on a GitHub Release. Obtainium can track this repo's
 # releases and download the APK automatically.
 #
 # Required repository secrets (Settings → Secrets and variables → Actions):
 #   ANDROID_KEYSTORE_BASE64      base64-encoded .jks file (see README for gen command)
 #   ANDROID_KEYSTORE_PASSWORD    password used with -storepass when creating the keystore
 #   ANDROID_KEY_ALIAS            alias used with -alias when creating the keystore
 #   ANDROID_KEY_PASSWORD         password used with -keypass when creating the keystore
 on:
  push:
    tags:
      - 'v*'
 permissions:
  contents: write   # gh release create needs write access
 env:
  CARGO_TERM_COLOR: always
  RUSTFLAGS: "-D warnings"
 # ---------------------------------------------------------------------------
 # Job 1: Linux x86_64 binary + assets tarball
 # ---------------------------------------------------------------------------
 jobs:
  build-linux:
    name: Build · Linux x86_64
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Install Rust stable
        uses: dtolnay/rust-toolchain@stable
      - name: Install system deps
        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 + build artifacts
        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: linux-release-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: linux-release-
      - name: Build release binary
        run: cargo build --release -p solitaire_app
      - name: Package tarball
        run: |
          mkdir solitaire-quest
          cp target/release/solitaire_app solitaire-quest/
          cp -r assets solitaire-quest/
          tar -czf solitaire-quest-linux-x86_64.tar.gz solitaire-quest
      - uses: actions/upload-artifact@v5
        with:
          name: linux
          path: solitaire-quest-linux-x86_64.tar.gz
 # ---------------------------------------------------------------------------
 # Job 2: Android APK (multi-arch) — release-built and signed via cargo-apk
 # ---------------------------------------------------------------------------
  build-android:
    name: Build · Android APK
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Install Rust stable + Android targets
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: aarch64-linux-android,armv7-linux-androideabi,x86_64-linux-android
      - name: Expose NDK root to cargo-apk
        # ANDROID_NDK_LATEST_HOME is set by the GitHub-hosted runner.
        # cargo-apk reads ANDROID_NDK_ROOT; write it to GITHUB_ENV so
        # all subsequent steps in this job inherit it.
        run: echo "ANDROID_NDK_ROOT=$ANDROID_NDK_LATEST_HOME" >> $GITHUB_ENV
      - name: Cache cargo registry + cargo-apk binary + build artifacts
        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            ~/.cargo/bin
            target
          key: android-release-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: android-release-
      - name: Install cargo-apk
        # --locked: use the dependency versions cargo-apk was tested with.
        # cargo install is a no-op when the cached binary is already current.
        run: cargo install --locked cargo-apk
      - name: Inject release signing config
        # cargo-apk --release requires [package.metadata.android.signing.release]
        # in solitaire_app/Cargo.toml. Appended at CI time so secrets never
        # live in the repo. printf keeps every line inside the YAML run block,
        # avoiding the YAML parse error a heredoc with column-0 content causes.
        env:
          ANDROID_KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
          ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
          ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
          ANDROID_KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
        run: |
          echo "$ANDROID_KEYSTORE_BASE64" | base64 -d > release.keystore
          {
            printf '\n[package.metadata.android.signing.release]\n'
            printf 'path = "%s"\n'             "${GITHUB_WORKSPACE}/release.keystore"
            printf 'keystore_password = "%s"\n' "$ANDROID_KEYSTORE_PASSWORD"
            printf 'key_alias = "%s"\n'        "$ANDROID_KEY_ALIAS"
            printf 'key_password = "%s"\n'     "$ANDROID_KEY_PASSWORD"
          } >> solitaire_app/Cargo.toml
      - name: Build and sign APK (release profile)
        # `--lib` scopes cargo-apk to the cdylib target only.
        # Without it, cargo-apk panics post-sign with
        # "Bin is not compatible with Cdylib" (cargo-subcommand
        # artifact iteration walks the bin target after the
        # cdylib APK is already produced). See SESSION_HANDOFF.md
        # "Cosmetic cargo apk build --lib workaround."
        run: cargo apk build -p solitaire_app --lib --release
      - name: Stage APK for upload
        run: |
          cp target/release/apk/solitaire-quest.apk \
             "solitaire-quest-${{ github.ref_name }}.apk"
          rm release.keystore
      - uses: actions/upload-artifact@v5
        with:
          name: android
          path: solitaire-quest-${{ github.ref_name }}.apk
 # ---------------------------------------------------------------------------
 # Job 3: Create the GitHub Release once both builds succeed
 # ---------------------------------------------------------------------------
  release:
    name: Publish GitHub Release
    runs-on: ubuntu-latest
    needs: [build-linux, build-android]
    steps:
      - uses: actions/download-artifact@v5
        with:
          name: linux
      - uses: actions/download-artifact@v5
        with:
          name: android
      - name: Create GitHub Release
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh release create "${{ github.ref_name }}" \
            --repo "${{ github.repository }}" \
            --title "Solitaire Quest ${{ github.ref_name }}" \
            --generate-notes \
            "solitaire-quest-linux-x86_64.tar.gz" \
            "solitaire-quest-${{ github.ref_name }}.apk"
@@ -14,4 +14,10 @@ data/
 # 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
@@ -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"
 }
@@ -0,0 +1,12 @@
 {
  "db_name": "SQLite",
  "query": "DELETE FROM refresh_tokens WHERE jti = ?",
  "describe": {
    "columns": [],
    "parameters": {
      "Right": 1
    },
    "nullable": []
  },
  "hash": "168e205e3eb832b78d085b48281a1bae74d5a0e64c4c793c18a6400605bacf76"
 }
@@ -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"
 }
@@ -0,0 +1,12 @@
 {
  "db_name": "SQLite",
  "query": "DELETE FROM refresh_tokens WHERE user_id = ?",
  "describe": {
    "columns": [],
    "parameters": {
      "Right": 1
    },
    "nullable": []
  },
  "hash": "40db0910531d4418d4d58d31f0f8ea3894248406cc016020a6e211ed66da91c0"
 }
@@ -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"
 }
@@ -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"
 }
@@ -0,0 +1,12 @@
 {
  "db_name": "SQLite",
  "query": "UPDATE users SET password_hash = ? WHERE id = ?",
  "describe": {
    "columns": [],
    "parameters": {
      "Right": 2
    },
    "nullable": []
  },
  "hash": "e4eb622073cbdf868ec1568a6bdb132e962480b0530d542102c05aa9e901463b"
 }
@@ -0,0 +1,12 @@
 {
  "db_name": "SQLite",
  "query": "DELETE FROM refresh_tokens WHERE expires_at < ?",
  "describe": {
    "columns": [],
    "parameters": {
      "Right": 1
    },
    "nullable": []
  },
  "hash": "ef7af925a8715c329dcafca5257c691e6bca31755eb5f54be47114f21fc04c8c"
 }
@@ -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"
 }
@@ -1,9 +1,9 @@
-# Solitaire Quest — Architecture Document
+# Ferrous Solitaire — Architecture Document
-> **Version:** 1.1  
+> **Version:** 1.3  
 > **Language:** Rust (Edition 2024)  
 > **Engine:** Bevy (latest stable)  
-> **Last Updated:** 2026-04-29
+> **Last Updated:** 2026-05-12
 ---
@@ -34,7 +34,7 @@
 ## 1. Project Overview
-Solitaire Quest is a cross-platform Klondike Solitaire game written in Rust, targeting macOS, Windows, and Linux desktops. It features a full progression system with XP, levels, achievements, daily challenges, and an optional self-hosted sync server so statistics and progress are available across all of a player's devices.
+Ferrous Solitaire is a cross-platform Klondike Solitaire game written in Rust, targeting macOS, Windows, and Linux desktops. It features a full progression system with XP, levels, achievements, daily challenges, and an optional self-hosted sync server so statistics and progress are available across all of a player's devices.
 ### Sync Backend by Platform
@@ -43,6 +43,7 @@ Solitaire Quest is a cross-platform Klondike Solitaire game written in Rust, tar
 | macOS | Self-hosted server | Full feature set |
 | Windows | Self-hosted server | Full feature set |
 | Linux | Self-hosted server | Full feature set |
 | Android | Self-hosted server | Touch input; safe-area insets via JNI; `cargo-apk` build |
 ### Design Principles
@@ -86,6 +87,7 @@ solitaire_quest/
 ├── solitaire_data/             # Persistence, sync client, settings
 ├── solitaire_engine/           # Bevy ECS systems, components, plugins
 ├── solitaire_server/           # Self-hosted sync server (Axum + SQLite)
 ├── solitaire_wasm/             # WebAssembly bindings — browser-side replay player
 └── solitaire_app/              # Main binary entry point
 ```
@@ -160,6 +162,20 @@ Owns:
 - Daily challenge seed generation
 - Leaderboard management
 ### `solitaire_wasm`
 **Dependencies:** `solitaire_core`, `serde`, `serde_json`, `chrono`, `wasm-bindgen`, `serde-wasm-bindgen`.
 WebAssembly bindings for browser-side replay playback. Compiled to `cdylib` via `wasm-pack build`; the output lives in `solitaire_server/web/pkg/` and is served statically by the server.
 Intentionally **does not** depend on `solitaire_data` (which pulls in `dirs`, `keyring`, `reqwest`, and other non-WASM crates). Instead it defines a minimal `Replay` mirror with the same serde shape as `solitaire_data::Replay` — the JSON wire format is the compatibility contract.
 Owns:
 - `ReplayPlayer` — WASM-exported state machine; steps through a replay's `Vec<ReplayMove>` against a live `GameState`
 - `StateSnapshot` — JS-facing pile snapshot returned by each `step()` call
 - `ReplayMove` / `Replay` mirrors — same serde shape as `solitaire_data` v2 equivalents
 Because `ReplayPlayer` uses the same `solitaire_core::GameState` as the desktop client, the two implementations cannot drift: the same seed + move list produces identical pile state at every step on both platforms.
 ### `solitaire_app`
 **Dependencies:** `bevy`, `solitaire_engine`.
@@ -261,6 +277,8 @@ The "Shortcut" column lists optional keyboard accelerators. Every action in this
 | `HomePlugin` | M | Main-menu overlay with keyboard shortcut reference |
 | `ProfilePlugin` | P | Player profile overlay: level, XP, achievements, sync status |
 | `SettingsPlugin` | O | Settings panel: audio, draw mode, theme, sync, cosmetics |
 | `ThemePlugin` | — | Owns `ActiveTheme` resource; registers the `CardTheme` SVG asset loader; rasterises themes once per (theme, target size) at load time and caches the resulting `Image`; handles the embedded default theme and user themes from `user_theme_dir()` |
 | `SyncSetupPlugin` | — | Sync setup modal (URL / username / password fields, "Log In" / "Register" buttons); account deletion confirm modal; re-auth trigger when `SyncError::Auth` is returned by a pull |
 | `LeaderboardPlugin` | L | Leaderboard overlay |
 | `HelpPlugin` | H | Help / controls overlay |
 | `PausePlugin` | Esc | Pause and resume |
@@ -305,6 +323,12 @@ struct FontResource(Handle<Font>);
 struct BackgroundImageSet {
    handles: Vec<Handle<Image>>,    // indices 0–4 match selected_background setting
 }
 // OS-reserved edge insets (physical px); zero on desktop
 struct SafeAreaInsets { top: f32, bottom: f32, left: f32, right: f32 }
 // Whether the HUD band is visible (auto-hide chrome feature)
 enum HudVisibility { Visible, Hidden }
 ```
 ### Key Bevy Events
@@ -365,10 +389,22 @@ All sync backends implement a single trait in `solitaire_data`. The `SyncPlugin`
 ```rust
 #[async_trait]
 pub trait SyncProvider: Send + Sync {
    // Required — must be implemented by every backend:
    async fn pull(&self) -> Result<SyncPayload, SyncError>;
    async fn push(&self, payload: &SyncPayload) -> Result<SyncResponse, SyncError>;
    fn backend_name(&self) -> &'static str;
    fn is_authenticated(&self) -> bool;
    // Optional — all have default no-op / empty implementations:
    async fn mirror_achievement(&self, _id: &str) -> Result<(), SyncError>;
    async fn fetch_leaderboard(&self) -> Result<Vec<LeaderboardEntry>, SyncError>;
    async fn fetch_daily_challenge(&self) -> Result<Option<ChallengeGoal>, SyncError>;
    async fn opt_in_leaderboard(&self, _display_name: &str) -> Result<(), SyncError>;
    async fn opt_out_leaderboard(&self) -> Result<(), SyncError>;
    async fn delete_account(&self) -> Result<(), SyncError>;
    // Returns the shareable web URL on success; defaults to Err(UnsupportedPlatform)
    // so LocalOnlyProvider silently no-ops the push-on-win path.
    async fn push_replay(&self, _replay: &Replay) -> Result<String, SyncError>;
 }
 ```
@@ -454,6 +490,24 @@ CREATE TABLE leaderboard (
    recorded_at     TEXT NOT NULL,
    PRIMARY KEY (user_id)
 );
 -- migrations/002_replays.sql
 CREATE TABLE IF NOT EXISTS replays (
    id              TEXT PRIMARY KEY,                      -- UUID v4 minted server-side
    user_id         TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    seed            INTEGER NOT NULL,
    draw_mode       TEXT NOT NULL,                          -- "DrawOne" | "DrawThree"
    mode            TEXT NOT NULL,                          -- "Classic" | "Zen" | "Challenge" | "TimeAttack"
    time_seconds    INTEGER NOT NULL,
    final_score     INTEGER NOT NULL,
    recorded_at     TEXT NOT NULL,                          -- replay-side date (YYYY-MM-DD)
    received_at     TEXT NOT NULL,                          -- server insert timestamp (ISO 8601)
    replay_json     TEXT NOT NULL                           -- full Replay serialisation
 );
 CREATE INDEX IF NOT EXISTS replays_received_at_idx ON replays(received_at DESC);
 CREATE INDEX IF NOT EXISTS replays_user_id_idx     ON replays(user_id);
 ```
 ### Request Lifecycle
@@ -584,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,
 }
 ```
@@ -600,7 +667,7 @@ All endpoints are under the base URL configured by the user (e.g., `https://soli
 |---|---|---|---|---|
 | POST | `/api/auth/register` | None | `{username, password}` | `{access_token, refresh_token}` |
 | POST | `/api/auth/login` | None | `{username, password}` | `{access_token, refresh_token}` |
-| POST | `/api/auth/refresh` | None | `{refresh_token}` | `{access_token}` |
+| POST | `/api/auth/refresh` | None | `{refresh_token}` | `{access_token, refresh_token}` (rotated) |
 ### Sync
@@ -617,6 +684,21 @@ All endpoints are under the base URL configured by the user (e.g., `https://soli
 | GET | `/api/leaderboard` | Bearer JWT | — | `Vec<LeaderboardEntry>` |
 | POST | `/api/leaderboard/opt-in` | Bearer JWT | — | `{ok: true}` |
 ### Replays
 | Method | Path | Auth | Body | Response |
 |---|---|---|---|---|
 | POST | `/api/replays` | Bearer JWT | Replay JSON | `{id, share_url}` |
 | GET | `/api/replays/recent` | None | — (`?limit=N`) | `Vec<ReplaySummary>` |
 | GET | `/api/replays/:id` | None | — | Full Replay JSON |
 ### Web Replay Player
 | Method | Path | Auth | Notes |
 |---|---|---|---|
 | GET | `/replays/:id` | None | Serves `web/index.html`; JS fetches `/api/replays/:id` and steps through via the `solitaire_wasm` WASM module |
 | GET | `/web/*` | None | Static assets served via `ServeDir` from `solitaire_server/web/` (includes `web/pkg/` with wasm-bindgen output) |
 ### Account Management
 | Method | Path | Auth | Body | Response |
@@ -825,7 +907,7 @@ All sound effect WAV files are embedded at compile time via `include_bytes!()` i
 | macOS | Primary | Self-hosted server | x86_64 + Apple Silicon (universal binary via `cargo-lipo`) |
 | Windows | Primary | Self-hosted server | x86_64, MSVC toolchain |
 | Linux | Primary | Self-hosted server | x86_64, tested on Ubuntu 22.04+ and Fedora 39+ |
-| Android | Stretch | Self-hosted server | `cargo-mobile2`, touch input |
+| Android | Active | Self-hosted server | `cargo-apk`; touch + long-press + double-tap; safe-area JNI; portrait layout |
 | iOS | Stretch | Self-hosted server | `cargo-mobile2`, touch input |
 Minimum Bevy window size enforced: 800×600. Desktop windows are freely resizable; layout recomputes on `WindowResized`.
@@ -945,6 +1027,7 @@ Migrations run automatically on startup via `sqlx::migrate!()`.
 | Password storage | bcrypt, cost factor 12 — never stored in plaintext |
 | Token security | JWTs signed with HS256, stored in OS keychain via `keyring` crate |
 | Token expiry | Access: 24h, Refresh: 30d |
 | Refresh token rotation | Each `/api/auth/refresh` call consumes the incoming refresh token (deletes its jti row) and issues a new one. Reuse of a consumed token returns 401. Expired rows are pruned inline. |
 | Brute force | `tower-governor`: 10 req/min per IP on `/api/auth/*` |
 | Payload abuse | 1MB max request body, enforced by Axum middleware |
 | Data deletion | `DELETE /api/account` removes all rows via `ON DELETE CASCADE` |
@@ -1,11 +1,115 @@
 # Changelog
-All notable changes to Solitaire Quest are documented here. The format is
+All notable changes to Ferrous Solitaire are documented here. The format is
 based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this
 project follows [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 ### Fixed
 - **BUG-3: Multi-modal stacking** (`hud_plugin.rs`). `handle_menu_button`
  now checks `scrims.is_empty()` — a `Query<(), With<ModalScrim>>` guard —
  before calling `spawn_menu_popover`. Tapping ≡ while any modal (Stats,
  Settings, Profile, Help) is open is now a no-op. Previously Stats + Profile
  could be open simultaneously.
 - **UX-7: Help text single-line overflow** (`help_plugin.rs`). The HUD menu
  button description "Menu: Stats, Settings, Profile, Achievements" wrapped to
  two lines on Android. Shortened to "Open menu (Stats, Settings, Profile...)"
  which fits on one line. Verified on device.
 - **UX-5b: Home mode glyph corruption** (`home_plugin.rs`). Mode selector icons
  were using Geometric Shapes block (U+25xx) absent from the bundled FiraMono
  font — rendered as missing-glyph rectangles on Android. Replaced with card
  suits (U+2660–2666) which FiraMono covers: ♦ Daily, ♥ Zen, ♠ Challenge.
 - **UX-1: Modal Done button in gesture zone** (`safe_area.rs`). New
  `apply_safe_area_to_modal_scrims` Bevy system pads every `ModalScrim` bottom
  by `SafeAreaInsets.bottom / scale_factor`. Modal cards are now centred over
  the safe area, not the full physical screen. The Settings / Help / Stats Done
  buttons are reachable on gesture-nav Android devices. Verified on device.
 ---
 ## [0.23.0] — 2026-05-12
 Phase 8 sync UI: the self-hosted-server connection flow is now fully
 playable end-to-end. Players can open a Connect modal from Settings,
 enter a server URL + credentials, log in or register, and see the
 sync-status section update live. Token expiry auto-reopens the modal.
 Account deletion ships a two-click destroy flow. Server deployment
 artifacts (Dockerfile + docker-compose) let self-hosters spin up in one
 command.
 ### Added
 - **Sync setup modal — Connect / Disconnect flow** (`432061c`).
  New `SyncSetupPlugin` (`solitaire_engine/src/sync_setup_plugin.rs`)
  provides the full server-connection UI. Three tab-stopped text fields
  (URL, Username, Password) handle keyboard input via `MessageReader<KeyboardInput>`
  with focus cycling on Tab. "Log In" and "Register" buttons each spawn an
  async `AsyncComputeTaskPool` task that calls the new
  `SolitaireServerClient::login()` / `::register()` methods; `poll_auth_task`
  harvests the result, stores tokens via `store_tokens()`, hot-swaps
  `SyncProviderResource` to the new server backend, fires
  `ManualSyncRequestEvent` to pull immediately, and closes the modal.
  An inline `SyncAuthError` label displays credential errors without a
  toast. The modal is idempotent (`existing.is_empty()` guard) — safe
  to open programmatically.
 - **`SyncConfigureRequestEvent`, `SyncLogoutRequestEvent`,
  `DeleteAccountRequestEvent`** (`432061c`). Three new engine events
  wire the Settings buttons → plugin handlers. `SyncConfigureRequestEvent`
  opens the setup modal; `SyncLogoutRequestEvent` disconnects and resets
  `SyncProviderResource` to `LocalOnlyProvider`; `DeleteAccountRequestEvent`
  opens the deletion confirmation modal.
 - **Settings sync section — dynamic backend UI** (`432061c`).
  `sync_row()` in `SettingsPlugin` now takes `backend: &SyncBackend` and
  renders conditionally: `Local` → "Connect" button; `SolitaireServer` →
  username label + "Sync Now" + "Disconnect" + "Delete Account". Three new
  `SettingsButton` discriminants (`ConnectSync` tab 91, `DisconnectSync`
  tab 92, `DeleteAccount` tab 93) feed into a new `handle_sync_buttons`
  system extracted from `handle_settings_buttons` to stay within Bevy's
  16-parameter system limit.
 - **`SolitaireServerClient::login()` and `::register()`** (`432061c`).
  Both POST to `/api/auth/login` and `/api/auth/register` respectively.
  Private helper `extract_auth_tokens` parses `{ access_token, refresh_token }`.
  409 CONFLICT → "username already taken"; 401/403 → "invalid credentials";
  400 → server message echoed to the player.
 - **Re-auth prompt on token expiry** (`6ce5564`).
  `poll_pull_result` in `SyncPlugin` now fires `InfoToastEvent("Session
  expired — please reconnect")` + `SyncConfigureRequestEvent` when the
  pull task resolves to `SyncError::Auth(_)`. Because the modal is
  idempotent the re-open is safe to trigger from any system path.
 - **Server deployment artifacts** (`6ce5564`).
  `solitaire_server/Dockerfile`: multi-stage build (`rust:1.95-slim` →
  `debian:bookworm-slim`); copies `.sqlx` offline cache so `SQLX_OFFLINE=true`
  succeeds without a live database at build time; exposes port 8080.
  `solitaire_server/docker-compose.yml`: single-service compose file;
  `db-data` volume at `/app/data`; `DATABASE_URL` and `JWT_SECRET` from
  environment; HTTP health-check via `wget`. `solitaire_server/.env.example`:
  documents all required variables with generation hint (`openssl rand -hex 32`).
 - **Account deletion flow** (`272d31f`).
  "Delete Account" in Settings fires `DeleteAccountRequestEvent` →
  `SyncSetupPlugin::open_delete_confirm_modal` spawns a danger-red
  confirmation modal with "Cancel" and "Delete Forever" buttons.
  "Delete Forever" submits an async `PendingDeleteTask` that calls
  `SyncProvider::delete_account()`; `poll_delete_task` on Ok fires
  `SyncLogoutRequestEvent` + a success toast; on Err shows an error toast
  and leaves the modal open. Two-click destroy pattern — no accidental
  account deletion possible.
 ### Removed
 - **`SyncAuthResultEvent`** (`432061c`). Defined but never emitted or
  consumed; removed as dead code.
 ### Stats
 - Tests: **1300+ passing** / 0 failing
 - Clippy: clean
 - Crates touched: `solitaire_data` (sync_client), `solitaire_engine`
  (events, settings_plugin, sync_plugin, sync_setup_plugin [new], lib),
  `solitaire_app` (lib.rs), `solitaire_server` (Dockerfile,
  docker-compose.yml, .env.example [new])
 ## [0.22.0] — 2026-05-08
 Adds difficulty-tier game selection, Android JNI bridges for keystore and
@@ -1,6 +1,6 @@
 # CLAUDE.md
-version: unified-3.0
+version: unified-4.0
 ---
@@ -29,8 +29,9 @@ solitaire_sync/    # Shared API + merge logic
 solitaire_data/    # Persistence + sync client
 solitaire_engine/  # Bevy ECS + UI + gameplay orchestration
 solitaire_server/  # Axum backend (optional sync layer)
 solitaire_wasm/    # WASM bindings for browser-side replay player
 solitaire_app/     # Entry binary
-assets/            # Runtime assets (except audio)
+assets/            # Runtime assets (except audio + default theme)
 ```
 ---
@@ -72,12 +73,16 @@ These override all other instructions.
 * NO `unwrap()`
 * NO `panic!()` in runtime/game logic
-* All state transitions:
+* Core game state mutations MUST return:
 ```rust id="err_model"
 Result<T, MoveError>
 ```
 * Engine / UI state changes follow ECS patterns (Resources, Events) —
  they do not return `MoveError`
 * Use `thiserror`-derived types for any new error enums outside `solitaire_core`
 ---
 ## 2.4 Threading Rules
@@ -126,10 +131,15 @@ trait SyncProvider
 ## 3.1 ECS Design
 * systems = single responsibility
-* communication = Events only
+* cross-system communication = Events (fire-and-forget triggers)
-* shared state = Resources only
+* persistent shared state = Resources (polled every frame or on change)
 * per-entity state = Components only
 Events and Resources are both valid communication paths — use Events when
 the receiver needs to react once; use Resources when the receiver polls
 or when multiple systems read the same value (e.g. `SafeAreaInsets`,
 `HudVisibility`, `LayoutResource`).
 ---
 ## 3.2 Game State Authority
@@ -149,11 +159,22 @@ Every player action MUST:
 Keyboard shortcuts are:
 → optional accelerators only
 **Exception — UI chrome gestures:**
 Tap-to-toggle visibility of UI chrome (e.g. auto-hiding HUD band) is
 permitted without a visible button. The gesture MUST:
 * affect only chrome visibility, never game state
 * restore chrome automatically when any modal opens
 * be purely additive (game remains fully playable with chrome always visible)
 ---
 ## 3.4 Layout System
 * recompute on `WindowResized`
 * recompute on `SafeAreaInsets` changed
 * recompute on `HudVisibility` changed
 * `compute_layout` MUST accept `hud_visible: bool`; pass `HUD_BAND_HEIGHT`
  when `true`, `0.0` when `false`
 * no fixed resolution assumptions
 ---
@@ -178,11 +199,18 @@ Includes:
 ## 4.2 Embedded Assets
-Only audio:
+Embed via `include_bytes!()` only when ALL of the following are true:
-```text id="audio_rule"
+* the asset is small (< 500 KB uncompressed)
-include_bytes!()
+* it changes rarely (not user-customisable)
-```
+* a missing file would be a hard crash, not a graceful degradation
 Currently embedded:
 * **Audio** — all `.wav` files in `audio_plugin.rs`
 * **Default card theme** — shipped via `embedded://` scheme in `ThemePlugin`
 Do NOT embed card face PNGs, background images, or user fonts —
 these are loaded via `AssetServer` so art can be swapped without recompile.
 ---
@@ -210,7 +238,9 @@ Must degrade gracefully under `MinimalPlugins`.
 ## 5.2 Public API Rules
 * prefer `Into<T>` over concrete types
-* all public items require doc comments
+* publicly exported functions, traits, and non-trivial types require doc comments
 * simple marker components, newtype wrappers, and internal `pub` items
  used only within the same crate are exempt from doc comment requirements
 ---
@@ -276,11 +306,13 @@ NEVER commit otherwise
 Claude must request confirmation before:
-* adding dependencies
+* adding dependencies to `solitaire_core` or `solitaire_sync`
-* modifying `solitaire_sync`
+  (engine/server crates may add deps without confirmation)
-* changing DB schema
+* modifying `solitaire_sync` types or the `SyncProvider` trait
 * changing DB schema (migrations are append-only)
 * introducing `unsafe`
-* changing merge strategy
+* changing the merge strategy in `solitaire_sync::merge`
 * changing the `SyncPayload` wire format (breaking change for existing servers)
 ---
@@ -304,10 +336,29 @@ Core is always the source of truth.
 Must always be handled explicitly:
 **All platforms**
 * Bevy `Time` uses `f32`
 * `sqlx::migrate!()` path is crate-relative
 * `dirs::data_dir()` may return `None`
-* Linux may lack keyring backend
+* Linux may lack keyring backend — handle `keyring::Error` gracefully
 **Android (active target — not stretch)**
 * Safe-area insets arrive in frames 1–3 via JNI polling, not at startup;
  UI that depends on them must handle the zero-inset initial state
 * Physical pixels ≠ logical pixels: `SafeAreaInsets` values are physical
  (from `WindowInsets` API); divide by `window.scale_factor()` before
  passing to Bevy `Val::Px`
 * `adb shell input tap` uses physical pixel coordinates
 * FiraMono (bundled font) covers: ASCII, card suits U+2660–2666,
  Arrows U+2190–21FF. It does NOT cover Geometric Shapes (U+25xx) —
  those render as missing-glyph rectangles on Android
 * The gesture/navigation bar at the bottom (≈132px physical on common
  devices) is inside the Bevy viewport; use `SafeAreaInsets.bottom` to
  avoid placing interactive elements in that zone
 * `HUD_BAND_HEIGHT` is 128px on Android (two-row wrap) vs 64px on desktop;
  layout constants are `#[cfg(target_os = "android")]` gated
 * JNI calls must use `attach_current_thread_permanently` — not
  `attach_current_thread` — to avoid detach-on-drop panics
 ---
@@ -318,6 +369,12 @@ Must always be handled explicitly:
 * blocking async calls in ECS
 * insecure credential storage
 * bypassing core logic layer
 * hardcoded pixel coordinates in layout — always derive from `compute_layout`
 * Unicode Geometric Shapes block (U+25xx) in UI text — not in FiraMono
 * spawning a second `ModalScrim` while one already exists without first
  dismissing the existing one (use `scrims.is_empty()` guard)
 * reading `SafeAreaInsets` physical values directly into `Val::Px` without
  dividing by `window.scale_factor()`
 ---
@@ -345,9 +402,74 @@ If unclear:
 | Both combined   | full system understanding |
 ---
-# 14. Context Injection System (AUTOMATIC SCOPE FILTER)
+# 14. Modal System Conventions
-## 14.1 Purpose
+All full-screen overlay panels MUST use the `spawn_modal` / `ModalScrim` pattern
 from `solitaire_engine::ui_modal`.
 ## 14.1 Spawn pattern
 ```rust
 let scrim = spawn_modal(commands, MyScreenMarker, Z_MODAL_PANEL, |card| {
    spawn_modal_header(card, "Title", font_res);
    // ... body nodes ...
    spawn_modal_actions(card, |actions| {
        spawn_modal_button(actions, MyCloseButton, "Done", None,
                           ButtonVariant::Primary, font_res);
    });
 });
 // Optional: allow clicking the scrim outside the card to dismiss
 commands.entity(scrim).insert(ScrimDismissible);
 ```
 ## 14.2 Guard rule
 Before spawning a new modal, check `scrims: Query<(), With<ModalScrim>>`
 and return early if `!scrims.is_empty()` — unless the new modal is
 explicitly replacing the current one (despawn first, then spawn).
 ## 14.3 Safe area
 Every `ModalScrim` automatically receives `padding.bottom` equal to the
 logical gesture-bar height via `apply_safe_area_to_modal_scrims` in
 `SafeAreaInsetsPlugin`. Do not manually add bottom padding to scrim nodes.
 ## 14.4 Z-ordering
 Use `Z_MODAL_PANEL` from `ui_theme` for all modal scrims. Do not use
 raw `z_index` values — they drift and cause ordering bugs.
 ---
 # 15. Android Build & Verification
 ## 15.1 Build command
 ```bash
 cargo apk build --package solitaire_app --lib
 adb install -r target/debug/apk/solitaire-quest.apk
 ```
 ## 15.2 Coordinate system reminder
 Device physical: 1080×2400. Bevy logical: 900×2000. Scale factor: 1.20.
 `adb shell input tap X Y` takes PHYSICAL coordinates.
 To convert from what you see on screen (logical): multiply by 1.20.
 ## 15.3 Android-specific test checklist
 Before shipping any Android build:
 - [ ] Safe area insets arrive and shift HUD correctly (check after 3s)
 - [ ] All modal Done buttons are above the gesture bar
 - [ ] No Geometric Shapes glyphs in UI text
 - [ ] HUD band does not overlap the top status bar
 - [ ] Touch drag-and-drop works on all pile types
 ---
 # 16. Context Injection System (AUTOMATIC SCOPE FILTER)
 ## 16.1 Purpose
 Before generating any response, Claude MUST construct a **minimal relevant context set**.
@@ -360,7 +482,7 @@ This prevents:
 ---
-## 14.2 Input Classification Step (MANDATORY)
+## 16.2 Input Classification Step (MANDATORY)
 Every request MUST be classified into exactly one task type:
@@ -381,13 +503,13 @@ If uncertain → ask clarification.
 ---
-## 14.3 Context Selection Engine
+## 16.3 Context Selection Engine
 After classification, Claude MUST include ONLY the relevant sections below.
 ---
-## 14.4 Context Map (CORE RULESET)
+## 16.4 Context Map (CORE RULESET)
 ### feature
@@ -495,7 +617,7 @@ Include:
 ---
-## 14.5 Context Compression Rules
+## 16.5 Context Compression Rules
 Claude MUST obey:
@@ -506,7 +628,7 @@ Claude MUST obey:
 ---
-## 14.6 Context Priority Order
+## 16.6 Context Priority Order
 When space is limited:
@@ -517,7 +639,7 @@ When space is limited:
 ---
-## 14.7 “No Context Pollution” Rule
+## 16.7 “No Context Pollution” Rule
 Claude must NOT include:
@@ -529,7 +651,7 @@ Claude must NOT include:
 ---
-## 14.8 Self-Check Before Execution
+## 16.8 Self-Check Before Execution
 Before writing code, Claude MUST verify:
@@ -542,7 +664,7 @@ If any fail → revise context selection.
 ---
-## 14.9 Injection Output Format (Internal Model)
+## 16.9 Injection Output Format (Internal Model)
 Claude should behave as if it constructed:
@@ -560,7 +682,7 @@ Claude should behave as if it constructed:
 ---
-## 14.10 Relationship to ARCHITECTURE.md
+## 16.10 Relationship to ARCHITECTURE.md
 * ARCHITECTURE.md = source of truth
 * CLAUDE.md = execution constraints
@@ -12,7 +12,7 @@ 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
+- 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
@@ -360,7 +360,7 @@ notes:
 target:
 "<what is slow>"
-constraints:CLAUDE_WORKFLOW.md
+constraints:
 - no behavior change
 - no architecture change
 - minimal code changes
@@ -41,6 +41,10 @@ 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"
@@ -180,7 +184,7 @@ threading:
 plugins:
 pattern: "feature_isolation"
-communication: "events"
+communication: "events and resources"
 ---
@@ -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.
@@ -7018,6 +7018,7 @@ dependencies = [
 "resvg",
 "ron",
 "serde",
 "serde_json",
 "solitaire_core",
 "solitaire_data",
 "solitaire_sync",
@@ -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
@@ -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.
@@ -1,338 +1,177 @@
-# Solitaire Quest — Session Handoff
+# Ferrous Solitaire — Session Handoff
-**Last updated:** 2026-05-08 — **v0.21.8 tagged at `c50eaf8`**;
+**Last updated:** 2026-05-12 — Leaderboard display name shipped (`03be4fc`). All commits pushed to origin.
 nine post-cut commits on master. Push pending.
-v0.21.8 closes the last optional polish items in the B-2
+Phase 8 closes the self-hosted-server connection arc end-to-end: login/register
-replay screen-takeover arc: **notch-label centering** (middle
+modal, re-auth on token expiry, account deletion flow, server deployment
-three scrub-bar labels now centred on their notch ticks via the
+artifacts (Dockerfile + docker-compose), replay upload on win, web replay
-CSS `translateX(-50%)` pattern for Bevy 0.18 UI) and **WIN
+player (WASM + HTML/CSS/JS served by the server), leaderboard opt-in/out,
-MOVE HC legibility** (lime stays lime under HC mode via the
+and full server integration tests.
 extended `HighContrastBackground::with_hc` constructor and a
 new `STATE_SUCCESS_HC` brighter-lime constant). The replay
 overlay arc is now fully closed with no known open items.
-Full v0.21.8 detail lives in `CHANGELOG.md` § [0.21.8]. This
+---
 file from here on focuses on what's *open* post-cut and how to
 resume.
-## Status at pause
+## Current state
- **HEAD locally:** `f281425` (Android Keystore JNI).
+- **HEAD locally:** `03be4fc` (feat: leaderboard custom display name).
-  Docs ride on top; push pending.
+- **HEAD on origin:** `03be4fc` (fully pushed).
- **HEAD on origin:** `395a322` (double-tap commit — last pushed).
+- **Working tree:** clean (only `solitaire-release.jks.bak2` untracked — intentional).
- **Working tree:** clean (docs uncommitted). No WIP outstanding.
+- **Build:** `cargo clippy --workspace --all-targets -- -D warnings` clean.
- **`artwork/` directory:** still untracked. Intentional.
+- **Tests:** **1300+ passing / 0 failing** across the workspace.
- **Build:** `cargo clippy --workspace --all-targets -- -D warnings`
+- **Tags on origin:** `v0.9.0` through `v0.22.0`.
  clean.
 - **Tests:** **1292 passing / 0 failing** across the workspace.
 - **Tags on origin:** `v0.9.0` through `v0.21.8`.
 - **Android:** APK verified booting on Pixel_7 AVD (Android 14,
  x86_64). All desktop-only systems (handle_fullscreen) now gated.
  See Phase Android punch list for remaining work.
-## Since the v0.21.8 cut
+---
-Seven commits since the v0.21.8 tag:
+## What shipped in Phase 8 (432061c – bd388fe)
 - `a449f60` — Stats Prev/Next selector spawn site
 - `202a64d` — Android launch fixes (android_main, resize_constraints,
  apply_smart_default_window_size) — **closes APK launch verification**
 - `16242e6` — Ignore .idea/ IDE files
 - `395a322` — double-tap auto-move for touch input
 - `0cb1587` — Play-by-Seed dialog + HomeMode card
 - `2062bd0` — 75 new challenge seeds + gen_seeds binary
 - `45436d0` — gate handle_fullscreen to non-Android
 - `2c822ba` — JNI clipboard bridge for Android Stats share-link
 - `f281425` — Android Keystore AES-GCM token storage via JNI
-CHANGELOG + SESSION_HANDOFF docs ride on top; push pending.
+| 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 |
-Open next-step menu:
+Also shipped (pre-Phase 8 but post-v0.22.0, already in CHANGELOG):
-1. **Phase 8 (sync)** — the biggest open arc. Local storage
+- `solitaire_wasm` crate: WASM ReplayPlayer bindings for browser-side replay playback
-   scaffolding, self-hosted Axum server, GPGS stub.
+- Server replay API: `POST /api/replays`, `GET /api/replays/recent`, `GET /api/replays/:id`
-2. **Android follow-ups** — JNI ClipboardManager, Android Keystore,
+- Server web UI: `/replays/:id` HTML route + `ServeDir /web` static assets
-   GPGS. Launch verification and double-tap both closed; these
+- DB migration 002: `replays` table + two indexes
-   are the remaining Phase Android items.
+- Full server integration tests for replay endpoints
-3. **Move Log auto-scroll** — only relevant if the panel
+- `push_replay` in `sync_plugin` (uploads on win, writes share URL into replay history)
-   row count grows beyond the current 5-row fixed window.
+- Stats panel "Copy Share Link" button reads `share_url` from replay history
-## Open punch list
+---
-### Phase Android (build + persistence shipped; runtime gaps remain)
+## Open punch list (ordered by priority)
- *APK launch verification — closed 2026-05-08 by `202a64d`.*
+### 1. Documentation debt (no code)
-  Three fixes shipped: `android_main` export (missing NativeActivity
+- [x] CHANGELOG [Unreleased] → v0.23.0 — done this session
-  entry point), `resize_constraints` gated to non-Android (max=0
+- [x] ARCHITECTURE.md update — all 8 gaps closed, bumped to v1.3
-  panic), `apply_smart_default_window_size` gated to non-Android
+- [x] SESSION_HANDOFF.md update — this file
  (clamp panic on zero-dimension window event). Verified booting on
  Pixel_7 AVD (Android 14, x86_64, SwiftShader Vulkan), 2+ min
  runtime without crash. B0004 ECS hierarchy warnings remain
  (non-fatal; entity parent/child component mismatch); investigate
  if they surface gameplay bugs.
 - *Double-tap auto-move — closed 2026-05-08 by `395a322`.*
  `handle_double_tap` fires `MoveRequestEvent` on two rapid
  `TouchPhase::Ended` events within 0.5 s. Prefers foundation;
  falls back to tableau stack move. Fires `MoveRejectedEvent` when
  no legal destination exists. System runs before `touch_end_drag`
  in the chain so drag state is readable.
 - *F11 fullscreen gate — closed 2026-05-08 by `45436d0`.*
  `handle_fullscreen` and its `MonitorSelection`/`WindowMode`
  imports are `#[cfg(not(target_os = "android"))]`-gated. The
  `add_systems` call is a separate statement (not mid-chain).
 - *JNI ClipboardManager bridge — closed 2026-05-08 by `2c822ba`.*
  `android_clipboard::set_text(url)` calls `ClipboardManager` via
  JNI. Stats share-link button now writes to the clipboard with a
  "Copied: {url}" toast; falls back to "Share link: {url}" on JNI
  error. Requires AVD functional test (see verification steps in
  the approved plan).
 - *Android Keystore for credentials — closed 2026-05-08 by `f281425`.*
  `android_keystore` module: AES-256/GCM/NoPadding device-bound key,
  tokens serialised to JSON and stored atomically at
  `{data_dir}/auth_tokens.bin` as `[12-byte IV][ciphertext+tag]`.
  `auth_tokens.rs` Android stubs now delegate to it. Key
  invalidation (biometric reset) → `TokenError::KeychainUnavailable`.
  Requires AVD functional test before Phase 8 sync goes live on
  Android.
 - **Cosmetic `cargo apk build --lib` workaround.** Post-sign
  panic doesn't affect the APK on disk but produces noisy stderr.
  Either upstream a cargo-apk fix or document `--lib` as
  canonical in the runbook.
-### Visual-identity follow-ups (post-v0.21.0)
+### 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.
-The visual-identity arc is effectively complete: token system,
+### 3. Security hardening
-chrome migration, splash boot screen, replay-overlay banner,
+- [x] **Refresh token rotation.** Done (`b129664`): `refresh_tokens` table
-card-face artwork (both rendering paths), and the `ACCENT_PRIMARY`
+  (migration 003); jti embedded in JWT; rotate-on-use pattern; 3 integration
-palette refresh all shipped in v0.20.0 + v0.21.0. What stays open:
+  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.
- *Replay-overlay screen-takeover redesign — closed 2026-05-08
+### 4. Android validation
-  across 13 commits (v0.21.4–v0.21.7).* The full mockup
+- [x] **Android Keystore functional test.** Done (2026-05-11, Pixel 7 AVD,
-  (`docs/ui-mockups/replay-overlay-mobile.html`) has shipped:
+  Android 14): `load_access_token()` exercised via `start_pull`; logcat confirmed
-  banner chrome (v0.21.0), floating MOVE chip (v0.21.2), WIN
+  `NotFound` returned cleanly — no JNI panic. See `docs/android/PLAYABILITY_TODO.md` P4.
-  MOVE scrub-bar marker (post-v0.21.3), playback controls /
+- [x] **JNI clipboard functional test.** Done (2026-05-11): temporary `KEYCODE_C`
-  Space accelerator (post-v0.21.3), scrub notches + labels +
+  hook confirmed `ClipboardManager.setPrimaryClip()` succeeds on Android 14.
-  keybind footer + ESC / ← / → accelerators + HC border
+  Hook reverted. Production path requires Interaction::Pressed + non-null `share_url`.
-  (v0.21.5), Move Log panel + HC scrub track + continuous
+  Note: `adb shell input tap` doesn't deliver touch events on headless AVD (documented).
-  scrub (v0.21.6), and full-screen 50 % opacity dim layer
+- [x] **`cargo apk build --lib` noisy stderr** — upstream cargo-apk bug; `--lib`
-  (v0.21.7). Every major B-2 sub-piece is now closed. The
+  is the canonical command (CLAUDE.md §15.1, docs/ANDROID.md). No in-repo fix possible.
  only remaining items are minor polish: notch-label centering
  and WIN MOVE HC contrast bump (see Open next-step menu).*
 - *Floating `MOVE N/M` chip above the focused card during
  playback — closed 2026-05-08 by `2fb2d63`.* World-space
  `Text2d` entity sibling to the banner overlay; uses the same
  `LayoutResource` pile coordinates so it survives window
  resizes without UI/camera math.
 - *Toast Warning variant wiring — closed 2026-05-08 by `279e23d`.*
  Daily-challenge-expiry toast fires once per `daily.date` when
  within 30 min of UTC midnight reset and today is incomplete.
  `ToastVariant` is now fully load-bearing (every variant has at
  least one real driver). Future Warning drivers can either reuse
  the generic `WarningToastEvent(String)` carrier or add their
  own domain message + `animation_plugin` handler.
 - *Toast Error variant wiring — closed 2026-05-08 by `68d50b5`.*
  `MoveRejectedEvent` now fires a 2-second pink-bordered
  "Invalid move" toast as the third leg of the
  audio + visual + text rejection-feedback stool.
 - *High-contrast accessibility mode — closed 2026-05-08 by
  `c5787c6` + `07e0357` (engine + UI) + v0.21.2's HC chrome
  rollout (`c9af1ea` + `d87761d` + `ec804d5`) + post-cut
  dynamic-paint rollout (`c153363`).* Card text rendering plus
  8 static-border chrome surfaces (modal scaffold, tooltip,
  onboarding key chips, help panel key chips, stats panel
  cells, home Level/XP/Score row, home mode buttons, home
  mode-hotkey chips, 4 settings panel surfaces) all boost
  borders to `BORDER_SUBTLE_HC` under HC via the
  `HighContrastBorder` marker. The previously-carved-out
  dynamic-paint sites are now also covered: HUD action buttons
  and modal buttons take the same marker (their paint cycles
  only mutate `BackgroundColor`, so no race); the radial menu
  rim folds HC into its per-frame spawn via
  `radial_rim_outline` so the focused rim boosts to
  `BORDER_SUBTLE_HC` under HC (preserving focused-vs-resting
  hierarchy that naive marker substitution would invert).
 - *Reduced-motion mode — closed 2026-05-08 by `c5787c6` +
  v0.21.2's `ed152e2`.* `effective_slide_secs` forces 0 on
  card animations; `pulse_splash_cursor` skips the per-frame
  pulse multiplier; `spawn_splash` skips the scanline overlay
  entirely. Future scope: gate any future card-lift z-bump
  animation, warning-chip pulse (when one materialises).
-### Carried forward from v0.19.0
+### 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.
- *App icon round — closed 2026-05-08 by `3eb3a26` + `716a025`.*
+### 5b. Android UX polish (2026-05-12)
  Runtime `Window::icon` wired (Linux/macOS/Windows); 9-size
  PNG hierarchy at `assets/icon/icon_<size>.png` covers Linux
  hicolor + downstream `.icns`/`.ico` packaging needs. The
  `.ico` and `.icns` bundle-format files themselves are *not*
  generated — both would need new crate deps (`ico` and
  `icns` respectively) and only matter at app-bundle time
  (cargo-bundle / packaging), not at `cargo run`. Open if the
  project later ships as a packaged macOS / Windows app.
-### Other small candidates
+- [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.
- *Play-by-Seed dialog — closed 2026-05-08 by `0cb1587`.*
+  **Note:** These 4 fixes are implemented and verified but not yet committed.
  `PlayBySeedPlugin` adds a numeric-input modal with async solver
  preview (debounced 500 ms). `HomeMode::PlayBySeed` card fires
  `StartPlayBySeedRequestEvent`. 5 unit tests. 75 new verified-win
  seeds (`2062bd0`) expand `CHALLENGE_SEEDS` via the new
  `solitaire_assetgen::gen_seeds` binary.
 - *Prev/Next selector chips spawn site — closed 2026-05-08 by
  `a449f60`.* `ReplayPrevButton` / `ReplayNextButton` /
  `ReplaySelectorCaption` / `ReplaySelectorDetail` now spawn in
  `spawn_stats_screen` as a compact chip row above the Watch
  Replay action. The Shareable badge is in the detail line.
  The click handler and repaint systems were already live since
  v0.19.0; this was purely the missing spawn site.
 - **Toast queue / immediate unification.** The two toast paths
  (`spawn_queued_toast` for `InfoToastEvent` queue; `spawn_toast`
  for fire-and-forget) now share visual treatment but remain
  separate functions because they serve different temporal
  needs (sequential vs. parallel). If overlap becomes a UX
  issue, merge into one queue with priority lanes.
-### Process notes
+### 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`.
- **The desktop-adaptation spec is the canonical reference for
+---
  geometry decisions** when porting any future plugin. Read
  `docs/ui-mockups/desktop-adaptation.md` first; apply the
  universal rules to every surface; consult the per-screen
  table for the priority surfaces. The 9 missing-plugin screens
  (splash now ported; eight remaining) inherit the universal
  rules without dedicated guidance.
 - **Stitch `generate_variants` is unreliable for layout-only
  adaptation prompts** as of 2026-05-07. The first call timed
  out and no variant ever landed in `list_screens`. If a future
  session wants visual desktop mockups, prefer
  `generate_screen_from_text` with a fresh narrow prompt per
  screen rather than `generate_variants` against existing
  mobile screens.
 - **Token-port pattern.** v0.20.0's chrome-migration commits
  set a reusable shape for "centralised design system applied
  across N plugins":
  1. Constants module (`ui_theme.rs`) is the source of truth.
  2. Const sites that can't call `Alpha::with_alpha` (not yet
     `const` on stable) use a literal RGB matching the token,
     with a unit test pinning the RGB to the token (e.g.
     `MARKER_VALID`, `HINT_PILE_HIGHLIGHT_COLOUR`,
     `RIGHT_CLICK_HIGHLIGHT_COLOUR`).
  3. Cross-plugin duplication (e.g. `MARKER_DEFAULT` ↔
     `PILE_MARKER_DEFAULT_COLOUR`) collapses to a single
     promoted const re-exported from one plugin and imported
     by the other — replaces "kept in sync" doc comments with a
     compile-time invariant.
  4. Domain colours (suit pips, card faces, lerp helpers) stay
     as literals with a comment naming the rationale; only UI
     chrome routes through tokens.
 - **`SplashFadable` scaffolding pattern** (introduced in
  `cacb19c`). Any future overlay that needs to fade `N >> 3`
  elements together should follow the same shape: one tiny
  marker carrying the full-alpha base colour, one global query
  that lerps every marker's alpha each frame, no per-element
  query plumbing. Cleanly outscales the `Without<X>, Without<Y>`
  query exclusion pattern that the old splash was hitting at
  three siblings.
-### Canonical remote
+## ARCHITECTURE.md gaps (for the update pass)
-`github.com/funman300/Rusty_Solitaire` is the canonical repo.
+Items missing from the doc:
-Always push there. As of v0.21.0 origin matches local; the next
+1. `solitaire_wasm` crate (§2 workspace + §3 responsibilities)
-push happens when post-cut work accumulates and is ready to roll
+2. Replay API endpoints (§9 API Reference — 3 new routes)
-into a v0.21.1 / v0.22.0 cut.
+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
-### Design direction (Terminal — base16-eighties)
+---
- **Tone:** retro-terminal / synthwave — flat depth (no box-shadows),
+## Process notes
-  monospaced-forward typography (JetBrains Mono / FiraMono), tight
+
-  16 px edge margins, 8 px card radius.
+- **Commit attribution:** use `funman300` as git user. Co-author line:
- **Palette:** near-black surface ramp (`#151515` / `#202020` /
+  `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
-  `#2a2a2a` / `#353535`), brick-red primary CTA (`#a54242` —
+- **Commit format:** `type(scope): description` per CLAUDE.md §7.
-  swapped from cyan `#6fc2ef` in v0.21.0 commit `a292a7e`), lime
+- **Never commit without:** `cargo test --workspace` passing + clippy clean.
-  success (`#acc267`), gold warning (`#ddb26f`), pink error /
+- **Sub-agents** stage/verify only; orchestrator commits.
-  suit-red (`#fb9fb1`), lavender celebration (`#e1a3ee`), teal
+- **`CARD_PLAN.md`** referenced in `theme/` module comments but not present in
-  info (`#12cfc0`).
+  repo. Clean up references or commit the file.
- **Two-color suits.** Red = `#fb9fb1`, black = `#d0d0d0`.
+- **Token-port pattern** (v0.20.0): when migrating tokens, walk every concrete
-  Outlined glyphs for diamonds & clubs are *always on*; the
+  artifact downstream — PNGs, SVGs, literals, comments. Three "walked past this"
-  Settings "color-blind mode" toggle swaps red → lime `#acc267`
+  follow-ups in v0.21.0 all had this shape.
-  (was red → cyan pre-v0.21.0; lime is the next-best non-red
+
-  base16-eighties accent now that the primary itself is red).
+---
 - **Card glyphs render upright in both corners** — no 180°
  inverted-corner-indicator rotation. Single-orientation
  digital play doesn't benefit from the traditional flip-
  readback convention. `design-system.md` § Game Cards
  documents this deliberate deviation.
 ## Resume prompt
 ```
-You are a senior Rust + Bevy developer working on Solitaire Quest.
+You are a senior Rust + Bevy developer working on Ferrous Solitaire.
-Working directory: <Rusty_Solitaire clone path on this machine>.
+Working directory: <Rusty_Solitaire clone path>.
-Branch: master. v0.21.8 is tagged at c50eaf8 (cut 2026-05-08,
+Branch: master. v0.23.0 is the current version (HEAD: 03be4fc). Fully pushed.
 replay-overlay polish). Seven post-cut commits are on master (see
 "Since the v0.21.8 cut" above); push of the last four pending.
 v0.21.7 stays at da3e542, v0.21.6 at f63db76, v0.21.5 at a2432df,
 v0.21.4 at 23ff62c, v0.21.3 at 3d92a91, v0.21.2 at f23df3b,
 v0.21.1 at daa655a, v0.21.0 at 04f9bf9.
 Working tree: uncommitted CHANGELOG + SESSION_HANDOFF docs; push
 pending. See CHANGELOG.md § [0.21.9] for full detail.
-State: HEAD locally — see `git rev-parse HEAD`. Workspace
+READ FIRST (in order):
 tests: 1292 passing / 0 failing. Clippy clean.
 READ FIRST (in order, before doing anything):
  1. SESSION_HANDOFF.md  — this file
-  2. CHANGELOG.md        — [0.21.9] section has the pending-cut items
+  2. CHANGELOG.md        — [0.23.0] section has full Phase 8 detail
-  3. CLAUDE.md           — unified-3.0 rule set
+  3. CLAUDE.md           — unified-4.0 rule set
-  4. CLAUDE_SPEC.md      — formal architecture spec
+  4. ARCHITECTURE.md     — v1.3, fully up to date
-  5. ARCHITECTURE.md     — crate responsibilities + data flow
+  5. docs/ui-mockups/    — design system + mockup library
-  6. docs/ui-mockups/    — design system + 24-mockup library +
+  6. docs/android/       — Android setup + build runbook
-                           desktop-adaptation.md (the rules-based
+  7. ~/.claude/projects/<this-project>/memory/MEMORY.md
                           companion to the mockups; read this
                           before any plugin port)
  7. docs/android/*      — Android setup + build runbook
  8. ~/.claude/projects/<this-project>/memory/MEMORY.md
                         — saved feedback / project context
                           (machine-local; may be missing on a
                           fresh machine)
-DECISION TO ASK THE PLAYER FIRST:
+OPEN WORK:
-  A. Android follow-ups — JNI ClipboardManager bridge (arboard
+  Phase 8 punch list is fully closed. All items verified complete.
-     has no Android backend), Android Keystore (blocked on Phase 8).
+  Remaining nuisance: `cargo apk build --lib` noisy stderr (cosmetic, non-blocking).
     Launch verification + double-tap are closed.
  B. Phase 8 (sync) — local storage scaffolding, self-hosted
     Axum server, `SolitaireServerClient` impl. The biggest open
     arc by scope; rolls up Android dependencies (Keystore,
     ClipboardManager).
  C. Play-by-Seed polish — the dialog is functional but has no
     visual preview of the solver verdict in the UI yet; the
     HomeMode card is wired but the dialog spawn site and verdict
     display could use a second pass.
-WORKFLOW NOTES:
+  4 Android UX fixes are implemented and verified but NOT YET COMMITTED:
-  - Use the system git config (already correct).
+    - BUG-3 (hud_plugin.rs): multi-modal stacking guard
-  - When attributing playtester feedback in commits/docs, use
+    - UX-7 (help_plugin.rs): help text wrap on Android
-    "Quat" not "Rhys" (saved feedback memory).
+    - UX-5b (home_plugin.rs): FiraMono glyph corruption in mode selector
-  - Sub-agents stage + verify only; orchestrator commits.
+    - UX-1 (safe_area.rs): modal Done button in gesture zone
  - Every commit must pass build / clippy / test before pushing.
  - Push to GitHub (origin) — gh auth setup-git wired on
    primary dev box; verify on laptop before first push.
  - Token-port pattern: when migrating tokens, walk every
    concrete artifact downstream of the token (PNG textures,
    embedded SVGs, hardcoded literals, comment color names),
    not just the token name. v0.21.0 surfaced three "the
    migration walked past this" follow-ups that all matched
    this shape — codified here so future similar work can
    pattern-match instead of rediscovering.
  - Doc-vs-implementation drift pattern: v0.21.1's pile-marker
    visibility fix (`4d48cad`) implemented an invariant that
    had been declared in a module doc comment but was never
    enforced in code. When future work touches a module with
    a "this does X" doc comment, verify the code actually does
    X and add a test if not. Two layers, two checks.
-OPEN AT THE START: ask which of A–C. Don't pick unilaterally.
+  Commit those first, then suggest Phase 9 planning.
 Note: every remaining option is multi-session by nature (A is
 gated on Android tooling; B and C are explicitly multi-session
 arcs). A fresh session is a better fit for any of them than the
 tail of a long working stretch.
 ```
@@ -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
@@ -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"
@@ -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
@@ -0,0 +1,25 @@
 apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
  name: solitaire-analytics
  namespace: solitaire
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
 spec:
  ingressClassName: traefik
  rules:
    - host: analytics.aleshym.co
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: matomo
                port:
                  name: http
  tls:
    - hosts:
        - analytics.aleshym.co
      secretName: analytics-tls
@@ -0,0 +1,27 @@
 apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
  name: solitaire-server
  namespace: solitaire
  annotations:
    # Remove the next two lines if you are not using cert-manager.
    cert-manager.io/cluster-issuer: letsencrypt-prod
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
 spec:
  ingressClassName: traefik
  rules:
    - host: klondike.aleshym.co
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: solitaire-server
                port:
                  name: http
  # Remove the tls block if you are not using cert-manager.
  tls:
    - hosts:
        - klondike.aleshym.co
      secretName: solitaire-tls
@@ -0,0 +1,23 @@
 apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 resources:
 - namespace.yaml
 - pvc.yaml
 - deployment.yaml
 - service.yaml
 - ingress.yaml
 - mariadb-pvc.yaml
 - mariadb-deployment.yaml
 - mariadb-service.yaml
 - matomo-pvc.yaml
 - matomo-deployment.yaml
 - matomo-service.yaml
 - ingress-analytics.yaml
 # CI updates this block automatically via `kustomize edit set image`.
 # The image name here matches the `image: solitaire-server` stub in deployment.yaml.
 images:
 - name: solitaire-server
  newName: git.aleshym.co/funman300/solitaire-server
  newTag: "32991301"
@@ -0,0 +1,72 @@
 apiVersion: apps/v1
 kind: Deployment
 metadata:
  name: mariadb
  namespace: solitaire
 spec:
  replicas: 1
  selector:
    matchLabels:
      app: mariadb
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        app: mariadb
    spec:
      containers:
        - name: mariadb
          image: mariadb:11
          env:
            - name: MYSQL_ROOT_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: matomo-secret
                  key: MYSQL_ROOT_PASSWORD
            - name: MYSQL_DATABASE
              valueFrom:
                secretKeyRef:
                  name: matomo-secret
                  key: MYSQL_DATABASE
            - name: MYSQL_USER
              valueFrom:
                secretKeyRef:
                  name: matomo-secret
                  key: MYSQL_USER
            - name: MYSQL_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: matomo-secret
                  key: MYSQL_PASSWORD
          ports:
            - containerPort: 3306
          volumeMounts:
            - name: mariadb-data
              mountPath: /var/lib/mysql
          livenessProbe:
            exec:
              command:
                - healthcheck.sh
                - --connect
                - --innodb_initialized
            initialDelaySeconds: 30
            periodSeconds: 30
          readinessProbe:
            exec:
              command:
                - healthcheck.sh
                - --connect
            initialDelaySeconds: 10
            periodSeconds: 10
          resources:
            requests:
              cpu: 100m
              memory: 256Mi
            limits:
              cpu: 500m
              memory: 512Mi
      volumes:
        - name: mariadb-data
          persistentVolumeClaim:
            claimName: mariadb-data
@@ -0,0 +1,11 @@
 apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
  name: mariadb-data
  namespace: solitaire
 spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 2Gi
@@ -0,0 +1,13 @@
 apiVersion: v1
 kind: Service
 metadata:
  name: mariadb
  namespace: solitaire
 spec:
  selector:
    app: mariadb
  ports:
    - name: mysql
      port: 3306
      targetPort: 3306
  clusterIP: None
@@ -0,0 +1,79 @@
 apiVersion: apps/v1
 kind: Deployment
 metadata:
  name: matomo
  namespace: solitaire
 spec:
  replicas: 1
  selector:
    matchLabels:
      app: matomo
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        app: matomo
    spec:
      containers:
        - name: matomo
          image: matomo:5.10.0
          env:
            - name: MATOMO_DATABASE_HOST
              value: mariadb
            - name: MATOMO_DATABASE_PORT
              value: "3306"
            - name: MATOMO_DATABASE_ADAPTER
              value: PDO\MYSQL
            - name: MATOMO_DATABASE_DBNAME
              valueFrom:
                secretKeyRef:
                  name: matomo-secret
                  key: MYSQL_DATABASE
            - name: MATOMO_DATABASE_USERNAME
              valueFrom:
                secretKeyRef:
                  name: matomo-secret
                  key: MYSQL_USER
            - name: MATOMO_DATABASE_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: matomo-secret
                  key: MYSQL_PASSWORD
            # Traefik terminates SSL; tell Matomo to trust X-Forwarded-* headers
            - name: MATOMO_GENERAL_ASSUME_SECURE_PROTOCOL
              value: "1"
            - name: MATOMO_GENERAL_PROXY_CLIENT_HEADERS
              value: HTTP_X_FORWARDED_FOR
            - name: MATOMO_GENERAL_PROXY_HOST_HEADERS
              value: HTTP_X_FORWARDED_HOST
          ports:
            - containerPort: 80
          volumeMounts:
            - name: matomo-data
              mountPath: /var/www/html
          livenessProbe:
            httpGet:
              path: /matomo.php
              port: 80
            initialDelaySeconds: 60
            periodSeconds: 30
            timeoutSeconds: 5
          readinessProbe:
            httpGet:
              path: /matomo.php
              port: 80
            initialDelaySeconds: 30
            periodSeconds: 10
            timeoutSeconds: 5
          resources:
            requests:
              cpu: 100m
              memory: 256Mi
            limits:
              cpu: 500m
              memory: 512Mi
      volumes:
        - name: matomo-data
          persistentVolumeClaim:
            claimName: matomo-data
@@ -0,0 +1,11 @@
 apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
  name: matomo-data
  namespace: solitaire
 spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
@@ -0,0 +1,22 @@
 # DO NOT COMMIT THE REAL VERSION OF THIS FILE.
 # deploy/matomo-secret.yaml is gitignored — apply it manually once:
 #
 #   cp deploy/matomo-secret.yaml.example deploy/matomo-secret.yaml
 #   # edit the passwords below, then:
 #   kubectl apply -f deploy/matomo-secret.yaml
 #   kubectl annotate secret matomo-secret -n solitaire \
 #     argocd.argoproj.io/sync-options=Prune=false --overwrite
 #
 # Generate strong passwords with:
 #   python3 -c "import secrets; print(secrets.token_urlsafe(18))"
 apiVersion: v1
 kind: Secret
 metadata:
  name: matomo-secret
  namespace: solitaire
 stringData:
  MYSQL_ROOT_PASSWORD: "CHANGE_ME"
  MYSQL_DATABASE: matomo
  MYSQL_USER: matomo
  MYSQL_PASSWORD: "CHANGE_ME"
  MATOMO_ADMIN_PASSWORD: "CHANGE_ME"
@@ -0,0 +1,12 @@
 apiVersion: v1
 kind: Service
 metadata:
  name: matomo
  namespace: solitaire
 spec:
  selector:
    app: matomo
  ports:
    - name: http
      port: 80
      targetPort: 80
@@ -0,0 +1,4 @@
 apiVersion: v1
 kind: Namespace
 metadata:
  name: solitaire
@@ -0,0 +1,11 @@
 apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
  name: solitaire-db
  namespace: solitaire
 spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
@@ -0,0 +1,12 @@
 apiVersion: v1
 kind: Service
 metadata:
  name: solitaire-server
  namespace: solitaire
 spec:
  selector:
    app: solitaire-server
  ports:
    - name: http
      port: 80
      targetPort: 8080
@@ -143,16 +143,18 @@ After the APK is signed cargo-apk panics with:
 thread 'main' panicked: Bin is not compatible with Cdylib
 ```
-This happens AFTER the APK is on disk and signed. cargo-apk is
+This happens AFTER the APK is on disk and signed. cargo-apk tries to
-trying to also wrap the desktop `[[bin]]` target. The APK is still
+also wrap the desktop `[[bin]]` target alongside the `[lib]`. The APK
-valid. Work around with `--lib`:
+is valid — the panic is cosmetic. **Always use `--lib`**, which is the
 canonical build command (see `CLAUDE.md §15.1`):
 ```bash
-cargo apk build -p solitaire_app --target x86_64-linux-android --lib
+cargo apk build -p solitaire_app --lib
 ```
-(Permanent fix to come — likely a `[[bin]] required-features = ["desktop"]`
+Root cause: upstream cargo-apk bug — it does not skip `[[bin]]` targets
-gate so cargo-apk skips the bin target on Android.)
+when building for Android. No in-repo fix is possible; `--lib` is the
 accepted workaround.
 ---
@@ -1,4 +1,8 @@
-# Solitaire Quest — Session Handoff
+# Ferrous Solitaire — Session Handoff (ARCHIVED)
 > **This file is from Phase 2 (2026-04-25, 242 tests). It is kept for historical
 > reference only. The authoritative session handoff is at the repo root:
 > `SESSION_HANDOFF.md`.**
 > Last updated: 2026-04-25
 > Branch: `master` — pushed to https://github.com/funman300/Rusty_Solitaire.git
@@ -20,7 +24,7 @@ All seven Cargo crates created and compiling cleanly:
 | `solitaire_engine` | Stub | Bevy ECS systems — all plugins added in Phase 3 |
 | `solitaire_server` | Stub | Axum sync server — implemented in Phase 8C |
 | `solitaire_gpgs` | Compile-time stub | Google Play Games bridge — Android only, JNI in Phase: Android |
-| `solitaire_app` | Working | Opens blank Bevy window titled "Solitaire Quest" at 1280×800 |
+| `solitaire_app` | Working | Opens blank Bevy window titled "Ferrous Solitaire" at 1280×800 |
 Fast compile profiles, `assets/` directory structure, and `.env.example` are all in place.
@@ -70,12 +70,8 @@ rewrites required.
  2026-05-10.* `spawn_action_button` now nulls the `hotkey`
  argument on Android via a `#[cfg(target_os = "android")]` rebind,
  so the U / Esc / F1 / N chips next to the action row labels
-  disappear on touch builds. Other hint sites (onboarding panel,
+  disappear on touch builds. Remaining hint sites swept in P3 —
-  pause-modal `Esc` hint, mode-card hotkey chips on the home
+  see full-keyboard-hint-sweep entry below.
  screen, replay overlay footer, modal toggle hints in
  profile/stats/leaderboard/settings, help screen) survive — they
  live behind navigation and a touch user reaches them less often.
  Track as a P3 sweep when more screens are audited on hardware.
 - [x] **Thumb-sized hit targets.** *Closed 2026-05-10.* Action
  button Node carries `min_width: Val::Px(48.0), min_height:
  Val::Px(48.0)` — meets Material's 48 dp baseline on touch and is
@@ -84,44 +80,181 @@ rewrites required.
  Material's guideline applies to all input modes. Cards, pile
  markers, modal close buttons not yet audited — track as P3 if
  they fall below threshold on hardware.
- [ ] **Portrait-first card spacing.** Stretch tableau piles vertically
+- [x] **Portrait-first card spacing.** *Closed 2026-05-11.*
-  to fill height; reduce inter-pile gaps so 7 columns fit in 360 dp.
+  `compute_layout` now derives an adaptive `tableau_fan_frac` from the
- [ ] **Double-tap auto-move visible feedback.** `handle_double_tap`
+  available vertical space below the tableau row. On height-limited
-  exists since `395a322` — verify it triggers on hardware and add a
+  (desktop) windows the formula returns ≈ 0.25 and the clamp keeps the
-  brief source-card flash / highlight to confirm to the user.
+  existing behaviour. On width-limited (portrait phone) windows — where
  card size is constrained by the 9-column horizontal packing — the fan
  fraction expands to fill the viewport (≈ 0.84 at 360 × 800 dp).
  `tableau_facedown_fan_frac` scales proportionally. Both values live in
  the `Layout` struct; `card_plugin::card_positions` and
  `input_plugin::card_position` / `pile_drop_rect` read from the struct
  so rendering and hit-testing stay in sync across viewport sizes.
 - [x] **Double-tap auto-move visible feedback.** *Closed 2026-05-11.*
  On a recognised double-tap (priority 1 single-card or priority 2
  stack move), the moved card(s) receive a 0.35 s lime flash
  (`STATE_SUCCESS` tint + `HintHighlight { remaining: 0.35 }`) before
  the move request is written. The flash persists through the card
  animation and is cleaned up by the existing `tick_hint_highlight`
  system. Hardware trigger-verification remains a manual step — connect
  AVD or device and confirm two rapid `TouchPhase::Ended` events within
  0.5 s produce the lime flash.
 ## P2 — Polish
- [ ] **Drag responsiveness on touch.** Bevy default touch-to-mouse
+- [x] **Drag responsiveness on touch.** *Closed 2026-05-11.*
-  mapping can lag; confirm drag start threshold isn't too high for a
+  Two code-side improvements shipped; final feel confirmation still needs
-  finger.
+  hardware:
- [ ] **Long-press menu.** Alternative to right-click (which doesn't
+  1. `start_drag` (mouse path) now bails out when a touch is just-pressed
-  exist on touch). Wire to the existing right-click-highlight system.
+     (`Touches::iter_just_pressed()`), ensuring `touch_start_drag` always
- [ ] **HUD typography.** Reduce text sizes for `Score:`, `Moves:`,
+     owns the drag state on touch-screen devices — including Bevy/Winit
-  timer so they fit cleanly in one row.
+     versions that simulate `MouseButton::Left` from the primary touch.
- [ ] **Orientation lock.** Set `android:screenOrientation="portrait"`
+  2. Mobile drag commit threshold lowered 10 px → 8 px, matching Android's
-  in cargo-apk manifest (or design a landscape layout).
+     `ViewConfiguration.getScaledTouchSlop()` spec. Smaller threshold →
     smaller snap-on-commit and faster perceived response.
  **Remaining:** connect AVD or device and verify drag feels responsive
  with no stutter; tune threshold further if needed.
 - [x] **Long-press menu.** *Closed 2026-05-11.* New system
  `radial_open_on_long_press` in `radial_menu.rs` counts up while a
  touch is held (`drag.active_touch_id.is_some() && !drag.committed`)
  and opens `RightClickRadialState::Active` after 0.5 s — the same
  state the right-click path uses. Existing radial infrastructure
  then handles everything:
  - `radial_track_cursor` extended to fall back to the first active
    touch when no cursor position is available, so sliding the held
    finger moves the hover ring.
  - `radial_handle_release_or_cancel` extended to confirm/cancel on
    `Touches::iter_just_released()` in addition to right-mouse release.
  - `handle_double_tap` skips when the radial is active (guards a
    narrow edge case where the finger lifts at exactly the same frame
    the 0.5 s threshold fires).
  Hardware verification needed: confirm the 0.5 s hold feel, verify
  sliding to a destination and lifting confirms the move.
 - [x] **HUD typography.** *Closed 2026-05-11.* New system
  `update_hud_typography` fires on `WindowResized` and adjusts Tier-1
  font sizes based on viewport width. Below 480 logical px: Score
  `TYPE_HEADLINE` (26) → `TYPE_BODY_LG` (18), Moves/Timer
  `TYPE_BODY_LG` (18) → `TYPE_CAPTION` (11), so all three items fit
  in the 180 dp HUD column on a 360 dp phone. At ≥ 480 px the
  original sizes are restored — desktop/tablet layout unchanged.
  `add_message::<WindowResized>()` added defensively to `HudPlugin`
  so the system works under `MinimalPlugins` in tests.
 - [x] **Orientation lock.** *Closed 2026-05-11.* Added
  `[package.metadata.android.application.activity]` section to
  `solitaire_app/Cargo.toml` with `orientation = "portrait"`.
  cargo-apk/ndk-build maps this to `android:screenOrientation="portrait"`
  in the generated `AndroidManifest.xml`. Remove (or add a landscape
  layout) before enabling auto-rotate.
 ## P3 — Asset density
- [ ] **Density-aware card scaling.** Currently single texture size; on
+- [x] **Density-aware card scaling.** *Closed 2026-05-11 — no code change
-  a high-DPI phone the cards look small. Scale by
+  required.* `WindowResized` fires with **logical** pixels; sprites are
-  `Window::scale_factor()` or ship multiple PNG sizes.
+  sized in world units (1 world unit = 1 logical pixel); Bevy's renderer
- [ ] **App-icon density buckets.** Nine sizes already exist in
+  maps logical → physical via `scale_factor` internally. On a 360 dp
-  `assets/icon/`; verify the manifest references them so Android's
+  3×-DPI phone, cards are 40 logical dp = 120 physical px. The 256 × 384 px
-  launcher picks the right one.
+  card textures are **downscaled** to fit (256 → 120 px) — quality is fine.
  Upscaling only occurs if `card_width × scale_factor > 256`, i.e. a
  tablet with a logical width > 765 dp at 3× DPI — no current target
  device falls in that range. Revisit if the game ships on large-screen
  high-DPI tablets.
 - [x] **App-icon density buckets.** *Closed 2026-05-11.* Created
  `solitaire_app/res/mipmap-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi}/ic_launcher.png`
  from the existing `assets/icon/` PNGs (48→mdpi, 64→hdpi, 128→xhdpi,
  256→xxhdpi+xxxhdpi). Added `resources = "res"` to
  `[package.metadata.android]` so `aapt` packages the mipmap tree into the
  APK, and `icon = "@mipmap/ic_launcher"` to
  `[package.metadata.android.application]` so the launcher references it.
 - [x] **Full keyboard-hint sweep.** *Closed 2026-05-11.* Extended the
  P1 suppression to cover all remaining hint sites:
  - `ui_modal.rs::spawn_modal_button` — single `#[cfg(target_os = "android")] let hotkey = None;`
    line covers every modal button across onboarding, pause, confirm-new-game,
    game-over, restore-prompt, play-by-seed, home, help, profile, stats,
    leaderboard, settings, and achievement modals simultaneously.
  - `home_plugin.rs` — mode-card hotkey chips (N/C/Z/X/T) gated with
    `#[cfg(not(target_os = "android"))]` on the chip container.
  - `replay_overlay.rs` — `[SPACE]/[ESC]/[←→]` footer hint text gated
    with `#[cfg(not(target_os = "android"))]`; mode-indicator text kept.
  - `help_plugin.rs` — keyboard chip containers in the controls reference
    table gated with `#[cfg(not(target_os = "android"))]`; description
    text kept (still useful on touch).
 ## P4 — Stability / runtime
- [ ] **B0004 ECS hierarchy warnings.** Flagged in
+- [x] **B0004 ECS hierarchy warnings.** *Investigated 2026-05-11 — no
-  `SESSION_HANDOFF.md` after APK launch verification — investigate
+  fix required.* B0004 fires via Bevy's `validate_parent_has_component<C>`
-  whether they cause gameplay bugs on hardware vs. AVD.
+  hook when a child entity has UI component `C` (e.g. `Node`,
- [ ] **AVD functional tests for JNI bridges.** Clipboard (`2c822ba`)
+  `InheritedVisibility`) but its parent doesn't yet. In Bevy 0.18,
-  and Keystore (`f281425`) shipped but never tested on real device
+  `.despawn()` is recursive (docs: "When a parent is despawned, all
-  or AVD.
+  children will also be despawned"), so all `.despawn()` calls in the
  engine are safe. The warnings seen on the Pixel 7 AVD during startup
  are a component-propagation timing artifact — UI children reach the
  hook before the parent's inherited components finish initialising —
  not a gameplay defect. `despawn_related::<Children>()` in
  `card_plugin.rs` is explicit child-only teardown (parent kept alive)
  and is correct. No gameplay bugs attributed to these warnings over 2+
  min AVD runtime.
 - [x] **AVD functional tests for JNI bridges.** *Closed 2026-05-11.*
  Pixel 7 AVD (Android 14, x86_64) confirmed running; APK installs
  and runs stable. Key findings:
  **Keystore JNI — verified working.** Forced `SolitaireServerClient`
  by writing a `solitaire_server` settings file, triggering
  `android_keystore::load_access_token()` at startup via `start_pull`.
  Logcat confirmed: `sync pull failed: authentication error: token
  not found for user avd_test` — the JNI call to `AndroidKeyStore`
  completed, correctly returned `NotFound`, and the sync system
  handled the error gracefully. No panic, no crash from the JNI layer.
  **Clipboard JNI — verified working.** Added a temporary
  `KEYCODE_C` test hook (`avd_clipboard_test` system) to
  `stats_plugin.rs`, rebuilt the APK, pressed C on the AVD.
  Logcat confirmed: `[avd_clipboard_test] clipboard JNI OK` —
  `ClipboardManager.setPrimaryClip()` succeeded on Android 14.
  Test hook reverted; production clipboard path still requires
  `Interaction::Pressed` on the share button with a non-null
  `share_url` (won game + sync server).
  **Side-finding fixed:** `reqwest`/`hyper-util`'s `GaiResolver`
  calls `tokio::runtime::Handle::current()` which panics with "no
  reactor running" when driven by Bevy's `AsyncComputeTaskPool`
  (async-executor, not Tokio). Fixed in `sync_plugin.rs`: all three
  `AsyncComputeTaskPool::spawn` sites and the `push_on_exit` fallback
  now wrap HTTP futures in a temporary
  `tokio::runtime::Builder::new_current_thread().enable_all()` runtime.
  **Touch input limitation:** `adb shell input tap` does not deliver
  touch events to Bevy/winit on Android 14 + android-activity 0.6.1
  in headless AVD mode. Keyboard events (`KEYCODE_*`) work normally.
 ---
 ## P5 — UX polish (2026-05-12)
 - [x] **UX-1 — Modal Done button unreachable in gesture zone.** *Closed
  2026-05-12.* New `apply_safe_area_to_modal_scrims` system in
  `safe_area.rs` pads every `ModalScrim` bottom by `insets.bottom /
  window.scale_factor()` (logical pixels). Fires when `SafeAreaInsets`
  changes AND when a new `ModalScrim` is spawned (`Added<ModalScrim>`
  filter). Verified on device: Settings Done button reachable at physical
  y ≈ 1800–2000 (was y ≈ 2232+, inside gesture zone).
 - [x] **UX-5b — Home mode selector glyph corruption.** *Closed
  2026-05-12.* `home_plugin.rs` mode glyphs changed from Geometric Shapes
  block (U+25xx — absent from FiraMono, renders as rectangles) to card
  suits U+2660 ♠ / U+2665 ♥ / U+2666 ♦. Affects Zen, Challenge, and
  Daily mode selector buttons shown at level 5+.
 - [x] **UX-7 — Help screen HUD button entry wraps to two lines.** *Closed
  2026-05-12.* Android `CONTROL_SECTIONS` entry for ≡ button shortened
  from `"Menu: Stats, Settings, Profile, Achievements"` to
  `"Open menu (Stats, Settings, Profile...)"` in `help_plugin.rs`.
  Fits on one line at 360 dp.
 - [x] **BUG-3 — Multi-modal stacking (Stats + Profile simultaneously).** *Closed
  2026-05-12.* `handle_menu_button` in `hud_plugin.rs` now checks
  `scrims: Query<(), With<ModalScrim>>` and only calls
  `spawn_menu_popover` when `scrims.is_empty()`. Tapping ≡ while any
  modal is open is a no-op. Verified on device.
 ## Notes / decisions
 * This list is screenshot-driven; expect more items to surface once
@@ -2,7 +2,7 @@
 > **Date:** 2026-04-28  
 > **Author:** Claude Code  
-> **Scope:** Feasibility analysis for porting Solitaire Quest to Android using cargo-mobile2
+> **Scope:** Feasibility analysis for porting Ferrous Solitaire to Android using cargo-mobile2
 ---
@@ -1,4 +1,4 @@
-# Solitaire Quest — Phase 1 + 2: Workspace & Core Game Engine
+# Ferrous Solitaire — Phase 1 + 2: Workspace & Core Game Engine
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
@@ -555,7 +555,7 @@ fn main() {
        .add_plugins(
            DefaultPlugins.set(WindowPlugin {
                primary_window: Some(Window {
-                    title: "Solitaire Quest".into(),
+                    title: "Ferrous Solitaire".into(),
                    resolution: (1280.0, 800.0).into(),
                    ..default()
                }),
@@ -571,7 +571,7 @@ fn main() {
 ```bash
 cargo run -p solitaire_app --features bevy/dynamic_linking
 ```
-Expected: A blank Bevy window titled "Solitaire Quest" opens. Press Escape or close the window to exit. No panics or errors in the terminal.
+Expected: A blank Bevy window titled "Ferrous Solitaire" opens. Press Escape or close the window to exit. No panics or errors in the terminal.
 ---
@@ -1210,7 +1210,7 @@ fn main() {
        .add_plugins(
            DefaultPlugins.set(WindowPlugin {
                primary_window: Some(Window {
-                    title: "Solitaire Quest".into(),
+                    title: "Ferrous Solitaire".into(),
                    resolution: (1280.0, 800.0).into(),
                    ..default()
                }),
@@ -11,7 +11,7 @@
 ### Infrastructure
 - Two machines (or VMs) referred to as **Machine A** and **Machine B** throughout this runbook. Both must be able to reach the sync server over the network.
- A running Solitaire Quest sync server reachable at a known URL, e.g. `https://solitaire.example.com`. See `README_SERVER.md` for setup.
+- A running Ferrous Solitaire sync server reachable at a known URL, e.g. `https://solitaire.example.com`. See `README_SERVER.md` for setup.
 - Verify the server is live before starting:
  ```bash
@@ -3,7 +3,7 @@
 > **Why this exists.** The 24 mockups in this directory are mobile
 > (390 × 844 logical, iPhone 14 Pro frame) with one exception
 > (`home-menu-desktop.html`). The Stitch project that produced them
-> is named "Solitaire Quest *Mobile* Redesign" — the mobile-first
+> is named "Ferrous Solitaire *Mobile* Redesign" — the mobile-first
 > framing was deliberate when the new Android target opened, but
 > desktop is still the primary delivery surface. Porting the mobile
 > mockups 1:1 would land a 390-px-wide column floating in the middle
@@ -0,0 +1,140 @@
 #!/usr/bin/env bash
 # Build a self-signed Android APK from solitaire_app's cdylib targets.
 #
 # Replaces the cargo-apk pipeline with explicit cargo-ndk + aapt2 + apksigner
 # steps. The CI runner was hitting an SDK-discovery bug inside cargo-apk's
 # ndk-build crate that we couldn't isolate; running each Android toolchain
 # step explicitly gives us a debuggable pipeline.
 #
 # Required environment:
 #   ANDROID_HOME            Path to Android SDK root
 #   ANDROID_NDK_HOME        Path to the specific NDK version
 #   BUILD_TOOLS_VERSION     e.g. "34.0.0"
 #   PLATFORM                e.g. "android-34"
 #
 # Optional environment:
 #   PROFILE                 "debug" (default) | "release"
 #   ABIS                    Space-separated Android ABIs to build (default:
 #                           "arm64-v8a armeabi-v7a x86_64"). Reduce in CI to
 #                           fit the runner's disk budget — a full three-ABI
 #                           debug build can exceed 25 GB of target/ output.
 #   APK_OUT                 Output APK path (default: target/$PROFILE/apk/solitaire-quest.apk)
 #   KEYSTORE                Path to keystore for signing (default: generates a debug keystore)
 #   KEYSTORE_PASS           Keystore password (default: "android" for the generated debug keystore)
 #   KEY_ALIAS               Key alias (default: "androiddebugkey")
 #   KEY_PASS                Key password (default: same as KEYSTORE_PASS)
 #
 # Outputs:
 #   $APK_OUT                Signed, zipaligned APK
 set -euo pipefail
 : "${ANDROID_HOME:?ANDROID_HOME must be set}"
 : "${ANDROID_NDK_HOME:?ANDROID_NDK_HOME must be set}"
 : "${BUILD_TOOLS_VERSION:?BUILD_TOOLS_VERSION must be set}"
 : "${PLATFORM:?PLATFORM must be set (e.g. android-34)}"
 PROFILE="${PROFILE:-debug}"
 ABIS="${ABIS:-arm64-v8a armeabi-v7a x86_64}"
 APK_OUT="${APK_OUT:-target/${PROFILE}/apk/solitaire-quest.apk}"
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$REPO_ROOT"
 BT="$ANDROID_HOME/build-tools/$BUILD_TOOLS_VERSION"
 PLATFORM_JAR="$ANDROID_HOME/platforms/$PLATFORM/android.jar"
 MANIFEST="solitaire_app/android/AndroidManifest.xml"
 RES_DIR="solitaire_app/res"
 ASSETS_DIR="assets"
 # --- sanity ----------------------------------------------------------------
 for f in "$BT/aapt2" "$BT/zipalign" "$BT/apksigner" "$PLATFORM_JAR" "$MANIFEST"; do
  [ -e "$f" ] || { echo "missing: $f"; exit 1; }
 done
 STAGING="$(mktemp -d)"
 trap 'rm -rf "$STAGING"' EXIT
 mkdir -p "$STAGING/lib" "$STAGING/compiled-res"
 # --- 1. native libraries via cargo-ndk -------------------------------------
 # `-o $STAGING/lib` lays out files as $STAGING/lib/<abi>/libsolitaire_app.so
 # which is the directory structure the APK expects under lib/.
 CARGO_NDK_ARGS=( --platform 26 -o "$STAGING/lib" )
 for abi in $ABIS; do
  CARGO_NDK_ARGS+=( -t "$abi" )
 done
 CARGO_NDK_ARGS+=( build --package solitaire_app --lib )
 if [ "$PROFILE" = "release" ]; then
  CARGO_NDK_ARGS+=( --release )
 fi
 echo ">>> cargo ndk ${CARGO_NDK_ARGS[*]}"
 cargo ndk "${CARGO_NDK_ARGS[@]}"
 # --- 2. compile + link resources and manifest ------------------------------
 if [ -d "$RES_DIR" ]; then
  echo ">>> aapt2 compile resources"
  "$BT/aapt2" compile --dir "$RES_DIR" -o "$STAGING/compiled-res"
 fi
 LINK_ARGS=(
  link
  -o "$STAGING/app-unsigned.apk"
  -I "$PLATFORM_JAR"
  --manifest "$MANIFEST"
 )
 [ -d "$ASSETS_DIR" ] && LINK_ARGS+=( -A "$ASSETS_DIR" )
 # Add compiled resources if any
 shopt -s nullglob
 RES_FLATS=( "$STAGING/compiled-res"/*.flat )
 shopt -u nullglob
 if [ ${#RES_FLATS[@]} -gt 0 ]; then
  LINK_ARGS+=( "${RES_FLATS[@]}" )
 fi
 echo ">>> aapt2 link"
 "$BT/aapt2" "${LINK_ARGS[@]}"
 # --- 3. add native libraries to the APK ------------------------------------
 echo ">>> bundle native libraries"
 ( cd "$STAGING" && zip -r -q app-unsigned.apk lib/ )
 # --- 4. zipalign -----------------------------------------------------------
 echo ">>> zipalign"
 "$BT/zipalign" -p -f 4 "$STAGING/app-unsigned.apk" "$STAGING/app-aligned.apk"
 # Free the unsigned intermediate now — apksigner reads $app-aligned.apk and
 # writes $APK_OUT, and the runner's disk is tight after a multi-ABI build.
 rm -f "$STAGING/app-unsigned.apk"
 # --- 5. sign ---------------------------------------------------------------
 if [ -z "${KEYSTORE:-}" ]; then
  # Generate a deterministic debug keystore on the fly.
  KEYSTORE="$STAGING/debug.keystore"
  KEYSTORE_PASS="${KEYSTORE_PASS:-android}"
  KEY_ALIAS="${KEY_ALIAS:-androiddebugkey}"
  KEY_PASS="${KEY_PASS:-$KEYSTORE_PASS}"
  echo ">>> generating debug keystore at $KEYSTORE"
  keytool -genkeypair -v \
    -keystore "$KEYSTORE" \
    -storepass "$KEYSTORE_PASS" \
    -alias "$KEY_ALIAS" \
    -keypass "$KEY_PASS" \
    -keyalg RSA -keysize 2048 -validity 10000 \
    -dname "CN=Android Debug,O=Android,C=US" > /dev/null
 fi
 KEYSTORE_PASS="${KEYSTORE_PASS:-android}"
 KEY_ALIAS="${KEY_ALIAS:-androiddebugkey}"
 KEY_PASS="${KEY_PASS:-$KEYSTORE_PASS}"
 mkdir -p "$(dirname "$APK_OUT")"
 echo ">>> apksigner sign -> $APK_OUT"
 "$BT/apksigner" sign \
  --ks "$KEYSTORE" \
  --ks-pass "pass:$KEYSTORE_PASS" \
  --ks-key-alias "$KEY_ALIAS" \
  --key-pass "pass:$KEY_PASS" \
  --out "$APK_OUT" \
  "$STAGING/app-aligned.apk"
 echo ">>> verify"
 "$BT/apksigner" verify --verbose "$APK_OUT"
 echo ">>> done: $APK_OUT"
@@ -60,6 +60,15 @@ package = "com.solitairequest.app"
 apk_name = "solitaire-quest"
 build_targets = ["aarch64-linux-android", "armv7-linux-androideabi", "x86_64-linux-android"]
 assets = "../assets"
 # Density-bucketed launcher icons. `aapt` processes `res/mipmap-*/` and
 # packages them into the APK; the launcher selects the best-fit bucket
 # for the device screen density. Sizes used:
 #   mdpi  (1×, 48 dp) → 48 px   (exact)
 #   hdpi  (1.5×, 72 dp) → 64 px (88 %, aapt scales up slightly)
 #   xhdpi (2×, 96 dp) → 128 px  (133 %, aapt scales down)
 #   xxhdpi (3×, 144 dp) → 256 px (178 %, aapt scales down)
 #   xxxhdpi (4×, 192 dp) → 256 px (133 %, aapt scales down)
 resources = "res"
 # No `runtime_libs` — we don't ship any precompiled .so files,
 # the entire app is pure Rust + Bevy. cargo-apk would try to
 # resolve `runtime_libs/<arch>/` if set, and fail on a non-existent
@@ -78,7 +87,15 @@ required = true
 name = "android.permission.INTERNET"
 [package.metadata.android.application]
-label = "Solitaire Quest"
+label = "Ferrous Solitaire"
 # Launcher icon — references the density-bucketed mipmap resource above.
 icon = "@mipmap/ic_launcher"
 # `debuggable` defaults to false on release builds; cargo-apk flips it
 # automatically for debug profiles. Leaving the field unset keeps the
 # default behaviour.
 [package.metadata.android.application.activity]
 # Lock to portrait — the current layout has only been designed and tested
 # in portrait orientation. Remove (or add a landscape layout) before
 # enabling auto-rotate.
 orientation = "portrait"
@@ -0,0 +1,51 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!--
  Mirrors what cargo-apk would generate from [package.metadata.android]
  in solitaire_app/Cargo.toml. Kept in-tree so the CI workflow can drive
  aapt2 directly without going through cargo-apk's brittle SDK discovery.
  Keep in sync with:
    * Cargo.toml: package, min_sdk_version, target_sdk_version,
      uses_feature, uses_permission, application label/icon,
      activity orientation
    * [lib].name (currently "solitaire_app") — matches the
      `android.app.lib_name` meta-data value below, which is the
      shared object name without the `lib` prefix or `.so` suffix.
 -->
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.solitairequest.app"
    android:versionCode="1"
    android:versionName="1.0">
    <uses-sdk
        android:minSdkVersion="26"
        android:targetSdkVersion="34" />
    <uses-feature
        android:name="android.hardware.touchscreen"
        android:required="true" />
    <uses-permission android:name="android.permission.INTERNET" />
    <application
        android:label="Ferrous Solitaire"
        android:icon="@mipmap/ic_launcher"
        android:hasCode="false">
        <activity
            android:name="android.app.NativeActivity"
            android:exported="true"
            android:screenOrientation="portrait"
            android:configChanges="orientation|keyboardHidden|screenSize|keyboard|navigation|screenLayout">
            <meta-data
                android:name="android.app.lib_name"
                android:value="solitaire_app" />
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
 </manifest>
@@ -25,14 +25,14 @@ use bevy::window::{Monitor, PrimaryMonitor, PrimaryWindow};
 use bevy::winit::WinitWindows;
 use solitaire_data::{load_settings_from, provider_for_backend, settings_file_path, Settings};
 use solitaire_engine::{
-    register_theme_asset_sources, AchievementPlugin, AnimationPlugin, AssetSourcesPlugin,
+    register_theme_asset_sources, AchievementPlugin, AnalyticsPlugin, AnimationPlugin, AssetSourcesPlugin,
    AudioPlugin, AutoCompletePlugin, CardAnimationPlugin, CardPlugin, ChallengePlugin,
    CursorPlugin, DailyChallengePlugin, DiagnosticsHudPlugin, DifficultyPlugin, FeedbackAnimPlugin,
    FontPlugin, GamePlugin, HelpPlugin, HomePlugin, HudPlugin, InputPlugin, LeaderboardPlugin,
    OnboardingPlugin, PausePlugin, PlayBySeedPlugin, ProfilePlugin, ProgressPlugin,
    RadialMenuPlugin, ReplayOverlayPlugin, ReplayPlaybackPlugin, SafeAreaInsetsPlugin,
    SelectionPlugin, SettingsPlugin,
-    SplashPlugin, StatsPlugin, SyncPlugin, TablePlugin, ThemePlugin, ThemeRegistryPlugin,
+    SplashPlugin, StatsPlugin, SyncPlugin, SyncSetupPlugin, TablePlugin, ThemePlugin, ThemeRegistryPlugin,
    TimeAttackPlugin, UiFocusPlugin, UiModalPlugin, UiTooltipPlugin, WeeklyGoalsPlugin,
    WinSummaryPlugin,
 };
@@ -106,7 +106,7 @@ pub fn run() {
            DefaultPlugins
                .set(WindowPlugin {
                    primary_window: Some(Window {
-                        title: "Solitaire Quest".into(),
+                        title: "Ferrous Solitaire".into(),
                        // X11/Wayland WM_CLASS so taskbar managers group
                        // multiple windows of this app correctly.
                        name: Some("solitaire-quest".into()),
@@ -193,6 +193,8 @@ pub fn run() {
        .add_plugins(AudioPlugin)
        .add_plugins(OnboardingPlugin)
        .add_plugins(SyncPlugin::new(sync_provider))
        .add_plugins(SyncSetupPlugin)
        .add_plugins(AnalyticsPlugin)
        .add_plugins(LeaderboardPlugin)
        .add_plugins(WinSummaryPlugin)
        .add_plugins(UiModalPlugin)
@@ -1,4 +1,4 @@
-//! Generates PNG assets for Solitaire Quest.
+//! Generates PNG assets for Ferrous Solitaire.
 //!
 //! Produces:
 //! - 52 card face PNGs (120×168) — one per card, with rank, suit symbol, and
@@ -145,6 +145,10 @@ pub struct GameState {
    /// Used by the `comeback` achievement condition.
    #[serde(default)]
    pub recycle_count: u32,
    /// When `true`, the player may move the top card of a foundation pile back
    /// onto a compatible tableau column. Off by default — non-standard house rule.
    #[serde(default)]
    pub take_from_foundation: bool,
    /// Save-file schema version. Defaults to `1` for older files that pre-date
    /// the field. The loader refuses any value other than
    /// [`GAME_STATE_SCHEMA_VERSION`].
@@ -187,6 +191,7 @@ impl GameState {
            is_auto_completable: false,
            undo_count: 0,
            recycle_count: 0,
            take_from_foundation: false,
            schema_version: GAME_STATE_SCHEMA_VERSION,
            undo_stack: VecDeque::new(),
        }
@@ -312,6 +317,18 @@ impl GameState {
                    }
                }
                PileType::Tableau(_) => {
                    if matches!(&from, PileType::Foundation(_)) {
                        if !self.take_from_foundation {
                            return Err(MoveError::RuleViolation(
                                "take-from-foundation rule is disabled".into(),
                            ));
                        }
                        if count != 1 {
                            return Err(MoveError::RuleViolation(
                                "only one card can return from foundation at a time".into(),
                            ));
                        }
                    }
                    let dest = self.piles.get(&to).ok_or(MoveError::InvalidDestination)?;
                    if !can_place_on_tableau(&bottom_card, dest) {
                        return Err(MoveError::RuleViolation("invalid tableau placement".into()));
@@ -409,12 +426,11 @@ impl GameState {
    /// Returns `true` when stock and waste are empty and all tableau cards are face-up.
    /// At that point the game can be completed without further player input.
    pub fn check_auto_complete(&self) -> bool {
        // Stock must be empty; waste may still have cards (they are resolved
        // by draw() calls inside next_auto_complete_move / auto_complete_step).
        if !self.piles[&PileType::Stock].cards.is_empty() {
            return false;
        }
        if !self.piles[&PileType::Waste].cards.is_empty() {
            return false;
        }
        (0..7).all(|i| {
            self.piles[&PileType::Tableau(i)]
                .cards
@@ -442,17 +458,36 @@ impl GameState {
        if !self.is_auto_completable || self.is_won {
            return None;
        }
        // Check waste top first — when stock is exhausted the waste may still
        // contain cards that can go directly to a foundation.
        let waste = PileType::Waste;
        if let Some((card, slot)) = self.piles[&waste].cards.last()
            .and_then(|c| self.foundation_slot_for(c).map(|s| (c, s)))
        {
            let _ = card; // borrow ends here
            return Some((waste, PileType::Foundation(slot)));
        }
        for i in 0..7 {
            let tableau = PileType::Tableau(i);
-            if let Some(card) = self.piles[&tableau].cards.last() {
+            if let Some(slot) = self.piles[&tableau].cards.last()
-                // Prefer the slot that already claims this card's suit so
+                .and_then(|c| self.foundation_slot_for(c))
-                // Aces don't sometimes land in slot 0 and then leave the
+            {
-                // matching suit-claimed slot empty.
+                return Some((tableau, PileType::Foundation(slot)));
            }
        }
        None
    }
    /// Return the foundation slot index that `card` can legally move to, or
    /// `None` if no such slot exists.
    ///
    /// Prefers the slot already claiming this card's suit so Aces always land
    /// in a consistent column. Falls back to an empty slot only for Aces.
    fn foundation_slot_for(&self, card: &crate::card::Card) -> Option<u8> {
        let mut candidate: Option<u8> = None;
        let mut empty_slot: Option<u8> = None;
        for slot in 0..4_u8 {
-                    let foundation = PileType::Foundation(slot);
+            let pile = &self.piles[&PileType::Foundation(slot)];
                    let pile = &self.piles[&foundation];
            if pile.cards.is_empty() {
                if empty_slot.is_none() {
                    empty_slot = Some(slot);
@@ -462,20 +497,12 @@ impl GameState {
                break;
            }
        }
-                let target_slot = candidate.or_else(|| {
+        let target = candidate.or_else(|| {
                    // Only fall back to an empty slot if the card is an Ace,
                    // which is the only rank that can claim an empty slot.
            if card.rank.value() == 1 { empty_slot } else { None }
        });
-                if let Some(slot) = target_slot {
+        target.filter(|&slot| {
-                    let foundation = PileType::Foundation(slot);
+            can_place_on_foundation(card, &self.piles[&PileType::Foundation(slot)])
-                    if can_place_on_foundation(card, &self.piles[&foundation]) {
+        })
                        return Some((tableau, foundation));
                    }
                }
            }
        }
        None
    }
    /// Time bonus added to score on win: `700_000 / elapsed_seconds` (0 if elapsed is 0).
@@ -1005,24 +1032,24 @@ mod tests {
    }
    #[test]
-    fn auto_complete_false_when_waste_not_empty() {
+    fn auto_complete_true_when_stock_empty_waste_has_cards() {
        // Waste no longer blocks auto-complete — draw() drains it during
        // auto-complete steps. Only stock-not-empty and face-down tableau
        // cards block the flag.
        let mut g = new_game();
        g.piles.get_mut(&PileType::Stock).unwrap().cards.clear();
        // Leave the waste pile untouched (it may be empty after clearing stock,
        // so add a card explicitly to ensure the waste guard is exercised).
        g.piles.get_mut(&PileType::Waste).unwrap().cards.push(Card {
            id: 99,
            suit: Suit::Clubs,
            rank: Rank::Ace,
            face_up: true,
        });
        // Make all tableau cards face-up so only the waste guard is the blocker.
        for i in 0..7 {
            for c in g.piles.get_mut(&PileType::Tableau(i)).unwrap().cards.iter_mut() {
                c.face_up = true;
            }
        }
-        assert!(!g.check_auto_complete());
+        assert!(g.check_auto_complete());
    }
    #[test]
@@ -1258,4 +1285,71 @@ mod tests {
            "must target the Hearts-claimed slot, not the empty slot 0",
        );
    }
    fn setup_take_from_foundation_game() -> GameState {
        let mut g = new_game();
        // Clear the board so we control the layout exactly.
        g.piles.get_mut(&PileType::Stock).unwrap().cards.clear();
        g.piles.get_mut(&PileType::Waste).unwrap().cards.clear();
        for i in 0..7 {
            g.piles.get_mut(&PileType::Tableau(i)).unwrap().cards.clear();
        }
        // Foundation slot 0: A♠, 2♠ (top = 2♠)
        let f = g.piles.get_mut(&PileType::Foundation(0)).unwrap();
        f.cards.push(Card { id: 1, suit: Suit::Spades, rank: Rank::Ace,  face_up: true });
        f.cards.push(Card { id: 2, suit: Suit::Spades, rank: Rank::Two,  face_up: true });
        // Tableau 0: 3♥ face-up (2♠ can go on 3♥ — different colour, rank-1)
        g.piles.get_mut(&PileType::Tableau(0)).unwrap().cards.push(Card {
            id: 3, suit: Suit::Hearts, rank: Rank::Three, face_up: true,
        });
        g
    }
    #[test]
    fn take_from_foundation_blocked_by_default() {
        let mut g = setup_take_from_foundation_game();
        assert!(!g.take_from_foundation);
        let err = g
            .move_cards(PileType::Foundation(0), PileType::Tableau(0), 1)
            .unwrap_err();
        assert!(
            matches!(err, MoveError::RuleViolation(_)),
            "expected RuleViolation, got {err:?}",
        );
    }
    #[test]
    fn take_from_foundation_allowed_when_enabled() {
        let mut g = setup_take_from_foundation_game();
        g.take_from_foundation = true;
        g.move_cards(PileType::Foundation(0), PileType::Tableau(0), 1).unwrap();
        // Foundation slot 0 should now hold only the Ace.
        assert_eq!(g.piles[&PileType::Foundation(0)].cards.len(), 1);
        assert_eq!(g.piles[&PileType::Foundation(0)].cards[0].rank, Rank::Ace);
        // The 2♠ should be on top of tableau 0 above the 3♥.
        let t0 = &g.piles[&PileType::Tableau(0)].cards;
        assert_eq!(t0.len(), 2);
        assert_eq!(t0[1].rank, Rank::Two);
    }
    #[test]
    fn take_from_foundation_rejects_illegal_tableau_placement() {
        let mut g = setup_take_from_foundation_game();
        g.take_from_foundation = true;
        // Tableau 1 is empty — only a King can go there; 2♠ is not a King.
        let err = g
            .move_cards(PileType::Foundation(0), PileType::Tableau(1), 1)
            .unwrap_err();
        assert!(matches!(err, MoveError::RuleViolation(_)));
    }
    #[test]
    fn take_from_foundation_rejects_count_gt_1() {
        let mut g = setup_take_from_foundation_game();
        g.take_from_foundation = true;
        let err = g
            .move_cards(PileType::Foundation(0), PileType::Tableau(0), 2)
            .unwrap_err();
        assert!(matches!(err, MoveError::RuleViolation(_)));
    }
 }
@@ -15,6 +15,7 @@ async-trait    = { workspace = true }
 dirs           = { workspace = true }
 reqwest        = { workspace = true }
 tokio          = { workspace = true }
 uuid           = { workspace = true }
 # `keyring-core` is the typed Entry/Error API used by
 # `auth_tokens`. The crate's own dependency tree pulls in
@@ -27,10 +27,6 @@ pub trait SyncProvider: Send + Sync {
    fn backend_name(&self) -> &'static str;
    /// Returns true if the user is currently authenticated with this backend.
    fn is_authenticated(&self) -> bool;
    /// Mirror an achievement unlock to this backend (no-op for most backends).
    async fn mirror_achievement(&self, _id: &str) -> Result<(), SyncError> {
        Ok(())
    }
    /// Fetch the global leaderboard from this backend. Returns an empty list
    /// for backends that do not support leaderboards (e.g. `LocalOnlyProvider`).
    async fn fetch_leaderboard(&self) -> Result<Vec<LeaderboardEntry>, SyncError> {
@@ -83,9 +79,6 @@ impl SyncProvider for Box<dyn SyncProvider + Send + Sync> {
    fn is_authenticated(&self) -> bool {
        (**self).is_authenticated()
    }
    async fn mirror_achievement(&self, id: &str) -> Result<(), SyncError> {
        (**self).mirror_achievement(id).await
    }
    async fn fetch_leaderboard(&self) -> Result<Vec<LeaderboardEntry>, SyncError> {
        (**self).fetch_leaderboard().await
    }
@@ -170,5 +163,8 @@ pub use replay::{
    REPLAY_HISTORY_CAP, REPLAY_HISTORY_SCHEMA_VERSION, REPLAY_SCHEMA_VERSION,
 };
 pub mod matomo_client;
 pub use matomo_client::MatomoClient;
 pub mod platform;
 pub use platform::data_dir;
@@ -0,0 +1,122 @@
 //! Matomo HTTP Tracking API client.
 //!
 //! Buffers game-play events and flushes them via the Matomo bulk tracking
 //! endpoint. Errors are silently discarded — analytics must never affect
 //! gameplay or block the UI.
 use std::sync::Mutex;
 use reqwest::Client;
 use uuid::Uuid;
 /// Sends game-play events to a self-hosted Matomo instance via the
 /// [HTTP Tracking API](https://developer.matomo.org/api-reference/tracking-api).
 ///
 /// Construct once per session and share via `Arc`. `event` is cheap and
 /// can be called from the Bevy main thread; `flush` is async and must be
 /// called from a background task.
 pub struct MatomoClient {
    tracking_url: String,
    site_id: u32,
    /// 16 hex-char visitor ID, stable for the lifetime of this client.
    visitor_id: String,
    uid: Option<String>,
    client: Client,
    /// Pre-encoded query strings, one per buffered event.
    pending: Mutex<Vec<String>>,
 }
 impl MatomoClient {
    /// Create a new client targeting `base_url` (e.g. `"https://analytics.example.com"`).
    pub fn new(base_url: impl AsRef<str>, site_id: u32, uid: Option<String>) -> Self {
        let base = base_url.as_ref().trim_end_matches('/');
        let tracking_url = format!("{}/matomo.php", base);
        // Take the lower 64 bits of a v4 UUID and format as 16 hex chars.
        let visitor_id = format!("{:016x}", Uuid::new_v4().as_u128() as u64);
        Self {
            tracking_url,
            site_id,
            visitor_id,
            uid,
            client: Client::new(),
            pending: Mutex::new(Vec::new()),
        }
    }
    /// Buffer one Matomo custom event. Never blocks; never fails visibly.
    ///
    /// When the buffer exceeds 100 events the oldest 50 are dropped to
    /// prevent unbounded memory growth during extended offline play.
    pub fn event(
        &self,
        category: &str,
        action: &str,
        name: Option<&str>,
        value: Option<f64>,
    ) {
        let Ok(mut guard) = self.pending.lock() else {
            return;
        };
        let mut qs = format!(
            "idsite={}&rec=1&apiv=1&send_image=0\
             &url=game%3A%2F%2Fsolitaire%2Fevent\
             &_id={}&e_c={}&e_a={}",
            self.site_id,
            self.visitor_id,
            url_encode(category),
            url_encode(action),
        );
        if let Some(n) = name {
            qs.push_str(&format!("&e_n={}", url_encode(n)));
        }
        if let Some(v) = value {
            qs.push_str(&format!("&e_v={v}"));
        }
        if let Some(uid) = &self.uid {
            qs.push_str(&format!("&uid={}", url_encode(uid)));
        }
        guard.push(qs);
        if guard.len() > 100 {
            guard.drain(0..50);
        }
    }
    /// Drain the pending buffer and POST it to Matomo's bulk tracking endpoint.
    ///
    /// The buffer is drained *before* the HTTP call so events recorded during
    /// an in-flight flush are not lost. Network errors are silently discarded.
    pub async fn flush(&self) {
        let pending = {
            let Ok(mut guard) = self.pending.lock() else {
                return;
            };
            if guard.is_empty() {
                return;
            }
            std::mem::take(&mut *guard)
        };
        let requests: Vec<String> = pending.into_iter().map(|qs| format!("?{qs}")).collect();
        let body = serde_json::json!({ "requests": requests });
        let _ = self
            .client
            .post(&self.tracking_url)
            .json(&body)
            .send()
            .await;
    }
 }
 fn url_encode(s: &str) -> String {
    s.chars()
        .flat_map(|c| match c {
            'A'..='Z' | 'a'..='z' | '0'..='9' | '-' | '_' | '.' | '~' => {
                vec![c]
            }
            c => format!("%{:02X}", c as u32).chars().collect(),
        })
        .collect()
 }
@@ -49,7 +49,7 @@ pub enum SyncBackend {
    #[default]
    #[serde(rename = "local")]
    Local,
-    /// Sync with a self-hosted Solitaire Quest server.
+    /// Sync with a self-hosted Ferrous Solitaire server.
    #[serde(rename = "solitaire_server")]
    SolitaireServer {
        /// Base URL of the server, e.g. `"https://solitaire.example.com"`.
@@ -143,11 +143,10 @@ pub struct Settings {
    #[serde(default)]
    pub window_geometry: Option<WindowGeometry>,
    /// Identifier of the active card-art theme. Matches `meta.id` from
-    /// the theme's `theme.ron` manifest. `"default"` is the bundled
+    /// the theme's `theme.ron` manifest. `"dark"` and `"classic"` are
-    /// theme and is always present in the registry; user-supplied
+    /// always present; user-supplied themes register under their own ids.
-    /// themes register under their own ids when they're imported.
+    /// Older `settings.json` files that stored `"default"` or `"classic"`
-    /// Older `settings.json` files default cleanly to `"default"` via
+    /// are migrated to `"dark"` by [`Settings::sanitized`].
    /// `#[serde(default = ...)]`.
    #[serde(default = "default_theme_id")]
    pub selected_theme_id: String,
    /// Set to `true` once the achievement-onboarding info-toast has been
@@ -231,6 +230,33 @@ pub struct Settings {
    /// cleanly to `None` via `#[serde(default)]`.
    #[serde(default)]
    pub last_difficulty: Option<DifficultyLevel>,
    /// Custom public name displayed on the leaderboard. When `None`, the
    /// player's server `username` is used instead. Trimmed to 32 characters
    /// before submission. Older `settings.json` files written before this
    /// field existed deserialize cleanly to `None` via `#[serde(default)]`.
    #[serde(default)]
    pub leaderboard_display_name: Option<String>,
    /// When `true`, the player may drag the top card of a completed foundation
    /// pile back onto a compatible tableau column — a non-standard house rule.
    /// Off by default. Older `settings.json` files deserialize cleanly to
    /// `false` via `#[serde(default)]`.
    #[serde(default)]
    pub take_from_foundation: bool,
    /// When `true`, anonymous game-play events (game start, game won, etc.)
    /// are sent to the configured Matomo instance. Opt-in; defaults to `false`.
    /// Requires `matomo_url` to be set. Older `settings.json` files deserialize
    /// cleanly to `false` via `#[serde(default)]`.
    #[serde(default)]
    pub analytics_enabled: bool,
    /// Base URL of the Matomo instance to send events to, e.g.
    /// `"https://analytics.example.com"`. When `None` the analytics toggle has
    /// no effect. Older `settings.json` files deserialize cleanly to `None`.
    #[serde(default)]
    pub matomo_url: Option<String>,
    /// Matomo site ID assigned when the tracked site was created in Matomo.
    /// Defaults to `1` (the first site created in a fresh Matomo install).
    #[serde(default = "default_matomo_site_id")]
    pub matomo_site_id: u32,
 }
 fn default_draw_mode() -> DrawMode {
@@ -246,7 +272,7 @@ fn default_music_volume() -> f32 {
 }
 fn default_theme_id() -> String {
-    "default".to_string()
+    "dark".to_string()
 }
 /// Default tooltip-hover dwell delay in seconds. Mirrors
@@ -299,6 +325,10 @@ fn default_replay_move_interval_secs() -> f32 {
    0.45
 }
 fn default_matomo_site_id() -> u32 {
    1
 }
 /// Lower bound of the player-tunable replay-playback per-move interval,
 /// in seconds. Below this the cards barely register visually before
 /// the next move fires; the cap keeps the playback legible.
@@ -350,6 +380,11 @@ impl Default for Settings {
            disable_smart_default_size: false,
            replay_move_interval_secs: default_replay_move_interval_secs(),
            last_difficulty: None,
            leaderboard_display_name: None,
            take_from_foundation: false,
            analytics_enabled: false,
            matomo_url: None,
            matomo_site_id: default_matomo_site_id(),
        }
    }
 }
@@ -360,6 +395,13 @@ impl Settings {
    /// their respective ranges after deserialization or hand-editing of
    /// `settings.json`.
    pub fn sanitized(self) -> Self {
        // Migrate stale theme IDs: "default" was removed when the theme was
        // renamed to "dark"; "classic" was briefly the default before "dark"
        // was restored as the shipped default.
        let selected_theme_id = match self.selected_theme_id.as_str() {
            "default" | "classic" => "dark".to_string(),
            _ => self.selected_theme_id,
        };
        Self {
            sfx_volume: self.sfx_volume.clamp(0.0, 1.0),
            music_volume: self.music_volume.clamp(0.0, 1.0),
@@ -372,6 +414,7 @@ impl Settings {
            replay_move_interval_secs: self
                .replay_move_interval_secs
                .clamp(REPLAY_MOVE_INTERVAL_MIN_SECS, REPLAY_MOVE_INTERVAL_MAX_SECS),
            selected_theme_id,
            ..self
        }
    }
@@ -6,7 +6,7 @@
 //! | Struct | Backend |
 //! |---|---|
 //! | [`LocalOnlyProvider`] | No-op; used when sync is disabled |
-//! | [`SolitaireServerClient`] | Self-hosted Solitaire Quest server (JWT auth) |
+//! | [`SolitaireServerClient`] | Self-hosted Ferrous Solitaire server (JWT auth) |
 //!
 //! Use [`provider_for_backend`] to obtain a `Box<dyn SyncProvider + Send + Sync>`
 //! without matching on [`SyncBackend`] anywhere else in the codebase.
@@ -55,7 +55,7 @@ impl SyncProvider for LocalOnlyProvider {
 // SolitaireServerClient
 // ---------------------------------------------------------------------------
-/// HTTP sync client for the self-hosted Solitaire Quest server.
+/// HTTP sync client for the self-hosted Ferrous Solitaire server.
 ///
 /// Authenticates via JWT stored in the OS keychain. On a 401 response the
 /// client automatically attempts a token refresh and retries the request once
@@ -83,18 +83,96 @@ impl SolitaireServerClient {
        }
    }
    /// Authenticate with a username + password and return `(access_token, refresh_token)`.
    ///
    /// On success call [`crate::auth_tokens::store_tokens`] with the returned pair.
    /// The client's `username` field is used as the credential — the caller must
    /// construct the client with the correct username before calling this.
    pub async fn login(&self, password: &str) -> Result<(String, String), SyncError> {
        let resp = self
            .client
            .post(format!("{}/api/auth/login", self.base_url))
            .json(&serde_json::json!({
                "username": self.username,
                "password": password,
            }))
            .send()
            .await
            .map_err(|e| SyncError::Network(e.to_string()))?;
        Self::extract_auth_tokens(resp).await
    }
    /// Register a new account with a username + password and return `(access_token, refresh_token)`.
    ///
    /// On success call [`crate::auth_tokens::store_tokens`] with the returned pair.
    pub async fn register(&self, password: &str) -> Result<(String, String), SyncError> {
        let resp = self
            .client
            .post(format!("{}/api/auth/register", self.base_url))
            .json(&serde_json::json!({
                "username": self.username,
                "password": password,
            }))
            .send()
            .await
            .map_err(|e| SyncError::Network(e.to_string()))?;
        Self::extract_auth_tokens(resp).await
    }
    /// Parse `{ "access_token": "...", "refresh_token": "..." }` from an auth response.
    async fn extract_auth_tokens(resp: reqwest::Response) -> Result<(String, String), SyncError> {
        let status = resp.status();
        if !status.is_success() {
            let body: serde_json::Value = resp
                .json()
                .await
                .unwrap_or(serde_json::json!({}));
            let msg = body["error"]
                .as_str()
                .or_else(|| body["message"].as_str())
                .unwrap_or("authentication failed");
            return Err(if status == reqwest::StatusCode::CONFLICT {
                SyncError::Auth("username already taken".into())
            } else if status == reqwest::StatusCode::UNAUTHORIZED
                || status == reqwest::StatusCode::FORBIDDEN
            {
                SyncError::Auth("invalid credentials".into())
            } else if status == reqwest::StatusCode::BAD_REQUEST {
                SyncError::Auth(msg.to_string())
            } else {
                SyncError::Network(format!("server returned {status}"))
            });
        }
        let body: serde_json::Value = resp
            .json()
            .await
            .map_err(|e| SyncError::Serialization(e.to_string()))?;
        let access = body["access_token"]
            .as_str()
            .ok_or_else(|| SyncError::Serialization("missing access_token".into()))?
            .to_string();
        let refresh = body["refresh_token"]
            .as_str()
            .ok_or_else(|| SyncError::Serialization("missing refresh_token".into()))?
            .to_string();
        Ok((access, refresh))
    }
    /// Attempt to refresh the access token using the stored refresh token.
    ///
-    /// On success the new access token is persisted to the OS keychain,
+    /// The server rotates refresh tokens on each call: the response includes a
-    /// replacing the previous one. The refresh token itself is unchanged.
+    /// new refresh token that replaces the old one. Both tokens are persisted
    /// to the OS keychain on success.
    async fn refresh_token(&self) -> Result<(), SyncError> {
-        let refresh = load_refresh_token(&self.username)
+        let old_refresh = load_refresh_token(&self.username)
            .map_err(|e| SyncError::Auth(e.to_string()))?;
        let resp = self
            .client
            .post(format!("{}/api/auth/refresh", self.base_url))
-            .json(&serde_json::json!({ "refresh_token": refresh }))
+            .json(&serde_json::json!({ "refresh_token": old_refresh }))
            .send()
            .await
            .map_err(|e| SyncError::Network(e.to_string()))?;
@@ -112,9 +190,11 @@ impl SolitaireServerClient {
            .as_str()
            .ok_or_else(|| SyncError::Serialization("missing access_token in refresh response".into()))?;
-        // store_tokens replaces both access and refresh; we keep the old
+        // Server rotates refresh tokens — store the new one.
-        // refresh token unchanged so its 30-day TTL is preserved.
+        // Fall back to the old token if the field is absent (pre-rotation server).
-        store_tokens(&self.username, new_access, &refresh)
+        let new_refresh = body["refresh_token"].as_str().unwrap_or(&old_refresh);
        store_tokens(&self.username, new_access, new_refresh)
            .map_err(|e| SyncError::Auth(e.to_string()))
    }
@@ -418,3 +418,56 @@ async fn pull_after_account_deletion_returns_default_or_error() {
    let _ = delete_tokens(username);
 }
 /// **Push retry on 401.**
 ///
 /// Mirrors `jwt_refresh_on_401_succeeds` but for the `push()` path.
 /// We install an expired access token so the first push attempt returns 401,
 /// the client refreshes, and the retry push succeeds.
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn push_retries_after_401_on_expired_access_token() {
    ensure_mock_keyring();
    let base = spawn_test_server().await;
    let username = "rt_push_expiring";
    let (_real_access, real_refresh) =
        register_user_raw(&base, username, "pushexpirepass1!").await;
    let user_id = decode_sub(&_real_access);
    #[derive(serde::Serialize)]
    struct Claims {
        sub: String,
        exp: usize,
        kind: String,
    }
    let exp = (Utc::now() - chrono::Duration::hours(2)).timestamp() as usize;
    let expired_access = encode(
        &Header::default(),
        &Claims {
            sub: user_id.clone(),
            exp,
            kind: "access".into(),
        },
        &EncodingKey::from_secret(TEST_SECRET.as_bytes()),
    )
    .expect("failed to encode expired access token");
    store_tokens(username, &expired_access, &real_refresh)
        .expect("storing tokens in mock keyring must succeed");
    let client = SolitaireServerClient::new(&base, username);
    let payload = make_payload(&user_id, 17);
    // Push: server returns 401, client refreshes, retries, succeeds.
    let push_resp = client
        .push(&payload)
        .await
        .expect("push must succeed after the client transparently refreshes the access token");
    assert_eq!(
        push_resp.merged.stats.games_played, 17,
        "merged games_played must reflect what was pushed after auto-refresh"
    );
    let _ = delete_tokens(username);
 }
@@ -14,6 +14,7 @@ chrono         = { workspace = true }
 uuid           = { workspace = true }
 tokio          = { workspace = true }
 serde          = { workspace = true }
 serde_json     = { workspace = true }
 thiserror      = { workspace = true }
 usvg           = { workspace = true }
 resvg          = { workspace = true }
@@ -0,0 +1,19 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <defs>
    <pattern id="dp" x="0" y="0" width="28" height="28" patternUnits="userSpaceOnUse">
      <rect width="28" height="28" fill="#1a3a6e"/>
      <polygon points="14,2 26,14 14,26 2,14" fill="#2255aa"/>
      <polygon points="14,7 21,14 14,21 7,14" fill="#1a3a6e"/>
    </pattern>
  </defs>
  <!-- White card background -->
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14" fill="#FAFAF8"/>
  <!-- Red outer border -->
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="none" stroke="#CC1111" stroke-width="4"/>
  <!-- Navy diamond pattern inset -->
  <rect x="16" y="16" width="224" height="352" rx="8" ry="8" fill="url(#dp)"/>
  <!-- Thin red frame around pattern -->
  <rect x="16" y="16" width="224" height="352" rx="8" ry="8"
        fill="none" stroke="#CC1111" stroke-width="2"/>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="11" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#111111">10</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="11" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#111111">10</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#111111">2</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#111111">2</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#111111">3</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#111111">3</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#111111">4</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#111111">4</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#111111">5</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#111111">5</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#111111">6</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#111111">6</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#111111">7</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#111111">7</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#111111">8</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#111111">8</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#111111">9</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#111111">9</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#111111">A</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#111111">A</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#111111">J</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#111111">J</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#111111">K</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#111111">K</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#111111">Q</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#111111">Q</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,4 C 13,4 10,7 10,10 C 10,12 11,13 12,14 C 9,14 4,17 4,21 C 4,24 7,27 10,27 C 12,27 14,26 14,24 L 13,30 L 19,30 L 18,24 C 18,26 20,27 22,27 C 25,27 28,24 28,21 C 28,17 23,14 20,14 C 21,13 22,12 22,10 C 22,7 19,4 16,4 Z" fill="#111111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="11" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">10</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="11" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">10</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">2</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">2</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">3</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">3</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">4</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">4</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">5</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">5</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">6</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">6</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">7</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">7</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">8</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">8</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">9</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">9</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">A</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">A</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">J</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">J</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">K</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">K</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">Q</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">Q</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,2 L 30,16 L 16,30 L 2,16 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="11" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">10</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="11" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">10</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">2</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">2</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">3</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">3</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">4</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">4</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">5</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">5</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
@@ -0,0 +1,25 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="256" height="384" viewBox="0 0 256 384">
  <rect x="2" y="2" width="252" height="380" rx="14" ry="14"
        fill="#FAFAF8" stroke="#AAAAAA" stroke-width="1.5"/>
  <!-- Top-left corner: rank label + small suit -->
  <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
        fill="#CC1111">6</text>
  <g transform="translate(14 50) scale(0.625)">
    <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
  </g>
  <!-- Centre: large suit, 64x64 in 256x384 card -->
  <g transform="translate(96 160) scale(2)">
    <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
  </g>
  <!-- Bottom-right corner: mirrored via 180° rotation around card centre -->
  <g transform="rotate(180 128 192)">
    <text x="14" y="44" font-family="Fira Mono" font-size="36" font-weight="700"
          fill="#CC1111">6</text>
    <g transform="translate(14 50) scale(0.625)">
      <path d="M16,28 C 8,22 2,17 2,11 C 2,7 5,4 9,4 C 12,4 14,6 16,9 C 18,6 20,4 23,4 C 27,4 30,7 30,11 C 30,17 24,22 16,28 Z" fill="#CC1111"/>
    </g>
  </g>
 </svg>
--- a/Show More
+++ b/Show More