fix(ci): always install Java regardless of SDK cache hit; harden release creation

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

.gitea/workflows/android-build.yml

@@ -0,0 +1,118 @@
+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_ROOT: /opt/android-sdk
+  NDK_VERSION: "25.2.9519653"
+  BUILD_TOOLS_VERSION: "34.0.0"
+
+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"
+
+      # ── Android SDK + NDK ──────────────────────────────────────────────
+      # Cache the entire SDK root so subsequent runs skip the ~2 GB download.
+      - name: Cache Android SDK
+        uses: actions/cache@v4
+        id: sdk-cache
+        with:
+          path: ${{ env.ANDROID_SDK_ROOT }}
+          key: android-sdk-ndk${{ env.NDK_VERSION }}-bt${{ env.BUILD_TOOLS_VERSION }}
+
+      - name: Install system dependencies
+        run: sudo apt-get install -y openjdk-17-jdk-headless unzip
+
+      - name: Install Android SDK + NDK
+        if: steps.sdk-cache.outputs.cache-hit != 'true'
+        run: |
+          mkdir -p "$ANDROID_SDK_ROOT/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
+          mv /tmp/cmdtools/cmdline-tools "$ANDROID_SDK_ROOT/cmdline-tools/latest"
+          # Accept all SDK licences non-interactively.
+          yes | "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager" --licenses \
+            > /dev/null 2>&1 || true
+          "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager" \
+            "build-tools;$BUILD_TOOLS_VERSION" \
+            "platforms;android-34" \
+            "ndk;$NDK_VERSION"
+
+      - name: Export Android environment
+        run: |
+          echo "ANDROID_HOME=$ANDROID_SDK_ROOT"              >> "$GITHUB_ENV"
+          echo "ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk/$NDK_VERSION" >> "$GITHUB_ENV"
+
+      # ── 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-apk binary
+        uses: actions/cache@v4
+        id: apk-tool-cache
+        with:
+          path: ~/.cargo/bin/cargo-apk
+          key: cargo-apk-${{ 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') }}-
+
+      # ── Build ──────────────────────────────────────────────────────────
+      - name: Install cargo-apk
+        if: steps.apk-tool-cache.outputs.cache-hit != 'true'
+        run: cargo install cargo-apk --locked
+
+      - name: Build debug APK
+        run: cargo apk build --package solitaire_app --lib
+
+      # ── Artifact ───────────────────────────────────────────────────────
+      - name: Upload APK
+        uses: actions/upload-artifact@v4
+        with:
+          name: solitaire-quest-debug-${{ steps.meta.outputs.sha }}
+          path: target/debug/apk/solitaire-quest.apk
+          retention-days: 30

.gitea/workflows/android-release.yml

@@ -0,0 +1,168 @@
+name: Android Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+env:
+  ANDROID_SDK_ROOT: /opt/android-sdk
+  NDK_VERSION: "25.2.9519653"
+  BUILD_TOOLS_VERSION: "34.0.0"
+  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"
+
+      # ── Android SDK + NDK ──────────────────────────────────────────────
+      # Shared cache key with the debug workflow so a warm debug run
+      # saves the ~2 GB SDK download for the release run too.
+      - name: Cache Android SDK
+        uses: actions/cache@v4
+        id: sdk-cache
+        with:
+          path: ${{ env.ANDROID_SDK_ROOT }}
+          key: android-sdk-ndk${{ env.NDK_VERSION }}-bt${{ env.BUILD_TOOLS_VERSION }}
+
+      # Java and jq are always needed (apksigner requires Java even on cache hits).
+      - name: Install system dependencies
+        run: sudo apt-get install -y openjdk-17-jdk-headless unzip jq
+
+      - name: Install Android SDK + NDK
+        if: steps.sdk-cache.outputs.cache-hit != 'true'
+        run: |
+          mkdir -p "$ANDROID_SDK_ROOT/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
+          mv /tmp/cmdtools/cmdline-tools "$ANDROID_SDK_ROOT/cmdline-tools/latest"
+          yes | "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager" --licenses \
+            > /dev/null 2>&1 || true
+          "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager" \
+            "build-tools;$BUILD_TOOLS_VERSION" \
+            "platforms;android-34" \
+            "ndk;$NDK_VERSION"
+
+      - name: Export Android environment
+        run: |
+          echo "ANDROID_HOME=$ANDROID_SDK_ROOT"                        >> "$GITHUB_ENV"
+          echo "ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk/$NDK_VERSION"  >> "$GITHUB_ENV"
+
+      # ── 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-apk binary
+        uses: actions/cache@v4
+        id: apk-tool-cache
+        with:
+          path: ~/.cargo/bin/cargo-apk
+          key: cargo-apk-${{ 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') }}-
+
+      # ── Build ──────────────────────────────────────────────────────────
+      - name: Install cargo-apk
+        if: steps.apk-tool-cache.outputs.cache-hit != 'true'
+        run: cargo install cargo-apk --locked
+
+      - name: Build release APK
+        run: cargo apk build --release --package solitaire_app --lib
+
+      # ── Sign ───────────────────────────────────────────────────────────
+      - name: Decode keystore
+        run: echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 -d > /tmp/solitaire-release.jks
+
+      - name: Align and sign APK
+        run: |
+          TAG="${{ steps.meta.outputs.tag }}"
+          UNSIGNED="target/release/apk/solitaire-quest.apk"
+          ALIGNED="/tmp/solitaire-quest-aligned.apk"
+          SIGNED="ferrous-solitaire-${TAG}.apk"
+
+          "$ANDROID_SDK_ROOT/build-tools/$BUILD_TOOLS_VERSION/zipalign" -v 4 \
+            "$UNSIGNED" "$ALIGNED"
+
+          "$ANDROID_SDK_ROOT/build-tools/$BUILD_TOOLS_VERSION/apksigner" sign \
+            --ks /tmp/solitaire-release.jks \
+            --ks-pass "pass:${{ secrets.KEYSTORE_PASS }}" \
+            --ks-key-alias "${{ secrets.KEY_ALIAS }}" \
+            --key-pass "pass:${{ secrets.KEY_PASS }}" \
+            --out "$SIGNED" \
+            "$ALIGNED"
+
+      - name: Verify APK signature
+        run: |
+          TAG="${{ steps.meta.outputs.tag }}"
+          "$ANDROID_SDK_ROOT/build-tools/$BUILD_TOOLS_VERSION/apksigner" verify \
+            --verbose "ferrous-solitaire-${TAG}.apk"
+
+      # ── Publish ────────────────────────────────────────────────────────
+      - name: Create Gitea release
+        id: release
+        run: |
+          TAG="${{ steps.meta.outputs.tag }}"
+          # Try to create; fall back to fetching the existing release on 409.
+          RESPONSE=$(curl -s -o /tmp/release.json -w "%{http_code}" \
+            -X POST "$GITEA_API/repos/$REPO/releases" \
+            -H "Authorization: token ${{ secrets.CI_TOKEN }}" \
+            -H "Content-Type: application/json" \
+            -d "{\"tag_name\":\"$TAG\",\"name\":\"$TAG\",\"draft\":false,\"prerelease\":false}")
+          if [ "$RESPONSE" = "409" ]; then
+            curl -sf "$GITEA_API/repos/$REPO/releases/tags/$TAG" \
+              -H "Authorization: token ${{ secrets.CI_TOKEN }}" \
+              > /tmp/release.json
+          elif [ "$RESPONSE" != "201" ]; then
+            echo "Release creation failed with HTTP $RESPONSE"
+            cat /tmp/release.json
+            exit 1
+          fi
+          RELEASE_ID=$(jq -r '.id' /tmp/release.json)
+          echo "release_id=$RELEASE_ID" >> "$GITHUB_OUTPUT"
+
+      - name: Upload signed APK
+        run: |
+          TAG="${{ steps.meta.outputs.tag }}"
+          APK="ferrous-solitaire-${TAG}.apk"
+          curl -sf -X POST \
+            "$GITEA_API/repos/$REPO/releases/${{ steps.release.outputs.release_id }}/assets?name=$APK" \
+            -H "Authorization: token ${{ secrets.CI_TOKEN }}" \
+            -H "Content-Type: application/octet-stream" \
+            --data-binary @"$APK"

.gitea/workflows/docker-build.yml

@@ -0,0 +1,73 @@
+name: Build and Deploy
+
+on:
+  push:
+    branches: [master]
+    # Only run when server code changes, not when CI itself updates deploy/.
+    paths-ignore:
+      - 'deploy/**'
+      - 'argocd/**'
+      - '**.md'
+
+env:
+  REGISTRY: git.aleshym.co
+  IMAGE: git.aleshym.co/funman300/solitaire-server
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Need full history so we can push the tag-update commit back.
+          fetch-depth: 0
+          token: ${{ secrets.CI_TOKEN }}
+
+      - name: Set image tag
+        id: meta
+        run: echo "sha=${GITHUB_SHA::8}" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Gitea registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ gitea.actor }}
+          password: ${{ secrets.CI_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver-opts: network=host
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: solitaire_server/Dockerfile
+          push: true
+          tags: |
+            ${{ env.IMAGE }}:${{ steps.meta.outputs.sha }}
+            ${{ env.IMAGE }}:latest
+          cache-from: type=registry,ref=${{ env.IMAGE }}:buildcache
+          cache-to: type=registry,ref=${{ env.IMAGE }}:buildcache,mode=max
+
+      - name: Install kustomize
+        run: |
+          curl -sL "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
+          sudo mv kustomize /usr/local/bin/kustomize
+
+      - name: Pin image tag in deploy manifests
+        run: |
+          cd deploy
+          kustomize edit set image solitaire-server=${{ env.IMAGE }}:${{ steps.meta.outputs.sha }}
+
+      - name: Commit and push updated kustomization
+        run: |
+          git config user.email "ci@gitea.local"
+          git config user.name "Gitea CI"
+          git add deploy/kustomization.yaml
+          git commit -m "chore(deploy): bump image to ${{ steps.meta.outputs.sha }} [skip ci]" || true
+          git pull --rebase origin master
+          git push

.github/workflows/ci.yml

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

.gitignore

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

.sqlx/query-0e199cafab7e71b0c7f28ede85a622e38649d2fe5a73a5c715f2319f5450f729.json

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

.sqlx/query-168e205e3eb832b78d085b48281a1bae74d5a0e64c4c793c18a6400605bacf76.json

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

.sqlx/query-2b814989a6632ca930ae1e895f97a7fc3389c91d1d2abf6900a21fb0d6e94ef3.json

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

.sqlx/query-40db0910531d4418d4d58d31f0f8ea3894248406cc016020a6e211ed66da91c0.json

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

.sqlx/query-893c45c27854ba15ea611e8254ef980ced21dc64e6ca95fde56af513f86ffa46.json

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

.sqlx/query-c9ee5c64ca547f0c730379919a642bd649cbf81fc1804159101a70efabf08b33.json

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

.sqlx/query-e4eb622073cbdf868ec1568a6bdb132e962480b0530d542102c05aa9e901463b.json

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

.sqlx/query-ef7af925a8715c329dcafca5257c691e6bca31755eb5f54be47114f21fc04c8c.json

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

.sqlx/query-f23630e78ae88e72d7930184f7cd8fc67e71f3930609f1cf14061d35d6de8ec3.json

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

ARCHITECTURE.md

@@ -1,9 +1,9 @@
-# Solitaire Quest — Architecture Document
+# Ferrous Solitaire — Architecture Document
 
-> **Version:** 1.1  
+> **Version:** 1.3  
 > **Language:** Rust (Edition 2024)  
 > **Engine:** Bevy (latest stable)  
-> **Last Updated:** 2026-04-29
+> **Last Updated:** 2026-05-12
 
 ---
 
@@ -34,7 +34,7 @@
 
 ## 1. Project Overview
 
-Solitaire Quest is a cross-platform Klondike Solitaire game written in Rust, targeting macOS, Windows, and Linux desktops. It features a full progression system with XP, levels, achievements, daily challenges, and an optional self-hosted sync server so statistics and progress are available across all of a player's devices.
+Ferrous Solitaire is a cross-platform Klondike Solitaire game written in Rust, targeting macOS, Windows, and Linux desktops. It features a full progression system with XP, levels, achievements, daily challenges, and an optional self-hosted sync server so statistics and progress are available across all of a player's devices.
 
 ### Sync Backend by Platform
 
@@ -43,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` |

CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-version: unified-3.0
+version: unified-4.0
 
 ---
 
@@ -29,8 +29,9 @@ solitaire_sync/    # Shared API + merge logic
 solitaire_data/    # Persistence + sync client
 solitaire_engine/  # Bevy ECS + UI + gameplay orchestration
 solitaire_server/  # Axum backend (optional sync layer)
+solitaire_wasm/    # WASM bindings for browser-side replay player
 solitaire_app/     # Entry binary
-assets/            # Runtime assets (except audio)
+assets/            # Runtime assets (except audio + default theme)
 ```
 
 ---
@@ -72,12 +73,16 @@ These override all other instructions.
 
 * NO `unwrap()`
 * NO `panic!()` in runtime/game logic
-* All state transitions:
+* Core game state mutations MUST return:
 
 ```rust id="err_model"
 Result<T, MoveError>
 ```
 
+* Engine / UI state changes follow ECS patterns (Resources, Events) —
+  they do not return `MoveError`
+* Use `thiserror`-derived types for any new error enums outside `solitaire_core`
+
 ---
 
 ## 2.4 Threading Rules
@@ -126,10 +131,15 @@ trait SyncProvider
 ## 3.1 ECS Design
 
 * systems = single responsibility
-* communication = Events only
+* 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

CLAUDE_PROMPT_PACK.md

@@ -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

CLAUDE_SPEC.md

@@ -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"
 
 ---
 

CREDITS.md

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

Cargo.lock

@@ -6957,6 +6957,8 @@ dependencies = [
  "keyring",
  "solitaire_data",
  "solitaire_engine",
+ "tiny-skia 0.12.0",
+ "winit",
 ]
 
 [[package]]
@@ -6965,6 +6967,8 @@ version = "0.1.0"
 dependencies = [
  "ab_glyph",
  "png 0.17.16",
+ "solitaire_core",
+ "solitaire_data",
 ]
 
 [[package]]
@@ -6982,8 +6986,10 @@ version = "0.1.0"
 dependencies = [
  "async-trait",
  "axum",
+ "bevy",
  "chrono",
  "dirs",
+ "jni 0.21.1",
  "jsonwebtoken",
  "keyring-core",
  "reqwest",
@@ -7007,10 +7013,12 @@ dependencies = [
  "bevy",
  "chrono",
  "dirs",
+ "jni 0.21.1",
  "kira",
  "resvg",
  "ron",
  "serde",
+ "serde_json",
  "solitaire_core",
  "solitaire_data",
  "solitaire_sync",

Cargo.toml

@@ -31,6 +31,7 @@ keyring     = "4"
 keyring-core = "1"
 reqwest     = { version = "0.13", features = ["json", "rustls", "rustls-native-certs"], default-features = false }
 arboard     = { version = "3", default-features = false }
+jni         = { version = "0.21", default-features = false }
 
 solitaire_core   = { path = "solitaire_core" }
 solitaire_sync   = { path = "solitaire_sync" }
@@ -54,7 +55,7 @@ bevy = { version = "0.18", default-features = false, features = [
     "bevy_window",
     "custom_cursor",
     "reflect_auto_register",
-    # default_platform (desktop subset; no android/webgl/gilrs/sysinfo)
+    # default_platform (desktop subset)
     "std",
     "bevy_winit",
     "default_font",
@@ -65,6 +66,13 @@ bevy = { version = "0.18", default-features = false, features = [
     # the game in an X11 frame inside the Wayland compositor.
     "wayland",
     "x11",
+    # Android: NativeActivity glue. The feature is target-gated inside
+    # bevy_internal — desktop builds compile it out, so leaving it on
+    # the always-on list is harmless on Linux/macOS/Windows. Pairs with
+    # cargo-apk's NativeActivity wrapper (cargo-apk 0.10+ uses this by
+    # default). Switch to `android-game-activity` later if we want
+    # AndroidX GameActivity for Google Play Games integration.
+    "android-native-activity",
     # common_api
     "bevy_color",
     "bevy_image",

README.md

@@ -1,4 +1,4 @@
-# Solitaire Quest
+# Ferrous Solitaire
 
 A cross-platform Klondike Solitaire game written in Rust, with a card-theme
 system, full progression (XP / levels / achievements / daily challenges), and

README_SERVER.md

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

SESSION_HANDOFF.md

@@ -1,180 +1,177 @@
-# Solitaire Quest — Session Handoff
+# Ferrous Solitaire — Session Handoff
 
-**Last updated:** 2026-05-06 (post-v0.19.0) — Tagged + pushed at
+**Last updated:** 2026-05-12 — Leaderboard display name shipped (`03be4fc`). All commits pushed to origin.
-`6037596`. v0.19.0 closes the v0.18.0 punch list (async H-key hint,
-persistent replay share URLs), expands desktop platform fit (Wayland
-session support + monitor-aware default window size), polishes the
-win-celebration and double-click animation paths, and clears two
-test-flake contributors. A short-lived "Rusty Pixel" pixel-art card
-theme was prototyped and reverted in the same window.
 
-## Status at pause
+Phase 8 closes the self-hosted-server connection arc end-to-end: login/register
+modal, re-auth on token expiry, account deletion flow, server deployment
+artifacts (Dockerfile + docker-compose), replay upload on win, web replay
+player (WASM + HTML/CSS/JS served by the server), leaderboard opt-in/out,
+and full server integration tests.
 
-- **HEAD on origin:** `6037596` (post-tag commit; the tag itself
+---
-  points at this commit).
-- **Working tree:** modified — `CHANGELOG.md` and
-  `SESSION_HANDOFF.md` carry the v0.19.0 promotion + this refresh,
-  ready to commit.
-- **Build:** `cargo clippy --workspace --all-targets -- -D warnings`
-  clean (verified this session).
-- **Tests:** **1170 passing / 0 failing** across the workspace
-  (verified this session). One known flake remains:
-  `solitaire_engine::sync_plugin::tests::pull_failure_sets_error_status`
-  occasionally fails when cargo-test parallelism starves the
-  `AsyncComputeTaskPool` within the test's 5-update budget. Same
-  shape as the auto-save flake before v0.19.0's hardening; could be
-  fixed similarly with a wall-clock-bounded loop.
-- **Tags on origin:** `v0.9.0` through `v0.18.0` (v0.19.0 ready to
-  push once committed).
 
-## Where we are
+## Current state
 
-v0.18.0's resume-prompt menu (A–D) is closed:
+- **HEAD locally:** `03be4fc` (feat: leaderboard custom display name).
+- **HEAD on origin:** `03be4fc` (fully pushed).
+- **Working tree:** clean (only `solitaire-release.jks.bak2` untracked — intentional).
+- **Build:** `cargo clippy --workspace --all-targets -- -D warnings` clean.
+- **Tests:** **1300+ passing / 0 failing** across the workspace.
+- **Tags on origin:** `v0.9.0` through `v0.22.0`.
 
-- ~~**A — Tag v0.18.0:**~~ shipped at `bfcd05f`.
+---
-- ~~**B — Solver-on-`AsyncComputeTaskPool` for the H-key hint:**~~
-  shipped at `3e11e9e`.
-- **C — Desktop packaging:** still gated on artwork + signing
-  certs. Icon export PNGs (11 sizes, 16–1024 px) sit in
-  `artwork/` from the v0.18-era export; not yet wired into the
-  Bevy window or assembled into `.icns` / `.ico`. App icon is
-  the first natural step.
-- ~~**D — Persistent share link:**~~ shipped at `42d90b1`.
 
-The Rusty Pixel theme arc is documented as a sub-history but
+## What shipped in Phase 8 (432061c – bd388fe)
-not part of v0.19.0's content:
 
-| Commit | Status |
+| Commit | Summary |
-|---|---|
+|--------|---------|
-| `de47511` PNG-format thumbnail support | reverted |
+| `432061c` | Sync setup modal (login/register/connect/disconnect) |
-| `17e3112` `pixel_art: bool` field + nearest-sampling opt-in | reverted |
+| `6ce5564` | Re-auth on expired session + server deployment artifacts |
-| `21ec03b` bundle Rusty Pixel as `embedded://` theme | reverted |
+| `272d31f` | Account deletion flow + `handle_sync_buttons` refactor |
-| `aad8bb9` / `e41def8` / `0b3140a` reverts | landed |
+| `bd388fe` | CHANGELOG v0.23.0 documentation |
 
-The arc remains in commit history for archaeology but the
+Also shipped (pre-Phase 8 but post-v0.22.0, already in CHANGELOG):
-codebase reaches v0.19.0's HEAD identical to where it would be if
+- `solitaire_wasm` crate: WASM ReplayPlayer bindings for browser-side replay playback
-the arc had never landed.
+- Server replay API: `POST /api/replays`, `GET /api/replays/recent`, `GET /api/replays/:id`
+- Server web UI: `/replays/:id` HTML route + `ServeDir /web` static assets
+- DB migration 002: `replays` table + two indexes
+- Full server integration tests for replay endpoints
+- `push_replay` in `sync_plugin` (uploads on win, writes share URL into replay history)
+- Stats panel "Copy Share Link" button reads `share_url` from replay history
 
-### Design direction (unchanged)
+---
 
-- **Tone:** Balatro — chunky readable type, theatrical hierarchy,
+## Open punch list (ordered by priority)
-  satisfying micro-interactions.
-- **Palette:** Midnight Purple base + Balatro yellow primary + warm
-  magenta secondary.
 
-### Canonical remote
+### 1. Documentation debt (no code)
+- [x] CHANGELOG [Unreleased] → v0.23.0 — done this session
+- [x] ARCHITECTURE.md update — all 8 gaps closed, bumped to v1.3
+- [x] SESSION_HANDOFF.md update — this file
 
-`github.com/funman300/Rusty_Solitaire` is the canonical repo.
+### 2. Leaderboard wiring gaps
-Always push there.
+- [x] **Best-score auto-post.** Done (`303c78a`): `update_leaderboard_if_opted_in`
+  called from both first-push and merge paths in `sync.rs`; uses SQLite `MIN`/`MAX`
+  in the UPDATE so scores never regress on stale data.
+- [x] **Display name = username.** Done (`03be4fc`): `leaderboard_display_name:
+  Option<String>` added to `Settings`; editor modal in leaderboard panel; persists
+  to `settings.json`; `handle_opt_in_button` prefers custom name over username.
 
-## v0.19.0 (2026-05-06)
+### 3. Security hardening
+- [x] **Refresh token rotation.** Done (`b129664`): `refresh_tokens` table
+  (migration 003); jti embedded in JWT; rotate-on-use pattern; 3 integration
+  tests.
+- [x] **Sync endpoint rate limiting.** Done (`6e6f3ef`): `UserIdKeyExtractor`
+  decodes JWT for per-user identity; falls back to IP; burst 10 / 6 min
+  steady-state; integration test passes.
 
-| Area | Commits | What landed |
+### 4. Android validation
-|---|---|---|
+- [x] **Android Keystore functional test.** Done (2026-05-11, Pixel 7 AVD,
-| Async H-key hint | `3e11e9e` | New `pending_hint.rs` module: `PendingHintTask` resource, `poll_pending_hint_task` + `drop_pending_hint_on_state_change` systems, cancel-on-replace, stale-state guard via `move_count_at_spawn`. Removes the last synchronous solver hot path. |
+  Android 14): `load_access_token()` exercised via `start_pull`; logcat confirmed
-| Persistent share URLs | `42d90b1` | `Replay.share_url: Option<String>` with `#[serde(default)]`. `poll_replay_upload_result` writes into `replays[0].share_url` + persists. Stats Copy button reads from selected replay. `LastSharedReplayUrl` deleted. |
+  `NotFound` returned cleanly — no JNI panic. See `docs/android/PLAYABILITY_TODO.md` P4.
-| Auto-save flake fix | `91b7605` | `test_app` clears `PendingRestoredGame(None)` after plugin build; test re-arms the timer in a bounded loop. No production-code change. |
+- [x] **JNI clipboard functional test.** Done (2026-05-11): temporary `KEYCODE_C`
-| Wayland support | `b57db01` | Adds `wayland` to Bevy features. winit prefers Wayland when `WAYLAND_DISPLAY` is set, falls back to X11. Native Wayland surface instead of XWayland frame. |
+  hook confirmed `ClipboardManager.setPrimaryClip()` succeeds on Android 14.
-| Smart default window size | `b57db01` | New `apply_smart_default_window_size` Update system queries `PrimaryMonitor` and resizes the window to ~70 % of monitor's logical size on the first frame. Skipped when saved geometry was applied. |
+  Hook reverted. Production path requires Interaction::Pressed + non-null `share_url`.
-| Win-celebration cleanup | `55c235b` | Drops the duplicate "You Win" toast that rendered behind the WinSummary modal. Cards-fly-off cascade kept; toast removed. |
+  Note: `adb shell input tap` doesn't deliver touch events on headless AVD (documented).
-| Double-click reject animation | `d7ffb16` | Single-card double-clicks with no destination now play the same shake + sound as multi-card stack misses. Both priorities' failure paths converge on one `MoveRejectedEvent` write. |
+- [x] **`cargo apk build --lib` noisy stderr** — upstream cargo-apk bug; `--lib`
-| Double-click animation dedup | `6037596` | Drops the redundant `StateChangedEvent` write in `end_drag`'s uncommitted-drag branch; previously raced an in-flight CardAnim and restarted the slide visibly. |
+  is the canonical command (CLAUDE.md §15.1, docs/ANDROID.md). No in-repo fix possible.
 
-## Open punch list
+### 5. Feature completeness
+- [x] **Theme importer UI.** Done (`613bbf8`): "Scan for new themes" button in
+  Settings Appearance section. Shows import path label, scans user_theme_dir()
+  for .zip archives, fires InfoToastEvent per file, refreshes ThemeRegistry.
+- [x] **`mirror_achievement` removed.** Done (`549a817`): method was a no-op
+  default never overridden and never called; achievements already sync via
+  `SyncPayload` push. Deleted from trait and blanket impl.
+- [x] **WASM build script.** Done (`40d0712`): `build_wasm.sh` at repo root
+  documents `wasm-pack build --target web`, cleans up pkg metadata files,
+  includes dependency guard + install instructions.
+- [x] **Server password reset.** Done (`7514684`): `--reset-password <username>`
+  subcommand reads new password from stdin, bcrypt-hashes it, invalidates all
+  active sessions for the user.
 
-### Carried forward
+### 5b. Android UX polish (2026-05-12)
 
-- **Desktop packaging** per `ARCHITECTURE.md §17`. Eleven icon
+- [x] **UX-1 — Modal Done button in gesture zone.** `apply_safe_area_to_modal_scrims` system
-  PNG sizes (16, 24, 32, 48, 64, 96, 128, 192, 256, 512, 1024)
+  added to `SafeAreaInsetsPlugin` (`safe_area.rs`). Pads every `ModalScrim` bottom by
-  exported via `artwork/Icon Export.html` sit in `artwork/`
+  `insets.bottom / scale`. Fires on resource change + `Added<ModalScrim>`. Verified on device.
-  pending wiring. Pending: actual Bevy window-icon hookup,
+- [x] **UX-5b — Home mode glyph corruption.** Geometric Shapes (U+25xx, absent from FiraMono)
-  macOS `.icns` assembly via `iconutil`, Windows `.ico` via
+  replaced with card suits U+2660–2666 in `home_plugin.rs`. Affects Zen/Challenge/Daily mode
-  `magick convert`, Linux hicolor PNG hierarchy install,
+  selector buttons at level 5+.
-  AppImage recipe, macOS notarisation cert, Windows
+- [x] **UX-7 — Help text wrap.** Android HUD entry shortened to
-  Authenticode cert.
+  `"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.
 
-### Possible next-round candidates
+  **Note:** These 4 fixes are implemented and verified but not yet committed.
 
-- **App icon round** — wire the icon into the Bevy window via
+### 6. Testing gaps
-  `Window::icon`, generate `.icns` and `.ico` from the existing
+- [x] **Server 401 → refresh → retry path.** Done (`198df75`): both
-  PNGs. Half-day task; doesn't depend on signing certs.
+  `jwt_refresh_on_401_succeeds` (pull) and
-- **`pull_failure_sets_error_status` flake fix** — same pattern
+  `push_retries_after_401_on_expired_access_token` (push) in
-  as the auto-save flake. Wall-clock-bounded loop instead of
+  `solitaire_data/tests/sync_round_trip.rs`.
-  fixed 5-update budget. ~10 lines.
+- [x] **WASM winning-replay step-through.** Done (`b4ada2a`): greedy solver
-- **Settings UI for "open at this size on launch"** — once the
+  searches seeds 1–200 at test time; steps every move through `ReplayPlayer`;
-  smart-default-size system is shipping, expose a checkbox to
+  asserts `is_won = true` on the final `StateSnapshot`.
-  *disable* it (player who specifically wants 1280×800 every
-  time). Trivial.
-- **Persistent share link URL on selector caption** — surface
-  whether the currently-selected replay has a `share_url`
-  populated (e.g. "Replay 3 / 8 \u{2022} Shareable") so players
-  know which entries the Copy button can copy.
 
-### Process notes (from this round)
+---
 
-- **Async port template (worked again):** the H-key port
+## ARCHITECTURE.md gaps (for the update pass)
-  followed `d489e7a`'s `PendingNewGameSeed` shape one-to-one
+
-  and the second async port required no new infrastructure.
+Items missing from the doc:
-  Future async ports (e.g. moving `try_solve_with_first_move`'s
+1. `solitaire_wasm` crate (§2 workspace + §3 responsibilities)
-  full-search variant, if it ever surfaces in the picker UI)
+2. Replay API endpoints (§9 API Reference — 3 new routes)
-  should follow the same shape.
+3. Web replay player route (`/replays/:id` + `ServeDir /web`)
-- **Rusty Pixel reverted cleanly:** `git revert` of three
+4. `SyncProvider` trait: 6 added methods
-  contiguous feature commits produced a clean three-revert
+5. Theme system in Bevy plugin table (§5)
-  sequence with no manual conflict resolution. Bisect remains
+6. `Settings` new fields: `color_blind_mode`, `high_contrast_mode`,
-  fast over the full v0.19.0 history because the reverts are
+   `reduce_motion_mode`, `window_geometry`, `selected_card_back`,
-  individual commits, not a squash.
+   `selected_background`
-- **Defensive event writes pattern:** the
+7. DB migration 002 (§7)
-  `auto_save_writes_after_30_seconds` flake AND the
+8. Update "Last Updated" date
-  `end_drag` double-animation bug shared a root cause:
+
-  defensive `MessageWriter` writes that originally covered an
+---
-  edge case which no longer holds, but became load-bearing
+
-  once another system started paying attention to the event.
+## Process notes
-  Worth a periodic pass: any event write that doesn't
+
-  correspond to a real state change is a candidate for
+- **Commit attribution:** use `funman300` as git user. Co-author line:
-  removal.
+  `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
+- **Commit format:** `type(scope): description` per CLAUDE.md §7.
+- **Never commit without:** `cargo test --workspace` passing + clippy clean.
+- **Sub-agents** stage/verify only; orchestrator commits.
+- **`CARD_PLAN.md`** referenced in `theme/` module comments but not present in
+  repo. Clean up references or commit the file.
+- **Token-port pattern** (v0.20.0): when migrating tokens, walk every concrete
+  artifact downstream — PNGs, SVGs, literals, comments. Three "walked past this"
+  follow-ups in v0.21.0 all had this shape.
+
+---
 
 ## Resume prompt
 
 ```
-You are a senior Rust + Bevy developer working on Solitaire Quest.
+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.19.0 just shipped. The next natural item is
+Branch: master. v0.23.0 is the current version (HEAD: 03be4fc). Fully pushed.
-desktop-packaging follow-through, starting with the app icon.
 
-State: HEAD at 6037596 + the v0.19.0 docs commit on top (this
+READ FIRST (in order):
-session). Tag v0.19.0 points at the docs commit.
-
-READ FIRST (in order, before doing anything):
   1. SESSION_HANDOFF.md  — this file
-  2. CHANGELOG.md        — [Unreleased] is empty; [0.19.0] just landed
+  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. ~/.claude/projects/<this-project>/memory/MEMORY.md
+  6. docs/android/       — Android setup + build runbook
-                         — saved feedback / project context
+  7. ~/.claude/projects/<this-project>/memory/MEMORY.md
-                           (machine-local; may be missing on a
-                           fresh machine)
 
-DECISION TO ASK THE PLAYER FIRST:
+OPEN WORK:
-  A. App icon — wire artwork/icon-{size}.png into Bevy's
+  Phase 8 punch list is fully closed. All items verified complete.
-     Window::icon, generate .icns + .ico, drop into Linux
+  Remaining nuisance: `cargo apk build --lib` noisy stderr (cosmetic, non-blocking).
-     hicolor hierarchy. Half-day task. No cert dependency.
-  B. Desktop packaging continued — AppImage recipe, .desktop
-     file, install scripts. Larger task; unlocks distro
-     packaging. No cert dependency.
-  C. macOS / Windows signing cert acquisition — needs user
-     action; agent can't drive.
-  D. `pull_failure_sets_error_status` flake fix — small, well-
-     scoped. Same pattern as the v0.19.0 auto-save flake fix.
 
-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 is already
-    wired on this machine.
 
-OPEN AT THE START: ask which of A–D. Don't pick unilaterally.
+  Commit those first, then suggest Phase 9 planning.
 ```

argocd/application.yaml

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

build_wasm.sh

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

deploy/deployment.yaml

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

deploy/ingress-analytics.yaml

@@ -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