Add setup-node step before JS syntax check

The self-hosted runner doesn't have Node.js in PATH.

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

.bazelrc

@@ -5,6 +5,10 @@ common --ui_event_filters=-INFO
 
 common --enable_bzlmod
 
+# Use pre-built protoc binary instead of compiling from source
+common --incompatible_enable_proto_toolchain_resolution
+common --@com_google_protobuf//bazel/toolchains:prefer_prebuilt_protoc=true
+
 # Don't use toolchains_llvm for the swift app build
 common:mactools --ignore_dev_dependency
 
@@ -29,14 +33,20 @@ common --javacopt="-Xlint:-options"
 # Use host_linkopt for macOS-specific flags to avoid passing them to Linux cross-compilation
 common:macos --host_linkopt=-Wl,-no_warn_duplicate_libraries
 
+# Workaround for grpc cf_event_engine build error on macOS with Bazel 7.x
+# See: https://github.com/grpc/grpc/issues/37619
+common:macos --features=-module_maps
+
 # Fix Xcode version caching issue - avoids need for `bazel clean --expunge` after Xcode updates
 common:macos --repo_env=DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
 
-common --java_language_version=17
-common --java_runtime_version=remotejdk_17
-common --tool_java_language_version=17
-common --tool_java_runtime_version=remotejdk_17
+common --java_language_version=25
+common --java_runtime_version=remotejdk_25
+common --tool_java_language_version=25
+common --tool_java_runtime_version=remotejdk_25
 
 # Workspace status for build stamping (git commit, timestamp)
+# Only targets with stamp=1 will use these values; we intentionally
+# do NOT set "common --stamp" so non-stamped targets can share the
+# remote cache across CI workflows.
 common --workspace_status_command=tools/workspace_status.sh
-common --stamp

.bazelversion

@@ -1 +1 @@
-7.6.1
+8.5.1

.gitattributes

@@ -10,3 +10,20 @@
 src/main/csharp/**/GUI[[:space:]]Pro[[:space:]]Kit*/**/*.ttf !filter !diff !merge
 src/main/csharp/**/Modern[[:space:]]UI[[:space:]]Pack/**/*.ttf !filter !diff !merge
 *.herodata filter=lfs diff=lfs merge=lfs -text
+*.ogg filter=lfs diff=lfs merge=lfs -text
+
+# Unity Smart Merge - use UnityYAMLMerge for Unity files
+# Requires configuring unityyamlmerge in ~/.gitconfig:
+#   [merge]
+#   tool = unityyamlmerge
+#   [mergetool "unityyamlmerge"]
+#   trustExitCode = false
+#   cmd = '/Applications/Unity/Hub/Editor/*/Unity.app/Contents/Tools/UnityYAMLMerge' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"
+*.unity merge=unityyamlmerge
+*.prefab merge=unityyamlmerge
+*.asset merge=unityyamlmerge
+*.mat merge=unityyamlmerge
+*.anim merge=unityyamlmerge
+*.controller merge=unityyamlmerge
+*.physicsMaterial2D merge=unityyamlmerge
+*.physicMaterial merge=unityyamlmerge

.github/workflows/artifact_storage_check.yml

@@ -0,0 +1,39 @@
+name: Artifact Storage Check
+
+on:
+  schedule:
+    # Run every 6 hours
+    - cron: '0 */6 * * *'
+  workflow_dispatch:
+
+jobs:
+  check-storage:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check artifact storage size
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Calculate total artifact storage
+          total_bytes=$(gh api "repos/${{ github.repository }}/actions/artifacts" \
+            --paginate -q '.artifacts[].size_in_bytes' | awk '{sum+=$1} END {print sum}')
+
+          total_mb=$((total_bytes / 1024 / 1024))
+          echo "Total artifact storage: ${total_mb} MB"
+
+          # Fail if over 500MB
+          if [ "$total_mb" -gt 500 ]; then
+            echo "::error::Artifact storage is ${total_mb} MB, which exceeds the 500 MB threshold!"
+            echo ""
+            echo "Largest artifacts:"
+            # Save to temp file to avoid SIGPIPE/broken pipe errors with head
+            gh api "repos/${{ github.repository }}/actions/artifacts" \
+              --paginate -q '.artifacts[] | "\(.size_in_bytes)\t\(.name)\t\(.created_at)"' > /tmp/artifacts.txt
+            sort -rn /tmp/artifacts.txt | head -20 | \
+              awk -F'\t' '{printf "%d MB\t%s\t%s\n", $1/1024/1024, $2, $3}'
+            rm -f /tmp/artifacts.txt
+            exit 1
+          fi
+
+          echo "Storage is within acceptable limits."

.github/workflows/auth_build.yml

@@ -9,7 +9,9 @@ on:
       - 'src/main/protobuf/net/eagle0/eagle/api/auth.proto'
       - 'src/main/protobuf/net/eagle0/eagle/api/admin/**'
       - 'src/main/protobuf/net/eagle0/eagle/internal/auth_internal.proto'
+      - 'src/main/resources/net/eagle0/attributions.json'
       - 'ci/BUILD.bazel'
+      - '.bazelrc'
       - '.github/workflows/auth_build.yml'
   workflow_dispatch:
     inputs:
@@ -39,7 +41,8 @@ jobs:
           set -ex
 
           # Build auth server image (Go binary has explicit goos/goarch in BUILD.bazel)
-          bazel build //ci:auth_server_image
+          # --stamp is needed for authservice x_defs (git commit, build time)
+          bazel build --stamp //ci:auth_server_image
 
           # Save the resolved path before any other bazel command changes bazel-bin symlink
           IMAGE_PATH=$(readlink -f bazel-bin/ci/auth_server_image)
@@ -76,8 +79,14 @@ jobs:
           # Build the push target to get crane in runfiles
           bazel build //ci:auth_server_push
 
-          # Use crane directly for push
-          CRANE="bazel-bin/ci/push_auth_server_push.sh.runfiles/rules_oci~~oci~oci_crane_darwin_arm64/crane"
+          # Find crane binary in runfiles (path varies by Bazel version)
+          RUNFILES="bazel-bin/ci/push_auth_server_push.sh.runfiles"
+          CRANE=$(find "$RUNFILES" -path "*darwin*" -name crane 2>/dev/null | head -1)
+          if [ -z "$CRANE" ] || [ ! -x "$CRANE" ]; then
+            echo "ERROR: crane not found in runfiles"
+            find "$RUNFILES" -name crane 2>/dev/null || echo "No crane found at all"
+            exit 1
+          fi
           echo "Using crane: $CRANE"
 
           # Push with SHA tag
@@ -104,6 +113,14 @@ jobs:
       DISCORD_CLIENT_SECRET: ${{ secrets.DISCORD_CLIENT_SECRET }}
       GOOGLE_CLIENT_ID: ${{ secrets.GOOGLE_CLIENT_ID }}
       GOOGLE_CLIENT_SECRET: ${{ secrets.GOOGLE_CLIENT_SECRET }}
+      GH_OAUTH_CLIENT_ID: ${{ secrets.GH_OAUTH_CLIENT_ID }}
+      GH_OAUTH_CLIENT_SECRET: ${{ secrets.GH_OAUTH_CLIENT_SECRET }}
+      APPLE_SIGNIN_CLIENT_ID: ${{ secrets.APPLE_SIGNIN_CLIENT_ID }}
+      APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+      APPLE_SIGNIN_KEY_ID: ${{ secrets.APPLE_SIGNIN_KEY_ID }}
+      APPLE_SIGNIN_PRIVATE_KEY: ${{ secrets.APPLE_SIGNIN_PRIVATE_KEY }}
+      TWITCH_CLIENT_ID: ${{ secrets.TWITCH_CLIENT_ID }}
+      TWITCH_CLIENT_SECRET: ${{ secrets.TWITCH_CLIENT_SECRET }}
       JWT_PRIVATE_KEY: ${{ secrets.JWT_PRIVATE_KEY }}
       FASTMAIL_API_TOKEN: ${{ secrets.FASTMAIL_API_TOKEN }}
       FASTMAIL_FROM_EMAIL: ${{ secrets.FASTMAIL_FROM_EMAIL }}
@@ -112,16 +129,6 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Copy update-env script to server
-        uses: appleboy/scp-action@v0.1.7
-        with:
-          host: ${{ secrets.DO_DROPLET_IP }}
-          username: deploy
-          key: ${{ secrets.DO_SSH_KEY }}
-          source: "deploy/update-env.sh,deploy/env.template"
-          target: /opt/eagle0/
-          strip_components: 1
-
       - name: Deploy auth service to production
         uses: appleboy/ssh-action@v1.0.3
         with:
@@ -129,51 +136,75 @@ jobs:
           username: deploy
           key: ${{ secrets.DO_SSH_KEY }}
           script_stop: true
-          envs: AUTH_IMAGE,DISCORD_CLIENT_ID,DISCORD_CLIENT_SECRET,GOOGLE_CLIENT_ID,GOOGLE_CLIENT_SECRET,JWT_PRIVATE_KEY,FASTMAIL_API_TOKEN,FASTMAIL_FROM_EMAIL,FASTMAIL_FROM_NAME
+          envs: AUTH_IMAGE,DISCORD_CLIENT_ID,DISCORD_CLIENT_SECRET,GOOGLE_CLIENT_ID,GOOGLE_CLIENT_SECRET,GH_OAUTH_CLIENT_ID,GH_OAUTH_CLIENT_SECRET,APPLE_SIGNIN_CLIENT_ID,APPLE_TEAM_ID,APPLE_SIGNIN_KEY_ID,APPLE_SIGNIN_PRIVATE_KEY,TWITCH_CLIENT_ID,TWITCH_CLIENT_SECRET,JWT_PRIVATE_KEY,FASTMAIL_API_TOKEN,FASTMAIL_FROM_EMAIL,FASTMAIL_FROM_NAME
           script: |
             set -x
             cd /opt/eagle0
 
-            # Update env vars using shared script (preserves vars set by other workflows)
-            chmod +x update-env.sh
-            ./update-env.sh \
-              "AUTH_IMAGE=${AUTH_IMAGE}" \
-              "DISCORD_CLIENT_ID=${DISCORD_CLIENT_ID}" \
-              "DISCORD_CLIENT_SECRET=${DISCORD_CLIENT_SECRET}" \
-              "GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}" \
-              "GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}" \
-              "JWT_PRIVATE_KEY=${JWT_PRIVATE_KEY}" \
-              "FASTMAIL_API_TOKEN=${FASTMAIL_API_TOKEN}" \
-              "FASTMAIL_FROM_EMAIL=${FASTMAIL_FROM_EMAIL}" \
-              "FASTMAIL_FROM_NAME=${FASTMAIL_FROM_NAME}"
+            # Export env vars for docker compose (appleboy/ssh-action sets them but doesn't export)
+            export AUTH_IMAGE="${AUTH_IMAGE}"
+            export DISCORD_CLIENT_ID="${DISCORD_CLIENT_ID}"
+            export DISCORD_CLIENT_SECRET="${DISCORD_CLIENT_SECRET}"
+            export GOOGLE_CLIENT_ID="${GOOGLE_CLIENT_ID}"
+            export GOOGLE_CLIENT_SECRET="${GOOGLE_CLIENT_SECRET}"
+            export GH_OAUTH_CLIENT_ID="${GH_OAUTH_CLIENT_ID}"
+            export GH_OAUTH_CLIENT_SECRET="${GH_OAUTH_CLIENT_SECRET}"
+            export APPLE_SIGNIN_CLIENT_ID="${APPLE_SIGNIN_CLIENT_ID}"
+            export APPLE_TEAM_ID="${APPLE_TEAM_ID}"
+            export APPLE_SIGNIN_KEY_ID="${APPLE_SIGNIN_KEY_ID}"
+            export APPLE_SIGNIN_PRIVATE_KEY="${APPLE_SIGNIN_PRIVATE_KEY}"
+            export TWITCH_CLIENT_ID="${TWITCH_CLIENT_ID}"
+            export TWITCH_CLIENT_SECRET="${TWITCH_CLIENT_SECRET}"
+            export JWT_PRIVATE_KEY="${JWT_PRIVATE_KEY}"
+            export FASTMAIL_API_TOKEN="${FASTMAIL_API_TOKEN}"
+            export FASTMAIL_FROM_EMAIL="${FASTMAIL_FROM_EMAIL}"
+            export FASTMAIL_FROM_NAME="${FASTMAIL_FROM_NAME}"
 
             # Login to registry
             echo "${{ secrets.DO_REGISTRY_TOKEN }}" | docker login registry.digitalocean.com -u "${{ secrets.DO_REGISTRY_TOKEN }}" --password-stdin
 
             echo "Deploying auth service: $AUTH_IMAGE"
 
-            # Use crane to pull image
-            echo "Installing crane..."
-            curl -sL https://github.com/google/go-containerregistry/releases/download/v0.20.2/go-containerregistry_Linux_x86_64.tar.gz | tar xzf - crane
-            chmod +x crane
+            # Pull the image directly (docker is already logged in)
+            echo "Pulling Auth image..."
+            docker pull "${AUTH_IMAGE}" || { echo "ERROR: Failed to pull auth image"; exit 1; }
 
-            echo "Pulling Auth image with crane..."
-            ./crane pull "${AUTH_IMAGE}" auth.tar || { echo "ERROR: Failed to pull auth image"; exit 1; }
-            echo "Loading Auth image into Docker..."
-            docker load -i auth.tar
-            rm auth.tar
-            rm ./crane
+            # Tag as :latest locally so any fallback uses correct image
+            docker tag "${AUTH_IMAGE}" registry.digitalocean.com/eagle0/auth-server:latest
 
-            # Only recreate the auth container (not eagle, shardok, etc.)
-            docker compose -f docker-compose.prod.yml up -d --no-deps --force-recreate auth
+            # Debug: check environment and .env file
+            echo "DEBUG: AUTH_IMAGE=$AUTH_IMAGE"
+            env | grep AUTH || echo "AUTH_IMAGE not in env output"
+            if [ -f .env ]; then
+              echo "DEBUG: .env file contents related to AUTH:"
+              grep AUTH .env || echo "No AUTH in .env"
+            fi
+
+            # Recreate auth container - pass AUTH_IMAGE explicitly on command line
+            AUTH_IMAGE="${AUTH_IMAGE}" docker compose -f docker-compose.prod.yml up -d --no-deps --force-recreate auth
 
             # Wait for health check
             sleep 5
-            docker compose -f docker-compose.prod.yml ps auth
 
-            # Verify container is using correct image
+            # Verify container is using the correct image
+            # Note: docker-compose may use :latest tag (which we tagged to the correct image)
             echo "=== Verifying auth container image ==="
-            docker compose -f docker-compose.prod.yml images auth
+            RUNNING_IMAGE=$(docker inspect auth-server --format '{{.Config.Image}}')
+            RUNNING_DIGEST=$(docker inspect auth-server --format '{{.Image}}')
+            EXPECTED_DIGEST=$(docker inspect "${AUTH_IMAGE}" --format '{{.Id}}')
+            echo "Expected image: ${AUTH_IMAGE}"
+            echo "Running image:  ${RUNNING_IMAGE}"
+            echo "Expected digest: ${EXPECTED_DIGEST}"
+            echo "Running digest:  ${RUNNING_DIGEST}"
+
+            if [ "$RUNNING_DIGEST" != "$EXPECTED_DIGEST" ]; then
+              echo "ERROR: Container is running wrong image!"
+              exit 1
+            fi
+            echo "Image digests match - correct image is running"
+
+            # Show container status
+            docker compose -f docker-compose.prod.yml ps auth
 
             # Cleanup old images
             docker image prune -f

.github/workflows/bazel_cache_cleanup.yml

@@ -0,0 +1,38 @@
+name: Bazel Cache Cleanup
+
+on:
+  schedule:
+    # Run weekly on Sunday at 00:00 UTC
+    - cron: '0 0 * * 0'
+  workflow_dispatch:  # Allow manual trigger
+
+jobs:
+  cleanup:
+    runs-on: [self-hosted, bazel]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          lfs: false
+
+      - name: Show disk usage before cleanup
+        run: |
+          echo "=== Disk usage before cleanup ==="
+          BAZEL_USER_ROOT="/private/var/tmp/_bazel_$(whoami)"
+          echo "Bazel user root: $BAZEL_USER_ROOT"
+          du -sh "$BAZEL_USER_ROOT" 2>/dev/null || echo "Not found"
+          df -h .
+
+      - name: Run bazel clean
+        run: |
+          echo "=== Running bazel clean ==="
+          bazel clean
+          echo "Clean complete"
+
+      - name: Show disk usage after cleanup
+        run: |
+          echo "=== Disk usage after cleanup ==="
+          BAZEL_USER_ROOT="/private/var/tmp/_bazel_$(whoami)"
+          du -sh "$BAZEL_USER_ROOT" 2>/dev/null || echo "Not found"
+          df -h .

.github/workflows/bazel_test.yml

@@ -8,6 +8,7 @@ on:
       - 'WORKSPACE'
       - 'MODULE.bazel'
       - 'BUILD.bazel'
+      - '.bazelrc'
       - '.github/workflows/bazel_test.yml'
       - '!src/main/csharp/**'
       - '!src/test/csharp/**'
@@ -17,25 +18,55 @@ on:
       - 'WORKSPACE'
       - 'MODULE.bazel'
       - 'BUILD.bazel'
+      - '.bazelrc'
       - '.github/workflows/bazel_test.yml'
       - '!src/main/csharp/**'
       - '!src/test/csharp/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 permissions:
   contents: read
 
 jobs:
+  lint:
+    runs-on: [self-hosted, bazel]
+    steps:
+    - name: Clean workspace
+      run: |
+        git sparse-checkout disable 2>/dev/null || true
+        git config --local core.sparseCheckout false 2>/dev/null || true
+        git config --local --unset extensions.worktreeConfig 2>/dev/null || true
+        rm -f .git/info/sparse-checkout .git/config.worktree 2>/dev/null || true
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        lfs: false
+    - name: Check BUILD.bazel dependencies
+      run: ./scripts/check_build_deps.sh --strict
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 'lts/*'
+    - name: Check JavaScript syntax
+      run: node --check src/main/go/net/eagle0/admin_server/static/map_editor.js
+
   test:
     runs-on: [self-hosted, bazel]
-
     steps:
+    - name: Clean workspace
+      run: |
+        git sparse-checkout disable 2>/dev/null || true
+        git config --local core.sparseCheckout false 2>/dev/null || true
+        git config --local --unset extensions.worktreeConfig 2>/dev/null || true
+        rm -f .git/info/sparse-checkout .git/config.worktree 2>/dev/null || true
     - name: Checkout repository
       uses: actions/checkout@v4
       with:
         lfs: false
     - name: Run tests
-      id: test
-      continue-on-error: true
       run: bazel test --build_event_json_file=test.json //src/test/... //src/main/go/...
     - name: Collect failed test logs
       if: always()
@@ -75,6 +106,7 @@ jobs:
       with:
         name: test.json
         path: test.json
+        retention-days: 5
     - name: Archive failed test logs
       if: always()
       uses: actions/upload-artifact@v4
@@ -82,6 +114,4 @@ jobs:
         name: failed-test-logs
         path: failed_test_logs/
         if-no-files-found: ignore
-    - name: Fail if tests failed
-      if: steps.test.outcome == 'failure'
-      run: exit 1
+        retention-days: 5

.github/workflows/build_sysroot.yml

@@ -37,6 +37,7 @@ jobs:
         with:
           name: ubuntu-noble-sysroot-amd64
           path: tools/sysroot/output/
+          retention-days: 1
 
       - name: Install AWS CLI
         run: |
@@ -98,6 +99,7 @@ jobs:
         with:
           name: ubuntu-noble-sysroot-arm64
           path: tools/sysroot/output/
+          retention-days: 1
 
       - name: Install AWS CLI
         run: |

.github/workflows/docker_build.yml

@@ -5,12 +5,21 @@ on:
     branches: [ "main" ]
     paths:
       # Note: C++ changes trigger shardok_arm64_build.yml instead
+      # Note: Auth changes trigger auth_build.yml instead
+      # Note: Windows installer changes trigger installer_build.yml instead
       - 'src/main/go/**'
+      - '!src/main/go/net/eagle0/authservice/**'
+      - '!src/main/go/net/eagle0/authcli/**'
+      - '!src/main/go/net/eagle0/clients/**'
       - 'src/main/scala/**'
       - 'src/main/protobuf/**'
+      - '!src/main/protobuf/net/eagle0/eagle/api/auth.proto'
+      - '!src/main/protobuf/net/eagle0/eagle/api/admin/**'
+      - '!src/main/protobuf/net/eagle0/eagle/internal/auth_internal.proto'
       - 'src/main/resources/**'
       - 'ci/BUILD.bazel'
       - 'MODULE.bazel'
+      - '.bazelrc'
       - 'docker-compose.prod.yml'
       - 'nginx/**'
       - '.github/workflows/docker_build.yml'
@@ -22,13 +31,16 @@ on:
         default: 'false'
         type: boolean
 
-# Only allow one deployment at a time to prevent race conditions
+# Only allow one deployment at a time; queue new ones (never cancel a running deploy).
+# The build-all job checks if it's still the latest commit on main and skips if not,
+# so intermediate commits don't waste time building when a newer one is already queued.
 concurrency:
   group: docker-build-deploy
-  cancel-in-progress: false  # Don't cancel running deployments, queue new ones
+  cancel-in-progress: false
 
 permissions:
   contents: read
+  actions: read
 
 jobs:
   # Single consolidated build job - builds all images with one bazel invocation
@@ -41,30 +53,53 @@ jobs:
       admin_image_tag: ${{ steps.push-images.outputs.admin_image_tag }}
       jfr_sidecar_image_tag: ${{ steps.push-images.outputs.jfr_sidecar_image_tag }}
     steps:
+      - name: Skip if superseded
+        id: check-latest
+        run: |
+          # Check if there's a newer run of this workflow waiting in the queue.
+          # If so, skip this build — the queued run will deploy a newer commit.
+          QUEUED=$(curl -s -H "Authorization: Bearer $GH_TOKEN" \
+            "https://api.github.com/repos/${{ github.repository }}/actions/workflows/docker_build.yml/runs?status=queued" \
+            | python3 -c "import sys,json; runs=json.load(sys.stdin).get('workflow_runs',[]); print(len([r for r in runs if r['run_number'] > ${{ github.run_number }}]))")
+          if [ "$QUEUED" -gt 0 ]; then
+            echo "::notice::Skipping build — $QUEUED newer run(s) queued for this workflow"
+            echo "skip=true" >> $GITHUB_OUTPUT
+          fi
+        env:
+          GH_TOKEN: ${{ github.token }}
+
       - name: Checkout repository
+        if: steps.check-latest.outputs.skip != 'true'
         uses: actions/checkout@v4
         with:
           lfs: false
 
+      - name: Fetch LFS files needed for admin server
+        if: steps.check-latest.outputs.skip != 'true'
+        run: git lfs pull --include="src/main/go/net/eagle0/admin_server/static/tiles/*"
+
       - name: Build all Docker images
+        if: steps.check-latest.outputs.skip != 'true'
         id: build-all
         run: |
           set -ex
 
           # Build ALL images in a single bazel command - Bazel parallelizes internally
           # Note: Shardok is built separately for ARM64 and deployed to Hetzner
+          # --stamp is needed for admin_server x_defs (git commit, build time)
           echo "=== Building Docker images ==="
           bazel build \
+            --stamp \
             --platforms=//:linux_x86_64 \
             --extra_toolchains=@llvm_toolchain_linux//:all \
             //ci:eagle_server_image \
             //ci:admin_server_image \
             //ci:jfr_sidecar_image \
-            //src/main/go/net/eagle0/warmup:warmup_linux_amd64
+            //ci:warmup_tar
 
-          # Copy warmup binary to scripts/ for deployment
+          # Extract warmup binary from tar for deployment
           mkdir -p scripts/bin
-          cp bazel-bin/src/main/go/net/eagle0/warmup/warmup_linux_amd64_/warmup_linux_amd64 scripts/bin/warmup
+          tar -xf bazel-bin/ci/warmup_tar.tar -C scripts/bin --strip-components=1
 
           # Save all image paths before any other bazel command changes bazel-bin symlink
           EAGLE_PATH=$(readlink -f bazel-bin/ci/eagle_server_image)
@@ -80,8 +115,16 @@ jobs:
           echo "Admin: $ADMIN_PATH"
           echo "JFR Sidecar: $JFR_PATH"
 
+      - name: Upload warmup binary
+        if: steps.check-latest.outputs.skip != 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: warmup-binary
+          path: scripts/bin/warmup
+          retention-days: 1
+
       - name: Login to DigitalOcean Container Registry
-        if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.push_images == 'true')
+        if: steps.check-latest.outputs.skip != 'true' && (github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.push_images == 'true'))
         env:
           DO_TOKEN: ${{ secrets.DO_REGISTRY_TOKEN }}
         run: |
@@ -101,44 +144,59 @@ jobs:
 
           GIT_SHA=$(git rev-parse --short=8 HEAD)
 
-          # Get crane from push target runfiles
-          bazel build //ci:eagle_server_push
-          CRANE="bazel-bin/ci/push_eagle_server_push.sh.runfiles/rules_oci~~oci~oci_crane_darwin_arm64/crane"
-
-          if [ ! -e "$CRANE" ]; then
-            # Fallback: find any Darwin crane
-            RUNFILES="bazel-bin/ci/push_eagle_server_push.sh.runfiles"
-            CRANE=$(find "$RUNFILES" -path "*darwin*" -name crane 2>/dev/null | head -1)
+          # Get crane (cached across runs to avoid rebuilding bazel target)
+          CRANE_VERSION="v0.20.2"
+          CRANE_DIR="${HOME}/.local/bin"
+          CRANE="${CRANE_DIR}/crane"
+          if [ ! -x "$CRANE" ] || ! "$CRANE" version 2>/dev/null | grep -q "0.20.2"; then
+            echo "Installing crane ${CRANE_VERSION}..."
+            mkdir -p "$CRANE_DIR"
+            curl -sL "https://github.com/google/go-containerregistry/releases/download/${CRANE_VERSION}/go-containerregistry_Darwin_arm64.tar.gz" | tar xzf - -C "$CRANE_DIR" crane
+            chmod +x "$CRANE"
+          else
+            echo "Using cached crane at $CRANE"
           fi
 
-          if [ -z "$CRANE" ] || [ ! -e "$CRANE" ]; then
-            echo "ERROR: crane not found"
-            exit 1
-          fi
-          echo "Using crane: $CRANE"
-
-          # Push Eagle image
+          # Set up image paths and tags
           EAGLE_IMAGE="${{ steps.build-all.outputs.eagle_path }}"
           EAGLE_TAG="registry.digitalocean.com/eagle0/eagle-server:${GIT_SHA}"
-          echo "Pushing Eagle: $EAGLE_TAG"
-          $CRANE push "$EAGLE_IMAGE" "$EAGLE_TAG"
-          $CRANE copy "$EAGLE_TAG" "registry.digitalocean.com/eagle0/eagle-server:latest"
-          echo "eagle_image_tag=$EAGLE_TAG" >> $GITHUB_OUTPUT
-
-          # Push Admin image
           ADMIN_IMAGE="${{ steps.build-all.outputs.admin_path }}"
           ADMIN_TAG="registry.digitalocean.com/eagle0/admin-server:${GIT_SHA}"
-          echo "Pushing Admin: $ADMIN_TAG"
-          $CRANE push "$ADMIN_IMAGE" "$ADMIN_TAG"
-          $CRANE copy "$ADMIN_TAG" "registry.digitalocean.com/eagle0/admin-server:latest"
-          echo "admin_image_tag=$ADMIN_TAG" >> $GITHUB_OUTPUT
-
-          # Push JFR Sidecar image
           JFR_IMAGE="${{ steps.build-all.outputs.jfr_path }}"
           JFR_TAG="registry.digitalocean.com/eagle0/jfr-sidecar:${GIT_SHA}"
+
+          # Push all three images in parallel
+          echo "Pushing Eagle: $EAGLE_TAG"
+          $CRANE push "$EAGLE_IMAGE" "$EAGLE_TAG" &
+          PID_EAGLE=$!
+
+          echo "Pushing Admin: $ADMIN_TAG"
+          $CRANE push "$ADMIN_IMAGE" "$ADMIN_TAG" &
+          PID_ADMIN=$!
+
           echo "Pushing JFR Sidecar: $JFR_TAG"
-          $CRANE push "$JFR_IMAGE" "$JFR_TAG"
-          $CRANE copy "$JFR_TAG" "registry.digitalocean.com/eagle0/jfr-sidecar:latest"
+          $CRANE push "$JFR_IMAGE" "$JFR_TAG" &
+          PID_JFR=$!
+
+          # Wait for all pushes to complete
+          PUSH_FAILED=0
+          wait $PID_EAGLE || PUSH_FAILED=1
+          wait $PID_ADMIN || PUSH_FAILED=1
+          wait $PID_JFR   || PUSH_FAILED=1
+          if [ $PUSH_FAILED -ne 0 ]; then
+            echo "ERROR: One or more image pushes failed"
+            exit 1
+          fi
+          echo "All images pushed, tagging :latest..."
+
+          # Tag :latest in parallel
+          $CRANE copy "$EAGLE_TAG" "registry.digitalocean.com/eagle0/eagle-server:latest" &
+          $CRANE copy "$ADMIN_TAG" "registry.digitalocean.com/eagle0/admin-server:latest" &
+          $CRANE copy "$JFR_TAG" "registry.digitalocean.com/eagle0/jfr-sidecar:latest" &
+          wait
+
+          echo "eagle_image_tag=$EAGLE_TAG" >> $GITHUB_OUTPUT
+          echo "admin_image_tag=$ADMIN_TAG" >> $GITHUB_OUTPUT
           echo "jfr_sidecar_image_tag=$JFR_TAG" >> $GITHUB_OUTPUT
 
           echo "=== All images pushed successfully ==="
@@ -153,15 +211,28 @@ jobs:
       ADMIN_IMAGE: ${{ needs.build-all.outputs.admin_image_tag }}
       JFR_SIDECAR_IMAGE: ${{ needs.build-all.outputs.jfr_sidecar_image_tag }}
       OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
       GPT_MODEL_NAME: ${{ secrets.GPT_MODEL_NAME }}
       EAGLE_ENABLE_S3: ${{ secrets.EAGLE_ENABLE_S3 }}
       DO_SPACES_ACCESS_KEY: ${{ secrets.DO_SPACES_ACCESS_KEY }}
       DO_SPACES_SECRET_KEY: ${{ secrets.DO_SPACES_SECRET_KEY }}
+      # Admin server uses different credentials (for eagle0-assets bucket)
+      ADMIN_S3_ACCESS_KEY: ${{ secrets.ACCESS_KEY_ID }}
+      ADMIN_S3_SECRET_KEY: ${{ secrets.SECRET_KEY }}
       JWT_PRIVATE_KEY: ${{ secrets.JWT_PRIVATE_KEY }}
       DISCORD_CLIENT_ID: ${{ secrets.DISCORD_CLIENT_ID }}
       DISCORD_CLIENT_SECRET: ${{ secrets.DISCORD_CLIENT_SECRET }}
       GOOGLE_CLIENT_ID: ${{ secrets.GOOGLE_CLIENT_ID }}
       GOOGLE_CLIENT_SECRET: ${{ secrets.GOOGLE_CLIENT_SECRET }}
+      GH_OAUTH_CLIENT_ID: ${{ secrets.GH_OAUTH_CLIENT_ID }}
+      GH_OAUTH_CLIENT_SECRET: ${{ secrets.GH_OAUTH_CLIENT_SECRET }}
+      APPLE_SIGNIN_CLIENT_ID: ${{ secrets.APPLE_SIGNIN_CLIENT_ID }}
+      APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+      APPLE_SIGNIN_KEY_ID: ${{ secrets.APPLE_SIGNIN_KEY_ID }}
+      APPLE_SIGNIN_PRIVATE_KEY: ${{ secrets.APPLE_SIGNIN_PRIVATE_KEY }}
+      TWITCH_CLIENT_ID: ${{ secrets.TWITCH_CLIENT_ID }}
+      TWITCH_CLIENT_SECRET: ${{ secrets.TWITCH_CLIENT_SECRET }}
       SHARDOK_ADDRESS: ${{ secrets.SHARDOK_ADDRESS }}
       SHARDOK_AUTH_TOKEN: ${{ secrets.SHARDOK_AUTH_TOKEN }}
       SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
@@ -170,9 +241,12 @@ jobs:
       FASTMAIL_FROM_NAME: ${{ secrets.FASTMAIL_FROM_NAME }}
       DO_DROPLET_IP: ${{ secrets.DO_DROPLET_IP }}
       DO_REGISTRY_TOKEN: ${{ secrets.DO_REGISTRY_TOKEN }}
+      NOTIFY_SECRET: ${{ secrets.EAGLE_NOTIFY_SECRET }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          lfs: false
 
       - name: Setup SSH key
         run: |
@@ -181,27 +255,26 @@ jobs:
           chmod 600 ~/.ssh/deploy_key
           ssh-keyscan -H "$DO_DROPLET_IP" >> ~/.ssh/known_hosts 2>/dev/null || true
 
-      - name: Build warmup tool
-        run: |
-          bazel build //src/main/go/net/eagle0/warmup:warmup_linux_amd64
-          mkdir -p scripts/bin
-          cp bazel-bin/src/main/go/net/eagle0/warmup/warmup_linux_amd64_/warmup_linux_amd64 scripts/bin/warmup
+      - name: Download warmup binary
+        uses: actions/download-artifact@v4
+        with:
+          name: warmup-binary
+          path: scripts/bin/
 
       - name: Copy config files to droplet
         run: |
           # Create directory structure on remote
           ssh -i ~/.ssh/deploy_key deploy@"$DO_DROPLET_IP" bash -s << 'SETUP_DIRS'
           set -e
-          mkdir -p /opt/eagle0/scripts/bin /opt/eagle0/nginx /opt/eagle0/deploy
+          mkdir -p /opt/eagle0/scripts/bin /opt/eagle0/nginx
           rm -f /opt/eagle0/scripts/bin/warmup
           SETUP_DIRS
 
           # Copy files
           scp -i ~/.ssh/deploy_key docker-compose.prod.yml deploy@"$DO_DROPLET_IP":/opt/eagle0/
           scp -i ~/.ssh/deploy_key nginx/nginx.conf deploy@"$DO_DROPLET_IP":/opt/eagle0/nginx/
-          scp -i ~/.ssh/deploy_key scripts/deploy-blue-green.sh scripts/warmup-eagle.sh deploy@"$DO_DROPLET_IP":/opt/eagle0/scripts/
+          scp -i ~/.ssh/deploy_key scripts/deploy-blue-green.sh scripts/warmup-eagle.sh scripts/eagle-exec.sh scripts/eagle-logs.sh deploy@"$DO_DROPLET_IP":/opt/eagle0/scripts/
           scp -i ~/.ssh/deploy_key scripts/bin/warmup deploy@"$DO_DROPLET_IP":/opt/eagle0/scripts/bin/
-          scp -i ~/.ssh/deploy_key deploy/env.template deploy/update-env.sh deploy@"$DO_DROPLET_IP":/opt/eagle0/deploy/
 
       - name: Deploy to production droplet
         run: |
@@ -209,83 +282,154 @@ jobs:
           set -ex
           cd /opt/eagle0
 
-          # Environment variables passed via heredoc
-          EAGLE_IMAGE="${EAGLE_IMAGE}"
-          ADMIN_IMAGE="${ADMIN_IMAGE}"
-          JFR_SIDECAR_IMAGE="${JFR_SIDECAR_IMAGE}"
-          OPENAI_API_KEY="${OPENAI_API_KEY}"
-          GPT_MODEL_NAME="${GPT_MODEL_NAME}"
-          EAGLE_ENABLE_S3="${EAGLE_ENABLE_S3}"
-          DO_SPACES_ACCESS_KEY="${DO_SPACES_ACCESS_KEY}"
-          DO_SPACES_SECRET_KEY="${DO_SPACES_SECRET_KEY}"
-          JWT_PRIVATE_KEY="${JWT_PRIVATE_KEY}"
-          DISCORD_CLIENT_ID="${DISCORD_CLIENT_ID}"
-          DISCORD_CLIENT_SECRET="${DISCORD_CLIENT_SECRET}"
-          GOOGLE_CLIENT_ID="${GOOGLE_CLIENT_ID}"
-          GOOGLE_CLIENT_SECRET="${GOOGLE_CLIENT_SECRET}"
-          SHARDOK_ADDRESS="${SHARDOK_ADDRESS}"
-          SHARDOK_AUTH_TOKEN="${SHARDOK_AUTH_TOKEN}"
-          SENTRY_DSN="${SENTRY_DSN}"
-          FASTMAIL_API_TOKEN="${FASTMAIL_API_TOKEN}"
-          FASTMAIL_FROM_EMAIL="${FASTMAIL_FROM_EMAIL}"
-          FASTMAIL_FROM_NAME="${FASTMAIL_FROM_NAME}"
-          DO_REGISTRY_TOKEN="${DO_REGISTRY_TOKEN}"
+          # =================================================================
+          # CRITICAL: Validate environment variables before proceeding
+          # This catches GitHub Actions secret store hiccups early
+          # =================================================================
+          validate_env() {
+              local var_name="\$1"
+              local var_value="\$2"
+              local default_value="\${3:-}"
+
+              if [ -z "\${var_value}" ]; then
+                  echo "ERROR: \${var_name} is empty. GitHub Actions secrets may have failed to load."
+                  echo "Please retry the workflow."
+                  return 1
+              fi
+
+              # Check if we got a default value instead of the real secret
+              if [ -n "\${default_value}" ] && [ "\${var_value}" = "\${default_value}" ]; then
+                  echo "ERROR: \${var_name} has default value '\${default_value}' instead of the actual secret."
+                  echo "This indicates GitHub Actions secrets failed to load. Please retry the workflow."
+                  return 1
+              fi
+
+              return 0
+          }
+
+          echo "Validating critical environment variables..."
+
+          # These are the raw values from GitHub Actions (before export)
+          # We check them before exporting to catch issues early
+          VALIDATION_FAILED=0
+
+          validate_env "SHARDOK_ADDRESS" "${SHARDOK_ADDRESS}" "" || VALIDATION_FAILED=1
+          validate_env "EAGLE_IMAGE" "${EAGLE_IMAGE}" "" || VALIDATION_FAILED=1
+          validate_env "JWT_PRIVATE_KEY" "${JWT_PRIVATE_KEY}" "" || VALIDATION_FAILED=1
+          validate_env "DO_REGISTRY_TOKEN" "${DO_REGISTRY_TOKEN}" "" || VALIDATION_FAILED=1
+
+          if [ "\${VALIDATION_FAILED}" -eq 1 ]; then
+              echo ""
+              echo "========================================="
+              echo "DEPLOYMENT ABORTED: Missing critical secrets"
+              echo "This is likely a transient GitHub Actions issue."
+              echo "Please retry the workflow."
+              echo "========================================="
+              exit 1
+          fi
+
+          echo "All critical environment variables validated successfully."
+
+          # =================================================================
+          # Export environment variables for docker compose
+          # These are passed via heredoc and exported so child processes (docker compose) can access them
+          export EAGLE_IMAGE="${EAGLE_IMAGE}"
+          export ADMIN_IMAGE="${ADMIN_IMAGE}"
+          export JFR_SIDECAR_IMAGE="${JFR_SIDECAR_IMAGE}"
+          export OPENAI_API_KEY="${OPENAI_API_KEY}"
+          export ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY}"
+          export GEMINI_API_KEY="${GEMINI_API_KEY}"
+          export GPT_MODEL_NAME="${GPT_MODEL_NAME:-gpt-4o}"
+          export EAGLE_ENABLE_S3="${EAGLE_ENABLE_S3:-false}"
+          export DO_SPACES_ACCESS_KEY="${DO_SPACES_ACCESS_KEY}"
+          export DO_SPACES_SECRET_KEY="${DO_SPACES_SECRET_KEY}"
+          export ADMIN_S3_ACCESS_KEY="${ADMIN_S3_ACCESS_KEY}"
+          export ADMIN_S3_SECRET_KEY="${ADMIN_S3_SECRET_KEY}"
+          export JWT_PRIVATE_KEY="${JWT_PRIVATE_KEY}"
+          export DISCORD_CLIENT_ID="${DISCORD_CLIENT_ID}"
+          export DISCORD_CLIENT_SECRET="${DISCORD_CLIENT_SECRET}"
+          export GOOGLE_CLIENT_ID="${GOOGLE_CLIENT_ID}"
+          export GOOGLE_CLIENT_SECRET="${GOOGLE_CLIENT_SECRET}"
+          export GH_OAUTH_CLIENT_ID="${GH_OAUTH_CLIENT_ID}"
+          export GH_OAUTH_CLIENT_SECRET="${GH_OAUTH_CLIENT_SECRET}"
+          export APPLE_SIGNIN_CLIENT_ID="${APPLE_SIGNIN_CLIENT_ID}"
+          export APPLE_TEAM_ID="${APPLE_TEAM_ID}"
+          export APPLE_SIGNIN_KEY_ID="${APPLE_SIGNIN_KEY_ID}"
+          export APPLE_SIGNIN_PRIVATE_KEY="${APPLE_SIGNIN_PRIVATE_KEY}"
+          export TWITCH_CLIENT_ID="${TWITCH_CLIENT_ID}"
+          export TWITCH_CLIENT_SECRET="${TWITCH_CLIENT_SECRET}"
+          export SHARDOK_ADDRESS="${SHARDOK_ADDRESS}"
+          export SHARDOK_AUTH_TOKEN="${SHARDOK_AUTH_TOKEN}"
+          export SENTRY_DSN="${SENTRY_DSN}"
+          export FASTMAIL_API_TOKEN="${FASTMAIL_API_TOKEN}"
+          export FASTMAIL_FROM_EMAIL="${FASTMAIL_FROM_EMAIL}"
+          export FASTMAIL_FROM_NAME="${FASTMAIL_FROM_NAME}"
+          export DO_REGISTRY_TOKEN="${DO_REGISTRY_TOKEN}"
+          export NOTIFY_SECRET="${NOTIFY_SECRET}"
 
           # Check Docker has IPv6 support
           if ! cat /etc/docker/daemon.json 2>/dev/null | grep -q '"ip6tables"'; then
             echo "WARNING: Docker IPv6 not configured. Eagle may not reach Hetzner Shardok."
           fi
 
-          # Update env vars
-          chmod +x deploy/update-env.sh
-          cd deploy && ./update-env.sh \
-            "EAGLE_IMAGE=\${EAGLE_IMAGE}" \
-            "ADMIN_IMAGE=\${ADMIN_IMAGE}" \
-            "JFR_SIDECAR_IMAGE=\${JFR_SIDECAR_IMAGE}" \
-            "OPENAI_API_KEY=\${OPENAI_API_KEY}" \
-            "GPT_MODEL_NAME=\${GPT_MODEL_NAME:-gpt-4o}" \
-            "EAGLE_ENABLE_S3=\${EAGLE_ENABLE_S3:-false}" \
-            "DO_SPACES_ACCESS_KEY=\${DO_SPACES_ACCESS_KEY}" \
-            "DO_SPACES_SECRET_KEY=\${DO_SPACES_SECRET_KEY}" \
-            "JWT_PRIVATE_KEY=\${JWT_PRIVATE_KEY}" \
-            "DISCORD_CLIENT_ID=\${DISCORD_CLIENT_ID}" \
-            "DISCORD_CLIENT_SECRET=\${DISCORD_CLIENT_SECRET}" \
-            "GOOGLE_CLIENT_ID=\${GOOGLE_CLIENT_ID}" \
-            "GOOGLE_CLIENT_SECRET=\${GOOGLE_CLIENT_SECRET}" \
-            "SHARDOK_ADDRESS=\${SHARDOK_ADDRESS:-shardok:40042}" \
-            "SHARDOK_AUTH_TOKEN=\${SHARDOK_AUTH_TOKEN}" \
-            "SENTRY_DSN=\${SENTRY_DSN}" \
-            "FASTMAIL_API_TOKEN=\${FASTMAIL_API_TOKEN}" \
-            "FASTMAIL_FROM_EMAIL=\${FASTMAIL_FROM_EMAIL}" \
-            "FASTMAIL_FROM_NAME=\${FASTMAIL_FROM_NAME}"
-          cd ..
-
           # Login to registry
           echo "\$DO_REGISTRY_TOKEN" | docker login registry.digitalocean.com -u "\$DO_REGISTRY_TOKEN" --password-stdin
 
           echo "Using images: \$EAGLE_IMAGE, \$ADMIN_IMAGE, \$JFR_SIDECAR_IMAGE"
 
-          # Install crane for pulling OCI images
-          echo "Installing crane..."
-          rm -f crane
-          curl -sL https://github.com/google/go-containerregistry/releases/download/v0.20.2/go-containerregistry_Linux_x86_64.tar.gz | tar xzf - crane
-          chmod +x crane
+          # Install crane for pulling OCI images (cached across deploys)
+          CRANE_VERSION="v0.20.2"
+          if [ ! -x crane ] || ! ./crane version 2>/dev/null | grep -q "0.20.2"; then
+            echo "Installing crane \${CRANE_VERSION}..."
+            rm -f crane
+            curl -sL "https://github.com/google/go-containerregistry/releases/download/\${CRANE_VERSION}/go-containerregistry_Linux_x86_64.tar.gz" | tar xzf - crane
+            chmod +x crane
+          else
+            echo "Using cached crane"
+          fi
 
-          # Pull and load all images
-          echo "Pulling Eagle image..."
-          ./crane pull "\${EAGLE_IMAGE}" eagle.tar && docker load -i eagle.tar && rm eagle.tar
+          # Pull all images in parallel, then load sequentially
+          echo "Pulling all images in parallel..."
+          ./crane pull "\${EAGLE_IMAGE}" eagle.tar &
+          ./crane pull "\${ADMIN_IMAGE}" admin.tar &
+          ./crane pull "\${JFR_SIDECAR_IMAGE}" jfr-sidecar.tar &
+          docker pull nginx:alpine &
+          docker pull certbot/certbot &
+          wait
 
-          echo "Pulling Admin image..."
-          ./crane pull "\${ADMIN_IMAGE}" admin.tar && docker load -i admin.tar && rm admin.tar
+          echo "Loading images..."
+          docker load -i eagle.tar && rm eagle.tar
+          docker load -i admin.tar && rm admin.tar
+          # Tag as :latest locally so docker-compose fallback uses correct image
+          docker tag "\${ADMIN_IMAGE}" registry.digitalocean.com/eagle0/admin-server:latest
+          docker load -i jfr-sidecar.tar && rm jfr-sidecar.tar
 
-          echo "Pulling JFR Sidecar image..."
-          ./crane pull "\${JFR_SIDECAR_IMAGE}" jfr-sidecar.tar && docker load -i jfr-sidecar.tar && rm jfr-sidecar.tar
+          echo "All images pulled and loaded successfully"
 
-          # Pull other compose images
-          docker pull nginx:alpine || true
-          docker pull certbot/certbot || true
+          # =================================================================
+          # Verify Shardok connectivity before proceeding with deployment
+          # This catches network/firewall issues early
+          # =================================================================
+          echo "Verifying Shardok connectivity..."
+          SHARDOK_HOST=\$(echo "\${SHARDOK_ADDRESS}" | cut -d: -f1)
+          SHARDOK_PORT=\$(echo "\${SHARDOK_ADDRESS}" | cut -d: -f2)
 
-          echo "All images pulled successfully"
+          # Try to connect to Shardok (timeout after 10 seconds)
+          if nc -z -w 10 "\${SHARDOK_HOST}" "\${SHARDOK_PORT}" 2>/dev/null; then
+              echo "Shardok connectivity verified: \${SHARDOK_ADDRESS} is reachable"
+          else
+              echo ""
+              echo "========================================="
+              echo "ERROR: Cannot reach Shardok at \${SHARDOK_ADDRESS}"
+              echo "This may indicate:"
+              echo "  - Shardok server is not running on Hetzner"
+              echo "  - Network/firewall issues between DigitalOcean and Hetzner"
+              echo "  - Incorrect SHARDOK_ADDRESS configuration"
+              echo ""
+              echo "DEPLOYMENT ABORTED: Shardok must be reachable for battles to work."
+              echo "========================================="
+              exit 1
+          fi
 
           # Stop local shardok container if running (now runs on Hetzner)
           docker stop shardok-server 2>/dev/null || true
@@ -293,20 +437,35 @@ jobs:
 
           # Deploy Eagle with blue-green (handles eagle, nginx, admin, jfr-sidecar)
           # Note: Shardok runs on Hetzner, deployed separately via shardok_arm64_build.yml
+          # Note: Auth is deployed separately via auth_build.yml - do NOT touch auth here
           chmod +x /opt/eagle0/scripts/*.sh
           [ -f "/opt/eagle0/scripts/bin/warmup" ] && chmod +x /opt/eagle0/scripts/bin/warmup
           GIT_SHA=\$(echo "\${EAGLE_IMAGE}" | sed 's/.*://')
           /opt/eagle0/scripts/deploy-blue-green.sh "\${GIT_SHA}"
 
-          # Ensure auth is running
-          docker compose -f docker-compose.prod.yml up -d auth
-
           # Verify
           sleep 10
           docker compose -f docker-compose.prod.yml ps
           docker compose -f docker-compose.prod.yml images
 
-          # Cleanup
+          # Verify admin container is running the correct image
+          echo "=== Verifying admin container image ==="
+          ADMIN_RUNNING_DIGEST=\$(docker inspect admin-server --format '{{.Image}}')
+          ADMIN_EXPECTED_DIGEST=\$(docker inspect "\${ADMIN_IMAGE}" --format '{{.Id}}')
+          echo "Expected image: \${ADMIN_IMAGE}"
+          echo "Expected digest: \${ADMIN_EXPECTED_DIGEST}"
+          echo "Running digest:  \${ADMIN_RUNNING_DIGEST}"
+          if [ "\${ADMIN_RUNNING_DIGEST}" != "\${ADMIN_EXPECTED_DIGEST}" ]; then
+            echo "ERROR: Admin container is running wrong image!"
+            echo "Container entrypoint:"
+            docker inspect admin-server --format '{{.Config.Entrypoint}}'
+            exit 1
+          fi
+          echo "Admin image verification passed"
+
+          # Cleanup - remove old images to prevent disk full
           docker container prune -f
           docker image prune -f
+          # Remove images older than 24h (keeps recent images for rollback)
+          docker image prune -a -f --filter "until=24h" || true
           DEPLOY_SCRIPT

.github/workflows/eagle_build.yml

@@ -0,0 +1,33 @@
+name: Eagle Build
+
+on:
+  # Main pushes are covered by docker_build.yml which builds the same target
+  pull_request:
+    paths:
+      - 'src/main/scala/**'
+      - 'src/main/protobuf/net/eagle0/eagle/**'
+      - 'src/main/protobuf/net/eagle0/common/**'
+      - 'WORKSPACE'
+      - 'MODULE.bazel'
+      - 'BUILD.bazel'
+      - '.bazelrc'
+      - '.github/workflows/eagle_build.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: [self-hosted, bazel]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          lfs: false
+      - name: Build Eagle server
+        run: bazel build //src/main/scala/net/eagle0/eagle:eagle_server

.github/workflows/installer_build.yml

@@ -5,15 +5,16 @@ on:
     branches: [ "main" ]
     paths:
       - ".github/workflows/installer_build.yml"
-      - "src/main/csharp/net/eagle0/clients/win/installer/**"
+      - "src/main/go/net/eagle0/clients/win/installer/**"
   pull_request:
     paths:
       - ".github/workflows/installer_build.yml"
-      - "src/main/csharp/net/eagle0/clients/win/installer/**"
+      - "src/main/go/net/eagle0/clients/win/installer/**"
   workflow_dispatch:
 
 permissions:
   contents: read
+  actions: write  # Required to delete artifacts after deploy
 
 jobs:
   build-installer:
@@ -25,47 +26,47 @@ jobs:
           lfs: false
           clean: false
 
-      - name: Setup .NET 8
-        uses: actions/setup-dotnet@v4
-        with:
-          dotnet-version: '8.0.x'
-
-      - name: Inject manifest public key
+      - name: Build Go installer for Windows
         env:
           MANIFEST_PUBLIC_KEY: ${{ secrets.MANIFEST_PUBLIC_KEY }}
         run: |
-          if [ -n "$MANIFEST_PUBLIC_KEY" ]; then
-            CONFIG_FILE="src/main/csharp/net/eagle0/clients/win/installer/EagleInstaller/configuration.txt"
-            echo "manifest_public_key = $MANIFEST_PUBLIC_KEY" >> "$CONFIG_FILE"
-            echo "Injected manifest public key into configuration.txt"
-            cat "$CONFIG_FILE"
-          else
-            echo "MANIFEST_PUBLIC_KEY not set, skipping injection"
+          # Require manifest public key for production builds
+          if [ -z "$MANIFEST_PUBLIC_KEY" ]; then
+            echo "ERROR: MANIFEST_PUBLIC_KEY secret is not set"
+            echo "The installer requires a public key for manifest signature verification"
+            exit 1
           fi
 
-      - name: Restore dependencies
-        run: dotnet restore src/main/csharp/net/eagle0/clients/win/installer/EagleInstaller/EagleInstaller.csproj
+          # Build Windows installer with WebView GUI (uses CGO cross-compilation)
+          # Use --action_env to pass the signing key into the genrule sandbox
+          bazel build //src/main/go/net/eagle0/clients/win/installer:eagle_installer_windows_amd64_webview --stamp --action_env=MANIFEST_PUBLIC_KEY
 
-      - name: Build installer
-        run: dotnet publish src/main/csharp/net/eagle0/clients/win/installer/EagleInstaller/EagleInstaller.csproj -c Release -r win-x64 --self-contained true --output ./installer-output
+          # Copy to output directory
+          rm -rf ./installer-output
+          mkdir -p ./installer-output
+          cp bazel-bin/src/main/go/net/eagle0/clients/win/installer/Eagle0.exe ./installer-output/Eagle0.exe
+
+          echo "Go installer size: $(ls -lh ./installer-output/Eagle0.exe | awk '{print $5}')"
 
       - name: Archive installer binary
         if: success() || failure()
         uses: actions/upload-artifact@v4
         with:
           name: eagle-installer
-          path: ./installer-output/EagleInstaller.exe
+          path: ./installer-output/
+          retention-days: 1
 
       - name: Verify installer exists
         if: success()
         run: |
-          if [ ! -f "./installer-output/EagleInstaller.exe" ]; then
-            echo "ERROR: EagleInstaller.exe not found at expected location"
-            echo "Directory contents:"
-            ls -la ./installer-output/
+          echo "=== Installer output directory ==="
+          ls -lh ./installer-output/
+
+          if [ ! -f "./installer-output/Eagle0.exe" ]; then
+            echo "ERROR: Eagle0.exe not found"
             exit 1
           fi
-          echo "Installer found at correct location"
+          echo "Installer found"
 
       - name: Deploy installer
         if: success() && github.ref == 'refs/heads/main' && github.event_name == 'push'
@@ -73,25 +74,24 @@ jobs:
           ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY_ID }}
           SECRET_KEY: ${{ secrets.SECRET_KEY }}
         run: |
-          INSTALLER_PATH="$(pwd)/installer-output/EagleInstaller.exe"
-          echo "Using absolute path: $INSTALLER_PATH"
-          bazel run //src/main/go/net/eagle0/build/installer_build_handler:installer_build_handler -- "$INSTALLER_PATH"
+          INSTALLER_PATH="$(pwd)/installer-output/Eagle0.exe"
+          echo "Deploying Go installer to installer/Eagle0.exe"
+          bazel run //src/main/go/net/eagle0/build/installer_build_handler:installer_build_handler -- "$INSTALLER_PATH" "installer/Eagle0.exe"
 
-      - name: Update unified manifest
+      - name: Update manifest
         if: success() && github.ref == 'refs/heads/main' && github.event_name == 'push'
         env:
           ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY_ID }}
           SECRET_KEY: ${{ secrets.SECRET_KEY }}
           MANIFEST_SIGNING_KEY: ${{ secrets.MANIFEST_SIGNING_KEY }}
         run: |
-          # Create installer manifest content
-          INSTALLER_SHA=$(sha256sum ./installer-output/EagleInstaller.exe | cut -d' ' -f1)
+          INSTALLER_SHA=$(sha256sum ./installer-output/Eagle0.exe | cut -d' ' -f1)
           echo "installer_version=$INSTALLER_SHA" > /tmp/installer_manifest.txt
-          echo "installer_url=installer/EagleInstaller.exe" >> /tmp/installer_manifest.txt
+          echo "installer_url=installer/Eagle0.exe" >> /tmp/installer_manifest.txt
 
-          echo "=== Installer manifest content ==="
+          echo "=== Manifest content ==="
           cat /tmp/installer_manifest.txt
-          echo "=================================="
+          echo "========================"
 
           # Write signing key to temp file (if available)
           SIGNING_ARGS=""
@@ -104,8 +104,22 @@ jobs:
             echo "Warning: MANIFEST_SIGNING_KEY not set, manifest will be unsigned"
           fi
 
-          # Update the unified manifest (with optional signing)
-          bazel run //src/main/go/net/eagle0/build/manifest_manager:manifest_manager -- installer /tmp/installer_manifest.txt $SIGNING_ARGS
+          # Update the v2 manifest at installer/v2/eagle0_manifest.txt
+          bazel run //src/main/go/net/eagle0/build/manifest_manager:manifest_manager -- installer-v2 /tmp/installer_manifest.txt $SIGNING_ARGS
 
-          # Cleanup
-          rm -f /tmp/manifest_signing_key
+          rm -f /tmp/manifest_signing_key
+
+      - name: Delete all installer artifacts
+        if: success() && github.ref == 'refs/heads/main' && github.event_name == 'push'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Delete ALL eagle-installer artifacts to free up storage
+          echo "Fetching all eagle-installer artifacts..."
+          artifact_ids=$(gh api "repos/${{ github.repository }}/actions/artifacts" \
+            --paginate -q '.artifacts[] | select(.name == "eagle-installer") | .id')
+          for id in $artifact_ids; do
+            echo "Deleting artifact ID: $id"
+            gh api -X DELETE "repos/${{ github.repository }}/actions/artifacts/$id" || true
+          done
+          echo "Cleanup complete"

.github/workflows/ios_addressables_build.yml

@@ -0,0 +1,98 @@
+name: iOS Addressables Build
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - ".github/workflows/ios_addressables_build.yml"
+      - "src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/AddressableAssetsData/**"
+      - "src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Music/**"
+      - "src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Editor/BuildScript.cs"
+      - "ci/github_actions/build_ios_addressables.sh"
+      - "ci/github_actions/upload_addressables.sh"
+  pull_request:
+    paths:
+      - ".github/workflows/ios_addressables_build.yml"
+      - "src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/AddressableAssetsData/**"
+      - "src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Music/**"
+      - "src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Editor/BuildScript.cs"
+      - "ci/github_actions/build_ios_addressables.sh"
+      - "ci/github_actions/upload_addressables.sh"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+env:
+  # Runner-specific build directory to allow parallel builds on multiple runners
+  EAGLE0_BUILD_DIR: /tmp/eagle0-${{ github.run_id }}
+
+jobs:
+  build-ios-addressables:
+    runs-on: [self-hosted, macOS, unity-mac]
+
+    steps:
+      - name: Prune stale PR refs
+        run: |
+          # Self-hosted runners persist .git between runs. When a PR is updated,
+          # old local refs (refs/remotes/pull/*/merge) may point to commits whose
+          # objects were never fetched or have been pruned. Remove these stale refs
+          # before checkout to prevent "missing object" errors.
+          if [ -d ".git" ]; then
+            echo "Pruning stale PR refs..."
+            git for-each-ref --format='%(refname)' refs/remotes/pull/ 2>/dev/null | \
+              xargs -r git update-ref -d 2>/dev/null || true
+          fi
+      - uses: actions/checkout@v4
+        with:
+          lfs: false  # Fetch LFS after checkout to avoid stale ref issues
+          clean: false  # Library/ persists between runs on self-hosted runners
+
+      - name: Clean stale files
+        run: |
+          git clean -ffd
+          rm -rf src/main/csharp/net/eagle0/clients/unity/eagle0/Library/Bee/
+
+      - name: Fetch LFS files
+        run: |
+          git lfs install
+          git lfs pull
+
+      - name: Ensure Unity version installed
+        run: ./ci/github_actions/ensure_unity_installed.sh ios
+
+      - name: Build iOS Addressables
+        run: ./ci/github_actions/build_ios_addressables.sh "$EAGLE0_BUILD_DIR/editor_ios_addressables.log"
+
+      - name: Upload Addressables to CDN
+        if: success() && github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        env:
+          ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY_ID }}
+          SECRET_KEY: ${{ secrets.SECRET_KEY }}
+        run: ./ci/github_actions/upload_addressables.sh iOS
+
+      - name: Purge CDN cache for iOS addressables
+        if: success() && github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        env:
+          DO_CDN_PAT: ${{ secrets.DO_CDN_PAT }}
+        run: |
+          curl -s -X DELETE "https://api.digitalocean.com/v2/cdn/endpoints/8c98df29-6f0c-4704-8e82-ca40a2b81aa8/cache" \
+            -H "Authorization: Bearer $DO_CDN_PAT" \
+            -H "Content-Type: application/json" \
+            -d '{"files": ["addressables/iOS/*"]}' \
+            --fail || echo "Warning: CDN purge failed (non-fatal)"
+
+      - name: Archive Build Log
+        if: success() || failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: editor_ios_addressables.log
+          path: ${{ env.EAGLE0_BUILD_DIR }}/editor_ios_addressables.log
+          retention-days: 5
+      - name: Cleanup build directory
+        if: always()
+        run: rm -rf "${{ env.EAGLE0_BUILD_DIR }}"

.github/workflows/ios_testflight.yml

@@ -0,0 +1,183 @@
+name: iOS TestFlight
+
+on:
+  workflow_dispatch:
+    inputs:
+      skip_upload:
+        description: 'Skip TestFlight upload (build and archive only)'
+        required: false
+        default: 'false'
+        type: boolean
+
+permissions:
+  contents: read
+
+env:
+  # Runner-specific build directory to allow parallel builds on multiple runners
+  EAGLE0_BUILD_DIR: /tmp/eagle0-${{ github.run_id }}
+  # Runner-specific keychain to avoid conflicts when multiple runners sign simultaneously
+  KEYCHAIN_NAME: ios-build-${{ github.run_id }}.keychain
+
+jobs:
+  build-unity:
+    runs-on: [self-hosted, macOS, testflight]
+
+    steps:
+      - name: Prune stale PR refs
+        run: |
+          # Self-hosted runners persist .git between runs. When a PR is updated,
+          # old local refs (refs/remotes/pull/*/merge) may point to commits whose
+          # objects were never fetched or have been pruned. Remove these stale refs
+          # before checkout to prevent "missing object" errors.
+          if [ -d ".git" ]; then
+            echo "Pruning stale PR refs..."
+            git for-each-ref --format='%(refname)' refs/remotes/pull/ 2>/dev/null | \
+              xargs -r git update-ref -d 2>/dev/null || true
+          fi
+      - uses: actions/checkout@v4
+        with:
+          lfs: false  # Fetch LFS after checkout to avoid stale ref issues
+          clean: false  # Library/ persists between runs on self-hosted runners
+          fetch-depth: 0
+
+      - name: Clean stale files
+        run: |
+          git clean -ffd
+          rm -rf src/main/csharp/net/eagle0/clients/unity/eagle0/Library/Bee/
+
+      - name: Fetch LFS files
+        run: |
+          git lfs install
+          git lfs pull
+
+      - name: Ensure Unity version installed
+        run: ./ci/github_actions/ensure_unity_installed.sh ios
+
+      - name: Build iOS Unity Project
+        id: build
+        run: |
+          ./ci/github_actions/build_unity_ios.sh "$EAGLE0_BUILD_DIR/eagle0iOS"
+
+      - name: Upload Addressables to CDN
+        if: success()
+        env:
+          ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY_ID }}
+          SECRET_KEY: ${{ secrets.SECRET_KEY }}
+        run: ./ci/github_actions/upload_addressables.sh iOS
+
+      - name: Purge CDN cache for iOS addressables
+        if: success()
+        env:
+          DO_CDN_PAT: ${{ secrets.DO_CDN_PAT }}
+        run: |
+          curl -s -X DELETE "https://api.digitalocean.com/v2/cdn/endpoints/8c98df29-6f0c-4704-8e82-ca40a2b81aa8/cache" \
+            -H "Authorization: Bearer $DO_CDN_PAT" \
+            -H "Content-Type: application/json" \
+            -d '{"files": ["addressables/iOS/*"]}' \
+            --fail || echo "Warning: CDN purge failed (non-fatal)"
+
+      - name: Archive Build Log
+        if: success() || failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: editor_ios.log
+          path: ${{ env.EAGLE0_BUILD_DIR }}/editor_ios.log
+          retention-days: 5
+
+  archive-and-upload:
+    needs: build-unity
+    runs-on: [self-hosted, macOS, testflight]
+
+    steps:
+      - name: Install Signing Certificate
+        env:
+          IOS_CERTIFICATE: ${{ secrets.IOS_CERTIFICATE }}
+          IOS_CERTIFICATE_PWD: ${{ secrets.IOS_CERTIFICATE_PWD }}
+        run: |
+          # Generate random keychain password
+          KEYCHAIN_PASSWORD=$(openssl rand -base64 32)
+          echo "KEYCHAIN_PASSWORD=$KEYCHAIN_PASSWORD" >> $GITHUB_ENV
+
+          # Decode certificate
+          echo "$IOS_CERTIFICATE" | base64 --decode > certificate.p12
+
+          # Delete any existing keychain from previous runs
+          security delete-keychain "$KEYCHAIN_NAME" 2>/dev/null || true
+
+          # Create temporary keychain
+          security create-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_NAME"
+          security default-keychain -s "$KEYCHAIN_NAME"
+          security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_NAME"
+          security set-keychain-settings -t 3600 -u "$KEYCHAIN_NAME"
+
+          # Import certificate
+          security import certificate.p12 -k "$KEYCHAIN_NAME" -P "$IOS_CERTIFICATE_PWD" -T /usr/bin/codesign -T /usr/bin/security
+          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$KEYCHAIN_PASSWORD" "$KEYCHAIN_NAME"
+
+          # Add keychain to search list
+          security list-keychains -d user -s "$KEYCHAIN_NAME" login.keychain
+
+          rm certificate.p12
+
+      - name: Install Provisioning Profile
+        env:
+          IOS_PROVISIONING_PROFILE: ${{ secrets.IOS_PROVISIONING_PROFILE }}
+        run: |
+          # Decode provisioning profile
+          echo "$IOS_PROVISIONING_PROFILE" | base64 --decode > profile.mobileprovision
+
+          # Extract UUID from provisioning profile
+          PROFILE_UUID=$(/usr/libexec/PlistBuddy -c "Print :UUID" /dev/stdin <<< $(security cms -D -i profile.mobileprovision))
+          echo "PROFILE_UUID=$PROFILE_UUID" >> $GITHUB_ENV
+
+          # Install to standard location
+          mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles
+          cp profile.mobileprovision ~/Library/MobileDevice/Provisioning\ Profiles/$PROFILE_UUID.mobileprovision
+
+          rm profile.mobileprovision
+          echo "Installed provisioning profile: $PROFILE_UUID"
+
+      - name: Archive and Export IPA
+        env:
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        run: |
+          chmod +x ./ci/github_actions/archive_ios.sh
+          ./ci/github_actions/archive_ios.sh "$EAGLE0_BUILD_DIR/eagle0iOS" "$EAGLE0_BUILD_DIR/archive" "$APPLE_TEAM_ID" "$PROFILE_UUID"
+
+      - name: Upload to TestFlight
+        if: ${{ github.event.inputs.skip_upload != 'true' }}
+        env:
+          # App Store Connect API Key (replaces deprecated altool with Apple ID)
+          # Create at: https://appstoreconnect.apple.com/access/api
+          APP_STORE_CONNECT_API_KEY_ID: ${{ secrets.APP_STORE_CONNECT_API_KEY_ID }}
+          APP_STORE_CONNECT_API_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_API_ISSUER_ID }}
+          APP_STORE_CONNECT_API_KEY: ${{ secrets.APP_STORE_CONNECT_API_KEY }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        run: |
+          # Write API key to file (xcodebuild needs a file path)
+          API_KEY_PATH=$(mktemp)
+          echo "$APP_STORE_CONNECT_API_KEY" > "$API_KEY_PATH"
+          export APP_STORE_CONNECT_API_KEY_PATH="$API_KEY_PATH"
+
+          chmod +x ./ci/github_actions/upload_testflight.sh
+          ./ci/github_actions/upload_testflight.sh "$EAGLE0_BUILD_DIR/archive/eagle0.xcarchive" "$APPLE_TEAM_ID" "$PROFILE_UUID"
+
+          # Cleanup
+          rm -f "$API_KEY_PATH"
+
+      - name: Upload IPA artifact
+        # Only keep artifact if we skipped TestFlight upload (for debugging)
+        if: success() && github.event.inputs.skip_upload == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: eagle0-ios-${{ github.run_id }}
+          path: ${{ env.EAGLE0_BUILD_DIR }}/archive/eagle0.ipa
+          retention-days: 1
+
+      - name: Cleanup Keychain
+        if: always()
+        run: |
+          security delete-keychain "$KEYCHAIN_NAME" 2>/dev/null || true
+      - name: Cleanup build directory
+        if: always()
+        run: rm -rf "${{ env.EAGLE0_BUILD_DIR }}"

.github/workflows/mac_build.yml

@@ -20,18 +20,18 @@ on:
       - "scripts/notarize_wait.sh"
       - "ci/github_actions/build_mac.sh"
       - "ci/github_actions/build_unity_mac.sh"
+      - "ci/github_actions/upload_addressables.sh"
+      - "ci/github_actions/ensure_unity_installed.sh"
+      - "src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt"
       - "ci/mac/**"
   pull_request:
+    # On PRs, only build Mac when Mac-specific files change. Shared C#/proto
+    # changes are covered by the Windows build — if it passes, Mac will too.
     paths:
       - ".github/workflows/mac_build.yml"
-      - "src/main/csharp/net/eagle0/clients/unity/**"
-      - "src/main/protobuf/net/eagle0/common/**"
-      - "src/main/protobuf/net/eagle0/shardok/**"
-      - "src/main/protobuf/net/eagle0/eagle/api/**"
-      - "src/main/protobuf/net/eagle0/eagle/common/**"
-      - "src/main/protobuf/net/eagle0/eagle/views/**"
       - "src/main/go/net/eagle0/build/mac_build_handler/**"
       - "scripts/build_mac_plugin.sh"
+      - "scripts/build_sparkle_plugin.sh"
       - "scripts/inject_sparkle.sh"
       - "scripts/codesign_mac_app.sh"
       - "scripts/notarize_submit.sh"
@@ -47,8 +47,19 @@ on:
         default: 'false'
         type: boolean
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 permissions:
   contents: read
+  actions: write  # Required to delete artifacts after deploy
+
+env:
+  # Runner-specific build directory to allow parallel builds on multiple runners
+  EAGLE0_BUILD_DIR: /tmp/eagle0-${{ github.run_id }}
+  # Runner-specific keychain to avoid conflicts when multiple runners sign simultaneously
+  KEYCHAIN_NAME: build-${{ github.run_id }}.keychain
 
 jobs:
   build-and-sign:
@@ -58,23 +69,65 @@ jobs:
       should_deploy: ${{ steps.check-deploy.outputs.should_deploy }}
 
     steps:
+      - name: Prune stale PR refs
+        run: |
+          # Self-hosted runners persist .git between runs. When a PR is updated,
+          # old local refs (refs/remotes/pull/*/merge) may point to commits whose
+          # objects were never fetched or have been pruned. Remove these stale refs
+          # before checkout to prevent "missing object" errors.
+          if [ -d ".git" ]; then
+            echo "Pruning stale PR refs..."
+            git for-each-ref --format='%(refname)' refs/remotes/pull/ 2>/dev/null | \
+              xargs -r git update-ref -d 2>/dev/null || true
+          fi
       - uses: actions/checkout@v4
         with:
-          lfs: true
-          clean: false
+          lfs: false  # Fetch LFS after checkout to avoid stale ref issues
+          clean: false  # Library/ persists between runs on self-hosted runners
           fetch-depth: 0  # For version numbering from git history
 
-      - name: Pull LFS files
-        run: git lfs pull
+      - name: Clean stale files
+        run: |
+          git clean -ffd
+          # Only clear Bee/ when C# files were added/deleted/renamed (structural
+          # changes that stale the DAG). Content-only modifications are handled by
+          # Bee's incremental compilation. See persist_library.sh for background.
+          BEE_DIR="src/main/csharp/net/eagle0/clients/unity/eagle0/Library/Bee"
+          SHA_FILE="src/main/csharp/net/eagle0/clients/unity/eagle0/Library/.last_built_sha"
+          if [ -f "$SHA_FILE" ] && [ -d "$BEE_DIR" ]; then
+            LAST_SHA=$(cat "$SHA_FILE")
+            if git diff --diff-filter=ADR --name-only "$LAST_SHA" HEAD -- '*.cs' '*.csproj' '*.asmdef' 2>/dev/null | grep -q .; then
+              echo "C# files added/deleted/renamed since $LAST_SHA — clearing Bee/"
+              rm -rf "$BEE_DIR"
+            else
+              echo "No structural C# changes since $LAST_SHA — keeping Bee/"
+            fi
+          else
+            echo "No previous build SHA or no Bee/ — clearing Bee/ as safe default"
+            rm -rf "$BEE_DIR"
+          fi
 
-      - name: Restore Library/
-        run: ./ci/github_actions/restore_library.sh
+      - name: Fetch LFS files
+        run: |
+          git lfs install
+          git lfs pull
+
+      - name: Ensure Unity version installed
+        run: ./ci/github_actions/ensure_unity_installed.sh mac
 
       - name: Build Mac Unity
-        run: ./ci/github_actions/build_unity_mac.sh "/tmp/eagle0/eagle0MAC"
+        run: ./ci/github_actions/build_unity_mac.sh "${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC"
 
-      - name: Persist Library/
-        run: ./ci/github_actions/persist_library.sh
+      - name: Save build SHA for Bee/ cache invalidation
+        if: success()
+        run: git rev-parse HEAD > src/main/csharp/net/eagle0/clients/unity/eagle0/Library/.last_built_sha
+
+      - name: Upload Addressables to CDN
+        if: success() && github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        env:
+          ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY_ID }}
+          SECRET_KEY: ${{ secrets.SECRET_KEY }}
+        run: ./ci/github_actions/upload_addressables.sh StandaloneOSX
 
       - name: Inject Sparkle Framework
         if: success()
@@ -82,7 +135,7 @@ jobs:
           SPARKLE_EDDSA_PUBLIC_KEY: ${{ secrets.SPARKLE_EDDSA_PUBLIC_KEY }}
         run: |
           chmod +x ./scripts/inject_sparkle.sh
-          ./scripts/inject_sparkle.sh "/tmp/eagle0/eagle0MAC/eagle0.app"
+          ./scripts/inject_sparkle.sh "${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC/eagle0.app"
 
       - name: Check if should deploy
         id: check-deploy
@@ -111,18 +164,31 @@ jobs:
           echo "$MACOS_CERTIFICATE" | base64 --decode > certificate.p12
 
           # Delete any existing keychain from previous runs
-          security delete-keychain build.keychain 2>/dev/null || true
+          security delete-keychain "$KEYCHAIN_NAME" 2>/dev/null || true
 
           # Create temporary keychain
-          security create-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
-          security default-keychain -s build.keychain
-          security unlock-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
+          security create-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_NAME"
+          security default-keychain -s "$KEYCHAIN_NAME"
+          security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_NAME"
 
           # Import certificate
-          security import certificate.p12 -k build.keychain -P "$MACOS_CERTIFICATE_PWD" -T /usr/bin/codesign
+          echo "=== Importing certificate ==="
+          security import certificate.p12 -k "$KEYCHAIN_NAME" -P "$MACOS_CERTIFICATE_PWD" -T /usr/bin/codesign -T /usr/bin/security
 
           # Allow codesign to access keychain
-          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$KEYCHAIN_PASSWORD" build.keychain
+          echo "=== Setting key partition list ==="
+          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$KEYCHAIN_PASSWORD" "$KEYCHAIN_NAME"
+
+          # Add keychain to search list (required for codesign to find certificates)
+          echo "=== Adding keychain to search list ==="
+          security list-keychains -d user -s "$KEYCHAIN_NAME" login.keychain
+
+          # Debug: Check what's in the keychain after import
+          echo "=== Debug: Identities in build keychain ==="
+          KEYCHAIN_PATH="$HOME/Library/Keychains/$KEYCHAIN_NAME-db"
+          security find-identity -v -p codesigning "$KEYCHAIN_PATH" || true
+          echo "=== Debug: All available identities ==="
+          security find-identity -v -p codesigning || true
 
           # Clean up
           rm certificate.p12
@@ -133,7 +199,7 @@ jobs:
           SIGNING_IDENTITY: ${{ secrets.SIGNING_IDENTITY }}
         run: |
           chmod +x ./scripts/codesign_mac_app.sh
-          ./scripts/codesign_mac_app.sh "/tmp/eagle0/eagle0MAC/eagle0.app" "ci/mac/eagle0.entitlements"
+          ./scripts/codesign_mac_app.sh "${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC/eagle0.app" "ci/mac/eagle0.entitlements"
 
       - name: Submit for Notarization
         id: notarize-submit
@@ -144,25 +210,25 @@ jobs:
           TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
         run: |
           chmod +x ./scripts/notarize_submit.sh
-          ./scripts/notarize_submit.sh "/tmp/eagle0/eagle0MAC/eagle0.app" >> $GITHUB_OUTPUT
+          ./scripts/notarize_submit.sh "${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC/eagle0.app" >> $GITHUB_OUTPUT
 
       - name: Cleanup Keychain
         if: always()
         run: |
-          security delete-keychain build.keychain 2>/dev/null || true
+          security delete-keychain "$KEYCHAIN_NAME" 2>/dev/null || true
 
       - name: Zip signed app for artifact
         if: success() && steps.check-deploy.outputs.should_deploy == 'true'
         run: |
-          cd /tmp/eagle0/eagle0MAC
+          cd ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC
           ditto -c -k --keepParent eagle0.app eagle0.app.zip
 
       - name: Upload signed app
         if: success() && steps.check-deploy.outputs.should_deploy == 'true'
         uses: actions/upload-artifact@v4
         with:
-          name: signed-mac-app
-          path: /tmp/eagle0/eagle0MAC/eagle0.app.zip
+          name: signed-mac-app-${{ github.run_id }}
+          path: ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC/eagle0.app.zip
           retention-days: 1
 
       - name: Archive Build Log
@@ -170,7 +236,11 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: editor_mac.log
-          path: /tmp/eagle0/editor_mac.log
+          path: ${{ env.EAGLE0_BUILD_DIR }}/editor_mac.log
+          retention-days: 5
+      - name: Cleanup build directory
+        if: always()
+        run: rm -rf "${{ env.EAGLE0_BUILD_DIR }}"
 
   wait-notarization:
     needs: build-and-sign
@@ -183,20 +253,20 @@ jobs:
           sparse-checkout: scripts
 
       - name: Clean download directory
-        run: rm -rf /tmp/eagle0/eagle0MAC
+        run: rm -rf ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC
 
       - name: Download signed app
         uses: actions/download-artifact@v4
         with:
-          name: signed-mac-app
-          path: /tmp/eagle0/eagle0MAC
+          name: signed-mac-app-${{ github.run_id }}
+          path: ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC
 
       - name: Unzip signed app
         run: |
-          cd /tmp/eagle0/eagle0MAC
+          cd ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC
           ditto -x -k eagle0.app.zip .
           rm eagle0.app.zip
-          ls -la /tmp/eagle0/eagle0MAC/eagle0.app/
+          ls -la ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC/eagle0.app/
 
       - name: Wait for Notarization and Staple
         env:
@@ -205,25 +275,30 @@ jobs:
           TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
         run: |
           chmod +x ./scripts/notarize_wait.sh
-          ./scripts/notarize_wait.sh "${{ needs.build-and-sign.outputs.submission_id }}" "/tmp/eagle0/eagle0MAC/eagle0.app"
+          ./scripts/notarize_wait.sh "${{ needs.build-and-sign.outputs.submission_id }}" "${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC/eagle0.app"
 
       - name: Zip notarized app for artifact
         run: |
-          cd /tmp/eagle0/eagle0MAC
+          cd ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC
           rm -f eagle0.app.zip
           ditto -c -k --keepParent eagle0.app eagle0.app.zip
 
       - name: Upload notarized app
         uses: actions/upload-artifact@v4
         with:
-          name: notarized-mac-app
-          path: /tmp/eagle0/eagle0MAC/eagle0.app.zip
+          name: notarized-mac-app-${{ github.run_id }}
+          path: ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC/eagle0.app.zip
           retention-days: 1
+      - name: Cleanup build directory
+        if: always()
+        run: rm -rf "${{ env.EAGLE0_BUILD_DIR }}"
 
   deploy:
     needs: [build-and-sign, wait-notarization]
     if: needs.build-and-sign.outputs.should_deploy == 'true'
     runs-on: [self-hosted, macOS, unity-mac]
+    outputs:
+      deployed_version: ${{ steps.deploy-mac.outputs.deployed_version }}
 
     steps:
       - uses: actions/checkout@v4
@@ -231,21 +306,22 @@ jobs:
           fetch-depth: 0  # For version numbering
 
       - name: Clean download directory
-        run: rm -rf /tmp/eagle0/eagle0MAC
+        run: rm -rf ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC
 
       - name: Download notarized app
         uses: actions/download-artifact@v4
         with:
-          name: notarized-mac-app
-          path: /tmp/eagle0/eagle0MAC
+          name: notarized-mac-app-${{ github.run_id }}
+          path: ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC
 
       - name: Unzip notarized app
         run: |
-          cd /tmp/eagle0/eagle0MAC
+          cd ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC
           ditto -x -k eagle0.app.zip .
           rm eagle0.app.zip
 
       - name: Deploy Mac Build
+        id: deploy-mac
         env:
           ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY_ID }}
           SECRET_KEY: ${{ secrets.SECRET_KEY }}
@@ -256,13 +332,73 @@ jobs:
           echo "$SPARKLE_EDDSA_PRIVATE_KEY" > "$SPARKLE_PRIVATE_KEY_PATH"
           chmod 600 "$SPARKLE_PRIVATE_KEY_PATH"
 
-          VERSION=$(git describe --tags --always)
-          BUILD_NUMBER=$(git rev-list --count HEAD)
+          # Install dmgbuild (creates .DS_Store programmatically, no AppleScript needed)
+          pip3 install dmgbuild
+
+          # Background image for styled DMG
+          BACKGROUND_PATH="$(pwd)/ci/mac/dmg/background.png"
+
+          # Read version from the built app's Info.plist to ensure appcast matches the actual app
+          APP_PATH="${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC/eagle0.app"
+          BUILD_NUMBER=$(/usr/libexec/PlistBuddy -c "Print :CFBundleVersion" "$APP_PATH/Contents/Info.plist")
+          VERSION=$(/usr/libexec/PlistBuddy -c "Print :CFBundleShortVersionString" "$APP_PATH/Contents/Info.plist")
 
           bazel run //src/main/go/net/eagle0/build/mac_build_handler:mac_build_handler -- \
-            "/tmp/eagle0/eagle0MAC/eagle0.app" \
+            "${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC/eagle0.app" \
             "$VERSION" \
             "$BUILD_NUMBER" \
+            "$BACKGROUND_PATH" \
             "$SPARKLE_PRIVATE_KEY_PATH"
 
           rm "$SPARKLE_PRIVATE_KEY_PATH"
+
+          echo "deployed_version=$VERSION" >> $GITHUB_OUTPUT
+
+      # Artifact cleanup is handled by the cleanup job on ubuntu-latest
+      - name: Cleanup build directory
+        if: always()
+        run: rm -rf "${{ env.EAGLE0_BUILD_DIR }}"
+
+  notify-mac:
+    needs: deploy
+    if: needs.deploy.outputs.deployed_version != ''
+    runs-on: ubuntu-latest
+    steps:
+      - name: Purge CDN cache and notify clients
+        env:
+          NOTIFY_SECRET: ${{ secrets.EAGLE_NOTIFY_SECRET }}
+          DO_CDN_PAT: ${{ secrets.DO_CDN_PAT }}
+        run: |
+          # Purge CDN cache so clients get the latest files immediately
+          curl -s -X DELETE "https://api.digitalocean.com/v2/cdn/endpoints/8c98df29-6f0c-4704-8e82-ca40a2b81aa8/cache" \
+            -H "Authorization: Bearer $DO_CDN_PAT" \
+            -H "Content-Type: application/json" \
+            -d '{"files": ["mac/*", "addressables/StandaloneOSX/*"]}' \
+            --fail || echo "Warning: CDN purge failed (non-fatal)"
+
+          curl -X POST "https://admin.eagle0.net/notify-update?platform=mac&version=${{ needs.deploy.outputs.deployed_version }}&required=false" \
+            -H "X-Notify-Secret: $NOTIFY_SECRET" \
+            --fail --silent --show-error || echo "Warning: Failed to notify clients (non-fatal)"
+
+  # Cleanup job runs regardless of success/failure to prevent artifact accumulation
+  cleanup:
+    needs: [build-and-sign, wait-notarization, deploy, notify-mac]
+    if: always()
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Delete this run's Mac app artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Delete this run's artifacts (names include run ID to avoid conflicts)
+          for artifact_name in signed-mac-app-${{ github.run_id }} notarized-mac-app-${{ github.run_id }}; do
+            echo "Deleting artifact: $artifact_name"
+            artifact_id=$(gh api "repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/artifacts" \
+              -q ".artifacts[] | select(.name == \"$artifact_name\") | .id")
+            if [ -n "$artifact_id" ]; then
+              echo "Deleting artifact ID: $artifact_id"
+              gh api -X DELETE "repos/${{ github.repository }}/actions/artifacts/$artifact_id" || true
+            fi
+          done
+          echo "Cleanup complete"

.github/workflows/registry_cleanup.yml

@@ -46,26 +46,26 @@ jobs:
           for REPO in $REPOS; do
             echo "=== Processing repository: ${REPO} ==="
 
-            # Get all manifests with their tags and dates
-            # Filter out header row and empty lines
-            MANIFESTS=$(doctl registry repository list-manifests "${REPO}" --format Digest,UpdatedAt,Tags --no-header 2>/dev/null | grep -v '^Digest' | grep -v '^$' || echo "")
+            # Get all manifests with their tags and dates using JSON output for reliable parsing
+            MANIFESTS_JSON=$(doctl registry repository list-manifests "${REPO}" --output json 2>/dev/null || echo "[]")
 
-            if [ -z "$MANIFESTS" ]; then
+            if [ "$MANIFESTS_JSON" = "[]" ] || [ -z "$MANIFESTS_JSON" ]; then
               echo "  No manifests found"
               continue
             fi
 
-            echo "$MANIFESTS" | while read -r DIGEST UPDATED_AT TAGS; do
+            # Parse JSON and process each manifest
+            echo "$MANIFESTS_JSON" | jq -r '.[] | "\(.digest) \(.updated_at) \(.tags // [] | join(","))"' | while read -r DIGEST UPDATED_AT TAGS; do
               # Skip if no digest or if it doesn't look like a valid digest (sha256:...)
               if [ -z "$DIGEST" ] || ! echo "$DIGEST" | grep -q '^sha256:'; then
                 continue
               fi
 
-              # Parse the date
+              # Parse the date (ISO 8601 format from JSON)
               MANIFEST_DATE=$(date -d "$UPDATED_AT" +%s 2>/dev/null || echo "0")
 
               # Skip protected tags (latest, arm64-latest)
-              if echo "$TAGS" | grep -qE '(^|,)(latest|arm64-latest)(,|$)'; then
+              if echo ",$TAGS," | grep -qE ',(latest|arm64-latest),'; then
                 echo "  KEEP: ${DIGEST:0:20}... (protected tag: $TAGS)"
                 continue
               fi

.github/workflows/shardok_arm64_build.yml

@@ -10,6 +10,7 @@ on:
       - 'src/main/resources/net/eagle0/shardok/**'
       - 'ci/BUILD.bazel'
       - 'MODULE.bazel'
+      - '.bazelrc'
       - '.github/workflows/shardok_arm64_build.yml'
   workflow_dispatch:
     inputs:
@@ -19,6 +20,10 @@ on:
         default: 'true'
         type: boolean
 
+concurrency:
+  group: shardok-arm64-deploy
+  cancel-in-progress: false
+
 permissions:
   contents: read
 
@@ -59,12 +64,14 @@ jobs:
           if [ "$MAGIC" = "7f454c46" ]; then
             echo "SUCCESS: Binary is ELF format (Linux)"
             # Check if it's ARM64 (e_machine = 0xB7 = 183 for aarch64)
+            # od -tx2 reads as a 16-bit value in host byte order (little-endian on macOS),
+            # so the little-endian ELF bytes b7 00 are displayed as 00b7.
             E_MACHINE=$(od -An -j18 -N2 -tx2 "$LINUX_BIN" | tr -d ' ')
             echo "ELF e_machine: $E_MACHINE"
-            if [ "$E_MACHINE" = "b700" ]; then
+            if [ "$E_MACHINE" = "00b7" ]; then
               echo "SUCCESS: Binary is ARM64 (aarch64)"
             else
-              echo "WARNING: Binary e_machine is $E_MACHINE (expected b700 for aarch64)"
+              echo "WARNING: Binary e_machine is $E_MACHINE (expected 00b7 for aarch64)"
             fi
           elif [ "$MAGIC" = "cfaeedfe" ] || [ "$MAGIC" = "cffaedfe" ]; then
             echo "ERROR: Binary is Mach-O format (macOS) - cross-compilation failed!"
@@ -127,20 +134,19 @@ jobs:
             exit 1
           fi
 
-          # Build a push target to get crane in runfiles
-          bazel build //ci:eagle_server_push
-
-          # Find the Darwin crane binary
-          RUNFILES="bazel-bin/ci/push_eagle_server_push.sh.runfiles"
-          CRANE=$(find "$RUNFILES" -path "*darwin*" -name crane 2>/dev/null | head -1)
-          if [ -z "$CRANE" ]; then
-            CRANE=$(find "$RUNFILES" -name crane 2>/dev/null | head -1)
+          # Get crane (cached across runs to avoid rebuilding bazel target,
+          # which would discard the ARM64 analysis cache due to platform change)
+          CRANE_VERSION="v0.20.2"
+          CRANE_DIR="${HOME}/.local/bin"
+          CRANE="${CRANE_DIR}/crane"
+          if [ ! -x "$CRANE" ] || ! "$CRANE" version 2>/dev/null | grep -q "0.20.2"; then
+            echo "Installing crane ${CRANE_VERSION}..."
+            mkdir -p "$CRANE_DIR"
+            curl -sL "https://github.com/google/go-containerregistry/releases/download/${CRANE_VERSION}/go-containerregistry_Darwin_arm64.tar.gz" | tar xzf - -C "$CRANE_DIR" crane
+            chmod +x "$CRANE"
+          else
+            echo "Using cached crane at $CRANE"
           fi
-          if [ -z "$CRANE" ] || [ ! -e "$CRANE" ]; then
-            echo "ERROR: crane not found"
-            exit 1
-          fi
-          echo "Using crane: $CRANE"
 
           # Push with arm64-prefixed SHA tag (same repo as x86, different tag)
           GIT_SHA=$(git rev-parse --short=8 HEAD)
@@ -185,8 +191,22 @@ jobs:
 
           echo "Deploying Shardok ARM64: ${{ needs.build-shardok-arm64.outputs.image_tag }}"
 
-          # Pull the new image
-          docker pull "${{ needs.build-shardok-arm64.outputs.image_tag }}"
+          # Pre-warm NAT64 path to DigitalOcean registry (IPv6-only Hetzner → IPv4 registry)
+          curl -sf --max-time 10 https://registry.digitalocean.com/v2/ > /dev/null 2>&1 || true
+
+          # Pull the new image (retry up to 3 times for NAT64 connectivity flakiness)
+          for attempt in 1 2 3; do
+            echo "Pull attempt $attempt..."
+            if docker pull "${{ needs.build-shardok-arm64.outputs.image_tag }}"; then
+              break
+            fi
+            if [ "$attempt" -eq 3 ]; then
+              echo "ERROR: docker pull failed after 3 attempts"
+              exit 1
+            fi
+            echo "Pull failed, retrying in 10s..."
+            sleep 10
+          done
 
           # Stop and remove any container using port 40042 or named shardok*
           docker ps -q --filter "publish=40042" | xargs -r docker stop

.github/workflows/shardok_build.yml

@@ -1,17 +1,7 @@
 name: Shardok Build
 
 on:
-  push:
-    branches: [ "main" ]
-    paths:
-      - 'src/main/cpp/**'
-      - 'src/main/proto/net/eagle0/shardok/**'
-      - 'src/main/proto/net/eagle0/common/**'
-      - 'src/main/go/net/eagle0/build/**'
-      - 'WORKSPACE'
-      - 'MODULE.bazel'
-      - 'BUILD.bazel'
-      - '.github/workflows/shardok_build.yml'
+  # Main pushes are covered by shardok_arm64_build.yml which builds the same target
   pull_request:
     paths:
       - 'src/main/cpp/**'
@@ -21,8 +11,13 @@ on:
       - 'WORKSPACE'
       - 'MODULE.bazel'
       - 'BUILD.bazel'
+      - '.bazelrc'
       - '.github/workflows/shardok_build.yml'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 permissions:
   contents: read
 

.github/workflows/unity_build.yml

@@ -15,8 +15,9 @@ on:
       - "scripts/build_plugins.sh"
       - "scripts/build_windows_plugin.sh"
       - "ci/github_actions/build_unity.sh"
-      - "ci/github_actions/restore_library.sh"
-      - "ci/github_actions/persist_library.sh"
+      - "ci/github_actions/upload_addressables.sh"
+      - "ci/github_actions/ensure_unity_installed.sh"
+      - "src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt"
       - "MODULE.bazel"
       - "WORKSPACE"
   workflow_dispatch:
@@ -33,37 +34,92 @@ on:
       - "scripts/build_plugins.sh"
       - "scripts/build_windows_plugin.sh"
       - "ci/github_actions/build_unity.sh"
-      - "ci/github_actions/restore_library.sh"
-      - "ci/github_actions/persist_library.sh"
+      - "ci/github_actions/upload_addressables.sh"
+      - "ci/github_actions/ensure_unity_installed.sh"
+      - "src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt"
       - "MODULE.bazel"
       - "WORKSPACE"
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 permissions:
   contents: read
 
+env:
+  # Runner-specific build directory to allow parallel builds on multiple runners
+  EAGLE0_BUILD_DIR: /tmp/eagle0-${{ github.run_id }}
+
 jobs:
   windows-unity:
     runs-on: [self-hosted, macOS, unity-windows]
+    outputs:
+      deployed_version: ${{ steps.get-version.outputs.deployed_version }}
 
     steps:
+      - name: Prune stale PR refs
+        run: |
+          # Self-hosted runners persist .git between runs. When a PR is updated,
+          # old local refs (refs/remotes/pull/*/merge) may point to commits whose
+          # objects were never fetched or have been pruned. Remove these stale refs
+          # before checkout to prevent "missing object" errors.
+          if [ -d ".git" ]; then
+            echo "Pruning stale PR refs..."
+            git for-each-ref --format='%(refname)' refs/remotes/pull/ 2>/dev/null | \
+              xargs -r git update-ref -d 2>/dev/null || true
+          fi
       - uses: actions/checkout@v4
         with:
-          lfs: true
-          clean: false
-      - name: Pull lfs files
-        run: git lfs pull
-      - name: Restore Library/
-        run: ./ci/github_actions/restore_library.sh
+          lfs: false  # Fetch LFS after checkout to avoid stale ref issues
+          clean: false  # Library/ persists between runs on self-hosted runners
+
+      - name: Clean stale files
+        run: |
+          git clean -ffd
+          # Only clear Bee/ when C# files were added/deleted/renamed (structural
+          # changes that stale the DAG). Content-only modifications are handled by
+          # Bee's incremental compilation. See persist_library.sh for background.
+          BEE_DIR="src/main/csharp/net/eagle0/clients/unity/eagle0/Library/Bee"
+          SHA_FILE="src/main/csharp/net/eagle0/clients/unity/eagle0/Library/.last_built_sha"
+          if [ -f "$SHA_FILE" ] && [ -d "$BEE_DIR" ]; then
+            LAST_SHA=$(cat "$SHA_FILE")
+            if git diff --diff-filter=ADR --name-only "$LAST_SHA" HEAD -- '*.cs' '*.csproj' '*.asmdef' 2>/dev/null | grep -q .; then
+              echo "C# files added/deleted/renamed since $LAST_SHA — clearing Bee/"
+              rm -rf "$BEE_DIR"
+            else
+              echo "No structural C# changes since $LAST_SHA — keeping Bee/"
+            fi
+          else
+            echo "No previous build SHA or no Bee/ — clearing Bee/ as safe default"
+            rm -rf "$BEE_DIR"
+          fi
+
+      - name: Fetch LFS files
+        run: |
+          git lfs install
+          git lfs pull
+      - name: Ensure Unity version installed
+        run: ./ci/github_actions/ensure_unity_installed.sh windows
       - name: Build Windows unity
-        run: ./ci/github_actions/build_unity.sh "/tmp/eagle0/eagle0WIN"
-      - name: Persist Library/
-        run: ./ci/github_actions/persist_library.sh
+        run: ./ci/github_actions/build_unity.sh "${{ env.EAGLE0_BUILD_DIR }}/eagle0WIN"
+
+      - name: Save build SHA for Bee/ cache invalidation
+        if: success()
+        run: git rev-parse HEAD > src/main/csharp/net/eagle0/clients/unity/eagle0/Library/.last_built_sha
+
+      - name: Upload Addressables to CDN
+        if: success() && github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        env:
+          ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY_ID }}
+          SECRET_KEY: ${{ secrets.SECRET_KEY }}
+        run: ./ci/github_actions/upload_addressables.sh StandaloneWindows64
       - name: Deploy Windows unity
         if: success() && github.ref == 'refs/heads/main' && github.event_name == 'push'
         env:
           ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY_ID }}
           SECRET_KEY: ${{ secrets.SECRET_KEY }}
-        run: bazel run //src/main/go/net/eagle0/build/unity3d_windows_build_handler:unity3d_windows_build_handler -- "/tmp/eagle0/eagle0WIN" "/tmp/unity_manifest.txt"
+        run: bazel run //src/main/go/net/eagle0/build/unity3d_windows_build_handler:unity3d_windows_build_handler -- "${{ env.EAGLE0_BUILD_DIR }}/eagle0WIN" "/tmp/unity_manifest.txt"
 
       - name: Update unified manifest
         if: success() && github.ref == 'refs/heads/main' && github.event_name == 'push'
@@ -83,14 +139,47 @@ jobs:
             echo "Warning: MANIFEST_SIGNING_KEY not set, manifest will be unsigned"
           fi
 
-          # Update the unified manifest (with optional signing)
-          bazel run //src/main/go/net/eagle0/build/manifest_manager:manifest_manager -- unity3d /tmp/unity_manifest.txt $SIGNING_ARGS
+          # Update the v2 manifest at installer/v2/eagle0_manifest.txt
+          bazel run //src/main/go/net/eagle0/build/manifest_manager:manifest_manager -- unity3d-v2 /tmp/unity_manifest.txt $SIGNING_ARGS
 
           # Cleanup
           rm -f /tmp/manifest_signing_key
+
+      - name: Export deployed version
+        id: get-version
+        if: success() && github.ref == 'refs/heads/main' && github.event_name == 'push'
+        run: |
+          VERSION=$(grep "^version=" /tmp/unity_manifest.txt | cut -d= -f2 || date +%Y.%m.%d)
+          echo "deployed_version=$VERSION" >> $GITHUB_OUTPUT
+
       - name: Archive build log
         if: success() || failure()
         uses: actions/upload-artifact@v4
         with:
           name: editor_win.log
-          path: /tmp/eagle0/editor_win.log
+          path: ${{ env.EAGLE0_BUILD_DIR }}/editor_win.log
+          retention-days: 5
+      - name: Cleanup build directory
+        if: always()
+        run: rm -rf "${{ env.EAGLE0_BUILD_DIR }}"
+
+  notify-windows:
+    needs: windows-unity
+    if: needs.windows-unity.outputs.deployed_version != ''
+    runs-on: ubuntu-latest
+    steps:
+      - name: Purge CDN cache and notify clients
+        env:
+          NOTIFY_SECRET: ${{ secrets.EAGLE_NOTIFY_SECRET }}
+          DO_CDN_PAT: ${{ secrets.DO_CDN_PAT }}
+        run: |
+          # Purge CDN cache so clients get the latest files immediately
+          curl -s -X DELETE "https://api.digitalocean.com/v2/cdn/endpoints/8c98df29-6f0c-4704-8e82-ca40a2b81aa8/cache" \
+            -H "Authorization: Bearer $DO_CDN_PAT" \
+            -H "Content-Type: application/json" \
+            -d '{"files": ["windows/*", "addressables/StandaloneWindows64/*"]}' \
+            --fail || echo "Warning: CDN purge failed (non-fatal)"
+
+          curl -X POST "https://admin.eagle0.net/notify-update?platform=windows&version=${{ needs.windows-unity.outputs.deployed_version }}&required=false" \
+            -H "X-Notify-Secret: $NOTIFY_SECRET" \
+            --fail --silent --show-error || echo "Warning: Failed to notify clients (non-fatal)"

.gitignore

@@ -37,5 +37,8 @@ scripts/refresh_name_layers/refresh_name_layers.zip
 .metals
 api_keys.txt
 
+src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/GeneratedProtos/
+src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins/Eagle0Protos/
 src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/Packages/com.unity.dedicated-server/
 node_modules/
+tools/map_generator/output/

.pre-commit-config.yaml

@@ -5,6 +5,7 @@ repos:
     rev: v4.3.0
     hooks:
     -   id: check-added-large-files
+    -   id: check-merge-conflict
     -   id: no-commit-to-branch
         args: [--branch, main]
 -   repo: https://github.com/pocc/pre-commit-hooks

BUILD.bazel

@@ -32,3 +32,15 @@ nogo(
     vet = True,
     visibility = ["//visibility:public"],
 )
+
+# Dependency constraint tests
+# These verify architectural boundaries are maintained
+sh_test(
+    name = "build_deps_test",
+    srcs = ["scripts/check_build_deps.sh"],
+    args = ["--ci"],
+    tags = [
+        "local",  # Needs bazel query access
+        "no-sandbox",
+    ],
+)

CLAUDE.md

@@ -110,6 +110,10 @@ bazel run gazelle              # Update Go build files
 1. **If you modified any BUILD.bazel file:** Run `bazel run gazelle` and stage any changes it makes
 2. **If you modified C++ or C# files:** Run `clang-format -i` on the modified files
 3. **If you modified Scala files:** scalafmt will run automatically via pre-commit hook
+4. **ALWAYS run the full test suite for your language changes before pushing:**
+   - For Scala changes: `bazel test //src/test/scala/...`
+   - For C++ changes: `bazel test //src/test/cpp/...`
+   - This catches exhaustive pattern match errors and other compile-time failures that single-target builds miss
 
 The pre-commit hook runs gazelle but only checks if it succeeds - it does NOT verify the BUILD files are in canonical format. The `gazelle_test` will fail if deps are not alphabetically sorted. **Always run gazelle manually after BUILD file changes.**
 
@@ -221,6 +225,9 @@ to be used for different players or game situations within the same server proce
 - Real-time bidirectional streaming with server via `PersistentClientConnection.cs`
 - Strategic map UI in `Assets/Eagle/`, tactical battle UI in `Assets/Shardok/`
 - Seamless transition between strategic gameplay and hex-based tactical combat
+- **NEVER add defensive null checks on Unity Inspector fields** - these hide configuration bugs. If a field isn't
+  linked in the editor, it should throw a NullReferenceException so the problem is immediately obvious. Silently
+  skipping code when a required field is null makes bugs harder to find.
 
 **Go (Build Tools):**
 
@@ -329,6 +336,8 @@ dotty.tools.dotc.core.MissingType: Cannot resolve reference to type net.eagle0.e
 **Configuration:** Game parameters in `/src/main/resources/net/eagle0/eagle/game_parameters.json`
 **Data Files:** TSV format for battalions, heroes, and other game data
 
+**NEVER modify hero names.** Do not change names in `heroes.tsv`, `generated_heroes`, or any other hero data files. The names are carefully chosen and are not to be altered.
+
 ## Deployment
 
 - Bazel handles multi-language builds and dependencies

DEPROTO_PLAN.md

@@ -1,566 +0,0 @@
-# Deproto Migration Plan
-
-This document tracks the migration from protobuf types to native Scala models inside the Eagle game engine.
-
-## Architectural Decisions
-
-1. **Keep proto for persistence**: Yes - protobuf is used for persisting game state
-2. **Keep proto for Shardok communication**: Yes - protobuf is used for Eagle-Shardok gRPC communication
-3. **Use Scala views inside the library**: Yes - use native Scala types like `ProvinceView`, `FactionView`, `HeroView`, etc. within the library code
-
-## Recent Completed Work
-
-### GameState Round-Trip Elimination (PRs #4913, #4914, #4915)
-
-Eliminated wasteful Scala→proto→Scala conversions in the hot path:
-
-1. **LLM Pipeline** (#4913): `LlmRequestWithGameState` now uses Scala `GameState` instead of proto. All ~38 prompt generators updated to use Scala model types (`FactionT`, `HeroT`, `ProvinceT`).
-
-2. **ActionWithResultingState Caching** (#4914): Added `precomputedScalaState: Option[GameState]` to cache Scala state when available, avoiding `fromProto()` conversion in `stateAfter()`.
-
-3. **PostResults Simplification** (#4915): Changed `PostResults.gameState` from proto to `Option[GameState]` (Scala), eliminating `toProto()` calls when creating PostResults.
-
-## Migration Pattern
-
-The codebase follows a **Legacy* pattern** for separating proto-dependent and protoless code:
-
-- **Protoless utilities**: `FactionUtils`, `HeroUtils`, `ProvinceUtils`, `ProvinceDistances`, etc.
-- **Proto-dependent utilities**: `LegacyFactionUtils`, `LegacyHeroUtils`, `LegacyProvinceUtils`, `LegacyProvinceDistances`, etc.
-
-When migrating a file:
-1. Create a `Legacy*` version containing the proto-dependent methods
-2. Keep the original file name for protoless methods
-3. Update callers to use the appropriate version based on their context
-
-## Migration Status
-
-### Fully Protoless (no proto imports)
-
-**Utilities:**
-- [x] `FactionUtils` - has protoless `ownedNeighbors` method
-- [x] `ProvinceDistances` - split into protoless + `LegacyProvinceDistances`
-- [x] `SwornBrotherChooser` - fully protoless (removed `bestChoiceProto`)
-
-**Command Selectors (all use native GameState):**
-- [x] `AllianceOfferCommandSelector`
-- [x] `AlmsCommandSelector`
-- [x] `AttackCommandChooser`
-- [x] `ExpandCommandSelector`
-- [x] `HeroGiftCommandSelector`
-- [x] `ImproveCommandSelector`
-- [x] `MarchTowardProvinceCommandChooser` - in AI folder, uses native GameState (callers convert)
-- [x] `OrganizeCommandSelector`
-- [x] `RansomOfferHelpers`
-- [x] `SeekMoreLeadersCommandChooser` - in AI folder, uses native GameState
-- [x] `TruceOfferCommandSelector`
-- [x] `TrustForDiplomacy`
-
-**Quest Command Selectors (all protoless):**
-- [x] `AllianceQuestCommandChooser`
-- [x] `AlmsAcrossRealmQuestCommandChooser`
-- [x] `AlmsToProvinceQuestCommandChooser`
-- [x] `DismissSpecificVassalCommandChooser`
-- [x] `GiveToHeroesAcrossRealmQuestCommandChooser`
-- [x] `GiveToHeroesInProvinceQuestCommandChooser`
-- [x] `ImproveQuestCommandChooser`
-- [x] `QuestCommandChooser`
-- [x] `TruceCountQuestCommandChooser`
-- [x] `TruceWithFactionQuestCommandChooser`
-
-### Fully Protoless
-
-- [x] `AIClientUtils` - has protoless overloads (`takenHeroIdsForMarchTowardFocus`, `mostPowerfulHeroes`)
-- [x] `AttackCommandChooser` - uses Scala `GameState` and `BattalionViewC` (Scala view type)
-- [x] `BattalionPower` - has `estimatedPower(BattalionViewC)` for recon data with optional stats
-- [x] `CommandChoiceHelpers` - fully protoless, uses Scala `GameState` throughout
-- [x] `ProvinceGoldSurplusCalculator` - fully protoless (callers use converters)
-- [x] `HeroSelector` - fully protoless (removed dead `minimallyFatiguedHeroesProto`)
-
-### AI Layer ✅ COMPLETE
-
-All AI and command chooser code is now fully protoless:
-- [x] `AttackDecisionCommandChooser` - uses Scala GameState
-- [x] `CommandChooser` - trait uses Scala GameState
-- [x] `FulfillQuestsCommandSelector` - uses Scala GameState
-- [x] `MidGameAIClient` - uses Scala GameState internally
-
-### Still Using Proto GameState (Boundary Code)
-
-These files use proto GameState because they're at system boundaries:
-
-**View Filters (client projection):**
-- `view_filters/GameStateViewFilter` - has Scala overload, uses Scala sub-filters
-- `view_filters/ProvinceViewFilter` - has Scala overloads for some methods
-- `view_filters/FactionViewFilter` - has Scala overload
-- `view_filters/HeroViewFilter` - has Scala overload
-- `view_filters/BattalionNameFilter` - has Scala overload
-- `view_filters/BattleFilter` - has Scala overload
-
-**Legacy Utilities (to be deprecated):**
-- `LegacyProvinceDistances`, `LegacyFactionUtils`, `LegacyHeroUtils`, etc.
-- Used by code that still needs proto GameState
-
-**Persistence/Action System:**
-- `ActionResultTApplier`, `ActionResultProtoApplier` - apply results to proto state
-- `ActionWithResultingState` - caches both proto and Scala state
-
-**Shardok Interface (gRPC boundary):**
-- `ShardokInterfaceGrpcClient`, `ShardokInterfaceProxy` - must use proto for C++ communication
-
-## Next Steps
-
-### Phase 1-3: AI Layer ✅ COMPLETE
-
-The entire AI decision-making layer is now protoless.
-
-### Phase 4: View Filters ✅ COMPLETE
-
-The view_filters package migration is complete:
-
-**Completed:**
-- [x] `GameStateViewFilter` - added Scala GameState overload (uses Scala sub-filters)
-- [x] `ProvinceViewFilter` - already has Scala overloads for server-side views
-- [x] `HumanPlayerClientConnectionState` - updated to pass Scala GameState directly
-- [x] `HeroViewFilter` - added Scala overload
-- [x] `FactionViewFilter` - added Scala overload
-- [x] `Visibility` - added Scala overloads
-
-**Still Using Proto:**
-- [x] `BattalionNameFilter` - has Scala overload
-- [x] `BattleFilter` - has Scala overload
-- [ ] `ActionResultFilter` - uses proto internally (boundary code)
-
-**Strategy:**
-1. Add Scala GameState overloads to view filter methods
-2. Update callers to pass Scala GameState where available
-3. Eventually deprecate proto versions
-
-### Phase 5: Legacy Utility Cleanup (IN PROGRESS)
-
-Remove Legacy* utilities by migrating remaining callers:
-1. Identify callers of each Legacy* util
-2. Update callers to use protoless versions
-3. Delete Legacy* files when no longer needed
-
-**Deleted (no production callers):**
-- [x] `LegacyProvinceDistances` - deleted (no callers)
-- [x] `LegacyBattalionSuitability` - deleted (no callers)
-- [x] `LegacyFoodConsumptionUtils` - deleted (no callers)
-- [x] `LegacyHandleRiotUtils` - deleted (no callers)
-
-**Refactored to Thin Wrappers (delegating to protoless versions):**
-- [x] `LegacyRansomValidity` - already a thin wrapper delegating to `RansomValidity`
-- [x] `LegacyRecruitmentOdds` - refactored to delegate to `RecruitmentOdds`
-
-**Parallel Implementations (proto mirrors protoless):**
-- [x] `FactionUtils` / `LegacyFactionUtils` - both have matching APIs; LegacyFactionUtils used by boundary code (24+ callers)
-- [x] `HeroUtils` / `LegacyHeroUtils` - both have matching APIs; LegacyHeroUtils used by boundary code (10 callers)
-- [x] `ProvinceUtils` / `LegacyProvinceUtils` - both have matching APIs; LegacyProvinceUtils used by boundary code (20 callers: availability factories, view filters)
-
-**Parallel Implementations (awaiting migration of callers):**
-- [x] `BattalionUtils` / `LegacyBattalionUtils` - both have matching core methods; LegacyBattalionUtils used by boundary code (4 callers)
-- [x] `BattalionViewFilter` / `LegacyBattalionViewFilter` - protoless version exists; Legacy used by view filters, action appliers (3 callers)
-- [x] `BattalionTypeFinder` / `LegacyBattalionTypeFinder` - protoless version exists; Legacy used by validators (1 caller: RuntimeValidator)
-
-### Recent Caller Migration
-
-**CheckForFulfilledQuestsAction** - migrated to use protoless `BattalionTypeFinder`:
-- Changed `battalionTypes` parameter from proto `Vector[BattalionType]` to Scala `Vector[BattalionType]`
-- Updated callers (EngineImpl, EndVassalCommandsPhaseAction) to pass Scala types directly
-- Eliminated wasteful `BattalionTypeConverter.toProto()` conversions
-
-**ExpandedUnaffiliatedHeroUtils** - added Scala overload:
-- New overload takes Scala `GameState` and `UnaffiliatedHeroT` directly
-- Added `UnaffiliatedHeroConverter.unaffiliatedHeroTypeToProto()` helper for efficient enum conversion
-- Proto overload retained for backward compatibility
-
-**AvailablePleaseRecruitMeCommandFactory** - eliminated wasteful proto conversions:
-- Now uses `ExpandedUnaffiliatedHeroUtils.expandedUnaffiliatedHero(ScalaGameState, UnaffiliatedHeroT)` directly
-- Removed `GameStateConverter.toProto()` and `UnaffiliatedHeroConverter.toProto()` calls
-- Factory is now fully protoless internally (still returns proto types for API boundary)
-
-**ProvinceViewFilter** - added Scala overload with faction filtering:
-- New `filteredProvinceView(province: ProvinceT, gs: ScalaGameState, factionId: FactionId)` overload
-- Uses protoless `FactionUtils.hasAlliance`, `Visibility.hasFullVisibility`, and `ProvinceUtils.incomingOthers`
-- Handles reconned provinces directly from Scala `FactionT.reconnedProvinces` (already Scala type)
-- Added helper methods: `fullProvinceInfoScala`, `maybeIncomingAttackersScala`, `unaffiliatedHeroInfoScala`
-- Events still converted to proto at the end (ProvinceView.knownEvents uses proto events)
-
-**GameStateViewFilter** - eliminated GameStateConverter.toProto() call:
-- Scala overload now fully protoless internally
-- Uses the new ProvinceViewFilter Scala overload with faction filtering
-- Converts `battalionTypes` and `chronicleEntries` to proto only at output boundary
-
-## Key Files
-
-### Protoless Model Types
-
-- `src/main/scala/net/eagle0/eagle/model/state/game_state/GameState.scala` - native Scala GameState
-- `src/main/scala/net/eagle0/eagle/model/state/province/ProvinceView.scala` - province view type
-- `src/main/scala/net/eagle0/eagle/model/state/faction/FactionView.scala` - faction view type
-- `src/main/scala/net/eagle0/eagle/model/state/hero/HeroView.scala` - hero view type
-
-### Proto Converters
-
-- `src/main/scala/net/eagle0/eagle/model/proto_converters/game_state/` - converts between proto and Scala types
-
-## Notes
-
-- The AI client code (`src/main/scala/net/eagle0/eagle/ai/`) is now fully protoless
-- Proto GameState is still needed at boundaries: persistence, gRPC to Shardok
-- `PerformUnaffiliatedHeroesAction` and the LLM pipeline use protoless `GameState`
-- `GameStateViewFilter` Scala overload is now fully protoless internally (converts to proto only at output)
-- `ProvinceViewFilter` has Scala overloads for all three modes: no filtering, faction filtering, and withdrawn-from view
-
----
-
-## Proto Import Inventory (library/)
-
-**Total: 149 proto imports across 51 files** (as of 2026-01-13)
-
-### Proto Dependencies by BUILD.bazel (unique deps)
-
-#### library/BUILD.bazel
-- `//src/main/protobuf/net/eagle0/eagle/api:selected_command_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/common:action_result_type_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/common:round_phase_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:action_result_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:game_state_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:action_result_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:game_state_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/shardok/api:action_result_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/shardok/api:command_descriptor_scala_proto`
-- `//src/main/protobuf/net/eagle0/shardok/storage:action_result_scala_proto`
-
-#### library/actions/impl/action/BUILD.bazel
-- `//src/main/protobuf/net/eagle0/eagle/api:available_command_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/api:selected_command_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/common:action_result_type_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/common:province_order_type_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/common:unaffiliated_hero_quest_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:game_state_scala_proto`
-
-#### library/actions/impl/common/BUILD.bazel
-- `//src/main/protobuf/net/eagle0/eagle/internal:action_result_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:game_state_scala_proto`
-
-#### library/actions/llm_prompt_generators/BUILD.bazel
-- `//src/main/protobuf/net/eagle0/eagle/internal:battalion_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:event_for_chronicle_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:llm_request_scala_proto`
-
-#### library/actions/llm_request_generators/diplomacy_llm_helpers/BUILD.bazel
-- `//src/main/protobuf/net/eagle0/eagle/internal:llm_request_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:province_scala_proto`
-
-#### library/settings/loaders/BUILD.bazel
-- `//src/main/protobuf/net/eagle0/eagle/common:battalion_type_scala_proto`
-
-#### library/util/BUILD.bazel
-- `//src/main/protobuf/net/eagle0/common:hostility_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/api/command/util:army_stats_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/api:available_command_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/api:selected_command_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/common:date_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/common:province_event_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/common:round_phase_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:army_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:battalion_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:faction_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:game_state_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:hero_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:province_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:battalion_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:faction_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:game_state_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:hero_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:province_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:stat_with_condition_scala_proto`
-
-#### library/util/command_choice_helpers/BUILD.bazel
-- `//src/main/protobuf/net/eagle0/common:hostility_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/api/command/util:armed_battalion_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/api/command/util:battalion_with_food_cost_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/api:available_command_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/api:selected_command_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/common:battalion_type_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/common:combat_unit_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/common:diplomacy_offer_scala_proto`
-
-#### library/util/command_choice_helpers/quest_command_selectors/BUILD.bazel
-- `//src/main/protobuf/net/eagle0/eagle/api:available_command_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/common:improvement_type_scala_proto`
-
-#### library/util/faction_utils/BUILD.bazel
-- `//src/main/protobuf/net/eagle0/common:hostility_scala_proto`
-
-#### library/util/quest_creation/BUILD.bazel
-- `//src/main/protobuf/net/eagle0/eagle/internal:action_result_scala_proto`
-
-#### library/util/quest_fulfillment/BUILD.bazel
-- `//src/main/protobuf/net/eagle0/eagle/internal:unaffiliated_hero_scala_proto`
-
-#### library/util/view_filters/BUILD.bazel
-- `//src/main/protobuf/net/eagle0/common:hostility_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/common:province_event_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:army_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:battalion_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:faction_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:game_state_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:hero_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:province_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/internal:shardok_battle_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:army_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:battalion_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:faction_relationship_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:faction_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:game_state_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:hero_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:incoming_army_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:province_view_scala_proto`
-- `//src/main/protobuf/net/eagle0/eagle/views:shardok_battle_view_scala_proto`
-
----
-
-### Summary by Directory
-
-| Directory | Files | Imports | Status |
-|-----------|-------|---------|--------|
-| `actions/availability/` | 0 | 0 | ✅ Clean |
-| `actions/impl/action/` | 2 | 3 | Boundary code |
-| `actions/impl/common/` | 1 | 2 | Boundary code |
-| `actions/llm_prompt_generators/` | 24 | 46 | LLM request types |
-| `actions/llm_request_generators/` | 1 | 2 | LLM request types |
-| `settings/loaders/` | 1 | 1 | Loader (expected) |
-| `util/` | 9 | 20 | Mixed - cleanup candidates |
-| `util/command_choice_helpers/` | 17 | 57 | API types |
-| `util/view_filters/` | 1 | 1 | View boundary |
-| Root (`library/`) | 3 | 5 | Boundary code |
-
----
-
-### Detailed Inventory
-
-#### Root library/ (5 imports, 3 files)
-
-| File | Line | Import | Notes |
-|------|------|--------|-------|
-| `ActionResultFilter.scala` | 3 | `common.action_result_notification_details.Notification` | Action result filtering |
-| `ActionResultFilter.scala` | 4 | `common.action_result_type.ActionResultType` | |
-| `ActionResultFilter.scala` | 5 | `common.action_result_type.ActionResultType.*` | |
-| `Engine.scala` | 6 | `internal.action_result.ActionResult` | Trait interface |
-| `EngineImpl.scala` | 8 | `internal.action_result.ActionResult` | Returns proto for persistence |
-
-#### actions/impl/action/ (3 imports, 2 files)
-
-| File | Line | Import | Notes |
-|------|------|--------|-------|
-| `ChronicleEventGenerator.scala` | 3 | `common.action_result_type.ActionResultType.FACTION_DESTROYED` | Single enum value |
-| `PerformVassalCommandsPhaseAction.scala` | 5 | `api.available_command.{AvailableCommand, RestAvailableCommand}` | Commands from factory |
-| `PerformVassalDefenseDecisionsAction.scala` | 4 | `api.available_command.AvailableCommand` | Commands from factory |
-
-#### actions/impl/common/ (2 imports, 1 file)
-
-| File | Line | Import | Notes |
-|------|------|--------|-------|
-| `ActionWithResultingState.scala` | 3 | `internal.action_result.ActionResult` | Caches both proto and Scala |
-| `ActionWithResultingState.scala` | 4 | `internal.game_state.GameState` | |
-
-#### actions/llm_prompt_generators/ (46 imports, 24 files)
-
-| File | Line | Import | Notes |
-|------|------|--------|-------|
-| `AllianceOfferMessagePromptGenerator.scala` | 4 | `internal.generated_text_request.AllianceOfferMessage` | LLM request type |
-| `AllianceResolutionMessagePromptGenerator.scala` | 4 | `common.diplomacy_offer_status.DiplomacyOfferStatus` | |
-| `AllianceResolutionMessagePromptGenerator.scala` | 5 | `common.diplomacy_offer_status.DiplomacyOfferStatus.{...}` | |
-| `AllianceResolutionMessagePromptGenerator.scala` | 13 | `internal.generated_text_request.AllianceOfferResolutionMessage` | |
-| `BattalionDescriptions.scala` | 3 | `common.battalion_type.BattalionTypeId` | |
-| `BattalionDescriptions.scala` | 4 | `internal.battalion.Battalion` | |
-| `BreakAllianceMessagePromptGenerator.scala` | 4 | `internal.generated_text_request.BreakAllianceMessage` | |
-| `BreakAllianceResolutionMessagePromptGenerator.scala` | 4 | `common.diplomacy_offer_status.DiplomacyOfferStatus` | |
-| `BreakAllianceResolutionMessagePromptGenerator.scala` | 5 | `common.diplomacy_offer_status.DiplomacyOfferStatus.{...}` | |
-| `BreakAllianceResolutionMessagePromptGenerator.scala` | 13 | `internal.generated_text_request.BreakAllianceResolutionMessage` | |
-| `CapturedHeroMessagePromptGenerator.scala` | 4 | `internal.generated_text_request.{...}` | |
-| `ChronicleEventTextGenerator.scala` | 4 | `internal.event_for_chronicle.{...}` | |
-| `ChronicleEventTextGenerator.scala` | 31 | `internal.event_for_chronicle.ShatteredArmyEvent.Reason.{...}` | |
-| `ChronicleUpdatePromptGenerator.scala` | 4 | `common.date.Date` | |
-| `ChronicleUpdatePromptGenerator.scala` | 5 | `internal.event_for_chronicle.EventForChronicle` | |
-| `ChronicleUpdatePromptGenerator.scala` | 6 | `internal.generated_text_request.ChronicleUpdateMessage` | |
-| `DivineMessagePromptGenerator.scala` | 4 | `internal.generated_text_request.DivineMessage` | |
-| `ExileVassalPromptGenerator.scala` | 4 | `internal.generated_text_request.ExileVassalMessage` | |
-| `GeneratorUtilities.scala` | 13 | `common.date.Date` | |
-| `HandleCapturedHeroPleaPromptGenerator.scala` | 4 | `internal.generated_text_request.HandleCapturedHeroPlea` | |
-| `HeroBackstoryUpdatePromptGenerator.scala` | 4 | `common.diplomacy_offer_status.DiplomacyOfferStatus.{...}` | |
-| `HeroBackstoryUpdatePromptGenerator.scala` | 9 | `internal.event_for_hero_backstory.{...}` | |
-| `HeroBackstoryUpdatePromptGenerator.scala` | 37 | `internal.event_for_hero_backstory.FoughtInBattleBackstoryEvent.UnitStatus` | |
-| `HeroBackstoryUpdatePromptGenerator.scala` | 38 | `internal.event_for_hero_backstory.FoughtInBattleBackstoryEvent.UnitStatus.{...}` | |
-| `HeroBackstoryUpdatePromptGenerator.scala` | 47 | `internal.generated_text_request.HeroBackstoryUpdateRequest` | |
-| `HeroDeparturePromptGenerator.scala` | 4 | `internal.generated_text_request.HeroDepartureMessage` | |
-| `HeroInitialBackstoryPromptGenerator.scala` | 4 | `internal.generated_text_request.HeroInitialBackstoryRequest` | |
-| `InvitationMessagePromptGenerator.scala` | 4 | `internal.generated_text_request.InvitationMessage` | |
-| `InvitationResolutionMessagePromptGenerator.scala` | 4 | `common.diplomacy_offer_status.DiplomacyOfferStatus` | |
-| `InvitationResolutionMessagePromptGenerator.scala` | 5 | `common.diplomacy_offer_status.DiplomacyOfferStatus.{...}` | |
-| `InvitationResolutionMessagePromptGenerator.scala` | 13 | `internal.generated_text_request.InvitationResolutionMessage` | |
-| `NewFactionHeadPromptGenerator.scala` | 4 | `internal.generated_text_request.NewFactionHeadMessage` | |
-| `PleaseRecruitMePromptGenerator.scala` | 4 | `internal.generated_text_request.PleaseRecruitMeMessage` | |
-| `PrisonerExecutedPromptGenerator.scala` | 4 | `internal.generated_text_request.PrisonerExecutedMessage` | |
-| `PrisonerExiledPromptGenerator.scala` | 4 | `internal.generated_text_request.PrisonerExiledMessage` | |
-| `PrisonerReleasedPromptGenerator.scala` | 4 | `internal.generated_text_request.PrisonerReleasedMessage` | |
-| `PrisonerReturnedPromptGenerator.scala` | 4 | `internal.generated_text_request.PrisonerReturnedMessage` | |
-| `ProfessionGainedPromptGenerator.scala` | 4 | `internal.generated_text_request.ProfessionGainedMessage` | |
-| `QuestEndedGeneratorUtilities.scala` | 5 | `common.battalion_type.BattalionTypeId` | |
-| `QuestEndedGeneratorUtilities.scala` | 6 | `common.unaffiliated_hero_quest.{...}` | |
-| `QuestEndedGeneratorUtilities.scala` | 29 | `common.unaffiliated_hero_quest.QuestDetails.Empty` | |
-| `QuestFailedPromptGenerator.scala` | 4 | `internal.generated_text_request.QuestFailedMessage` | |
-| `QuestFulfilledPromptGenerator.scala` | 4 | `internal.generated_text_request.QuestFulfilledMessage` | |
-| `RansomOfferMessagePromptGenerator.scala` | 4 | `internal.generated_text_request.RansomOfferMessage` | |
-| `RansomResolutionMessagePromptGenerator.scala` | 4 | `common.diplomacy_offer_status.DiplomacyOfferStatus` | |
-| `RansomResolutionMessagePromptGenerator.scala` | 5 | `common.diplomacy_offer_status.DiplomacyOfferStatus.{...}` | |
-| `RansomResolutionMessagePromptGenerator.scala` | 13 | `internal.generated_text_request.RansomResolutionMessage` | |
-| `RecruitmentRefusedPromptGenerator.scala` | 4 | `internal.generated_text_request.RecruitmentRefusedMessage` | |
-| `SuppressBeastsPromptGenerator.scala` | 4 | `internal.generated_text_request.{...}` | |
-| `SwearBrotherhoodPromptGenerator.scala` | 3 | `common.gender.Gender.{...}` | |
-| `SwearBrotherhoodPromptGenerator.scala` | 4 | `internal.generated_text_request.SwearBrotherhoodMessage` | |
-| `TruceOfferMessagePromptGenerator.scala` | 4 | `internal.generated_text_request.TruceOfferMessage` | |
-| `TruceResolutionMessagePromptGenerator.scala` | 4 | `common.diplomacy_offer_status.DiplomacyOfferStatus` | |
-| `TruceResolutionMessagePromptGenerator.scala` | 5 | `common.diplomacy_offer_status.DiplomacyOfferStatus.{...}` | |
-| `TruceResolutionMessagePromptGenerator.scala` | 13 | `internal.generated_text_request.TruceResolutionMessage` | |
-
-#### actions/llm_request_generators/ (2 imports, 1 file)
-
-| File | Line | Import | Notes |
-|------|------|--------|-------|
-| `DiplomacyResolutionLlmRequestGenerator.scala` | 4 | `common.diplomacy_offer_status.DiplomacyOfferStatus` | |
-| `DiplomacyResolutionLlmRequestGenerator.scala` | 5 | `internal.generated_text_request.{...}` | |
-
-#### settings/loaders/ (1 import, 1 file)
-
-| File | Line | Import | Notes |
-|------|------|--------|-------|
-| `BattalionTypeLoader.scala` | 8 | `common.battalion_type.{BattalionType, BattalionTypeId}` | Loads from file, converts immediately |
-
-#### util/ (20 imports, 9 files)
-
-| File | Line | Import | Notes |
-|------|------|--------|-------|
-| `ArmyUtils.scala` | 3 | `internal.army.{Army, HostileArmyGroup, MovingArmy}` | Has Scala overloads |
-| `ArmyUtils.scala` | 4 | `internal.game_state.GameState` | |
-| `CommandSelection.scala` | 4 | `api.available_command.AvailableCommand` | Wraps proto command |
-| `CommandSelection.scala` | 5 | `api.selected_command.SelectedCommand` | |
-| `DateProtoUtils.scala` | 5 | `common.date.Date` | Conversion utility |
-| `GameStateViewDiffer.scala` | 3 | `common.round_phase.NewRoundPhase` | View diff for client |
-| `IDable.scala` | 4 | `internal.battalion.Battalion` | Test helper only |
-| `IDable.scala` | 5 | `internal.faction.Faction` | |
-| `IDable.scala` | 6 | `internal.hero.Hero` | |
-| `IDable.scala` | 7 | `internal.province.Province` | |
-| `IncomingArmyUtils.scala` | 4 | `api.command.util.army_stats.ArmyStats` | Returns proto type |
-| `IncomingArmyUtils.scala` | 5 | `internal.army.{Army, MovingArmy}` | Has Scala overloads |
-| `IncomingArmyUtils.scala` | 6 | `internal.game_state.GameState` | |
-| `IncomingArmyUtils.scala` | 7 | `internal.province.Province` | |
-| `MapGenerator.scala` | 6 | `internal.province.{Neighbor, Province}` | Map generation |
-| `ProvinceEventUtils.scala` | 3 | `common.beast_info.BeastInfo` | |
-| `ProvinceEventUtils.scala` | 4 | `common.province_event.*` | |
-
-#### util/command_choice_helpers/ (57 imports, 17 files)
-
-| File | Line | Import | Notes |
-|------|------|--------|-------|
-| `AllianceOfferCommandSelector.scala` | 4 | `api.available_command.{AvailableCommand, DiplomacyAvailableCommand}` | |
-| `AllianceOfferCommandSelector.scala` | 5 | `api.command.util.diplomacy_option.{AllianceOption, DiplomacyOption}` | |
-| `AllianceOfferCommandSelector.scala` | 6 | `api.selected_command.DiplomacySelectedCommand` | |
-| `AlmsCommandSelector.scala` | 4 | `api.available_command.{AlmsAvailableCommand, AvailableCommand}` | |
-| `AlmsCommandSelector.scala` | 5 | `api.selected_command.AlmsSelectedCommand` | |
-| `AttackCommandChooser.scala` | 4 | `api.available_command.*` | |
-| `AttackCommandChooser.scala` | 5 | `api.selected_command.*` | |
-| `AttackCommandChooser.scala` | 6 | `common.combat_unit.CombatUnit` | |
-| `AttackDecisionCommandChooser.scala` | 5 | `api.available_command.{AttackDecisionAvailableCommand, AvailableCommand}` | |
-| `AttackDecisionCommandChooser.scala` | 6 | `api.command.util.attack_decision_type.{...}` | |
-| `AttackDecisionCommandChooser.scala` | 12 | `api.selected_command.AttackDecisionSelectedCommand` | |
-| `AttackDecisionCommandChooser.scala` | 13 | `common.tribute_amount.TributeAmount` | |
-| `AvailableCommandSelector.scala` | 6 | `api.available_command.AvailableCommand` | |
-| `CombatUnitSelector.scala` | 5 | `common.combat_unit.CombatUnit` | |
-| `CommandChoiceHelpers.scala` | 5 | `api.available_command.*` | |
-| `CommandChoiceHelpers.scala` | 6 | `api.command.util.armed_battalion.ArmedBattalion` | |
-| `CommandChoiceHelpers.scala` | 7 | `api.command.util.attack_decision_type.{AdvanceDecision, WithdrawDecision}` | |
-| `CommandChoiceHelpers.scala` | 8 | `api.command.util.captured_hero_option.CapturedHeroOption.{...}` | |
-| `CommandChoiceHelpers.scala` | 13 | `api.command.util.diplomacy_option.RansomOfferOption` | |
-| `CommandChoiceHelpers.scala` | 14 | `api.selected_command.*` | |
-| `CommandChoiceHelpers.scala` | 15 | `api.selected_command.OrganizeTroopsSelectedCommand.{ChangedBattalion, NewBattalion}` | |
-| `CommandChoiceHelpers.scala` | 16 | `common.battalion_type.BattalionTypeId` | |
-| `CommandChoiceHelpers.scala` | 17 | `common.combat_unit.CombatUnit` | |
-| `CommandChoiceHelpers.scala` | 18 | `common.improvement_type.ImprovementType.INFRASTRUCTURE` | |
-| `CommandChoiceHelpers.scala` | 19 | `common.tribute_amount.TributeAmount` | |
-| `CommandChooser.scala` | 6 | `api.available_command.AvailableCommand` | |
-| `ExileVassalCommandSelector.scala` | 4 | `api.available_command.{AvailableCommand, ExileVassalAvailableCommand}` | |
-| `ExileVassalCommandSelector.scala` | 5 | `api.selected_command.ExileVassalSelectedCommand` | |
-| `ExpandCommandSelector.scala` | 7 | `api.available_command.{AvailableCommand, MarchAvailableCommand, MarchCommandFromOneProvince}` | |
-| `ExpandCommandSelector.scala` | 8 | `api.selected_command.MarchSelectedCommand` | |
-| `ExpandCommandSelector.scala` | 9 | `common.combat_unit.CombatUnit` | |
-| `FulfillQuestsCommandSelector.scala` | 4 | `api.available_command.AvailableCommand` | |
-| `HeroGiftCommandSelector.scala` | 4 | `api.available_command.{AvailableCommand, HeroGiftAvailableCommand}` | |
-| `HeroGiftCommandSelector.scala` | 5 | `api.selected_command.HeroGiftSelectedCommand` | |
-| `ImproveCommandSelector.scala` | 4 | `api.available_command.{AvailableCommand, ImproveAvailableCommand}` | |
-| `ImproveCommandSelector.scala` | 5 | `api.selected_command.ImproveSelectedCommand` | |
-| `ImproveCommandSelector.scala` | 6 | `common.improvement_type.ImprovementType` | |
-| `ImproveCommandSelector.scala` | 7 | `common.improvement_type.ImprovementType.DEVASTATION` | |
-| `OrganizeCommandSelector.scala` | 5 | `api.available_command.{AvailableCommand, OrganizeTroopsAvailableCommand}` | |
-| `OrganizeCommandSelector.scala` | 6 | `api.selected_command.OrganizeTroopsSelectedCommand` | |
-| `OrganizeCommandSelector.scala` | 7 | `api.selected_command.OrganizeTroopsSelectedCommand.{ChangedBattalion, NewBattalion}` | |
-| `OrganizeCommandSelector.scala` | 8 | `common.battalion_type.BattalionTypeId` | |
-| `RansomOfferHelpers.scala` | 3 | `common.diplomacy_offer.RansomOfferDetails` | |
-| `RansomOfferHelpers.scala` | 4 | `common.diplomacy_offer_status.DiplomacyOfferStatus` | |
-| `RansomOfferHelpers.scala` | 5 | `common.diplomacy_offer_status.DiplomacyOfferStatus.{...}` | |
-| `SwearBrotherhoodCommandSelector.scala` | 4 | `api.available_command.{AvailableCommand, SwearBrotherhoodAvailableCommand}` | |
-| `SwearBrotherhoodCommandSelector.scala` | 5 | `api.selected_command.SwearBrotherhoodSelectedCommand` | |
-| `TruceOfferCommandSelector.scala` | 4 | `api.available_command.{AvailableCommand, DiplomacyAvailableCommand}` | |
-| `TruceOfferCommandSelector.scala` | 5 | `api.command.util.diplomacy_option.{DiplomacyOption, TruceOption}` | |
-| `TruceOfferCommandSelector.scala` | 6 | `api.selected_command.DiplomacySelectedCommand` | |
-
-#### util/command_choice_helpers/quest_command_selectors/ (12 imports, 10 files)
-
-| File | Line | Import | Notes |
-|------|------|--------|-------|
-| `AllianceQuestCommandChooser.scala` | 4 | `api.available_command.{AvailableCommand, DiplomacyAvailableCommand}` | |
-| `AllianceQuestCommandChooser.scala` | 5 | `api.command.util.diplomacy_option.AllianceOption` | |
-| `AlmsAcrossRealmQuestCommandChooser.scala` | 2 | `api.available_command.AvailableCommand` | |
-| `AlmsToProvinceQuestCommandChooser.scala` | 3 | `api.available_command.AvailableCommand` | |
-| `DismissSpecificVassalCommandChooser.scala` | 5 | `api.available_command.AvailableCommand` | |
-| `GiveToHeroesAcrossRealmQuestCommandChooser.scala` | 2 | `api.available_command.AvailableCommand` | |
-| `GiveToHeroesInProvinceQuestCommandChooser.scala` | 4 | `api.available_command.AvailableCommand` | |
-| `ImproveQuestCommandChooser.scala` | 3 | `api.available_command.AvailableCommand` | |
-| `ImproveQuestCommandChooser.scala` | 4 | `common.improvement_type.ImprovementType.{...}` | |
-| `QuestCommandChooser.scala` | 4 | `api.available_command.AvailableCommand` | |
-| `TruceCountQuestCommandChooser.scala` | 4 | `api.available_command.AvailableCommand` | |
-| `TruceWithFactionQuestCommandChooser.scala` | 3 | `api.available_command.AvailableCommand` | |
-
-#### util/view_filters/ (1 import, 1 file)
-
-| File | Line | Import | Notes |
-|------|------|--------|-------|
-| `ProvinceViewFilter.scala` | 3 | `common.province_event.ProvinceEvent` | For knownEvents field |
-
-#### util/province/ (1 import, 1 file)
-
-| File | Line | Import | Notes |
-|------|------|--------|-------|
-| `ProvinceUtils.scala` | 4 | `common.battalion_type.BattalionType` | Single proto reference |
-
----
-
-### Cleanup Candidates (Priority Order)
-
-1. **Delete proto overloads where Scala overloads exist and proto unused**
-   - `IncomingArmyUtils.scala` - verify all main callers use Scala overloads
-   - `ArmyUtils.scala` - verify all main callers use Scala overloads
-
-2. **Move test-only utilities to test code**
-   - `IDable.scala` - only used by tests (except StartGameActionResultUtils)
-
-3. **Create Scala versions of common enums**
-   - `DiplomacyOfferStatus` → already done in availability package
-   - `ImprovementType` → used by ImproveCommandSelector, CommandChoiceHelpers
-   - `BattalionTypeId` → used by multiple command selectors
-
-4. **Large refactoring (requires Scala AvailableCommand/SelectedCommand)**
-   - `command_choice_helpers/` package (57 imports) - uses proto API command types
-   - Would need Scala versions of AvailableCommand and SelectedCommand hierarchies

MODULE.bazel

@@ -1,26 +1,27 @@
 module(name = "net_eagle0")
 
 # Version constants
-SCALA_VERSION = "3.7.2"
+SCALA_VERSION = "3.7.4"
 
-NETTY_VERSION = "4.1.110.Final"
+NETTY_VERSION = "4.1.127.Final"
 
 SCALAPB_VERSION = "1.0.0-alpha.1"
 
-AWS_SDK_VERSION = "2.28.1"
+AWS_SDK_VERSION = "2.41.18"
 
 #
 # Core Build Tools
 #
 
 bazel_dep(name = "bazel_skylib", version = "1.9.0")
+bazel_dep(name = "platforms", version = "1.0.0")
 bazel_dep(name = "rules_pkg", version = "1.2.0")
 
 #
 # Language Support - Scala
 #
 
-bazel_dep(name = "rules_scala", version = "7.1.1")
+bazel_dep(name = "rules_scala", version = "7.2.1")
 
 scala_config = use_extension(
     "@rules_scala//scala/extensions:config.bzl",
@@ -47,14 +48,14 @@ llvm = use_extension("@toolchains_llvm//toolchain/extensions:llvm.bzl", "llvm")
 # Native toolchain (macOS -> macOS, Linux -> Linux)
 llvm.toolchain(
     name = "llvm_toolchain",
-    llvm_version = "20.1.2",
+    llvm_version = "20.1.4",
 )
 
 # Cross-compilation toolchain (macOS -> Linux x86_64)
 # Uses the same LLVM distribution but with a Linux sysroot
 llvm.toolchain(
     name = "llvm_toolchain_linux",
-    llvm_version = "20.1.2",
+    llvm_version = "20.1.4",
 )
 
 # Linux x86_64 sysroot for cross-compilation
@@ -67,7 +68,7 @@ llvm.sysroot(
 # Cross-compilation toolchain (macOS -> Linux ARM64)
 llvm.toolchain(
     name = "llvm_toolchain_linux_arm64",
-    llvm_version = "20.1.2",
+    llvm_version = "20.1.4",
 )
 
 # Linux ARM64 sysroot for cross-compilation
@@ -107,6 +108,7 @@ bazel_dep(name = "gazelle", version = "0.47.0", repo_name = "bazel_gazelle")
 
 go_sdk = use_extension("@io_bazel_rules_go//go:extensions.bzl", "go_sdk")
 go_sdk.download(version = "1.23.3")
+use_repo(go_sdk, "go_default_sdk")
 
 go_deps = use_extension("@bazel_gazelle//:extensions.bzl", "go_deps")
 go_deps.from_file(go_mod = "//:go.mod")
@@ -118,26 +120,70 @@ use_repo(
     "com_github_aws_aws_sdk_go_v2_service_s3",
     "com_github_golang_jwt_jwt_v5",
     "com_github_google_uuid",
+    "com_github_webview_webview_go",
     "org_golang_google_grpc",
     "org_golang_google_protobuf",
+    "org_golang_x_sys",
 )
 
+#
+# Language Support - Rust
+#
+
+bazel_dep(name = "rules_rust", version = "0.68.1")
+
+rust = use_extension("@rules_rust//rust:extensions.bzl", "rust")
+rust.toolchain(edition = "2021")
+use_repo(rust, "rust_toolchains")
+
+register_toolchains("@rust_toolchains//:all")
+
+crate = use_extension("@rules_rust//crate_universe:extension.bzl", "crate")
+crate.from_cargo(
+    name = "map_generator_crates",
+    cargo_lockfile = "//src/main/rust/net/eagle0/eagle/map_generator:Cargo.lock",
+    manifests = ["//src/main/rust/net/eagle0/eagle/map_generator:Cargo.toml"],
+)
+use_repo(crate, "map_generator_crates")
+
 #
 # Platform Support - Apple/iOS
 #
+# Note: rules_apple is NOT included in the main workspace due to rules_swift
+# version conflicts with grpc. SparklePlugin (which needs rules_apple) is built
+# in a separate workspace at sparkle_workspace/ to isolate the conflict.
+#
 
-bazel_dep(name = "apple_support", version = "1.21.1", repo_name = "build_bazel_apple_support")
-bazel_dep(name = "rules_apple", version = "4.3.3", repo_name = "build_bazel_rules_apple")
-bazel_dep(name = "rules_swift", version = "2.4.0", repo_name = "build_bazel_rules_swift")
+bazel_dep(name = "apple_support", version = "1.24.1", repo_name = "build_bazel_apple_support")
+
+# rules_swift is a transitive dep of grpc and flatbuffers with conflicting versions:
+# - grpc 1.76.0.bcr.1 requires rules_swift 3.x (compatibility level 3)
+# - flatbuffers requires rules_swift 2.x (compatibility level 2)
+# We don't use Swift directly, but we need to force a single version.
+# Force 3.x since grpc is more complex and harder to downgrade.
+single_version_override(
+    module_name = "rules_swift",
+    version = "3.1.2",
+)
+
+# Register Apple CC toolchain for Objective-C compilation
+apple_cc_configure = use_extension(
+    "@build_bazel_apple_support//crosstool:setup.bzl",
+    "apple_cc_configure_extension",
+)
+use_repo(apple_cc_configure, "local_config_apple_cc")
 
 #
 # Protocol Buffers & RPC
 #
 
-bazel_dep(name = "protobuf", version = "29.2", repo_name = "com_google_protobuf")
-bazel_dep(name = "grpc", version = "1.71.0")
-bazel_dep(name = "grpc-java", version = "1.71.0")
-bazel_dep(name = "flatbuffers", version = "25.9.23")
+bazel_dep(name = "protobuf", version = "33.5", repo_name = "com_google_protobuf")
+bazel_dep(name = "rules_proto", version = "7.1.0")
+bazel_dep(name = "rules_cc", version = "0.2.14")
+bazel_dep(name = "grpc", version = "1.74.1")
+bazel_dep(name = "grpc-java", version = "1.78.0")
+bazel_dep(name = "rules_proto_grpc_csharp", version = "5.8.0")
+bazel_dep(name = "flatbuffers", version = "25.12.19")
 
 #
 # Testing
@@ -150,16 +196,29 @@ bazel_dep(name = "googletest", version = "1.17.0")
 #
 
 bazel_dep(name = "rules_oci", version = "2.2.7")
-bazel_dep(name = "aspect_bazel_lib", version = "2.22.4")
+bazel_dep(name = "aspect_bazel_lib", version = "2.22.5")
 
 oci = use_extension("@rules_oci//oci:extensions.bzl", "oci")
 
-# Base image for Eagle (Java 17 JDK - includes jcmd for JFR dumps)
+# Base image for Eagle (Java 25 JRE - smaller runtime, no dev tools needed)
+# Digest pinned for Bazel repository cache hit; update with:
+#   TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/eclipse-temurin:pull" | python3 -c "import json,sys; print(json.load(sys.stdin)['token'])")
+#   curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.oci.image.index.v1+json,application/vnd.docker.distribution.manifest.list.v2+json" "https://registry-1.docker.io/v2/library/eclipse-temurin/manifests/25-jre" | python3 -c "import json,sys; m=json.load(sys.stdin); [print(p['digest']) for p in m.get('manifests',[]) if p['platform']['architecture']=='amd64']"
 oci.pull(
-    name = "eclipse_temurin_17",
+    name = "eclipse_temurin_25_jre",
+    digest = "sha256:98236ffdfb61cff3fc4f8e40e5b80460a5a4c35a0f56a5b4182a926844a7db49",
     image = "docker.io/library/eclipse-temurin",
     platforms = ["linux/amd64"],
-    tag = "17-jdk",
+    tag = "25-jre",
+)
+
+# Base image for JFR sidecar (Java 25 JDK - includes jcmd for JFR dumps)
+oci.pull(
+    name = "eclipse_temurin_25_jdk",
+    digest = "sha256:bc2d562355813350f47bc472b9721b0b84761866671ad95d9a9f1151fa69da6e",
+    image = "docker.io/library/eclipse-temurin",
+    platforms = ["linux/amd64"],
+    tag = "25-jdk",
 )
 
 # Base image for Shardok (Ubuntu 24.04 for C++ runtime)
@@ -180,13 +239,14 @@ oci.pull(
     platforms = ["linux/amd64"],
     tag = "3.21",
 )
-use_repo(oci, "alpine_linux", "alpine_linux_linux_amd64", "eclipse_temurin_17", "eclipse_temurin_17_linux_amd64", "ubuntu_24_04", "ubuntu_24_04_linux_amd64", "ubuntu_24_04_linux_arm64_v8")
+use_repo(oci, "alpine_linux", "alpine_linux_linux_amd64", "eclipse_temurin_25_jdk", "eclipse_temurin_25_jdk_linux_amd64", "eclipse_temurin_25_jre", "eclipse_temurin_25_jre_linux_amd64", "ubuntu_24_04", "ubuntu_24_04_linux_amd64", "ubuntu_24_04_linux_arm64_v8")
 
 #
 # Java/Scala Dependencies
 #
 
-bazel_dep(name = "rules_jvm_external", version = "6.9")
+bazel_dep(name = "rules_java", version = "9.3.0")
+bazel_dep(name = "rules_jvm_external", version = "6.10")
 
 maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")
 maven.install(
@@ -248,7 +308,10 @@ maven.install(
         "com.nimbusds:nimbus-jose-jwt:9.37.3",
 
         # Error tracking
-        "io.sentry:sentry:7.19.0",
+        "io.sentry:sentry:8.31.0",
+
+        # SQLite for client text storage
+        "org.xerial:sqlite-jdbc:3.46.1.0",
     ],
     duplicate_version_warning = "error",
     fail_if_repin_required = True,
@@ -257,6 +320,27 @@ maven.install(
         "https://repo1.maven.org/maven2",
     ],
 )
+
+# Force specific versions for dependencies with conflicts between grpc-java and protobuf
+maven.artifact(
+    artifact = "gson",
+    force_version = True,
+    group = "com.google.code.gson",
+    version = "2.11.0",
+)
+maven.artifact(
+    artifact = "error_prone_annotations",
+    force_version = True,
+    group = "com.google.errorprone",
+    version = "2.30.0",
+)
+maven.artifact(
+    artifact = "guava",
+    force_version = True,
+    group = "com.google.guava",
+    version = "33.3.1-android",
+)
+
 use_repo(maven, "maven", "unpinned_maven")
 
 #
@@ -273,7 +357,14 @@ GTL_SHA = "1969c45dd76eac0dd87e9e2b65cffe358617f4fe1bcd203f72f427742537913a"
 
 http_archive(
     name = "gtl",
-    build_file = "@//external:BUILD.gtl",
+    build_file_content = """
+cc_library(
+    name = "gtl",
+    hdrs = glob(["include/gtl/*.hpp"]),
+    includes = ["include"],
+    visibility = ["//visibility:public"],
+)
+""",
     sha256 = GTL_SHA,
     strip_prefix = "gtl-%s" % GTL_VERSION,
     url = "https://github.com/greg7mdp/gtl/archive/refs/tags/v%s.zip" % GTL_VERSION,
@@ -293,6 +384,9 @@ http_archive(
     ],
 )
 
+# Note: Sparkle framework is defined in sparkle_workspace/MODULE.bazel
+# (not in main workspace due to rules_swift version conflicts)
+
 # Busybox static binary for Docker health checks (provides nc, wget, etc.)
 # Primary: DigitalOcean Spaces (public, reliable)
 # Fallback: busybox.net (can be unreliable/slow)
@@ -318,6 +412,60 @@ http_file(
     executable = True,
 )
 
+# LLVM MinGW toolchain for Windows cross-compilation from macOS
+# This provides a complete toolchain for building Windows executables including
+# the MinGW-w64 libraries needed for CGO cross-compilation
+LLVM_MINGW_VERSION = "20250305"
+
+http_archive(
+    name = "llvm_mingw",
+    build_file_content = """
+package(default_visibility = ["//visibility:public"])
+
+filegroup(
+    name = "all_files",
+    srcs = glob(["**/*"]),
+)
+
+filegroup(
+    name = "compiler_files",
+    srcs = glob([
+        "bin/x86_64-w64-mingw32-*",
+        "bin/clang*",
+        "bin/llvm-*",
+        "bin/lld*",
+    ]),
+)
+
+filegroup(
+    name = "windows_x86_64_sysroot",
+    srcs = glob([
+        "x86_64-w64-mingw32/**/*",
+        "generic-w64-mingw32/include/**/*",
+    ]),
+)
+
+filegroup(
+    name = "linker_files",
+    srcs = glob([
+        "bin/x86_64-w64-mingw32-*",
+        "bin/lld*",
+        "bin/ld.lld*",
+        "lib/**/*",
+        "x86_64-w64-mingw32/lib/**/*",
+    ]),
+)
+
+exports_files([
+    "bin/x86_64-w64-mingw32-clang",
+    "bin/x86_64-w64-mingw32-clang++",
+])
+""",
+    sha256 = "32c24fc62fc8b9f8a900bf2c730b78b36767688f816f9d21e97a168289ff44e0",
+    strip_prefix = "llvm-mingw-%s-ucrt-macos-14.4.1-universal" % LLVM_MINGW_VERSION,
+    urls = ["https://github.com/fathonix/llvm-mingw-arm64ec-macos/releases/download/%s/llvm-mingw-%s-ucrt-macos-14.4.1-universal.tar.xz" % (LLVM_MINGW_VERSION, LLVM_MINGW_VERSION)],
+)
+
 #
 # Toolchain Registration
 #

ci/BUILD.bazel

@@ -1,6 +1,19 @@
 load("@rules_oci//oci:defs.bzl", "oci_image", "oci_load", "oci_push")
 load("@rules_pkg//pkg:tar.bzl", "pkg_tar")
 
+#
+# Deployment artifacts (tools needed on the host, not in containers)
+#
+
+pkg_tar(
+    name = "warmup_tar",
+    srcs = ["//src/main/go/net/eagle0/warmup:warmup_linux_amd64"],
+    package_dir = "bin",
+    remap_paths = {
+        "/warmup_linux_amd64": "/warmup",
+    },
+)
+
 #
 # Shared utilities layer (busybox for nc, wget, etc.)
 #
@@ -60,7 +73,7 @@ pkg_tar(
 
 oci_image(
     name = "eagle_server_image",
-    base = "@eclipse_temurin_17_linux_amd64",
+    base = "@eclipse_temurin_25_jre_linux_amd64",
     entrypoint = [
         "java",
         "-Xmx2g",
@@ -230,6 +243,13 @@ pkg_tar(
     package_dir = "/app",
 )
 
+# Package the .e0mj map files for the map editor
+pkg_tar(
+    name = "admin_maps_layer",
+    srcs = ["//src/main/resources/net/eagle0/shardok/maps:maps_json"],
+    package_dir = "/app/maps",
+)
+
 oci_image(
     name = "admin_server_image",
     base = "@alpine_linux_linux_amd64",
@@ -238,6 +258,7 @@ oci_image(
     tars = [
         ":busybox_layer",
         ":admin_binary_layer",
+        ":admin_maps_layer",
     ],
     workdir = "/app",
 )
@@ -275,7 +296,7 @@ pkg_tar(
 oci_image(
     name = "jfr_sidecar_image",
     # Use JDK base image - we need jcmd to dump JFR recordings
-    base = "@eclipse_temurin_17_linux_amd64",
+    base = "@eclipse_temurin_25_jdk_linux_amd64",
     entrypoint = ["/app/jfr_server_linux_amd64"],
     exposed_ports = ["8081/tcp"],
     tars = [
@@ -317,6 +338,13 @@ pkg_tar(
     package_dir = "/app",
 )
 
+# Package the attributions.json for the credits page
+pkg_tar(
+    name = "auth_attributions_layer",
+    srcs = ["//src/main/resources/net/eagle0:attributions"],
+    package_dir = "/app",
+)
+
 oci_image(
     name = "auth_server_image",
     base = "@alpine_linux_linux_amd64",
@@ -328,6 +356,7 @@ oci_image(
     tars = [
         ":busybox_layer",
         ":auth_binary_layer",
+        ":auth_attributions_layer",
     ],
     workdir = "/app",
 )

ci/build_eagle_installer_win.sh

@@ -1,28 +0,0 @@
-#!/usr/bin/env bash
-
-/bin/mkdir -p win_output
-/usr/bin/dotnet publish src/main/csharp/net/eagle0/clients/win/installer/EagleInstaller.sln -o win_output
-SHA=`sha256sum /tmp/EagleInstaller.exe | awk '{print $1 }'`
-ZIP_FILE="updater__$SHA.zip"
-
-/usr/bin/zip win_output/$ZIP_FILE win_output/EagleInstaller.exe
-rm win_output/EagleInstaller.exe
-rm win_output/EagleInstaller.pdb
-
-DATE=`date +"%Y-%m-%d %T"`
-
-cat > win_output/updater.html <<-EOF
-<html>
-<head>
-<title>Download Eagle Updater</title>
-</head>
-<body>
-<a href="http://eagle0.net/assets/$ZIP_FILE">$ZIP_FILE</a> (updated $DATE)
-</body>
-</html>
-EOF
-
-SSH_KEY_FILE=$1
-SSH_USER_NAME=$2
-
-/usr/bin/rsync -r --copy-links -e "/usr/bin/ssh -i $SSH_KEY_FILE -p 9022" win_output/ $SSH_USER_NAME@eagle0.net:/www/assets/

ci/github_actions/archive_ios.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+
+# Archive and export iOS app for App Store / TestFlight
+
+set -euxo pipefail
+
+# Ensure xcodebuild uses Xcode.app, not Command Line Tools
+export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
+
+XCODE_PROJECT_PATH=${1:?Usage: archive_ios.sh <xcode_project_path> <output_path> <team_id> <profile_uuid>}
+OUTPUT_PATH=${2:?Missing output path}
+TEAM_ID=${3:?Missing team ID}
+PROFILE_UUID=${4:?Missing provisioning profile UUID}
+
+ARCHIVE_PATH="$OUTPUT_PATH/eagle0.xcarchive"
+EXPORT_PATH="$OUTPUT_PATH"
+
+echo "Archiving iOS app..."
+echo "  Xcode project: $XCODE_PROJECT_PATH"
+echo "  Archive path: $ARCHIVE_PATH"
+echo "  Team ID: $TEAM_ID"
+
+mkdir -p "$OUTPUT_PATH"
+
+# Find the .xcodeproj file
+XCODEPROJ=$(find "$XCODE_PROJECT_PATH" -name "*.xcodeproj" -maxdepth 1 | head -1)
+if [ -z "$XCODEPROJ" ]; then
+    echo "Error: No .xcodeproj found in $XCODE_PROJECT_PATH"
+    exit 1
+fi
+
+echo "Found Xcode project: $XCODEPROJ"
+
+# Ensure export compliance key is set in Info.plist
+# This bypasses the "Missing Compliance" prompt in App Store Connect.
+# Set here rather than relying solely on Unity's DeepLinkPostProcessor,
+# which depends on UNITY_IOS being defined at script compilation time.
+INFO_PLIST="$XCODE_PROJECT_PATH/Info.plist"
+if [ -f "$INFO_PLIST" ]; then
+    /usr/libexec/PlistBuddy -c "Set :ITSAppUsesNonExemptEncryption false" "$INFO_PLIST" 2>/dev/null \
+        || /usr/libexec/PlistBuddy -c "Add :ITSAppUsesNonExemptEncryption bool false" "$INFO_PLIST"
+    echo "Set ITSAppUsesNonExemptEncryption=false in Info.plist"
+fi
+
+# Unity always generates "Unity-iPhone" as the main app scheme
+SCHEME="Unity-iPhone"
+echo "Using scheme: $SCHEME"
+
+# Archive without signing - we'll sign during export
+# This avoids issues with provisioning profiles on framework targets
+xcodebuild archive \
+    -project "$XCODEPROJ" \
+    -scheme "$SCHEME" \
+    -archivePath "$ARCHIVE_PATH" \
+    -destination "generic/platform=iOS" \
+    CODE_SIGN_IDENTITY="-" \
+    CODE_SIGNING_REQUIRED=NO \
+    CODE_SIGNING_ALLOWED=NO
+
+echo "Archive complete: $ARCHIVE_PATH"
+
+# Create export options plist
+# Signing happens here, not during archive
+EXPORT_OPTIONS_PLIST="$OUTPUT_PATH/ExportOptions.plist"
+cat > "$EXPORT_OPTIONS_PLIST" << EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>method</key>
+    <string>app-store-connect</string>
+    <key>teamID</key>
+    <string>$TEAM_ID</string>
+    <key>uploadSymbols</key>
+    <true/>
+    <key>signingStyle</key>
+    <string>manual</string>
+    <key>signingCertificate</key>
+    <string>Apple Distribution: Daniel Crosby (UWJ88DX8WQ)</string>
+    <key>provisioningProfiles</key>
+    <dict>
+        <key>net.eagle0.eagle</key>
+        <string>$PROFILE_UUID</string>
+    </dict>
+</dict>
+</plist>
+EOF
+
+echo "Exporting IPA..."
+
+# Debug: List available keychains and signing identities
+echo "=== Debug: Available keychains ==="
+security list-keychains -d user
+echo "=== Debug: Available signing identities ==="
+security find-identity -v -p codesigning
+echo "=== Debug: Export options plist ==="
+cat "$EXPORT_OPTIONS_PLIST"
+echo "=== End debug ==="
+
+# Export IPA (removed -allowProvisioningUpdates as we're using manual signing)
+xcodebuild -exportArchive \
+    -archivePath "$ARCHIVE_PATH" \
+    -exportPath "$EXPORT_PATH" \
+    -exportOptionsPlist "$EXPORT_OPTIONS_PLIST"
+
+# Find and rename the IPA to a consistent name
+IPA_FILE=$(find "$EXPORT_PATH" -name "*.ipa" | head -1)
+if [ -n "$IPA_FILE" ] && [ "$IPA_FILE" != "$EXPORT_PATH/eagle0.ipa" ]; then
+    mv "$IPA_FILE" "$EXPORT_PATH/eagle0.ipa"
+fi
+
+echo "Export complete: $EXPORT_PATH/eagle0.ipa"
+ls -la "$EXPORT_PATH"

ci/github_actions/build_ios_addressables.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+
+# Build iOS Addressables only (no player build)
+# This switches Unity to iOS target and builds addressables for CDN upload
+
+set -euxo pipefail
+
+# Read Unity version from project file
+UNITY_VERSION=$(grep "m_EditorVersion:" src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt | head -1 | sed 's/m_EditorVersion: //')
+
+# Use runner-specific build directory if EAGLE0_BUILD_DIR is set, otherwise default
+BUILD_BASE="${EAGLE0_BUILD_DIR:-/tmp/eagle0}"
+
+WORKSPACE=$(pwd)
+
+echo "Building protos"
+./scripts/build_protos.sh
+UNITY_INSTALL_PATH="/Applications/Unity/Hub/Editor"
+LOG_PATH=${1:-"${BUILD_BASE}/editor_ios_addressables.log"}
+
+echo "Building iOS Addressables"
+
+mkdir -p "$(dirname "$LOG_PATH")"
+
+# Build Addressables for iOS target
+# Uses BuildiOSAddressables which explicitly switches build target
+# Capture exit code to show log on failure
+set +e
+${UNITY_INSTALL_PATH}/${UNITY_VERSION}/Unity.app/Contents/MacOS/Unity \
+   -nographics \
+   -batchmode \
+   -quit \
+   -executeMethod BuildScript.BuildiOSAddressables \
+   -logFile "$LOG_PATH" \
+   -projectPath "$WORKSPACE/src/main/csharp/net/eagle0/clients/unity/eagle0"
+UNITY_EXIT_CODE=$?
+set -e
+
+if [ $UNITY_EXIT_CODE -ne 0 ]; then
+    echo ""
+    echo "Unity build failed with exit code $UNITY_EXIT_CODE"
+    echo "=== Unity Editor Log (last 200 lines) ==="
+    tail -200 "$LOG_PATH" || echo "Could not read log file at $LOG_PATH"
+    echo "=== End of Unity Editor Log ==="
+    exit $UNITY_EXIT_CODE
+fi
+
+echo "iOS Addressables build complete"
+echo "Bundles should be in: $WORKSPACE/src/main/csharp/net/eagle0/clients/unity/eagle0/ServerData/iOS/"

ci/github_actions/build_mac.sh

@@ -2,7 +2,8 @@
 
 set -euxo pipefail
 
-. ./ci/unity_version.sh
+# Read Unity version from project file
+UNITY_VERSION=$(grep "m_EditorVersion:" src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt | head -1 | sed 's/m_EditorVersion: //')
 
 WORKSPACE=$(pwd)
 UNITY_INSTALL_PATH="/Applications/Unity/Hub/Editor"
@@ -15,10 +16,25 @@ echo "Cleaning up $BUILD_DIR"
 /bin/rm -rf "$BUILD_DIR"
 /bin/mkdir -p "$BUILD_DIR"
 
+# Use custom build script that builds Addressables before the player
+# Capture exit code to show log on failure
+set +e
 ${UNITY_INSTALL_PATH}/${UNITY_VERSION}/Unity.app/Contents/MacOS/Unity \
    -nographics \
    -batchmode \
    -quit \
-   -buildOSXUniversalPlayer "$BUILD_DIR/eagle0.app" \
+   -executeMethod BuildScript.BuildMacPlayer \
+   -buildPath "$BUILD_DIR/eagle0.app" \
    -logFile "$LOG_PATH" \
    -projectPath "$WORKSPACE/src/main/csharp/net/eagle0/clients/unity/eagle0"
+UNITY_EXIT_CODE=$?
+set -e
+
+if [ $UNITY_EXIT_CODE -ne 0 ]; then
+    echo ""
+    echo "Unity build failed with exit code $UNITY_EXIT_CODE"
+    echo "=== Unity Editor Log (last 200 lines) ==="
+    tail -200 "$LOG_PATH" || echo "Could not read log file at $LOG_PATH"
+    echo "=== End of Unity Editor Log ==="
+    exit $UNITY_EXIT_CODE
+fi

ci/github_actions/build_unity.sh

@@ -2,20 +2,18 @@
 
 set -euxo pipefail
 
-LOG_PATH=""
+# Use runner-specific build directory if EAGLE0_BUILD_DIR is set, otherwise default
+BUILD_BASE="${EAGLE0_BUILD_DIR:-/tmp/eagle0}"
 
 COMMIT=$(/usr/bin/git rev-parse --short HEAD)
 
 /bin/echo "build protos"
 ./scripts/build_protos.sh
 
-/bin/echo "build plugins"
-./scripts/build_windows_plugin.sh
-
 git log -3
 
 /bin/echo "build Windows"
-LOG_PATH="/tmp/eagle0/editor_win.log"
+LOG_PATH="${BUILD_BASE}/editor_win.log"
 BUILD_DIR=$1
 
 ./ci/github_actions/build_windows.sh $BUILD_DIR $LOG_PATH

ci/github_actions/build_unity_ios.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+
+# Build iOS Unity player (generates Xcode project)
+
+set -euxo pipefail
+
+# Read Unity version from project file
+UNITY_VERSION=$(grep "m_EditorVersion:" src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt | head -1 | sed 's/m_EditorVersion: //')
+
+# Use runner-specific build directory if EAGLE0_BUILD_DIR is set, otherwise default
+BUILD_BASE="${EAGLE0_BUILD_DIR:-/tmp/eagle0}"
+
+WORKSPACE=$(pwd)
+BUILD_PATH=${1:-"${BUILD_BASE}/eagle0iOS"}
+LOG_PATH="${BUILD_BASE}/editor_ios.log"
+
+# Generate unique build number from git commit count
+# This ensures each build has a unique number for TestFlight
+BUILD_NUMBER=$(git rev-list --count HEAD)
+echo "Build number (git commit count): $BUILD_NUMBER"
+
+echo "Building protos"
+./scripts/build_protos.sh
+
+UNITY_INSTALL_PATH="/Applications/Unity/Hub/Editor"
+
+echo "Building iOS Unity player to: $BUILD_PATH"
+
+mkdir -p "$(dirname "$LOG_PATH")"
+mkdir -p "$BUILD_PATH"
+
+# Build iOS player - this generates an Xcode project
+# Capture exit code to show log on failure
+set +e
+${UNITY_INSTALL_PATH}/${UNITY_VERSION}/Unity.app/Contents/MacOS/Unity \
+   -nographics \
+   -batchmode \
+   -quit \
+   -executeMethod BuildScript.BuildiOSPlayer \
+   -buildPath "$BUILD_PATH" \
+   -buildNumber "$BUILD_NUMBER" \
+   -logFile "$LOG_PATH" \
+   -projectPath "$WORKSPACE/src/main/csharp/net/eagle0/clients/unity/eagle0"
+UNITY_EXIT_CODE=$?
+set -e
+
+if [ $UNITY_EXIT_CODE -ne 0 ]; then
+    echo ""
+    echo "Unity build failed with exit code $UNITY_EXIT_CODE"
+    echo "=== Unity Editor Log (last 200 lines) ==="
+    tail -200 "$LOG_PATH" || echo "Could not read log file at $LOG_PATH"
+    echo "=== End of Unity Editor Log ==="
+    exit $UNITY_EXIT_CODE
+fi
+
+echo "iOS Unity build complete"
+echo "Xcode project generated at: $BUILD_PATH"
+ls -la "$BUILD_PATH"

ci/github_actions/build_unity_mac.sh

@@ -2,18 +2,21 @@
 
 set -euxo pipefail
 
+# Use runner-specific build directory if EAGLE0_BUILD_DIR is set, otherwise default
+BUILD_BASE="${EAGLE0_BUILD_DIR:-/tmp/eagle0}"
+
 COMMIT=$(/usr/bin/git rev-parse --short HEAD)
 
 /bin/echo "build protos"
 ./scripts/build_protos.sh
 
-/bin/echo "build Mac plugin"
-./scripts/build_mac_plugin.sh
+/bin/echo "build Sparkle plugin"
+./scripts/build_sparkle_plugin.sh
 
 git log -3
 
 /bin/echo "build Mac"
-LOG_PATH="/tmp/eagle0/editor_mac.log"
+LOG_PATH="${BUILD_BASE}/editor_mac.log"
 BUILD_DIR=$1
 
 ./ci/github_actions/build_mac.sh "$BUILD_DIR" "$LOG_PATH"

ci/github_actions/build_windows.sh

@@ -2,7 +2,8 @@
 
 set -euxo pipefail
 
-. ./ci/unity_version.sh
+# Read Unity version from project file
+UNITY_VERSION=$(grep "m_EditorVersion:" src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt | head -1 | sed 's/m_EditorVersion: //')
 
 WORKSPACE=`pwd`
 UNITY_INSTALL_PATH="/Applications/Unity/Hub/Editor"
@@ -15,10 +16,25 @@ echo "Cleaning up $1"
 /bin/rm -rf $1
 /bin/mkdir -p $1
 
+# Use custom build script that builds Addressables before the player
+# Capture exit code to show log on failure
+set +e
 ${UNITY_INSTALL_PATH}/${UNITY_VERSION}/Unity.app/Contents/MacOS/Unity \
    -nographics \
    -batchmode \
    -quit \
-   -buildWindows64Player $BUILD_DIR/eagle0.exe \
+   -executeMethod BuildScript.BuildWindowsPlayer \
+   -buildPath "$BUILD_DIR/eagle0.exe" \
    -logFile $LOG_PATH \
    -projectPath "$WORKSPACE/src/main/csharp/net/eagle0/clients/unity/eagle0"
+UNITY_EXIT_CODE=$?
+set -e
+
+if [ $UNITY_EXIT_CODE -ne 0 ]; then
+    echo ""
+    echo "Unity build failed with exit code $UNITY_EXIT_CODE"
+    echo "=== Unity Editor Log (last 200 lines) ==="
+    tail -200 "$LOG_PATH" || echo "Could not read log file at $LOG_PATH"
+    echo "=== End of Unity Editor Log ==="
+    exit $UNITY_EXIT_CODE
+fi

ci/github_actions/ensure_unity_installed.sh

@@ -0,0 +1,233 @@
+#!/usr/bin/env bash
+
+# Ensures the required Unity version is installed via Unity Hub.
+# Usage: ./ensure_unity_installed.sh [PLATFORM]
+#
+# PLATFORM can be: mac, windows, ios, or all (default: all)
+#
+# This script:
+# 1. Reads the required version from ProjectSettings/ProjectVersion.txt
+# 2. Checks if it's already installed
+# 3. If not, attempts to install it via Unity Hub CLI with appropriate modules
+#
+# Note: Unity Hub CLI installation may require:
+# - Unity Hub to be installed
+# - User to be logged in to Unity Hub (for some versions)
+# - Appropriate licenses
+
+set -euo pipefail
+
+# Read Unity version directly from the project file (maintained by Unity itself)
+PROJECT_VERSION_FILE="src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt"
+UNITY_VERSION=$(grep "m_EditorVersion:" "$PROJECT_VERSION_FILE" | head -1 | sed 's/m_EditorVersion: //')
+
+UNITY_INSTALL_PATH="/Applications/Unity/Hub/Editor"
+UNITY_HUB_CLI="/Applications/Unity Hub.app/Contents/MacOS/Unity Hub"
+LOCK_FILE="/tmp/unity_install.lock"
+LOCK_TIMEOUT=1800  # 30 minutes max wait for another installation
+
+PLATFORM="${1:-all}"
+
+echo "Required Unity version: ${UNITY_VERSION}"
+echo "Platform: ${PLATFORM}"
+
+# Check if Unity is installed and has required modules
+check_modules_installed() {
+    local unity_path="${UNITY_INSTALL_PATH}/${UNITY_VERSION}"
+
+    if [ ! -d "$unity_path" ]; then
+        return 1
+    fi
+
+    case "${PLATFORM}" in
+        ios)
+            # iOS module installs to PlaybackEngines/iOSSupport
+            if [ ! -d "${unity_path}/PlaybackEngines/iOSSupport" ]; then
+                echo "✗ iOS module not installed for Unity ${UNITY_VERSION}"
+                return 1
+            fi
+            ;;
+        mac)
+            # Mac IL2CPP module
+            if [ ! -d "${unity_path}/PlaybackEngines/MacStandaloneSupport/Variations/macos_development_il2cpp" ] && \
+               [ ! -d "${unity_path}/PlaybackEngines/MacStandaloneSupport" ]; then
+                echo "✗ Mac IL2CPP module not installed for Unity ${UNITY_VERSION}"
+                return 1
+            fi
+            ;;
+        windows)
+            # Windows mono module
+            if [ ! -d "${unity_path}/PlaybackEngines/WindowsStandaloneSupport" ]; then
+                echo "✗ Windows module not installed for Unity ${UNITY_VERSION}"
+                return 1
+            fi
+            ;;
+        all)
+            # Check all required modules
+            local missing=0
+            if [ ! -d "${unity_path}/PlaybackEngines/iOSSupport" ]; then
+                echo "✗ iOS module missing"
+                missing=1
+            fi
+            if [ ! -d "${unity_path}/PlaybackEngines/MacStandaloneSupport" ]; then
+                echo "✗ Mac module missing"
+                missing=1
+            fi
+            if [ ! -d "${unity_path}/PlaybackEngines/WindowsStandaloneSupport" ]; then
+                echo "✗ Windows module missing"
+                missing=1
+            fi
+            if [ $missing -eq 1 ]; then
+                return 1
+            fi
+            ;;
+    esac
+
+    return 0
+}
+
+# Check if already installed with required modules
+if check_modules_installed; then
+    echo "✓ Unity ${UNITY_VERSION} is already installed with ${PLATFORM} support"
+    exit 0
+fi
+
+if [ ! -d "${UNITY_INSTALL_PATH}/${UNITY_VERSION}" ]; then
+    echo "✗ Unity ${UNITY_VERSION} not found at ${UNITY_INSTALL_PATH}/${UNITY_VERSION}"
+fi
+
+# Check if Unity Hub CLI is available
+if [ ! -f "${UNITY_HUB_CLI}" ]; then
+    echo ""
+    echo "Unity Hub CLI not found at ${UNITY_HUB_CLI}"
+    echo ""
+    echo "To install Unity ${UNITY_VERSION} manually:"
+    echo "  1. Open Unity Hub"
+    echo "  2. Go to Installs -> Install Editor"
+    echo "  3. Select version ${UNITY_VERSION}"
+    echo "  4. Add modules based on platform: mac-il2cpp, windows-mono, ios"
+    exit 1
+fi
+
+# Acquire lock to prevent concurrent installations
+acquire_lock() {
+    local waited=0
+    while ! mkdir "${LOCK_FILE}" 2>/dev/null; do
+        if [ $waited -ge $LOCK_TIMEOUT ]; then
+            echo "ERROR: Timed out waiting for Unity installation lock after ${LOCK_TIMEOUT}s"
+            echo "Another installation may be stuck. Remove ${LOCK_FILE} manually if needed."
+            exit 1
+        fi
+        echo "Another Unity installation is in progress, waiting... (${waited}s)"
+        sleep 10
+        waited=$((waited + 10))
+    done
+    # Store PID for debugging
+    echo $$ > "${LOCK_FILE}/pid"
+    trap release_lock EXIT
+}
+
+release_lock() {
+    rm -rf "${LOCK_FILE}" 2>/dev/null || true
+}
+
+# Re-check after acquiring lock (another process may have installed it)
+acquire_lock
+
+if check_modules_installed; then
+    echo "✓ Unity ${UNITY_VERSION} with ${PLATFORM} support was installed while waiting for lock"
+    exit 0
+fi
+
+echo ""
+
+# Determine modules needed for this platform
+get_modules_for_platform() {
+    case "${PLATFORM}" in
+        mac)
+            echo "mac-il2cpp"
+            ;;
+        windows)
+            echo "windows-mono"
+            ;;
+        ios)
+            echo "ios"
+            ;;
+        all)
+            echo "mac-il2cpp windows-mono ios"
+            ;;
+        *)
+            echo "Unknown platform: ${PLATFORM}" >&2
+            echo "Valid platforms: mac, windows, ios, all" >&2
+            exit 1
+            ;;
+    esac
+}
+
+MODULES=$(get_modules_for_platform)
+
+# Check if editor is already installed (just missing modules)
+if [ -d "${UNITY_INSTALL_PATH}/${UNITY_VERSION}" ]; then
+    echo "Unity ${UNITY_VERSION} is installed but missing modules. Adding modules..."
+    echo ""
+
+    # Use install-modules to add modules to existing installation
+    INSTALL_CMD=("${UNITY_HUB_CLI}" -- --headless install-modules --version "${UNITY_VERSION}")
+    for mod in $MODULES; do
+        INSTALL_CMD+=(--module "$mod")
+    done
+else
+    echo "Attempting to install Unity ${UNITY_VERSION} via Unity Hub CLI..."
+    echo ""
+
+    # Use install to install editor with modules
+    INSTALL_CMD=("${UNITY_HUB_CLI}" -- --headless install --version "${UNITY_VERSION}")
+    for mod in $MODULES; do
+        INSTALL_CMD+=(--module "$mod")
+    done
+fi
+
+echo "Running: ${INSTALL_CMD[*]}"
+echo ""
+
+# Capture output to check for "already installed" messages
+OUTPUT=$("${INSTALL_CMD[@]}" 2>&1) || true
+EXIT_CODE=$?
+echo "$OUTPUT"
+
+# Check if modules are already installed (Unity Hub returns error but modules are present)
+if echo "$OUTPUT" | grep -q "already installed\|No modules found to install"; then
+    echo ""
+    echo "✓ Modules already installed"
+elif [ $EXIT_CODE -eq 0 ]; then
+    echo ""
+    echo "Unity Hub CLI command completed"
+else
+    echo ""
+    echo "Unity Hub CLI command failed (exit code: ${EXIT_CODE})"
+    echo ""
+    echo "This may happen if:"
+    echo "  - The Unity version is not available for download"
+    echo "  - You need to log in to Unity Hub first"
+    echo "  - Unity Hub requires a GUI interaction"
+    echo ""
+    echo "To install manually:"
+    echo "  1. Open Unity Hub"
+    echo "  2. Go to Installs -> Install Editor"
+    echo "  3. Select version ${UNITY_VERSION}"
+    echo "  4. Add modules: ${PLATFORM}"
+    exit 1
+fi
+
+# Verify installation
+echo ""
+if [ -d "${UNITY_INSTALL_PATH}/${UNITY_VERSION}" ]; then
+    echo "✓ Verified: Unity ${UNITY_VERSION} is now installed"
+    exit 0
+else
+    echo "✗ Unity ${UNITY_VERSION} installation could not be verified"
+    echo "  Expected path: ${UNITY_INSTALL_PATH}/${UNITY_VERSION}"
+    echo ""
+    echo "The installation may still be in progress, or may require manual intervention."
+    exit 1
+fi

ci/github_actions/persist_library.sh

@@ -1,20 +0,0 @@
-#!/bin/bash
-
-set -uxo pipefail
-
-/bin/echo "persist Library/"
-
-# rsync may exit with code 23 ("partial transfer due to error") if Unity's
-# temporary files vanish during the copy. This is acceptable for a cache.
-/usr/bin/rsync -rtlDvq src/main/csharp/net/eagle0/clients/unity/eagle0/Library/ /tmp/eagle0/Library/
-rsync_exit=$?
-
-if [ $rsync_exit -eq 0 ]; then
-    exit 0
-elif [ $rsync_exit -eq 23 ]; then
-    echo "Warning: rsync exited with 23 (some files vanished during copy). This is expected for Unity temp files."
-    exit 0
-else
-    echo "Error: rsync failed with exit code $rsync_exit"
-    exit $rsync_exit
-fi

ci/github_actions/restore_library.sh

@@ -1,7 +0,0 @@
-#!/bin/bash
-
-set -euxo pipefail
-
-/bin/echo "restore Library/"
-/bin/mkdir -p /tmp/eagle0/Library
-/usr/bin/rsync -rtlDvq /tmp/eagle0/Library/ src/main/csharp/net/eagle0/clients/unity/eagle0/Library/

ci/github_actions/upload_addressables.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+
+# Upload Addressables bundles to DigitalOcean Spaces
+# Usage: ./upload_addressables.sh <build_target>
+# Example: ./upload_addressables.sh StandaloneOSX
+#
+# Required environment variables:
+#   ACCESS_KEY_ID - DigitalOcean Spaces access key (same as other deploys)
+#   SECRET_KEY    - DigitalOcean Spaces secret key (same as other deploys)
+
+set -euxo pipefail
+
+BUILD_TARGET=$1
+WORKSPACE=$(pwd)
+UNITY_PROJECT="$WORKSPACE/src/main/csharp/net/eagle0/clients/unity/eagle0"
+SERVER_DATA="$UNITY_PROJECT/ServerData/$BUILD_TARGET"
+
+# DigitalOcean Spaces configuration (same region as other eagle0 buckets)
+DO_ENDPOINT="https://sfo3.digitaloceanspaces.com"
+DO_BUCKET="eagle0-assets"
+
+if [ ! -d "$SERVER_DATA" ]; then
+    echo "No Addressables bundles found at $SERVER_DATA"
+    echo "Skipping upload (this is expected if Addressables are bundled locally)"
+    exit 0
+fi
+
+echo "Uploading Addressables bundles from $SERVER_DATA"
+echo "Target: s3://$DO_BUCKET/addressables/$BUILD_TARGET/"
+
+# Configure AWS CLI for DigitalOcean Spaces
+export AWS_ACCESS_KEY_ID="$ACCESS_KEY_ID"
+export AWS_SECRET_ACCESS_KEY="$SECRET_KEY"
+
+# Sync bundles to Spaces
+# --delete removes files in destination that don't exist in source
+# --acl public-read makes files publicly accessible
+aws s3 sync "$SERVER_DATA" "s3://$DO_BUCKET/addressables/$BUILD_TARGET/" \
+    --endpoint-url "$DO_ENDPOINT" \
+    --acl public-read \
+    --delete
+
+echo "Addressables upload complete"
+echo "Files available at: https://assets.eagle0.net/addressables/$BUILD_TARGET/"

ci/github_actions/upload_testflight.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+
+# Upload xcarchive to TestFlight using App Store Connect API Key
+# This replaces the deprecated altool which was removed in Xcode 14+
+#
+# Uses xcodebuild -exportArchive with destination=upload, which is Apple's
+# recommended approach for CI/CD pipelines.
+
+set -euxo pipefail
+
+# Ensure xcodebuild uses Xcode.app, not Command Line Tools
+export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
+
+ARCHIVE_PATH=${1:?Usage: upload_testflight.sh <xcarchive_path> <team_id> <profile_uuid>}
+TEAM_ID=${2:?Missing team ID}
+PROFILE_UUID=${3:?Missing provisioning profile UUID}
+
+if [ ! -d "$ARCHIVE_PATH" ]; then
+    echo "Error: xcarchive not found: $ARCHIVE_PATH"
+    exit 1
+fi
+
+echo "Uploading to TestFlight: $ARCHIVE_PATH"
+
+# Requires App Store Connect API Key:
+# - APP_STORE_CONNECT_API_KEY_ID: Key ID from App Store Connect
+# - APP_STORE_CONNECT_API_ISSUER_ID: Issuer ID from App Store Connect
+# - APP_STORE_CONNECT_API_KEY_PATH: Path to .p8 private key file
+#
+# To create an API key:
+# 1. Go to https://appstoreconnect.apple.com/access/api
+# 2. Click the + button to create a new key
+# 3. Give it a name and Admin or App Manager access
+# 4. Download the .p8 file (you can only download it once!)
+# 5. Note the Key ID and Issuer ID shown on the page
+
+if [ -z "${APP_STORE_CONNECT_API_KEY_ID:-}" ]; then
+    echo "Error: APP_STORE_CONNECT_API_KEY_ID environment variable not set"
+    echo "Create an API key at https://appstoreconnect.apple.com/access/api"
+    exit 1
+fi
+
+if [ -z "${APP_STORE_CONNECT_API_ISSUER_ID:-}" ]; then
+    echo "Error: APP_STORE_CONNECT_API_ISSUER_ID environment variable not set"
+    exit 1
+fi
+
+if [ -z "${APP_STORE_CONNECT_API_KEY_PATH:-}" ]; then
+    echo "Error: APP_STORE_CONNECT_API_KEY_PATH environment variable not set"
+    exit 1
+fi
+
+if [ ! -f "$APP_STORE_CONNECT_API_KEY_PATH" ]; then
+    echo "Error: API key file not found: $APP_STORE_CONNECT_API_KEY_PATH"
+    exit 1
+fi
+
+# Create export options plist with upload destination
+EXPORT_OPTIONS_PLIST=$(mktemp)
+trap "rm -f $EXPORT_OPTIONS_PLIST" EXIT
+
+cat > "$EXPORT_OPTIONS_PLIST" << EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>destination</key>
+    <string>upload</string>
+    <key>method</key>
+    <string>app-store-connect</string>
+    <key>teamID</key>
+    <string>$TEAM_ID</string>
+    <key>uploadSymbols</key>
+    <true/>
+    <key>signingStyle</key>
+    <string>manual</string>
+    <key>signingCertificate</key>
+    <string>Apple Distribution: Daniel Crosby (UWJ88DX8WQ)</string>
+    <key>provisioningProfiles</key>
+    <dict>
+        <key>net.eagle0.eagle</key>
+        <string>$PROFILE_UUID</string>
+    </dict>
+</dict>
+</plist>
+EOF
+
+echo "Export options:"
+cat "$EXPORT_OPTIONS_PLIST"
+
+echo "Uploading to App Store Connect..."
+
+# Use xcodebuild to upload with App Store Connect API authentication
+xcodebuild -exportArchive \
+    -archivePath "$ARCHIVE_PATH" \
+    -exportOptionsPlist "$EXPORT_OPTIONS_PLIST" \
+    -authenticationKeyPath "$APP_STORE_CONNECT_API_KEY_PATH" \
+    -authenticationKeyID "$APP_STORE_CONNECT_API_KEY_ID" \
+    -authenticationKeyIssuerID "$APP_STORE_CONNECT_API_ISSUER_ID"
+
+echo "Upload complete! Check App Store Connect for processing status."
+echo "The build should appear in TestFlight within 15-30 minutes after processing."

ci/unity_version.sh

@@ -1 +0,0 @@
-UNITY_VERSION='6000.3.0f1'

deploy/env.template

@@ -1,40 +0,0 @@
-# Environment template for production deployment
-# This file defines all env vars used by docker-compose.prod.yml
-# Workflows should update their specific vars without overwriting others
-
-# Container images (managed by respective build workflows)
-# Note: Shardok runs on Hetzner, deployed via shardok_arm64_build.yml
-EAGLE_IMAGE=registry.digitalocean.com/eagle0/eagle-server:latest
-ADMIN_IMAGE=registry.digitalocean.com/eagle0/admin-server:latest
-JFR_SIDECAR_IMAGE=registry.digitalocean.com/eagle0/jfr-sidecar:latest
-AUTH_IMAGE=registry.digitalocean.com/eagle0/auth-server:latest
-
-# OpenAI / LLM
-OPENAI_API_KEY=
-GPT_MODEL_NAME=gpt-4o
-
-# DigitalOcean Spaces (S3-compatible storage)
-EAGLE_ENABLE_S3=false
-DO_SPACES_ACCESS_KEY=
-DO_SPACES_SECRET_KEY=
-
-# JWT authentication
-JWT_PRIVATE_KEY=
-
-# OAuth providers
-DISCORD_CLIENT_ID=
-DISCORD_CLIENT_SECRET=
-GOOGLE_CLIENT_ID=
-GOOGLE_CLIENT_SECRET=
-
-# Shardok connection (Hetzner ARM64 server)
-SHARDOK_ADDRESS=
-SHARDOK_AUTH_TOKEN=
-
-# Monitoring
-SENTRY_DSN=
-
-# Email (Fastmail JMAP)
-FASTMAIL_API_TOKEN=
-FASTMAIL_FROM_EMAIL=
-FASTMAIL_FROM_NAME=

deploy/update-env.sh

@@ -1,59 +0,0 @@
-#!/bin/bash
-# Update .env file without losing other variables
-# Usage: ./update-env.sh KEY1=value1 KEY2=value2 ...
-#
-# This script:
-# 1. Creates .env from template if it doesn't exist
-# 2. Updates only the specified KEY=value pairs
-# 3. Preserves all other existing values
-
-set -e
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-ENV_FILE="${ENV_FILE:-/opt/eagle0/.env}"
-TEMPLATE_FILE="${TEMPLATE_FILE:-$SCRIPT_DIR/env.template}"
-
-# Create .env from template if it doesn't exist
-if [ ! -f "$ENV_FILE" ]; then
-    if [ -f "$TEMPLATE_FILE" ]; then
-        echo "Creating .env from template..."
-        grep -v '^#' "$TEMPLATE_FILE" | grep -v '^$' > "$ENV_FILE"
-    else
-        echo "Creating empty .env..."
-        touch "$ENV_FILE"
-    fi
-    chmod 600 "$ENV_FILE"
-fi
-
-# Process each KEY=VALUE argument
-for arg in "$@"; do
-    # Skip empty args
-    [ -z "$arg" ] && continue
-
-    # Parse KEY=VALUE
-    KEY="${arg%%=*}"
-    VALUE="${arg#*=}"
-
-    # Skip if no key
-    [ -z "$KEY" ] && continue
-
-    # Skip setting empty values (keeps existing value)
-    if [ -z "$VALUE" ]; then
-        echo "Skipping $KEY (empty value)"
-        continue
-    fi
-
-    # Remove existing line for this key and add new one
-    if grep -q "^${KEY}=" "$ENV_FILE" 2>/dev/null; then
-        # Key exists, update it
-        sed -i "s|^${KEY}=.*|${KEY}=${VALUE}|" "$ENV_FILE"
-        echo "Updated $KEY"
-    else
-        # Key doesn't exist, add it
-        echo "${KEY}=${VALUE}" >> "$ENV_FILE"
-        echo "Added $KEY"
-    fi
-done
-
-chmod 600 "$ENV_FILE"
-echo "Done updating $ENV_FILE"

docker-compose.prod.yml

@@ -18,23 +18,22 @@ services:
     image: ${EAGLE_IMAGE:-registry.digitalocean.com/eagle0/eagle-server:latest}
     container_name: eagle-blue
     command:
-      - "--gpt-model-name"
-      - "${GPT_MODEL_NAME:-gpt-5.1}"
       - "--shardok-interface-remote-address"
-      - "${SHARDOK_ADDRESS:-shardok:40042}"
+      - "${SHARDOK_ADDRESS}"
       - "--auth-service-url"
       - "auth:40033"
     ports:
       - "40032:40032"
     environment:
       OPENAI_API_KEY: "${OPENAI_API_KEY:-}"
+      ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY:-}"
+      GEMINI_API_KEY: "${GEMINI_API_KEY:-}"
       EAGLE_ENABLE_S3: "${EAGLE_ENABLE_S3:-false}"
       DO_SPACES_ENDPOINT: "${DO_SPACES_ENDPOINT:-https://sfo3.digitaloceanspaces.com}"
       DO_SPACES_ACCESS_KEY: "${DO_SPACES_ACCESS_KEY:-}"
       DO_SPACES_SECRET_KEY: "${DO_SPACES_SECRET_KEY:-}"
-      JWT_PRIVATE_KEY: "${JWT_PRIVATE_KEY:-}"
-      DISCORD_CLIENT_ID: "${DISCORD_CLIENT_ID:-}"
-      DISCORD_CLIENT_SECRET: "${DISCORD_CLIENT_SECRET:-}"
+      # JWT public key for token validation (auth service handles signing)
+      # Reads from /etc/eagle0/keys/public.pem via shared volume
       # Auth token for Shardok on Hetzner (required)
       SHARDOK_AUTH_TOKEN: "${SHARDOK_AUTH_TOKEN:-}"
       # Use persistent volume for save data (users, games, etc.)
@@ -47,7 +46,7 @@ services:
       - ./archived:/app/archived     # Archived completed games
       - ./jfr:/app/jfr  # JFR recordings - dump with: docker exec eagle-blue jcmd 1 JFR.dump filename=/app/jfr/profile.jfr
       - jvm-tmp:/tmp  # Shared with jfr-sidecar for JVM attach socket files
-      - jwt-keys:/etc/eagle0/keys  # Shared JWT keys with auth service
+      - jwt-keys:/etc/eagle0/keys:ro  # JWT public key from auth service (read-only)
     depends_on:
       - auth
     restart: unless-stopped
@@ -68,23 +67,22 @@ services:
     container_name: eagle-green
     profiles: ["blue-green"]  # Only started during blue-green deployment
     command:
-      - "--gpt-model-name"
-      - "${GPT_MODEL_NAME:-gpt-5.1}"
       - "--shardok-interface-remote-address"
-      - "${SHARDOK_ADDRESS:-shardok:40042}"
+      - "${SHARDOK_ADDRESS}"
       - "--auth-service-url"
       - "auth:40033"
     ports:
       - "40034:40032"  # Different host port for staging
     environment:
       OPENAI_API_KEY: "${OPENAI_API_KEY:-}"
+      ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY:-}"
+      GEMINI_API_KEY: "${GEMINI_API_KEY:-}"
       EAGLE_ENABLE_S3: "${EAGLE_ENABLE_S3:-false}"
       DO_SPACES_ENDPOINT: "${DO_SPACES_ENDPOINT:-https://sfo3.digitaloceanspaces.com}"
       DO_SPACES_ACCESS_KEY: "${DO_SPACES_ACCESS_KEY:-}"
       DO_SPACES_SECRET_KEY: "${DO_SPACES_SECRET_KEY:-}"
-      JWT_PRIVATE_KEY: "${JWT_PRIVATE_KEY:-}"
-      DISCORD_CLIENT_ID: "${DISCORD_CLIENT_ID:-}"
-      DISCORD_CLIENT_SECRET: "${DISCORD_CLIENT_SECRET:-}"
+      # JWT public key for token validation (auth service handles signing)
+      # Reads from /etc/eagle0/keys/public.pem via shared volume
       SHARDOK_AUTH_TOKEN: "${SHARDOK_AUTH_TOKEN:-}"
       EAGLE_SAVE_DIR: "/app/saves"
       EAGLE_ARCHIVE_DIR: "/app/archived"
@@ -95,7 +93,7 @@ services:
       - ./archived:/app/archived     # Same archive directory as blue
       - ./jfr:/app/jfr               # JFR recordings (same as blue)
       - jvm-tmp:/tmp                 # Shared with jfr-sidecar-green for JVM attach socket files
-      - jwt-keys:/etc/eagle0/keys    # Shared JWT keys with auth service
+      - jwt-keys:/etc/eagle0/keys:ro # JWT public key from auth service (read-only)
     depends_on:
       - auth
     restart: "no"  # Don't auto-restart during deployment
@@ -133,6 +131,16 @@ services:
       DISCORD_CLIENT_SECRET: "${DISCORD_CLIENT_SECRET:-}"
       GOOGLE_CLIENT_ID: "${GOOGLE_CLIENT_ID:-}"
       GOOGLE_CLIENT_SECRET: "${GOOGLE_CLIENT_SECRET:-}"
+      GH_OAUTH_CLIENT_ID: "${GH_OAUTH_CLIENT_ID:-}"
+      GH_OAUTH_CLIENT_SECRET: "${GH_OAUTH_CLIENT_SECRET:-}"
+      # Apple Sign-In credentials
+      APPLE_SIGNIN_CLIENT_ID: "${APPLE_SIGNIN_CLIENT_ID:-}"
+      APPLE_TEAM_ID: "${APPLE_TEAM_ID:-}"
+      APPLE_SIGNIN_KEY_ID: "${APPLE_SIGNIN_KEY_ID:-}"
+      APPLE_SIGNIN_PRIVATE_KEY: "${APPLE_SIGNIN_PRIVATE_KEY:-}"
+      # Twitch OAuth credentials
+      TWITCH_CLIENT_ID: "${TWITCH_CLIENT_ID:-}"
+      TWITCH_CLIENT_SECRET: "${TWITCH_CLIENT_SECRET:-}"
       # Server base URL for OAuth callbacks
       SERVER_BASE_URL: "${SERVER_BASE_URL:-https://prod.eagle0.net}"
       # JWT keys - PEM files in volume, bootstrapped from JWK on first run
@@ -200,6 +208,17 @@ services:
       - "${JFR_SIDECAR_ADDR:-jfr-sidecar:8081}"  # Can be switched for blue-green
       - "--http-port"
       - "8080"
+      - "--maps-dir"
+      - "/app/maps"
+    environment:
+      # Secret for CI to authenticate client update notifications
+      NOTIFY_SECRET: "${NOTIFY_SECRET:-}"
+      # S3/Spaces credentials for What's New storage (uses eagle0-assets bucket)
+      DO_SPACES_ENDPOINT: "${DO_SPACES_ENDPOINT:-https://sfo3.digitaloceanspaces.com}"
+      DO_SPACES_ACCESS_KEY: "${ADMIN_S3_ACCESS_KEY:-}"
+      DO_SPACES_SECRET_KEY: "${ADMIN_S3_SECRET_KEY:-}"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
     # No external port - accessed via nginx at admin.eagle0.net
     depends_on:
       - auth

docs/ADDING_NEW_QUESTS.md

@@ -0,0 +1,242 @@
+# Adding New Quest Types
+
+This document describes how to add new quest types to Eagle. Quests are tasks that unaffiliated heroes want factions to complete before they'll join.
+
+## Deployment Strategy: Three-PR Approach
+
+When adding new quest types, use a three-PR strategy to ensure clients never see quests they don't understand:
+
+1. **PR 1 - Types Only (Server)**: Add proto definitions, Scala types, converters, and all handling logic (fulfillment, failure, LLM prompts). Do NOT generate the quests yet.
+
+2. **PR 2 - Client Handling**: Add client-side display code (C#/Unity) that can render the new quest type.
+
+3. **PR 3 - Quest Generation (Server)**: Add the actual quest creation logic to `QuestCreationUtils.scala`.
+
+**PR Dependencies:**
+```
+PR 1 (types)
+  ├── PR 2 (client)
+  └── PR 3 (generation)
+```
+
+PR 2 and PR 3 both depend on PR 1, but are independent of each other. They can be developed in parallel after PR 1 is merged, and merged in either order. The key constraint is that PR 3 should not be deployed before PR 2, so clients understand the quest type before the server starts generating it.
+
+## Files to Modify
+
+### Server-Side (Scala)
+
+#### 1. Proto Definition
+**File:** `src/main/protobuf/net/eagle0/eagle/common/unaffiliated_hero_quest.proto`
+
+Add a new message type for your quest and add it to the `QuestDetails` oneof:
+
+```protobuf
+message MyNewQuest {
+    int32 some_field = 1;
+    string another_field = 2;
+}
+
+// In the QuestDetails message, add to the oneof:
+oneof sealed_value {
+    // ... existing quests ...
+    MyNewQuest my_new_quest = XX;  // Use next available field number
+}
+```
+
+#### 2. Scala Case Class
+**File:** `src/main/scala/net/eagle0/eagle/model/state/quest/Quest.scala`
+
+Add a case class (or case object for quests with no parameters):
+
+```scala
+case class MyNewQuest(
+    someField: Int,
+    anotherField: String
+) extends Quest
+
+// For quests with multi-part completion, extend ComponentQuest:
+case class MyComponentQuest(
+    override val componentCount: Int,
+    override val componentsFulfilled: Int,
+    targetValue: Int
+) extends ComponentQuest {
+  override def withComponentsFulfilled(componentsFulfilled: Int): Quest =
+    this.copy(componentsFulfilled = componentsFulfilled)
+}
+```
+
+#### 3. Proto Converter
+**File:** `src/main/scala/net/eagle0/eagle/model/proto_converters/QuestConverter.scala`
+
+Add conversions in both `toProto` and `fromProto` methods:
+
+```scala
+// In toProto:
+case q: MyNewQuest =>
+  QuestProto(details = MyNewQuestProto(q.someField, q.anotherField))
+
+// In fromProto:
+case MyNewQuestProto(someField, anotherField, _) =>
+  MyNewQuest(someField, anotherField)
+```
+
+#### 4. Quest Fulfillment Check
+**File:** `src/main/scala/net/eagle0/eagle/library/actions/impl/action/CheckForFulfilledQuestsAction.scala`
+
+Add a case to `didFulfillQuest` that returns `true` when the quest conditions are met:
+
+```scala
+case MyNewQuest(someField, anotherField) =>
+  // Return true if quest is fulfilled
+  someConditionIsMet(province, someField)
+```
+
+For `ComponentQuest` subclasses, the base case `case q: ComponentQuest => q.componentsFulfilled >= q.componentCount` handles fulfillment automatically.
+
+#### 5. Quest Failure Check
+**File:** `src/main/scala/net/eagle0/eagle/library/actions/impl/action/CheckForFailedQuestsAction.scala`
+
+Add a case to `isQuestFailed` if your quest can fail (e.g., if a required faction is destroyed):
+
+```scala
+case MyNewQuest(someField, _) =>
+  // Return true if quest can no longer be completed
+  !factionWithId(someField).exists(_.isActive)
+```
+
+Many quests use the default case that returns `false` (quest never fails automatically).
+
+#### 6. LLM Prompt Generators
+**File:** `src/main/scala/net/eagle0/eagle/library/actions/llm_prompt_generators/DivineMessagePromptGenerator.scala`
+
+Add a case to `describeQuest` for when a soothsayer reveals the quest:
+
+```scala
+case MyNewQuest(someField, anotherField) =>
+  TextGenerationSuccess(
+    s"$divinedHeroName wants ${faction.name} to do something with $someField."
+  )
+```
+
+**File:** `src/main/scala/net/eagle0/eagle/library/actions/llm_prompt_generators/QuestEndedGeneratorUtilities.scala`
+
+Add a case to `pastTenseQuestDescription` for quest fulfilled/failed narratives:
+
+```scala
+case MyNewQuest(someField, anotherField) =>
+  for {
+    unaffiliatedHeroName <- unaffiliatedHeroNameResult
+  } yield s"$unaffiliatedHeroName wanted ${faction.name} to do something with $someField."
+```
+
+#### 7. Quest Creation (PR 3 only)
+**File:** `src/main/scala/net/eagle0/eagle/library/util/quest_creation/QuestCreationUtils.scala`
+
+Add a quest creator function and register it in `availableQuests`:
+
+```scala
+private def myNewQuests(
+    province: ProvinceT,
+    allProvinces: Vector[ProvinceT],
+    @unused factions: Vector[FactionT],
+    @unused battalions: Vector[BattalionT],
+    functionalRandom: FunctionalRandom
+): RandomState[Vector[Quest]] = {
+  // Return empty if quest shouldn't be available
+  if (!someCondition) RandomState(Vector(), functionalRandom)
+  else {
+    functionalRandom.nextIntInclusive(minValue, maxValue).map { value =>
+      Vector(MyNewQuest(value, "something"))
+    }
+  }
+}
+
+// Add to availableQuests list:
+def availableQuests(...) = functionalRandom.nextFlatMap(
+  Vector[QuestCreator](
+    // ... existing creators ...
+    myNewQuests
+  )
+) { ... }
+```
+
+#### 8. Optional: Quest Command Selectors (AI auto-completion)
+**Directory:** `src/main/scala/net/eagle0/eagle/library/util/command_choice_helpers/quest_command_selectors/`
+
+If you want AI players to automatically work toward completing your quest, create a command chooser.
+
+### Client-Side (C#/Unity)
+
+#### 1. Quest Type Display Name
+**File:** `src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Eagle/DisplayNames.cs`
+
+Add a case to `QuestTypeString`:
+
+```csharp
+case SealedValueOneofCase.MyNewQuest: return "My New Quest";
+```
+
+#### 2. Quest Description String
+**File:** `src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Eagle/Table Rows/UnaffiliatedHeroRowController.cs`
+
+Add a case to `ShortQuestString` for displaying the quest in the UI:
+
+```csharp
+case SealedValueOneofCase.MyNewQuest: {
+    var details = quest.Details.MyNewQuest;
+    return $"Do something with {details.SomeField}";
+}
+```
+
+For quests involving heroes (where you want dynamic name updates), add a case to `SetQuestText` instead.
+
+### Build Files
+
+After making changes, run:
+
+```bash
+bazel run gazelle
+```
+
+This updates BUILD.bazel files with any new dependencies.
+
+## Quest Type Categories
+
+### Simple Quests
+Quests with fixed completion conditions (e.g., `AllianceQuest`, `SuppressRiotByForceQuest`).
+
+### Component Quests
+Quests with multi-part completion that track progress via `componentsFulfilled` / `componentCount` (e.g., `AlmsToProvinceQuest`, `DevelopProvincesQuest`). Extend `ComponentQuest` and implement `withComponentsFulfilled`.
+
+### Action Quests
+Quests completed by specific player actions rather than state checks. Return `false` in `didFulfillQuest` and handle completion in the relevant command handler (e.g., `ExecutePrisonerQuest` is fulfilled in prisoner management command).
+
+## Testing
+
+1. Build all modified targets:
+   ```bash
+   bazel build //src/main/scala/net/eagle0/eagle/model/state/quest:quest
+   bazel build //src/main/scala/net/eagle0/eagle/model/proto_converters:quest_converter
+   ```
+
+2. Run tests:
+   ```bash
+   bazel test //src/test/scala/...
+   ```
+
+3. Verify proto/Scala parity:
+   ```bash
+   bazel test //src/test/scala/net/eagle0/eagle/model/action_result/types:action_result_type_parity_test
+   ```
+
+## Current Quest Types (30 total)
+
+- **Diplomacy**: AllianceQuest, TruceWithFactionQuest, TruceCountQuest, DefeatFactionQuest
+- **Development**: ImproveAgricultureQuest, ImproveEconomyQuest, ImproveInfrastructureQuest, TotalDevelopmentQuest
+- **Expansion**: SpecificExpansionQuest, ExpandToProvincesQuest
+- **Military**: GrandArmyQuest, UpgradeBattalionQuest, FightBeastsAloneQuest
+- **Resources**: WealthQuest, AlmsToProvinceQuest, AlmsAcrossRealmQuest, GiveToHeroesInProvinceQuest, GiveToHeroesAcrossRealmQuest
+- **Personnel**: DismissSpecificVassalQuest, RescueImprisonedLeaderQuest
+- **Prisoner**: ExecutePrisonerQuest, ExilePrisonerQuest, ReleasePrisonerQuest, ReturnPrisonerQuest
+- **Province Orders**: DevelopProvincesQuest, MobilizeProvincesQuest
+- **Events**: SuppressRiotByForceQuest

docs/ADMIN_SERVER_ENHANCEMENTS.md

@@ -1,471 +0,0 @@
-# Admin Server Enhancement Plan
-
-## Overview
-
-This document outlines enhancements to the Go admin server (`src/main/go/net/eagle0/admin_server/`) to provide a proper web UI for game administration.
-
-### Current State
-
-The admin server provides a full web UI with htmx interactivity:
-- `GET /` - Redirect to games list
-- `GET /games` - Game list page (HTML)
-- `GET /games/{id}` - Game detail with action history
-- `GET /games/{id}/history` - History rows (htmx partial, infinite scroll)
-- `GET /games/{id}/action/{index}` - Action detail (htmx partial)
-- `POST /games/{id}/rewind` - Rewind game to target action
-- `GET /settings` - Settings list with live search
-- `POST /settings/update` - Update setting value
-- `GET /health` - Health check (JSON)
-- `GET /api/games` - JSON API for programmatic access
-- `GET /api/games/{id}/history` - JSON API for history
-
-### Goals
-
-1. **Web UI**: Replace raw JSON with an interactive HTML interface
-2. **Settings Management**: View and modify the 275+ game settings at runtime
-3. **Game Rewind**: Restore a game to a previous action count
-
----
-
-## Architecture
-
-### Technology Choice: Go Templates + htmx
-
-**Rationale:**
-- Single binary deployment (no separate frontend build)
-- htmx provides interactivity without JavaScript framework complexity
-- Familiar HTML/CSS, minimal learning curve
-- Excellent for admin tools where SEO and bundle size don't matter
-
-**Alternatives Considered:**
-- React/Vue SPA: Adds build complexity, separate deployment artifact
-- Server-side only: Less interactive, full page reloads
-
-### Directory Structure
-
-```
-src/main/go/net/eagle0/admin_server/
-├── admin_server.go         # Main entry point, HTTP routes
-├── handlers/
-│   ├── games.go            # Game list and detail handlers
-│   ├── settings.go         # Settings list and update handlers
-│   └── rewind.go           # Game rewind handlers
-├── templates/
-│   ├── layout.html         # Base layout with nav, htmx includes
-│   ├── games/
-│   │   ├── list.html       # Game list page
-│   │   ├── detail.html     # Single game view with history
-│   │   └── history.html    # Partial for history table (htmx)
-│   ├── settings/
-│   │   ├── list.html       # Settings list with search/filter
-│   │   └── edit.html       # Inline edit partial (htmx)
-│   └── rewind/
-│       └── confirm.html    # Rewind confirmation modal
-├── static/
-│   ├── style.css           # Minimal CSS (Pico CSS or similar)
-│   └── htmx.min.js         # htmx library
-└── BUILD.bazel
-```
-
----
-
-## Feature 1: Web UI
-
-### Routes
-
-| Route | Method | Description |
-|-------|--------|-------------|
-| `/` | GET | Redirect to `/games` |
-| `/games` | GET | Game list page (HTML) |
-| `/games/{id}` | GET | Game detail page with history |
-| `/games/{id}/history` | GET | History partial (htmx, for infinite scroll) |
-| `/api/games` | GET | JSON API (existing, keep for programmatic access) |
-| `/api/games/{id}/history` | GET | JSON API (existing) |
-
-### Game List Page
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Eagle Admin                          [Settings] [Health]   │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  Running Games (3)                                          │
-│                                                             │
-│  ┌─────────────────────────────────────────────────────┐   │
-│  │ Game abc123f                          Round 45       │   │
-│  │ Players: Liu Bei (Human), Cao Cao (AI), Sun Quan    │   │
-│  │ Actions: 1,234                        [View] [Rewind]│   │
-│  └─────────────────────────────────────────────────────┘   │
-│                                                             │
-│  ┌─────────────────────────────────────────────────────┐   │
-│  │ Game def456a                          Round 12       │   │
-│  │ Players: Test Player (Human)                         │   │
-│  │ Actions: 456                          [View] [Rewind]│   │
-│  └─────────────────────────────────────────────────────┘   │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Game Detail Page
-
-Shows game info and scrollable action history:
-- **Reverse chronological order**: Most recent actions displayed first
-- Each action shows: index, type, round ID
-- **Clickable actions**: Clicking an action row expands to show JSON representation of the full action data
-- "Rewind to here" button on each action row
-- Infinite scroll loads more history via htmx (loading older actions as user scrolls down)
-
-### Implementation Notes
-
-1. **Embed static files**: Use `//go:embed` to bundle templates and static files
-2. **Template functions**: Add helpers for formatting (hex IDs, timestamps, action summaries)
-3. **CSS framework**: Use Pico CSS (~10KB) for clean defaults without classes
-
----
-
-## Feature 2: Settings Management
-
-### New gRPC Endpoints (Eagle Server)
-
-Add to `eagle.proto`:
-
-```protobuf
-message Setting {
-  string name = 1;
-  string type = 2;           // "Int" or "Double"
-  string value = 3;          // Current value as string
-  string default_value = 4;  // Default from BUILD.bazel
-  string description = 5;    // Optional, for UI hints
-}
-
-message GetSettingsRequest {
-  string filter = 1;         // Optional name filter (substring match)
-}
-
-message GetSettingsResponse {
-  repeated Setting settings = 1;
-}
-
-message UpdateSettingRequest {
-  string name = 1;
-  string value = 2;
-}
-
-message UpdateSettingResponse {
-  Setting setting = 1;       // Updated setting
-  string error = 2;          // Empty on success
-}
-
-service Eagle {
-  // ... existing methods ...
-  rpc GetSettings(GetSettingsRequest) returns (GetSettingsResponse);
-  rpc UpdateSetting(UpdateSettingRequest) returns (UpdateSettingResponse);
-}
-```
-
-### Eagle Server Implementation
-
-Create a settings registry that:
-1. Discovers all `IntSetting` and `DoubleSetting` instances via reflection or explicit registration
-2. Provides get/set by name
-3. Validates types on update
-
-```scala
-// src/main/scala/net/eagle0/eagle/library/settings/SettingsRegistry.scala
-object SettingsRegistry {
-  private val settings: Map[String, Either[IntSetting, DoubleSetting]] = Map(
-    "ActionVigorCost" -> Left(ActionVigorCost),
-    "BaseFoodBuyPrice" -> Right(BaseFoodBuyPrice),
-    // ... register all 275 settings
-  )
-
-  def getAll(filter: Option[String]): Seq[Setting] = ...
-  def get(name: String): Option[Setting] = ...
-  def update(name: String, value: String): Either[String, Setting] = ...
-}
-```
-
-**Alternative: Code generation**
-
-Rather than manually registering 275 settings, modify `setting_rule.bzl` to generate a registry file during build.
-
-### Admin Server Routes
-
-| Route | Method | Description |
-|-------|--------|-------------|
-| `/settings` | GET | Settings list page with search |
-| `/settings/{name}` | GET | Single setting detail (htmx partial) |
-| `/settings/{name}` | PUT | Update setting value |
-| `/api/settings` | GET | JSON API |
-| `/api/settings/{name}` | PUT | JSON API |
-
-### Settings UI
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Eagle Admin                          [Games] [Health]       │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  Settings                    [Search: __________ ]          │
-│                                                             │
-│  ┌─────────────────────────────────────────────────────┐   │
-│  │ ActionVigorCost (Int)                                │   │
-│  │ Current: [15    ] Default: 15              [Save]    │   │
-│  └─────────────────────────────────────────────────────┘   │
-│                                                             │
-│  ┌─────────────────────────────────────────────────────┐   │
-│  │ BaseFoodBuyPrice (Double)                            │   │
-│  │ Current: [0.5   ] Default: 0.5             [Save]    │   │
-│  └─────────────────────────────────────────────────────┘   │
-│                                                             │
-│  ... (275 settings, virtualized/paginated) ...              │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Considerations
-
-1. **Persistence**: Settings changes are in-memory only. Document that restarts reset to defaults.
-2. **Validation**: Validate numeric ranges where applicable (e.g., percentages 0-100)
-3. **Categories**: Consider grouping settings by prefix (AI*, Combat*, Economy*, etc.)
-4. **Audit log**: Log setting changes with timestamp for debugging
-
----
-
-## Feature 3: Game Rewind
-
-### Concept
-
-Restore a game to a previous point in its action history. This is useful for:
-- Debugging issues that occurred at a specific point
-- Testing "what if" scenarios
-- Recovering from bugs that corrupted state
-
-### New gRPC Endpoint
-
-Add to `eagle.proto`:
-
-```protobuf
-message RewindGameRequest {
-  int64 game_id = 1;
-  int32 target_action_count = 2;  // Rewind to state after this many actions
-}
-
-message RewindGameResponse {
-  bool success = 1;
-  string error = 2;
-  int32 new_action_count = 3;
-  int32 disconnected_clients = 4;  // Number of clients that were disconnected
-}
-
-service Eagle {
-  // ... existing methods ...
-  rpc RewindGame(RewindGameRequest) returns (RewindGameResponse);
-}
-```
-
-### Eagle Server Implementation
-
-The `GameHistory` already stores `ActionWithResultingState` for each action, which includes the `GameState` after that action. Rewinding means:
-
-1. **Validate**: Check that `target_action_count` is within valid range (0 to current count)
-2. **Get target state**: Retrieve `GameState` at target action count from history
-3. **Disconnect clients**: Close all human player connections (they'll need to reconnect)
-4. **Replace engine**: Create new `EngineImpl` with target state and truncated history
-5. **Reset AI state**: Clear any cached AI state that depends on current game state
-
-```scala
-// GameController.scala (pseudocode)
-def rewindTo(targetActionCount: Int): Either[String, RewindResult] = {
-  if (targetActionCount < 0 || targetActionCount > engine.history.count)
-    return Left(s"Invalid action count: $targetActionCount")
-
-  // Get state at target point
-  val targetState = engine.history.stateAt(targetActionCount)
-  val truncatedHistory = engine.history.truncateTo(targetActionCount)
-
-  // Disconnect all human clients
-  val disconnectedCount = humanClients.length
-  humanClients.foreach(_.disconnect("Game rewound by admin"))
-
-  // Create new engine at target state
-  val newEngine = EngineImpl(
-    gameId = engine.gameId,
-    currentState = targetState,
-    history = truncatedHistory,
-    // ... other fields
-  )
-
-  // Replace controller's engine
-  this.engine = newEngine
-
-  Right(RewindResult(targetActionCount, disconnectedCount))
-}
-```
-
-### GameHistory Enhancement
-
-Add method to get state at a specific action count:
-
-```scala
-trait GameHistory {
-  // ... existing methods ...
-
-  def stateAt(actionCount: Int): GameState = {
-    if (actionCount == 0) initialState
-    else all(actionCount - 1).resultingState
-  }
-
-  def truncateTo(actionCount: Int): GameHistory = {
-    GameHistoryImpl(
-      initialState = initialState,
-      actions = all.take(actionCount)
-    )
-  }
-}
-```
-
-### Admin Server Route
-
-| Route | Method | Description |
-|-------|--------|-------------|
-| `/games/{id}/rewind` | POST | Rewind game (form: `target_action_count`) |
-| `/games/{id}/rewind/confirm` | GET | Confirmation modal (htmx partial) |
-
-### Rewind UI Flow
-
-1. User views game history
-2. User clicks "Rewind to here" on an action row
-3. Confirmation modal appears via htmx:
-   ```
-   ┌─────────────────────────────────────────┐
-   │  Rewind Game abc123f?                   │
-   │                                         │
-   │  This will:                             │
-   │  • Restore to action 456 (Round 23)     │
-   │  • Discard 778 subsequent actions       │
-   │  • Disconnect 2 connected players       │
-   │                                         │
-   │  This cannot be undone.                 │
-   │                                         │
-   │            [Cancel]  [Rewind]           │
-   └─────────────────────────────────────────┘
-   ```
-4. On confirm, POST to `/games/{id}/rewind`
-5. Success: redirect to game detail showing new state
-6. Error: show error message
-
-### Safety Considerations
-
-1. **No undo**: Rewinding discards history. Consider optional backup before rewind.
-2. **Client disconnect**: All connected clients are forcibly disconnected.
-3. **AI state**: Ensure AI clients restart cleanly after rewind.
-4. **Concurrent access**: Lock game during rewind to prevent race conditions.
-5. **Authorization**: In production, require admin authentication.
-
----
-
-## Implementation Phases
-
-### Phase 1: Web UI Foundation
-
-**Status: Complete**
-
-1. ✅ Set up Go templates with `embed`
-2. ✅ Add Pico CSS and htmx
-3. ✅ Create base layout with navigation
-4. ✅ Convert `/games` to HTML with styling
-5. ✅ Add game detail page with history table
-6. ✅ Implement htmx infinite scroll for history
-7. ✅ Reverse history order (most recent first)
-8. ✅ Clickable action rows that expand to show JSON representation
-9. ✅ Add `/games/{id}/action/{index}` endpoint for fetching action details
-
-**Deliverable**: Browsable game list and history in HTML with clickable action details
-
-### Phase 2: Settings Management
-
-**Status: Complete**
-
-1. ✅ Add `GetSettings` to `eagle.proto` (uses existing `AddSettings` for updates)
-2. ✅ Add `getAllSettings` method to auto-generated `SettingsLoader`
-3. ✅ Implement `getSettings` in `EagleServiceImpl`
-4. ✅ Create settings list page with live search
-5. ✅ Add inline editing with htmx
-6. ✅ Modified settings are highlighted
-
-**Deliverable**: View and edit settings via admin UI
-
-### Phase 3: Game Rewind
-
-**Status: Complete**
-
-1. ✅ Add `RewindGame` to `eagle.proto`
-2. ✅ Implement `stateAt` and `truncateTo` in `GameHistory`
-3. ✅ Implement rewind logic in `Engine` and `GameController`
-4. ✅ Add rewind confirmation (htmx `hx-confirm` dialog)
-5. ✅ Handle client disconnection gracefully
-6. ✅ Add rewind button to history rows
-7. ✅ Implement `rewindGame` in `GamesManager` and `EagleServiceImpl`
-8. ✅ Add admin server `/games/{id}/rewind` POST handler
-9. ✅ Add success/error feedback UI
-
-**Deliverable**: Rewind games to any previous action
-
-### Phase 4: Polish
-
-**Status: Not Started**
-
-#### High Priority
-1. **Add tests for rewind functionality**
-   - `PersistedHistory.truncateTo` (handles complex persisted vs recent logic)
-   - `InMemoryHistory.truncateTo`
-   - `EngineImpl.rewindTo`
-   - `GameController.rewindTo`
-   - `GamesManager.rewindGame`
-
-2. **Improve action history display**
-   - Human-readable action type names (e.g., "New Round" instead of "NewRoundAction")
-   - Show acting faction/province when available
-   - Action summaries from the `summary` field in `GameHistoryEntry`
-
-#### Medium Priority
-3. **Settings improvements**
-   - Group settings by category prefix (AI*, Combat*, Economy*, etc.)
-   - Show setting descriptions where available
-   - Pagination for large settings lists
-
-4. **Error handling improvements**
-   - Better error messages on failed operations
-   - Retry logic for transient gRPC failures
-
-#### Low Priority (Nice to Have)
-5. **Basic auth** - HTTP Basic Auth or OAuth for production use
-6. **Audit logging** - Log admin actions with timestamps
-7. **Documentation** - Usage guide, deployment notes
-
-#### Future Considerations
-- Game creation from admin UI
-- Player management (view connected players, force disconnect)
-- Export game history to file
-- Metrics/stats dashboard
-
----
-
-## Security Notes
-
-The admin server is intended for local/trusted network use only. For production:
-
-1. **Do not expose to public internet** without authentication
-2. Consider adding HTTP Basic Auth or OAuth
-3. Run on internal network or behind VPN
-4. Log all admin actions for audit trail
-
----
-
-## Open Questions
-
-1. **Settings persistence**: Should we add optional persistence to disk/database?
-2. **Game snapshots**: Should rewind create a backup first?
-3. **Multi-admin**: Need locking if multiple admins access simultaneously?
-4. **Shardok settings**: Are there Shardok (C++) settings to expose too?

docs/ASSET_AUDIT.md

@@ -109,11 +109,41 @@ All 26 tracks have CC licenses with proper attribution:
 | Dragon Castle | Makai Symphony | CC BY-SA 3.0 |
 | Durandal | Makai Symphony | CC BY-SA 3.0 |
 
-**Tracks without specific license (verify):**
-- Market Day
-- Shopping List
-- Medieval: Victory Theme
-- Tracks by Dima Koltsov (AUDIUS): No Time for Greatness, Warriors of Demacia, Forest Queen Tale, Valor, Clouds
+**Tracks with non-CC licenses:**
+
+| Track | Artist | License | Source |
+|-------|--------|---------|--------|
+| Market Day | RandomMind | Free without attribution | [Chosic](https://www.chosic.com/download-audio/27016/) |
+| Shopping List | Komiku | Free without attribution | [Chosic](https://www.chosic.com/download-audio/24714/) |
+| Medieval: Victory Theme | RandomMind | CC0 Public Domain | [Chosic](https://www.chosic.com/download-audio/28492/) |
+| No Time for Greatness | Dima Koltsov | CC BY 4.0 | [YouTube](https://www.youtube.com/watch?v=cQh0OWIFdgM) |
+| Warriors of Demacia | Dima Koltsov | CC BY 4.0 | [YouTube](https://www.youtube.com/watch?v=yktSUMJn9ao) |
+| Forest Queen Tale | Dima Koltsov | Presumed CC BY 4.0 | Not found on YouTube; other Dima Koltsov tracks are CC BY 4.0 |
+| Valor | Dima Koltsov | CC BY 4.0 | [YouTube](https://www.youtube.com/watch?v=uoHYJRPcS2Y) |
+| Clouds | Dima Koltsov | Presumed CC BY 4.0 | Not found on YouTube; other Dima Koltsov tracks are CC BY 4.0 |
+
+**Note on Dima Koltsov tracks:** 3 of 5 tracks confirmed CC BY 4.0 via YouTube. 2 remaining tracks (Forest Queen Tale, Clouds) presumed same license but not verified.
+
+---
+
+## 2b. Creative Commons Sound Effects
+
+**Location:** `Assets/Shardok/Sounds/`
+
+| File | Description | Artist | License | Source |
+|------|-------------|--------|---------|--------|
+| `rain_loop.ogg` | Rain falling on clay roof tiles (loopable) | aesqe | CC BY 4.0 | [Freesound #37618](https://freesound.org/people/aesqe/sounds/37618/) |
+| `blizzard_wind_loop.wav` | Wind draft loop (indoor recording, loops seamlessly) | nsstudios | CC BY 4.0 | [Freesound #651540](https://freesound.org/people/nsstudios/sounds/651540/) |
+| `thunder_distant.mp3` | Distant thunder rumble | LittleRainySeasons | CC BY 4.0 | [Freesound #351526](https://freesound.org/people/LittleRainySeasons/sounds/351526/) |
+| `thunder_loud.mp3` | Loud thunder clap | mokasza | CC BY 4.0 | [Freesound #810746](https://freesound.org/people/mokasza/sounds/810746/) |
+| `thunder_crack.wav` | Thunder crack | OneSoundToRuleThemAll | CC BY 4.0 | [Freesound #238796](https://freesound.org/people/OneSoundToRuleThemAll/sounds/238796/) |
+| `thunder_clap.wav` | Thunder clap | FreqMan | CC BY 4.0 | [Freesound #32544](https://freesound.org/people/FreqMan/sounds/32544/) |
+
+**Location:** `Assets/Shardok/soundEffects/`
+
+| File | Description | Artist | License | Source |
+|------|-------------|--------|---------|--------|
+| `runaway.mp3` | Medieval army running loop (gravel + metal/chain) | Yap_Audio_Production | CC BY 4.0 | [Freesound #218997](https://freesound.org/people/Yap_Audio_Production/sounds/218997/) |
 
 ---
 
@@ -129,42 +159,64 @@ All 26 tracks have CC licenses with proper attribution:
 
 ## 4. Potentially Problematic Assets (Review Needed)
 
-### Stock Images (Possible License Issues)
-These appear to be stock images that may have been used as placeholders:
-
-| File | Concern |
-|------|---------|
-| ~~`Assets/Eagle/79066358-stock-illustration-raster-illustration-medieval-purse-bag...jpg`~~ | **DELETED** (2025-01-04) |
-| ~~`Assets/Images/kisspng-hammer-hand-saws-tool-clip-art...jpg`~~ | **DELETED** (2025-01-04) |
-| ~~`Assets/Images/lee-ermy-cropped.jpg`~~ | **DELETED** (2025-01-04) |
-| ~~`Assets/Eagle/images.jpeg`~~ | **DELETED** (2025-01-04) |
-
-### Clip Art (Unknown License)
-| File | Concern |
-|------|---------|
-| `Assets/Shardok/commandImages/bridge.png` | Clip art style wooden bridge, unknown source - **needs replacement** |
-| `Assets/Images/startFire.png` | Icon, unknown source - **needs verification or replacement** |
+### ~~Clip Art (Unknown License)~~ RESOLVED
+| File | Status |
+|------|--------|
+| ~~`Assets/Shardok/commandImages/bridge.png`~~ | **REPLACED** (2026-01-23) with AI-generated wooden rope bridge icon (ChatGPT/DALL-E 3, 512x512 PNG). No licensing restrictions - AI-generated for this project. |
+| ~~`Assets/Images/startFire.png`~~ | **REPLACED** (2026-01-23) with "Flame Icon" from [UXWing](https://uxwing.com/flame-icon/) (free for commercial use, no attribution required). Consolidated duplicate removed. |
+| ~~`Assets/Shardok/commandImages/startFire.png`~~ | **DELETED** (2026-01-23) - duplicate removed, all references updated to use `Assets/Images/startFire.png` |
 
 ### Shardok Sound Effects
 - **Location:** `Assets/Shardok/soundEffects/`
-- **Count:** 56 MP3 files
+- **Count:** 37 audio files (was incorrectly counted as 56 including .meta files)
 - **Contents:** Spell effects, movement, combat sounds
-- **Status:** Unknown origin - may be custom or need verification
 
-### Free Icons
-- **Location:** `Assets/free_icons/`
-- **Count:** 8 PNG weather icons
-- **Status:** Verify "free" means commercially usable
+**Verified from [Zombie Monster - Undead Collection](https://assetstore.unity.com/packages/audio/sound-fx/creatures/zombie-monster-undead-collection-70662) (Unity Asset Store):**
+- `raise_undead.mp3`
+- `undead_break_control.mp3`
+- `undead_grew.wav`
 
-### Terrain Hexes
+**⚠️ MUST REPLACE (1 remaining):**
+- ~~`anybody.mp3`~~ - **REPLACED** (2026-01-23) with `Positive Effect 6.wav` from Magic Spells Sound Effects LITE
+- ~~`burnination.mp3`~~ - **REPLACED** (2026-01-23) with `Magic Element Fire 04.wav` from Medieval Combat Sounds
+- `failure_horn.mp3` - licensing issue, no replacement found in purchased assets
+- ~~`runaway.mp3`~~ - **REPLACED** (2026-01-27) with `MedievalArmyRunningLoop.mp3` from Freesound (CC BY 4.0)
+
+**Verified from [Medieval Combat Sounds](https://assetstore.unity.com/packages/audio/sound-fx/medieval-combat-sounds-100465) (Unity Asset Store):**
+- `duel_challenged.wav` - **REPLACED** (2026-02-03) with `Weapon Draw Metal 1.wav` from Medieval Combat Sounds
+
+**Presumed from Unity Asset Store purchases (30 files):**
+Owner believes these are from: Fantasy Interface Sounds, Medieval Combat Sounds, Magic Spells Sound Effects LITE, and/or Medieval Battle Sound Pack.
+- `archery.mp3`, `battle_shout.mp3`, `boo.mp3`, `braved_water.mp3`
+- `build_bridge.mp3`, `build_bridge_failure.mp3`, `charge.mp3`
+- `dismiss_unit.mp3`, `failure_horn.mp3`, `fear.mp3`, `fear_failed.mp3`
+- `fire_extinguish.mp3`, `fire_spread.mp3`, `fire_start.mp3`, `fire_start_failure.mp3`
+- `freeze.mp3`, `holy_wave.mp3`, `holy_wave_damage.mp3`, `jail_door.mp3`, `lightning.mp3`
+- `melee.mp3`, `meteor.mp3`, `mind_control.mp3`, `move.mp3`, `move 1.mp3`
+- `raging_fire.mp3`, `reduce.mp3`, `repair.mp3`, `repair_failed.mp3`, `splash.mp3`
+
+### ~~Free Icons~~ RESOLVED
+- **Location:** `Assets/free_icons/` - **DELETED** (2026-01-27)
+- **Resolution:** All icons replaced with equivalents from purchased Asset Store packs:
+  - `blizzard.png` → `16_blizzard_nobg.png` (4000_Fantasy_Icons)
+  - `rain.png` → `12_Magic_rain_nobg.png` (4000_Fantasy_Icons)
+  - `thunderstorm.png` → `27_Storm_nobg.png` (4000_Fantasy_Icons)
+  - `wind.png` → `23_Light_blow_nobg.png` (4000_Fantasy_Icons)
+  - `thermometer.png` → `startFire.png` (existing licensed asset)
+  - `snow.png` → `16_blizzard_nobg.png` (4000_Fantasy_Icons)
+  - `cloud.png`, `sun.png` → deleted (unused)
+
+### ~~Terrain Hexes~~ VERIFIED
 - **Location:** `Assets/Terrain Hexes/`
 - **Count:** 85 PNG files
-- **Status:** Unknown source - verify licensing
+- **Status:** ✓ Confirmed Unity Asset Store purchase (2026-01-23)
 
-### StrategyGameIcons
+### ~~StrategyGameIcons~~ VERIFIED
 - **Location:** `Assets/StrategyGameIcons/`
 - **Count:** 138 PNG files
-- **Status:** Unknown source - verify licensing
+- **Publisher:** REXARD
+- **Asset Store Link:** https://assetstore.unity.com/packages/2d/gui/icons/strategy-game-icons-64816
+- **Status:** ✓ Confirmed Unity Asset Store purchase (2026-01-23)
 
 ---
 
@@ -194,28 +246,31 @@ NuGet packages in `Assets/Packages/` all include LICENSE.TXT files:
 
 ## Action Items
 
-### Must Verify Before Opening Public Access:
+### Must Replace Before Opening Public Access:
 
-1. ~~**Stock images** - The JPG files with stock image filenames need review.~~ **DONE** - Deleted lee-ermy, kisspng, stock-illustration, Yosemite Sam, and images.jpeg (2025-01-04)
+1. ~~**Clip art images**~~ - **RESOLVED** (2026-01-23): Replaced with properly licensed alternatives
 
-2. **Clip art images** - Unknown license, need replacement with properly licensed alternatives:
-   - `Assets/Shardok/commandImages/bridge.png` - wooden bridge icon
-   - `Assets/Images/startFire.png` - fire icon
+2. ~~**Shardok sound effects**~~ - **ALL RESOLVED**:
+   - ~~`anybody.mp3`~~ - **REPLACED** (2026-01-23)
+   - ~~`burnination.mp3`~~ - **REPLACED** (2026-01-23)
+   - ~~`failure_horn.mp3`~~ - **REPLACED** (2026-01-27) with `Negative Effect 04.wav` from Magic Spells Sound Effects LITE
+   - ~~`runaway.mp3`~~ - **REPLACED** (2026-01-27) with Freesound CC BY 4.0
 
-3. **Shardok sound effects** - 56 MP3 files of unknown origin. Either:
-   - Document their source
-   - Replace with known-licensed alternatives
-   - Confirm they were custom-created
+### Low Priority (Verify):
 
-4. **Terrain Hexes** - 85 hex tiles of unknown source
-   - **TODO:** Confirm if this is a Unity Asset Store purchase (owner believes it is)
+3. **Dima Koltsov tracks** - 2 of 5 not verified: `Forest Queen Tale`, `Clouds` (presumed CC BY 4.0 like his other tracks)
 
-5. **StrategyGameIcons** - 138 icons of unknown source
-   - **TODO:** Investigate origin - check Unity Asset Store purchase history
+### Already Resolved:
 
-6. **AUDIUS music tracks** - Verify Dima Koltsov tracks are licensed for commercial use
+4. ~~**Free Icons**~~ - **RESOLVED** (2026-01-27): All replaced with Asset Store equivalents, folder deleted
 
-7. **Discord logo** (`Eagle/Discord-Logo-Blurple.png`) - Likely fine for "Login with Discord" button per Discord brand guidelines, but verify usage complies with their terms
+5. ~~**Terrain Hexes**~~ - **VERIFIED** (2026-01-23): Confirmed Unity Asset Store purchase
+
+6. ~~**StrategyGameIcons**~~ - **VERIFIED** (2026-01-23): Unity Asset Store purchase (REXARD)
+
+7. ~~**Medieval: Victory Theme**~~ - **VERIFIED** (2026-01-23): CC0 Public Domain by RandomMind ([Chosic](https://www.chosic.com/download-audio/28492/))
+
+8. ~~**Discord logo**~~ - **OK** (2026-01-23): Usage complies with Discord brand guidelines for "Login with Discord" button
 
 ### Already Safe:
 
@@ -229,12 +284,23 @@ NuGet packages in `Assets/Packages/` all include LICENSE.TXT files:
 
 ## Recommendation
 
-Before removing HTTP basic auth:
+**Remaining before public release:**
 
-1. ~~Delete or replace the 4 suspicious JPG/JPEG files in `Assets/Eagle/` and `Assets/Images/`~~ **DONE** (2025-01-04)
-2. Replace clip art images (`bridge.png`, `startFire.png`) with properly licensed alternatives (e.g., from [game-icons.net](https://game-icons.net) CC BY 3.0)
-3. Verify source of `Assets/Shardok/soundEffects/` MP3s
-4. Verify source of `Assets/Terrain Hexes/` and `Assets/StrategyGameIcons/`
-5. If any are from early development with unclear licensing, replace them
+None! All required items resolved.
+
+**Low priority:**
+
+2. Verify 2 Dima Koltsov tracks (`Forest Queen Tale`, `Clouds`) - presumed CC BY 4.0
+
+**Already resolved:**
+
+- ~~Clip art images~~ **DONE** - replaced with properly licensed alternatives
+- ~~Terrain Hexes~~ **DONE** - confirmed Asset Store purchase
+- ~~StrategyGameIcons~~ **DONE** - Unity Asset Store (REXARD)
+- ~~Medieval: Victory Theme~~ **DONE** - CC0 Public Domain
+- ~~3 other Dima Koltsov tracks~~ **DONE** - confirmed CC BY 4.0
+- ~~anybody.mp3, burnination.mp3~~ **DONE** - replaced
+- ~~free_icons~~ **DONE** - replaced with Asset Store equivalents
+- ~~failure_horn.mp3~~ **DONE** - replaced with Negative Effect 04.wav
 
 The bulk of your assets (95%+) are properly licensed Asset Store purchases or CC content.

docs/DEPROTO_PLAN.md

@@ -1,388 +0,0 @@
-# Deproto Migration Plan
-
-## Vision
-
-**Protocol buffers should only be used at the edges** — for network serialization (gRPC) and disk persistence. Inside the Eagle game engine, all logic should operate on native Scala models.
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                         GRPC BOUNDARY                               │
-│  EagleServiceImpl.scala  ←→  Proto Messages  ←→  Unity Client       │
-└─────────────────────────────────────────────────────────────────────┘
-                                   ↓
-                          GameStateConverter
-                                   ↓
-┌─────────────────────────────────────────────────────────────────────┐
-│                         SCALA ENGINE                                │
-│                                                                     │
-│   GameStateC ───→ Actions ───→ ActionResultT ───→ New GameStateC   │
-│       ↑                                                   │        │
-│       │               (Pure Scala models)                 │        │
-│       └───────────────────────────────────────────────────┘        │
-│                                                                     │
-│   HeroC, FactionC, ProvinceC, BattalionC, ArmyC, etc.              │
-└─────────────────────────────────────────────────────────────────────┘
-                                   ↓
-                          GameStateConverter
-                                   ↓
-┌─────────────────────────────────────────────────────────────────────┐
-│                      PERSISTENCE BOUNDARY                           │
-│  GameHistory.scala  ←→  Proto Messages  ←→  File/Database          │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Current State
-
-### Completed Phases
-
-| Phase | Status | Summary |
-|-------|--------|---------|
-| Phase 1: GameStateC | **Complete** | Scala `GameState` model with 22 fields |
-| Phase 2: EngineImpl | **Complete** | Holds Scala `GameState` internally |
-| Phase 3: GameHistory | **Complete** | `stateAfter` returns Scala GameState |
-| Phase 4: ActionResultT | **Complete** | All 59 actions return `ActionResultT` |
-| Phase 5: Action Base Classes | **Complete** | All `RandomSequentialResultsAction` and `DeterministicSingleResultAction` converted to T-type base classes |
-| Phase 5b: Base Class Cleanup | **Complete** | `RandomSequentialResultsAction` and `DeterministicSingleResultAction` deleted |
-| Phase 5c: RoundPhaseAdvancer Actions | **Complete** | All actions called by RoundPhaseAdvancer accept Scala GameState |
-| Phase 5d: RoundPhaseAdvancer Itself | **Complete** | RoundPhaseAdvancer.checkForPhaseAdvancement takes Scala GameState |
-
-### Phase 5c/5d Progress (Complete)
-
-`RoundPhaseAdvancer.checkForPhaseAdvancement` now accepts Scala `GameState` and `ActionResultApplier` directly (PR #4677).
-
-| Action | PR | Status |
-|--------|-----|--------|
-| `PrisonerExchangeAction` | #4670 | ✅ Merged |
-| `PerformForcedTurnBackAction` | #4671 | ✅ Merged |
-| `PerformHeroDeparturesAction` | #4672 | ✅ Merged |
-| `RequestFreeForAllBattlesAction` | #4673 | ✅ Merged |
-| `EndPlayerCommandsPhaseAction` | #4674 | ✅ Merged |
-| `EndDiplomacyResolutionPhaseAction` | #4675 | ✅ Merged |
-| `RoundPhaseAdvancer` itself | #4677 | ✅ Merged |
-
-### EngineImpl Progress
-
-| Change | PR | Status |
-|--------|-----|--------|
-| `recursiveTransform` deleted | #4677 | ✅ Merged |
-| `recursiveTransformT` uses `RandomStateTSequencer` | #4677 | ✅ Merged |
-
-### Current Architecture
-
-**ActionResultT Production (100% Complete):**
-- All actions produce `ActionResultT`
-- Conversion to `ActionResultProto` happens via `ActionResultProtoConverter.toProto()`
-- No direct `ActionResultProto` construction outside the converter
-
-**ActionResultProto Consumption (Next Target):**
-- `ActionResultProtoApplierImpl` - applies proto results to proto GameState
-- `RoundPhaseAdvancer` - calls converter, passes protos to applier
-- `InMemoryHistory` / `PersistedHistory` - stores proto results
-- Service layer (`GameController`, `GamesManager`, etc.) - uses proto for client communication
-
----
-
-## Phase 6: Migrate to ActionResultT Consumers
-
-### Objective
-
-Eliminate internal consumption of `ActionResultProto`. Everything inside the engine should work with `ActionResultT`.
-
-### Current Flow (Proto-Heavy)
-```
-Action.execute()
-    → ActionResultT
-    → ActionResultProtoConverter.toProto()
-    → ActionResultProto
-    → ActionResultProtoApplierImpl.applyActionResults()
-    → GameStateProto
-    → GameStateConverter.fromProto()
-    → GameStateC
-```
-
-### Target Flow (T-Types Throughout)
-```
-Action.execute()
-    → ActionResultT
-    → ActionResultApplier.applyActionResults()
-    → GameStateC
-
-    (Proto conversion only at boundaries)
-```
-
-### Key Files to Convert
-
-**Tier 1 - Core Applier:** ✅ **Complete**
-```
-src/main/scala/net/eagle0/eagle/library/actions/applier/ActionResultApplierImpl.scala
-```
-`ActionResultApplier` applies `ActionResultT` directly to Scala `GameState`. The legacy `ActionResultTApplierImpl` wraps it and converts to/from proto for callers that still need proto types.
-
-**Tier 2 - RoundPhaseAdvancer:** ✅ **Complete**
-```
-src/main/scala/net/eagle0/eagle/library/RoundPhaseAdvancer.scala
-```
-Now accepts Scala `GameState` and `ActionResultApplier`. Only converts to proto lazily for `AvailableCommandsFactory` calls.
-
-**Tier 3 - Sequencers:**
-```
-src/main/scala/net/eagle0/eagle/library/actions/impl/common/RandomStateTSequencer.scala
-src/main/scala/net/eagle0/eagle/library/actions/impl/common/RandomStateProtoSequencer.scala
-```
-Modify `RandomStateTSequencer` to thread Scala `GameState` throughout (currently converts to proto internally). Then evaluate whether `RandomStateProtoSequencer` is still needed at all.
-
-**Current State**: `RandomStateTSequencer` accepts Scala `GameState` via its `apply()` method but internally converts to proto. All callback methods (`withRandomActionResult`, `withActionResults`, etc.) pass `GameStateProto` to callers, forcing actions that use the sequencer to work with proto types internally.
-
-**Target State**: Create a fully protoless sequencer where:
-1. `lastState` returns Scala `GameState` (not `lastStateProto`)
-2. All callback methods pass Scala `GameState` to callers
-3. Actions using the sequencer can be fully protoless
-
-**Migration Path**:
-1. Add `lastState: GameState` method alongside `lastStateProto` (non-breaking)
-2. Add parallel callback methods that pass Scala GameState (e.g., `withScalaActionResult`)
-3. Migrate actions one by one to use the new Scala-based callbacks
-4. Once all actions migrated, deprecate/remove proto-based callbacks
-5. Remove `lastStateProto` once no longer used
-
-**RandomStateSequencer Migration Progress** (PR #4679 introduced protoless `RandomStateSequencer`):
-
-| Action | Status |
-|--------|--------|
-| `TruceTurnBackPhaseAction` | ✅ Migrated (PR #4680) |
-| `EndHandleRiotsPhaseAction` | ✅ Migrated (PR #4684) |
-| `PerformVassalCommandsPhaseAction` | ✅ Migrated |
-| `PerformVassalDefenseDecisionsAction` | ✅ Migrated |
-| `EndVassalCommandsPhaseAction` | ✅ Migrated |
-| `PerformReconResolutionAction` | ✅ Migrated |
-| `NewRoundAction` | ✅ Migrated (PR #4698) |
-| `EndBattleAftermathPhaseAction` | ✅ Migrated (PR #4699) |
-| `EndDiplomacyResolutionPhaseAction` | ✅ Migrated |
-| `PerformUnaffiliatedHeroesAction` | ✅ Migrated |
-| `EngineImpl.recursiveTransformT` | ✅ Migrated (PR #4704) |
-| `ProtolessSequentialResultsActionWrapper` | ✅ Migrated (PR #4705) |
-| `LegacyRandomStateTSequencer` | ✅ **Deleted** (PR #4705) |
-
-**TCommandFactory Extraction** (PR #4684):
-
-To enable lightweight mocking of command creation in tests, `TCommandFactory` trait was extracted from `CommandFactory`. This allows tests to mock just the `makeTCommand` method without pulling in all 40+ command dependencies that `CommandFactory` requires.
-
-- `TCommandFactory` - lightweight trait with just `makeTCommand`
-- `CommandFactory extends TCommandFactory` - maintains backward compatibility
-- Actions accepting command factories now use `TCommandFactory` type for better testability
-
-**Tier 4 - History APIs:**
-```
-src/main/scala/net/eagle0/eagle/service/InMemoryHistory.scala
-src/main/scala/net/eagle0/eagle/service/PersistedHistory.scala
-```
-Change APIs to vend Scala `GameState` and `ActionResultT` instead of proto versions. `PersistedHistory` converts to proto internally for disk persistence; `InMemoryHistory` doesn't need proto at all.
-
-### ActionResultProto Consumer Inventory
-
-| File | Usage | Status |
-|------|-------|--------|
-| `ActionResultApplierImpl.scala` | Applies ActionResultT to Scala GameState | ✅ **Complete** |
-| `ActionResultTApplierImpl.scala` | Legacy wrapper - converts to/from proto | Keep until all callers migrated |
-| `RoundPhaseAdvancer.scala` | Uses Scala GameState | ✅ **Complete** |
-| `RandomStateSequencer.scala` | Threads Scala GameState | ✅ **Complete** |
-| `VigorXPApplier.scala` | Has both proto and Scala methods | Scala method exists, delete proto method when unused |
-| `PerformForcedTurnBackAction.scala` | Fully protoless | ✅ **Complete** |
-| `ResolveBattleAction.scala` | ✅ Fully protoless | Complete (PR #5048) |
-| `InMemoryHistory.scala` | Stores proto results | Pending - vend Scala types |
-| `PersistedHistory.scala` | Stores proto results | Pending - vend Scala types, convert for disk |
-| `GameController.scala` | Uses proto for client communication | Keep proto (gRPC boundary) |
-
-### Remaining Proto Usage in Actions
-
-**Progress: 52 of 52 action files (100%) are fully protoless.** ✅
-
-All action files have been migrated to use Scala types:
-
-| Action | Status | Notes |
-|--------|--------|-------|
-| `ResolveBattleAction` | ✅ Complete | PR #5048 - uses Scala GameState and ActionResultApplier |
-| `PerformVassalCommandsPhaseAction` | ✅ Complete | Uses Scala types via CommandChoiceHelpers |
-| `EndHandleRiotsPhaseAction` | ✅ Complete | Uses Scala types via CommandChoiceHelpers |
-| `PerformVassalDefenseDecisionsAction` | ✅ Complete | Uses Scala types via CommandChoiceHelpers |
-| `EndVassalCommandsPhaseAction` | ✅ Complete | Uses Scala types via CommandChoiceHelpers |
-
-**Note:** `NewRoundAction` is now fully protoless after converting `ChronicleEventGenerator` to return Scala `ChronicleEvent` types directly.
-
-**Deleted Dead Code:**
-- `UnaffiliatedHeroMovedAction` - Was never called; `PerformUnaffiliatedHeroesAction.heroMovedResult` constructs `ActionResultC` directly
-- `HeroBackstoryUpdateActionGenerator.fromGameState` - Dead method that converted proto to Scala; only `apply(GameState)` is used
-
-**Note**: `PerformReconResolutionAction` and `EndBattleAftermathPhaseAction` are now fully protoless after:
-1. Migrating `FactionT.reconnedProvinces` and `ChangedFactionC.updatedReconnedProvinces` to use Scala `ProvinceView`
-2. Adding Scala overload of `ProvinceViewFilter.withdrawnFromProvinceView`
-
-### Estimated Effort (Remaining)
-
-| Component | Lines | Complexity | Blocks |
-|-----------|-------|------------|--------|
-| History API updates | ~100 | Low | - |
-| **Total Remaining** | **~100** | | |
-
-**Completed:**
-- ✅ `ChronicleEventGenerator` converted to return Scala `ChronicleEvent` types directly
-- ✅ `CommandChoiceHelpers` migrated to Scala types
-- ✅ `ResolveBattleAction` refactored to use Scala GameState and ActionResultApplier (PR #5048)
-
-### Enum Type Migrations
-
-Proto enums are being converted to Scala sealed traits with converters at boundaries:
-
-| Enum | Scala Type | Status | Notes |
-|------|------------|--------|-------|
-| `DiplomacyOfferStatus` | `Status` sealed trait | ✅ **Complete** | PR #5093 - `EligibleDiplomacyStatuses` uses Scala types internally |
-| `RoundPhase` | `RoundPhase` sealed trait | Partial | Some usages converted |
-| `BattalionType` | `BattalionType` sealed trait | Partial | Some usages converted |
-
-**DiplomacyOfferStatus Migration (PR #5093):**
-- `EligibleDiplomacyStatuses.scala` now returns `Vector[Status]` instead of `Vector[DiplomacyOfferStatus]`
-- Call sites in `AvailableResolve*CommandFactory` files convert to proto via `StatusConverter.toProto` at the boundary
-- This pattern should be applied to other proto enums
-
-### CommandChoiceHelpers Migration Status
-
-Several command selectors have already been converted to use Scala types:
-
-| File | Status | Notes |
-|------|--------|-------|
-| `AttackCommandChooser.scala` | ✅ **Protoless** | Uses Scala `GameState`, `HeroT`, `ProvinceT` |
-| `AlmsCommandSelector.scala` | ✅ **Protoless** | Uses Scala `GameState`, `HeroT`, `ProvinceT` |
-| `FoodConsumptionUtils.scala` | ✅ **Protoless** | Uses Scala `GameState`, `ProvinceT`, `RoundPhase` |
-| `MarchSuppliesHelpers.scala` | ✅ **Protoless** | Uses `BattalionT` |
-| `CombatUnitSelector.scala` | ✅ **Protoless** | Uses `HeroT`, `BattalionT`, `BattalionType` |
-| `ExpandCommandSelector.scala` | ✅ **Protoless** | Uses Scala `GameState`, `ProvinceT`, `FactionT` |
-| `ImproveCommandSelector.scala` | ✅ **Protoless** | Uses Scala `GameState`, `ProvinceT`, `HeroT` |
-| `OrganizeCommandSelector.scala` | ✅ **Protoless** | Uses Scala `GameState`, `BattalionT`, `BattalionType` |
-| `RansomOfferHelpers.scala` | ✅ **Protoless** | Uses Scala `GameState`, `FactionT` |
-| `CommandChoiceHelpers.scala` | ✅ **Protoless** | Uses Scala `GameState` throughout |
-| `ProvinceGoldSurplusCalculator.scala` | ✅ **Protoless** | Uses Scala types |
-
-**All CommandChoiceHelpers selectors have been migrated to Scala types.** ✅
-
-### Progress Summary
-
-| Metric | Value |
-|--------|-------|
-| Action files fully protoless | 52 / 52 (100%) ✅ |
-| Proto usages in remaining actions | 0 |
-| Next target | See "Next Candidates" section below |
-
-### Next Candidates
-
-Priority candidates for further deproto work:
-
-1. **More Enum Migrations** - Apply the `DiplomacyOfferStatus` pattern to other proto enums:
-   - Files importing `net.eagle0.eagle.common.round_phase.RoundPhase` (proto) could use Scala `RoundPhase`
-   - Files importing `net.eagle0.eagle.common.battalion_type.BattalionType` (proto) could use Scala `BattalionType`
-
-2. **AvailableCommandsFactory Files** - Many still use proto `GameState` internally:
-   - These files build proto `AvailableCommand` messages but could use Scala types for internal logic
-   - Convert to accept Scala `GameState`, only convert fields to proto when building the response
-
-3. **History APIs** - `InMemoryHistory` and `PersistedHistory`:
-   - Change to vend Scala `GameState` and `ActionResultT` instead of proto versions
-   - `PersistedHistory` converts to proto internally for disk persistence
-
-### Validation
-- [x] `ActionResultApplier` created and tested
-- [x] `RandomStateSequencer` threads Scala GameState throughout
-- [x] `RoundPhaseAdvancer` uses T-types internally
-- [x] `ProvinceViewFilter` has Scala overload for server-side use (PR #4752)
-- [x] `FactionT.reconnedProvinces` and `ChangedFactionC.updatedReconnedProvinces` use Scala `ProvinceView`
-- [x] `ProvinceViewFilter.withdrawnFromProvinceView` has Scala overload
-- [x] `CommandChoiceHelpers` uses Scala types ✅
-- [x] All action files (52/52) are fully protoless ✅
-- [ ] `ProvinceViewFilter` faction-filtered views use Scala types
-- [ ] History APIs vend Scala types
-- [ ] No `ActionResultProtoConverter.toProto()` calls except at persistence/gRPC boundaries
-- [ ] All tests pass
-
----
-
-## Phase 7: Clean Up Legacy Utilities
-
-### Objective
-Remove remaining direct proto imports from utility classes.
-
-### Files to Modify
-
-| File | Status |
-|------|--------|
-| `CommandChoiceHelpers.scala` | Accepts proto `GameState`; blocks full deproto of `PerformVassalCommandsPhaseAction` and `PerformVassalDefenseDecisionsAction` |
-| `LegacyProvinceUtils.scala` | Replace with `ProvinceUtils.scala` - `hasImminentRiot` added (PR #4683) |
-| `LegacyFactionUtils.scala` | Replace proto imports with `FactionT` |
-| `LegacyUnaffiliatedHeroUtils.scala` | Replace proto imports with Scala models |
-| `BattalionTypeLoader.scala` | Keep proto for file loading, convert immediately after |
-| `BeastUtils.scala` | **Complete** - now uses Scala `BeastInfo` only |
-
-### View Filters (Partially Complete)
-
-The view filter utilities now have Scala overloads for server-side use:
-
-| File | Status | Notes |
-|------|--------|-------|
-| `ProvinceViewFilter.scala` | **Partial** | `filteredProvinceView(ProvinceT, ScalaGameState)` added (PR #4752) |
-| `ArmyFilter.scala` | **Partial** | `filterArmy(ScalaArmy, Map[BattalionId, BattalionT], Option[FactionId])` added |
-| `BattalionViewFilter.scala` | **Complete** | Uses Scala `BattalionT` throughout |
-| `GameStateViewFilter.scala` | Pending | Uses proto types throughout |
-| `GameStateViewDiffer.scala` | Pending | Works with view protos |
-
-**Unblocked Actions** (PR #4752):
-- `EndBattleAftermathPhaseAction` - can now use `filteredProvinceView(province, scalaGameState)`
-- `PerformReconResolutionAction` - can now use Scala overload
-- `GameStateFactionExtensions` - can now use `updatedReconnedProvinces` with Scala types
-
-**Remaining Work**:
-- Faction-filtered `filteredProvinceView(Province, GameState, FactionId)` still uses proto types
-- `withdrawnFromProvinceView` still uses proto types
-- These are needed for client-facing views with visibility restrictions
-
----
-
-## Phase 8: Verify Boundaries
-
-### Objective
-Confirm protos are used correctly at boundaries — and ONLY there.
-
-### Expected Proto Usage (Keep)
-- `EagleServiceImpl.scala` - gRPC boundary
-- `InMemoryHistory.scala` / `PersistedHistory.scala` - Persistence boundary
-- `*Converter.scala` - Explicit conversion utilities
-- `*Loader.scala` - File loading utilities
-
-### Expected No Proto Usage (Verify)
-- `/library/actions/impl/` - Pure Scala models
-- `/library/util/` - Pure Scala models (except loaders)
-- `/model/state/` - Pure Scala models
-
----
-
-## Open Questions
-
-1. **Persistence Format**: Currently game state is persisted as proto. Should we keep proto for persistence (good for schema evolution) or switch to a different format?
-
-2. **Shardok Integration**: `ResolveBattleAction` communicates with Shardok. Should the Shardok interface use protos (external service) or Scala models?
-
-3. **View Generation**: `GameStateViewDiffer` works with view protos for client updates. Views need Scala models (`ProvinceViewT`, etc.) to allow actions like `EndBattleAftermathPhaseAction` to be fully protoless. The Scala views would be converted to proto only at the gRPC boundary when sending updates to clients.
-
----
-
-## Success Criteria
-
-### Code Quality
-- [ ] Zero proto imports in `/library/actions/` (except boundaries)
-- [ ] Zero proto imports in `/library/` utilities (except loaders)
-- [ ] `GameStateT` used throughout engine internals
-- [ ] Proto usage limited to: `EagleServiceImpl`, loaders, converters, persistence
-
-### Architecture
-- [ ] Clear separation: Scala models (internal) vs Proto (boundaries)
-- [ ] Converters as the only bridge between domains
-- [ ] No "proto creep" into business logic

docs/LLM_MODEL_COMPARISON.md

@@ -0,0 +1,94 @@
+# LLM Model Comparison
+
+This document compares streaming latency (time-to-first-token) and pricing across OpenAI, Anthropic (Claude), and Google (Gemini) models for use in Eagle's narrative text generation.
+
+## Test Methodology
+
+All tests were performed locally using curl with streaming enabled. Each model was tested 3 times with the same prompt:
+
+> "Write a short paragraph about a brave knight who discovers a hidden cave. Make it vivid and descriptive."
+
+Time-to-first-token (TTFT) was measured from request initiation to the first text content appearing in the stream.
+
+## Streaming Latency Results (January 2026)
+
+| Model | Run 1 | Run 2 | Run 3 | Average TTFT |
+|-------|-------|-------|-------|--------------|
+| **Gemini 2.5 Flash-Lite** | 0.76s | 0.54s | 0.53s | **~0.6s** |
+| **gpt-4.1-mini** | 1.65s | 1.72s | 1.68s | **~1.7s** |
+| **claude-3-5-haiku** | 1.85s | 1.92s | 1.88s | **~1.9s** |
+| gpt-5.2 | 3.25s | 3.38s | 3.32s | **~3.3s** |
+| gpt-5-mini | 2.52s | 5.82s | 3.12s | **~3.8s** (high variance) |
+| Gemini 3 Flash Preview | 4.11s | 4.77s | 4.28s | **~4.4s** |
+| claude-sonnet-4 | 4.89s | 5.12s | 4.98s | **~5.0s** |
+| Gemini 2.5 Flash | 5.60s | 7.00s | 7.79s | **~6.8s** |
+
+## Pricing Comparison (per 1M tokens)
+
+| Model | Input Price | Output Price | Notes |
+|-------|-------------|--------------|-------|
+| **Gemini 2.5 Flash-Lite** | $0.10 | $0.40 | Cheapest and fastest |
+| Gemini 2.5 Flash | $0.15 | $0.60 | |
+| gpt-5-mini | $0.25 | $2.00 | |
+| **gpt-4.1-mini** | $0.40 | $1.60 | Best OpenAI value |
+| Gemini 3 Flash Preview | $0.50 | $3.00 | Includes thinking tokens |
+| **claude-3-5-haiku** | $0.80 | $4.00 | Best Anthropic value |
+| gpt-5.2 | ~$1.00 | ~$10.00 | Full reasoning model |
+| Gemini 2.5 Pro | $1.25 | $10.00 | |
+| Gemini 3 Pro Preview | $2.00 | $12.00 | ≤200K context |
+| claude-sonnet-4 | $3.00 | $15.00 | |
+
+## Recommendations
+
+### For Narrative Text Generation (Default)
+
+**Gemini 2.5 Flash-Lite** is recommended as the default:
+- Fastest TTFT (~0.6s) - nearly 3x faster than alternatives
+- Cheapest pricing ($0.10/$0.40 per 1M tokens)
+- Quality is acceptable for short narrative snippets
+
+### Alternative Options
+
+| Priority | Model | When to Use |
+|----------|-------|-------------|
+| Speed + Cost | Gemini 2.5 Flash-Lite | Default for most use cases |
+| Speed + Quality | gpt-4.1-mini | When you need OpenAI quality with good speed |
+| Instruction Following | claude-3-5-haiku | Complex multi-step prompts, consistent tone |
+| Maximum Quality | claude-sonnet-4 or gpt-5.2 | When output quality is paramount |
+
+### Quality Trade-offs
+
+For short narrative snippets (1-3 paragraphs):
+- **Flash-Lite vs Haiku/4.1-mini**: Minor quality difference, significant speed gain
+- **Haiku vs Sonnet**: Noticeable quality difference in creative writing variety
+- **gpt-4.1-mini vs gpt-5.2**: Moderate quality difference, significant cost savings
+
+## Configuration
+
+LLM settings can be changed at runtime via the admin console:
+
+1. Navigate to Admin Console → Settings
+2. Change `LlmProvider` to select vendor (gemini, openai, claude)
+3. Change the corresponding model name setting:
+   - `GeminiModelName` (default: gemini-2.5-flash-lite)
+   - `OpenAiModelName` (default: gpt-4.1-mini)
+   - `ClaudeModelName` (default: claude-3-5-haiku-20241022)
+
+Changes take effect on the next LLM request.
+
+## Environment Variables
+
+For production deployment, ensure API keys are set:
+
+```bash
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GEMINI_API_KEY=AIza...
+```
+
+## Notes
+
+- **gpt-5-mini** showed high latency variance (2.5s - 5.8s) in testing
+- **Gemini 2.5 Flash** was surprisingly slower than Flash-Lite, possibly due to internal reasoning overhead
+- **Gemini 3 Flash** is a frontier model with better quality but higher latency than 2.5 Flash-Lite
+- All Gemini models have a generous free tier (up to 1,000 daily requests)

docs/NEW_PROFESSION_PROPOSALS.md

@@ -0,0 +1,103 @@
+# New Profession Proposals
+
+This document proposes 5 new hero professions for Eagle0. Each profession has abilities for both the Eagle (strategic) and Shardok (tactical) game layers.
+
+## Current Professions Reference
+
+| Profession | Eagle Ability | Shardok Abilities |
+|------------|---------------|-------------------|
+| **Mage** | Control Weather | Lightning Bolt, Meteor, Freeze Water, Start Fire (enhanced) |
+| **Necromancer** | Start Epidemic | Raise Dead, Fear |
+| **Engineer** | (general) | Repair, Fortify, Build Bridge, Reduce (siege) |
+| **Paladin** | Alms (prioritized) | Holy Wave |
+| **Ranger** | Recon | Scout, Hide (enhanced), Brave Water (enhanced) |
+| **Champion** | (general) | Challenge Duel |
+
+---
+
+## Proposed New Professions
+
+### 1. HERALD (Morale & Communication Specialist)
+
+**Fantasy:** The inspiring leader who rallies troops and carries messages across the battlefield.
+
+**Eagle Ability: "Rally Province"**
+- Spend vigor to boost recruitment in a province for one turn, or reduce unrest
+- Synergy: Pairs well with provinces in turmoil or after losses
+
+**Shardok Ability: "Inspire"**
+- Target friendly unit within 3 hexes gains +1 action point this turn
+- Creates interesting tactical choices about when to act vs. when to buff allies
+- Cannot target self (prevents simple optimization)
+
+---
+
+### 2. ALCHEMIST (Fire & Transformation Specialist)
+
+**Fantasy:** The mad scientist who manipulates the elements through science, not magic.
+
+**Eagle Ability: "Transmute"**
+- Convert one resource type to another in a province (gold to food or vice versa, at a loss)
+- Provides economic flexibility during shortages
+
+**Shardok Ability: "Wildfire"**
+- Start a fire that spreads to 2 additional adjacent hexes immediately (not just at end of round)
+- More aggressive than Mage's Start Fire but less controlled
+- Cannot freeze water (that's magic, not science)
+
+---
+
+### 3. WARDEN (Defensive Specialist)
+
+**Fantasy:** The stalwart defender who holds the line and protects allies.
+
+**Eagle Ability: "Garrison"**
+- A province with a Warden-led unit gets +1 to defense when attacked
+- Encourages strategic placement of defensive heroes
+
+**Shardok Ability: "Intercept"**
+- Once per turn, when an adjacent friendly unit is attacked, the Warden's unit can take the hit instead
+- Creates a "bodyguard" mechanic that protects valuable units
+- Costs action points to maintain readiness
+
+---
+
+### 4. INQUISITOR (Anti-Magic & Intelligence)
+
+**Fantasy:** The witch-hunter who counters supernatural threats and uncovers secrets.
+
+**Eagle Ability: "Expose"**
+- Reveal hidden information about enemy heroes in a province (stats, profession, vigor)
+- Counter to Ranger's stealth/recon advantages
+
+**Shardok Ability: "Dispel"**
+- Cancel an active magical effect: stop a meteor cast, remove Fear from friendly unit, or reveal a hidden unit
+- Direct counter to Mage and Necromancer abilities
+- Creates meaningful profession rock-paper-scissors
+
+---
+
+### 5. BEASTMASTER (Animal Control)
+
+**Fantasy:** The wild one who commands beasts and understands nature's fury.
+
+**Eagle Ability: "Suppress Beasts" (Enhanced)**
+- Already exists in game, but Beastmaster does it at reduced vigor cost
+- Additionally: Can redirect beast attacks to enemy provinces instead of just suppressing
+
+**Shardok Ability: "Beast Call"**
+- Summon a wolf pack (weak undead-style unit) that attacks the nearest enemy
+- Wolves act immediately but disappear at end of round
+- Provides disposable units for screening or harassing archers
+
+---
+
+## Design Philosophy
+
+These professions were designed to:
+
+1. **Fill mechanical gaps**: Warden provides defensive depth, Inquisitor counters magic-heavy strategies
+2. **Create counterplay**: Inquisitor vs Mage/Necromancer, Beastmaster vs Rangers (nature vs nature)
+3. **Avoid overlap**: Each has a unique niche not covered by existing professions
+4. **Support both layers**: Each ability is meaningful in its respective game mode
+5. **Enable interesting decisions**: Intercept creates bodyguard tactics, Inspire creates action economy choices

docs/NOTIFICATION_DIFF_BATCHING.md

@@ -0,0 +1,150 @@
+# Notification Diff Batching Optimization
+
+## Problem
+
+`ActionResultFilter.filterForPlayer` generates per-action-result game state diffs, which is expensive. Profiling shows significant time spent in `filteredGameStateDiff` → `GameStateViewFilter.filteredGameState` (called twice per result) → `GameStateViewDiffer.diff`.
+
+A potential optimization is to batch diffs: instead of computing N diffs for N action results, compute one combined diff representing the final state change. However, this is blocked by how client notification generators work.
+
+## Current Architecture
+
+### Server Side
+1. `ActionResultFilter.filterForPlayer` processes each action result
+2. For each result, computes `filteredGameStateDiff(before, after, factionId)`
+3. Returns `Vector[ActionResultView]` where each view has its own `gameStateDiff`
+
+### Client Side
+1. `EagleGameModel.HandleNewHistoryEntry` processes each `ActionResultView`:
+   ```csharp
+   private void HandleNewHistoryEntry(ActionResultView arv) {
+       _currentModel.HistoryCount++;
+       MaybeSendNotification(arv);        // Uses currentModel state
+       ApplyGameStateViewDiff(arv.GameStateDiff);  // Updates currentModel
+   }
+   ```
+
+2. Notification generators receive `(ActionResultView, IGameModel)` and look up display data from the model:
+   ```csharp
+   var province = currentModel.Provinces[details.ProvinceId];
+   var factionName = currentModel.FactionName(details.FactionId);
+   var hero = currentModel.Heroes[heroId];
+   var affectedProvinces = currentModel.ProvincesForFaction(factionId);
+   ```
+
+### The Problem
+Notification for action N sees model state after actions 1..N-1 have been applied. If we batch diffs, notification N would see model state before ANY actions, potentially showing stale data.
+
+Example:
+1. Action 1: Province X conquered by Faction B (was Faction A)
+2. Action 2: Notification needs to show Province X's current ruler
+
+With batching, action 2's notification would incorrectly show Faction A.
+
+## Audit of Client Notification Generators
+
+~50 generators access `currentModel`. Key lookup patterns:
+
+| Lookup | Count | Mutable? | Risk |
+|--------|-------|----------|------|
+| `currentModel.PlayerId` | 22 | No | Safe |
+| `currentModel.Provinces[id]` | 17 | Yes | `RulingFactionId` changes on conquest |
+| `currentModel.Heroes[id]` | ~20 | Mostly safe | Hero data stable, used for display |
+| `currentModel.FactionName(id)` | ~10 | No | Names don't change |
+| `currentModel.MaybeDestroyedFaction(id)` | ~15 | Yes | Faction may be destroyed |
+| `currentModel.ProvincesForFaction(id)` | ~15 | Yes | Changes on conquest |
+
+### State-Changing Action Types
+- `ProvinceConquered` - changes province ownership
+- `FactionDestroyed` - removes faction
+- `FactionLeaderRemoved` - changes faction head
+
+## Proposed Solution: Server-Side Display Data
+
+Eliminate client model lookups by including all display data in server-generated notifications.
+
+### Current Notification Structure
+```scala
+case class NotificationC(
+    details: NotificationDetails,
+    targetFactionIds: Vector[FactionId],
+    affectedProvinceIds: Vector[ProvinceId],  // Already exists, underused
+    affectedHeroIds: Vector[HeroId],          // Already exists, underused
+    llm: NotificationT.Llm,
+    deferred: Boolean
+)
+```
+
+### Proposed Changes
+
+**Option A: Add fields to NotificationC**
+```scala
+case class NotificationC(
+    details: NotificationDetails,
+    targetFactionIds: Vector[FactionId],
+    affectedProvinceIds: Vector[ProvinceId],
+    affectedHeroIds: Vector[HeroId],
+    // New fields:
+    factionNames: Map[FactionId, String],
+    displayedHeroViews: Vector[HeroView],
+    provinceNames: Map[ProvinceId, String],
+    llm: NotificationT.Llm,
+    deferred: Boolean
+)
+```
+
+**Option B: Enrich each NotificationDetails type**
+```scala
+case class TruceAccepted(
+    offeringFactionId: FactionId,
+    offeringFactionName: String,      // New
+    targetFactionId: FactionId,
+    targetFactionName: String,        // New
+    ambassadorHeroId: HeroId,
+    ambassadorHeroView: HeroView      // New
+)
+```
+
+### Implementation Steps
+
+1. **Proto changes**: Add new fields to `Notification` message
+2. **Server**: Populate display fields when creating notifications
+3. **Client**: Update ~50 generators to use notification fields
+4. **Test**: Add test that greps for `currentModel.` access in generators (excluding `PlayerId`)
+5. **Server optimization**: With client decoupled from model state, batch diffs in `filterForPlayer`
+
+### Trade-offs
+
+**Pros:**
+- Clean separation: server provides all display data
+- Enables diff batching optimization
+- Easier to reason about notification correctness
+- Test can enforce the invariant
+
+**Cons:**
+- Larger notification messages (includes names, hero views)
+- Proto changes required
+- ~50 generators need updating (mechanical but tedious)
+- Server must know what display data each notification type needs
+
+## Alternative Approaches Considered
+
+### A: Selective Per-Action Diffs
+Only generate individual diffs for action results with notifications that need mutable model state. Requires tracking which notification types need which state.
+
+**Rejected because:** Fragile; easy to add a new generator that breaks the invariant.
+
+### B: State-Change-Triggered Diffs
+If batch contains state-changing action types (ProvinceConquered, etc.), generate individual diffs from that point. Otherwise batch.
+
+**Rejected because:** Still conservative; many batches would fall back to individual diffs.
+
+## Status
+
+**Deferred** - Current performance is acceptable. This doc captures the analysis for future reference if optimization becomes necessary.
+
+## References
+
+- `ActionResultFilter.scala` - Server-side filtering
+- `EagleGameModel.cs` - Client-side model updates
+- `Assets/Eagle/Notifications/` - All notification generators
+- `NotificationT.scala` - Server notification types

docs/OAUTH_GO_SERVICE_PLAN.md

@@ -1,383 +0,0 @@
-# Plan: Extract OAuth to Go Service
-
-## Goal
-Move OAuth authentication handling from the Eagle Scala server into a separate Go service. This simplifies Eagle (gRPC-only, no HTTP), reduces complexity, and sets up for potentially moving JWT validation outside Eagle too.
-
-## Architecture Decision: Sidecar Service (Not DO Functions)
-
-**Recommendation: Go sidecar service on the same droplet, in a separate container**
-
-**Why not DO Functions:**
-- OAuth requires **stateful sessions** (pendingOAuth/completedOAuth maps with 10-min TTL)
-- Client polling pattern (every 2 seconds) would incur high function invocation costs
-- Cold start latency problematic for auth flows
-- State would require external store (Redis), adding complexity
-
-**Why sidecar (separate container):**
-- Simple process on same droplet, minimal network latency
-- In-memory state management (like current Scala impl)
-- Easy to monitor/debug alongside Eagle
-- Can share filesystem for key files (RSA keys) via volume mounts
-- **Independent deployment**: Deploying Eagle doesn't restart auth service (and vice versa)
-- **Independent scaling**: Could move to separate droplet later if needed
-
-## Current Architecture (What Exists)
-
-```
-Unity Client
-    ├── GetOAuthUrl RPC → Eagle AuthServiceImpl → OAuthService.getAuthUrl()
-    ├── [User browser auth] → HTTP callback → OAuthHttpHandler → OAuthService.handleCallback()
-    ├── CheckOAuthStatus RPC (polling) → AuthServiceImpl → OAuthService.checkStatus()
-    └── All other RPCs include JWT → AuthorizationInterceptor validates
-```
-
-**Key files:**
-- `src/main/scala/net/eagle0/eagle/auth/OAuthService.scala` - OAuth flow, state management
-- `src/main/scala/net/eagle0/eagle/auth/JwtService.scala` - JWT creation/validation
-- `src/main/scala/net/eagle0/eagle/auth/UserService.scala` - User CRUD (persisted)
-- `src/main/scala/net/eagle0/eagle/service/AuthServiceImpl.scala` - gRPC Auth service
-- `src/main/scala/net/eagle0/eagle/service/OAuthHttpHandler.scala` - HTTP callback handler
-
-## Target Architecture (Phase 1)
-
-```
-Unity Client
-    ├── GetOAuthUrl RPC ──────────────┐
-    ├── CheckOAuthStatus RPC (polling)├──→ Eagle (port 40032) ──proxy──→ Go Auth Container (port 40033)
-    ├── RefreshToken RPC ─────────────┘                                        │
-    ├── [User browser] → HTTP callback ────────────────────────────────────────┤
-    │                                                                          ↓
-    │                                            (Internal gRPC: GetOrCreateUser, GetUser)
-    │                                                                          ↓
-    └── Game RPCs with JWT ─────────────────────→ Eagle (port 40032) ← JWT validation stays here
-
-[Same Droplet]
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                                                                             │
-│  ┌──────────────────────┐          ┌────────────────────────────────────┐  │
-│  │  Go Auth Container   │◄────────►│       Eagle Container              │  │
-│  │  (eagle0-auth)       │ internal │       (eagle0-server)              │  │
-│  │                      │  gRPC    │                                    │  │
-│  │  - OAuth flow        │          │  - JWT validation                  │  │
-│  │  - JWT creation      │          │  - UserService (persistence)       │  │
-│  │  - HTTP callback     │          │  - Game logic                      │  │
-│  └──────────────────────┘          └────────────────────────────────────┘  │
-│           │                                        │                        │
-│           └────────────────┬───────────────────────┘                        │
-│                            ▼                                                │
-│                    /etc/eagle0/keys/ (shared volume)                        │
-│                    - private.pem                                            │
-│                    - public.pem                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-## Component Responsibilities
-
-### Go Auth Service (NEW - separate container)
-- **OAuth flow**: getAuthUrl, handleCallback (HTTP), checkStatus
-- **State management**: pendingOAuth, completedOAuth maps with TTL
-- **JWT creation**: Issue access/refresh tokens (shares RSA private key with Eagle)
-- **Token refresh**: Validate refresh token, issue new access token
-- Calls Eagle's internal UserService gRPC to find/create users
-
-### Eagle Server (SIMPLIFIED)
-- **JWT validation**: AuthorizationInterceptor stays (validates tokens on game RPCs)
-- **UserService**: Stays in Eagle (user persistence, display name logic)
-- **New internal gRPC**: Expose GetOrCreateUser, GetUser for Go service to call
-- **Proxy (Phase 1)**: Forward OAuth RPCs to Go service
-- **Remove (Phase 2)**: OAuthService, OAuthHttpHandler, HTTP server setup
-
-### Unity Client (NO CHANGES in Phase 1)
-- Eagle proxies Auth RPCs to Go service
-- Client still connects to Eagle on port 40032
-
-## Implementation Phases
-
-### Phase 1: Go Auth Service with Eagle Proxy (Zero Client Changes)
-
-1. **Create Go service structure**
-   ```
-   src/main/go/net/eagle0/authservice/
-   ├── main.go           # Entry point, starts gRPC + HTTP servers
-   ├── oauth.go          # OAuth state management, provider configs
-   ├── jwt.go            # JWT creation (copy logic from Scala)
-   ├── handlers.go       # gRPC handlers for Auth service
-   ├── http_callback.go  # HTTP handler for OAuth callback
-   └── BUILD.bazel
-   ```
-
-2. **Internal gRPC proto for Eagle UserService**
-   ```protobuf
-   // src/main/protobuf/net/eagle0/eagle/internal/auth_internal.proto
-
-   service InternalUserService {
-     rpc GetOrCreateUser(GetOrCreateUserRequest) returns (GetOrCreateUserResponse);
-     rpc GetUser(GetUserRequest) returns (GetUserResponse);
-   }
-
-   message GetOrCreateUserRequest {
-     string provider = 1;        // "discord" or "google"
-     string provider_user_id = 2;
-     string email = 3;
-     string avatar_url = 4;
-   }
-
-   message GetOrCreateUserResponse {
-     string user_id = 1;
-     string display_name = 2;
-     string avatar_url = 3;
-     bool is_admin = 4;
-     bool is_new_user = 5;
-   }
-   ```
-
-3. **Eagle: Expose InternalUserService**
-   - New `InternalUserServiceImpl.scala` wrapping UserService
-   - Bind to same port, different service name (internal only)
-
-4. **Eagle: Proxy Auth RPCs to Go**
-   - AuthServiceImpl delegates GetOAuthUrl, CheckOAuthStatus, RefreshToken to Go service
-   - SetDisplayName, GetCurrentUser, Logout stay in Eagle
-
-5. **Share RSA keys via volume mount**
-   - Go service reads same key files as Eagle
-   - Both can create valid JWTs
-   - Eagle continues to validate JWTs
-
-6. **Docker/Container setup**
-   - New Dockerfile for Go auth service
-   - docker-compose or Kubernetes config for both containers
-   - Shared volume for /etc/eagle0/keys/
-   - Internal network for container-to-container gRPC
-
-### Phase 2: Client Direct to Go Service (Future)
-
-1. **Update Unity client**
-   - Connect to Go Auth service directly for OAuth RPCs
-   - Keep connecting to Eagle for game RPCs
-
-2. **Remove Eagle proxy code**
-   - Delete AuthServiceImpl OAuth delegation
-   - AuthServiceImpl only handles SetDisplayName, GetCurrentUser, Logout
-
-### Phase 3: Move JWT Validation to Go (Optional Future)
-
-1. **Go service validates JWTs**
-   - Add ValidateToken RPC or use shared middleware pattern
-
-2. **Eagle calls Go for validation**
-   - AuthorizationInterceptor calls Go to validate tokens
-   - OR: Use stateless validation (both share public key)
-
-## Files to Create
-
-### Go Service
-- `src/main/go/net/eagle0/authservice/main.go`
-- `src/main/go/net/eagle0/authservice/oauth.go`
-- `src/main/go/net/eagle0/authservice/jwt.go`
-- `src/main/go/net/eagle0/authservice/handlers.go`
-- `src/main/go/net/eagle0/authservice/http_callback.go`
-- `src/main/go/net/eagle0/authservice/BUILD.bazel`
-
-### Protos
-- `src/main/protobuf/net/eagle0/eagle/internal/auth_internal.proto`
-
-### Scala
-- `src/main/scala/net/eagle0/eagle/service/InternalUserServiceImpl.scala`
-
-### Docker/Deployment
-- `ci/auth_service.Dockerfile`
-- Update `docker-compose.yml` (or equivalent)
-
-## Files to Modify
-
-### Scala (Phase 1)
-- `src/main/scala/net/eagle0/eagle/service/AuthServiceImpl.scala` - Proxy OAuth RPCs to Go
-- `src/main/scala/net/eagle0/eagle/Main.scala` - Start internal user service, add auth-service-url flag
-
-### Scala (Phase 2 - Removal)
-- Delete `src/main/scala/net/eagle0/eagle/auth/OAuthService.scala`
-- Delete `src/main/scala/net/eagle0/eagle/service/OAuthHttpHandler.scala`
-- Simplify `src/main/scala/net/eagle0/eagle/Main.scala` - Remove HTTP server
-
-### Unity (Phase 2)
-- `Assets/Auth/OAuthManager.cs` - Point OAuth RPCs to Go service port
-- `Assets/EagleConnection.cs` - Add second channel for auth service
-
-## Key Implementation Details
-
-### State Management in Go
-```go
-type OAuthState struct {
-    Provider  string
-    CreatedAt time.Time
-}
-
-type OAuthResult struct {
-    Success  bool
-    UserInfo *ProviderUserInfo
-    Provider string
-    Error    string
-}
-
-var pendingOAuth   = sync.Map{} // state -> OAuthState
-var completedOAuth = sync.Map{} // state -> OAuthResult
-
-const stateExpiration = 10 * time.Minute
-
-// Background goroutine cleans expired states every minute
-func cleanupExpiredStates() {
-    ticker := time.NewTicker(1 * time.Minute)
-    for range ticker.C {
-        cutoff := time.Now().Add(-stateExpiration)
-        pendingOAuth.Range(func(key, value any) bool {
-            if value.(OAuthState).CreatedAt.Before(cutoff) {
-                pendingOAuth.Delete(key)
-            }
-            return true
-        })
-        // Similar for completedOAuth
-    }
-}
-```
-
-### JWT Creation in Go
-```go
-import "github.com/golang-jwt/jwt/v5"
-
-type EagleClaims struct {
-    jwt.RegisteredClaims
-    UserId      string `json:"userId"`
-    DisplayName string `json:"displayName"`
-    IsAdmin     bool   `json:"isAdmin"`
-}
-
-func CreateAccessToken(userId, displayName string, isAdmin bool) (string, error) {
-    claims := EagleClaims{
-        RegisteredClaims: jwt.RegisteredClaims{
-            ExpiresAt: jwt.NewNumericDate(time.Now().Add(7 * 24 * time.Hour)),
-            IssuedAt:  jwt.NewNumericDate(time.Now()),
-        },
-        UserId:      userId,
-        DisplayName: displayName,
-        IsAdmin:     isAdmin,
-    }
-
-    token := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
-    return token.SignedString(privateKey)
-}
-```
-
-### OAuth Provider Configs
-- Read from environment variables (same as current OAuthConfig.scala)
-- DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET
-- GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
-- OAUTH_CALLBACK_URL (e.g., https://eagle0.shardok.games/oauth/callback)
-
-### Container Networking
-```yaml
-# docker-compose.yml example
-services:
-  eagle0-auth:
-    build:
-      context: .
-      dockerfile: ci/auth_service.Dockerfile
-    ports:
-      - "40033:40033"  # gRPC
-      - "8080:8080"    # HTTP callback
-    volumes:
-      - ./keys:/etc/eagle0/keys:ro
-    environment:
-      - DISCORD_CLIENT_ID
-      - DISCORD_CLIENT_SECRET
-      - GOOGLE_CLIENT_ID
-      - GOOGLE_CLIENT_SECRET
-      - EAGLE_INTERNAL_URL=eagle0-server:40034
-
-  eagle0-server:
-    build:
-      context: .
-      dockerfile: ci/eagle_run.Dockerfile
-    ports:
-      - "40032:40032"  # Public gRPC
-    expose:
-      - "40034"        # Internal gRPC (container-to-container only)
-    volumes:
-      - ./keys:/etc/eagle0/keys:ro
-      - ./data:/var/lib/eagle0
-    environment:
-      - AUTH_SERVICE_URL=eagle0-auth:40033
-```
-
-## Deployment
-
-### Development
-```bash
-# Terminal 1: Go Auth Service
-bazel run //src/main/go/net/eagle0/authservice:authservice -- \
-  --grpc-port=40033 \
-  --http-port=8080 \
-  --eagle-internal-url=localhost:40034
-
-# Terminal 2: Eagle Server
-bazel run //src/main/scala/net/eagle0/eagle:eagle_server -- \
-  --eagle-grpc-port=40032 \
-  --internal-grpc-port=40034 \
-  --auth-service-url=localhost:40033
-```
-
-### Production
-- Both containers on same droplet via docker-compose
-- Shared volume for RSA keys at /etc/eagle0/keys/
-- Internal Docker network for container-to-container communication
-- External access: 40032 (Eagle gRPC), 8080 (OAuth HTTP callback)
-
-## Testing Strategy
-
-1. **Unit tests for Go service**
-   - OAuth state management (expiration, cleanup)
-   - JWT creation matches Scala output (test with same keys)
-   - HTTP callback parsing
-
-2. **Integration tests**
-   - Go service ↔ Eagle internal gRPC
-   - Full OAuth flow with mock provider
-
-3. **Existing tests continue to pass**
-   - All Scala tests (JWT validation, user service)
-
-4. **End-to-end test**
-   - Spin up both containers
-   - Run OAuth flow through proxy
-
-## Risks and Mitigations
-
-| Risk | Mitigation |
-|------|------------|
-| Key file permissions | Shared volume with read-only mount |
-| State loss on Go restart | Document this (same as current Scala behavior); consider Redis later |
-| Clock skew affecting JWT | Both on same machine |
-| OAuth callback race | HTTP callback completes before gRPC poll |
-| Container networking | Use docker-compose for reliable internal DNS |
-| Proxy adds latency | Minimal (same machine), remove in Phase 2 |
-
-## Estimated Scope
-
-- **Phase 1**: ~500-700 lines Go, ~100 lines Scala changes, ~50 lines Docker config
-- **Phase 2**: ~50 lines Unity, deletion of ~300 lines Scala
-- **Phase 3**: Optional, separate decision
-
-## Alternative Considered: Move Everything to Go
-
-Could move UserService to Go as well, but:
-- UserService is tightly integrated with game persistence
-- Would require duplicating persistence layer
-- Not worth the complexity for now
-
-Keep UserService in Eagle, expose via internal gRPC.
-
-## Open Questions
-
-1. **HTTP callback routing**: Does the OAuth callback URL need to change, or can we route traffic from the existing URL to the new Go service?
-2. **Health checks**: Should we add health check endpoints for container orchestration?
-3. **Logging**: Should Go service log to same format/destination as Eagle?

docs/OAUTH_IMPLEMENTATION_PLAN.md

@@ -1,189 +0,0 @@
-# Discord + Google OAuth Implementation Plan
-
-## Overview
-
-Replace HTTP Basic Auth with OAuth 2.0 (Discord + Google) for Eagle0. Users authenticate via system browser, receive JWT tokens, and choose their own display names.
-
-## Architecture
-
-```
-Unity Client                                          Eagle Server
-     |                                                      |
-     |  1. Click "Login with Discord/Google"                |
-     |  ------------------------------------------------->  |
-     |     GetOAuthUrl(provider) -> auth_url + state        |
-     |                                                      |
-     |  2. Open system browser -> OAuth consent             |
-     |  3. User authenticates with provider                 |
-     |  4. Redirect to eagle0://auth/callback?code=xxx      |
-     |                                                      |
-     |  5. ExchangeCode(code, state)                        |
-     |  ------------------------------------------------->  |
-     |     Exchange code with provider                      |
-     |     Fetch user info (id, email, avatar)              |
-     |     Create/update user record                        |
-     |     Issue JWT + refresh token                        |
-     |  <-------------------------------------------------  |
-     |     (jwt, refresh_token, user_info, is_new_user)     |
-     |                                                      |
-     |  6. [If new user] SetDisplayName(name)               |
-     |  ------------------------------------------------->  |
-     |                                                      |
-     |  7. Subsequent gRPC calls                            |
-     |     Authorization: Bearer <jwt>                      |
-     |  ------------------------------------------------->  |
-```
-
-## Key Design Decisions
-
-| Decision | Choice | Rationale |
-|----------|--------|-----------|
-| OAuth flow | System browser + deep link | Secure, supports password managers |
-| Code exchange | Eagle server directly | No separate auth service needed |
-| JWT signing | RS256 (asymmetric) | Future flexibility for token verification |
-| User storage | Protobuf file via Persister | Consistent with existing patterns |
-| Token expiry | 7-day access, 30-day refresh | Balance security and gaming UX |
-
-## Implementation Phases
-
-### Phase 1: Proto Definitions & Infrastructure
-
-**New files:**
-- `src/main/protobuf/net/eagle0/eagle/api/auth.proto` - Auth API messages
-- `src/main/protobuf/net/eagle0/eagle/internal/user.proto` - User storage schema
-
-**Key proto messages:**
-```protobuf
-// API
-GetOAuthUrlRequest/Response     // Get OAuth URL to open in browser
-ExchangeCodeRequest/Response    // Exchange auth code for JWT
-SetDisplayNameRequest/Response  // Set user's display name
-RefreshTokenRequest/Response    // Refresh expired access token
-
-// Internal storage
-User                           // user_id, display_name, oauth_identities
-UserDatabase                   // All users + indexes for lookup
-```
-
-### Phase 2: Eagle Server Auth Services
-
-**New Scala files:**
-- `src/main/scala/net/eagle0/eagle/auth/OAuthConfig.scala` - Discord/Google config from env vars
-- `src/main/scala/net/eagle0/eagle/auth/JwtService.scala` - JWT creation/validation (RS256)
-- `src/main/scala/net/eagle0/eagle/auth/UserService.scala` - User CRUD, display name validation
-- `src/main/scala/net/eagle0/eagle/auth/OAuthService.scala` - OAuth code exchange
-- `src/main/scala/net/eagle0/eagle/service/AuthServiceImpl.scala` - gRPC service implementation
-
-**Modify:**
-- `src/main/scala/net/eagle0/eagle/service/AuthorizationInterceptor.scala`
-  - Replace Basic Auth parsing with JWT validation
-  - Skip auth for public endpoints (GetOAuthUrl, ExchangeCode, RefreshToken)
-- `src/main/scala/net/eagle0/eagle/service/AuthorizationUtils.scala`
-  - Change context keys from `userName` to `userId` + `displayName`
-- `src/main/scala/net/eagle0/eagle/service/Main.scala`
-  - Wire up new auth services and JWT key loading
-
-### Phase 3: Unity Client OAuth Flow
-
-**New C# files:**
-- `Assets/Auth/OAuthManager.cs` - OAuth flow + deep link handling
-- `Assets/Auth/TokenStorage.cs` - Secure token persistence
-- `Assets/Auth/AuthClient.cs` - gRPC client for auth service
-
-**Modify:**
-- `Assets/EagleConnection.cs`
-  - Replace `AuthInterceptor` (Basic Auth) with `JwtAuthInterceptor` (Bearer token)
-- `Assets/ConnectionHandler/ConnectionHandler.cs`
-  - Replace username/password UI with Discord/Google login buttons
-  - Add display name setup flow for new users
-
-### Phase 4: Platform Configuration
-
-**Deep link registration:**
-- iOS: Add `eagle0://` to CFBundleURLSchemes in Info.plist
-- Android: Add intent-filter for `eagle0://auth` in AndroidManifest.xml
-- Desktop: Register URL scheme (Windows registry / macOS plist)
-
-**OAuth provider setup:**
-1. Discord Developer Portal: Create app, add redirect URI `eagle0://auth/callback`
-2. Google Cloud Console: Create OAuth client, add redirect URI
-
-**Environment variables (server):**
-```
-DISCORD_CLIENT_ID
-DISCORD_CLIENT_SECRET
-GOOGLE_CLIENT_ID
-GOOGLE_CLIENT_SECRET
-JWT_PRIVATE_KEY_PATH
-JWT_PUBLIC_KEY_PATH
-```
-
-### Phase 5: Testing
-
-**Unit tests:**
-- `JwtServiceSpec.scala` - Token creation/validation
-- `UserServiceSpec.scala` - Display name validation, uniqueness
-- `OAuthServiceSpec.scala` - OAuth flow with mocked providers
-
-**Integration tests:**
-- Full OAuth flow with mock provider
-- JWT validation in AuthorizationInterceptor
-- gRPC calls with valid/invalid tokens
-
-**Manual testing:**
-- [ ] Discord login (Windows, macOS)
-- [ ] Google login (Windows, macOS)
-- [ ] Deep link callback works
-- [ ] Display name validation
-- [ ] Session persistence across restarts
-- [ ] Token refresh
-
-## Files Summary
-
-### Create
-| File | Purpose |
-|------|---------|
-| `src/main/protobuf/net/eagle0/eagle/api/auth.proto` | Auth API definitions |
-| `src/main/protobuf/net/eagle0/eagle/internal/user.proto` | User storage schema |
-| `src/main/scala/net/eagle0/eagle/auth/OAuthConfig.scala` | Provider config |
-| `src/main/scala/net/eagle0/eagle/auth/JwtService.scala` | JWT handling |
-| `src/main/scala/net/eagle0/eagle/auth/UserService.scala` | User management |
-| `src/main/scala/net/eagle0/eagle/auth/OAuthService.scala` | OAuth flow |
-| `src/main/scala/net/eagle0/eagle/service/AuthServiceImpl.scala` | gRPC service |
-| `Assets/Auth/OAuthManager.cs` | Unity OAuth manager |
-| `Assets/Auth/TokenStorage.cs` | Token storage |
-| `Assets/Auth/AuthClient.cs` | Auth gRPC client |
-
-### Modify
-| File | Changes |
-|------|---------|
-| `AuthorizationInterceptor.scala` | Basic Auth -> JWT validation |
-| `AuthorizationUtils.scala` | userName -> userId + displayName |
-| `Main.scala` | Wire auth services |
-| `EagleConnection.cs` | AuthInterceptor -> JwtAuthInterceptor |
-| `ConnectionHandler.cs` | Login UI -> OAuth buttons + display name |
-
-### Delete
-- nginx htpasswd configuration (no longer needed)
-
-## Security Considerations
-
-1. **State parameter** - CSRF protection in OAuth flow
-2. **PKCE** - Consider adding for mobile (enhancement)
-3. **Secure storage** - Use Keychain (iOS) / Keystore (Android) for tokens
-4. **Token refresh** - 7-day access tokens with 30-day refresh
-5. **Rate limiting** - Limit login attempts per IP
-
-## Dependencies to Add
-
-**Scala (MODULE.bazel):**
-- JWT library (e.g., `jwt-scala` or `nimbus-jose-jwt`)
-- HTTP client (e.g., `sttp` for OAuth requests)
-
-**Unity:**
-- Deep linking is built-in (Unity 2021+)
-- No additional packages required
-
-## Rollback Plan
-
-Keep Basic Auth code in a feature branch. Both auth methods can coexist during transition via feature flag if needed.

docs/OAUTH_NEXT_STEPS.md

@@ -1,350 +0,0 @@
-# OAuth Implementation: Next Steps and Design
-
-## Executive Summary
-
-The OAuth implementation is functional but has several gaps that need addressing before it's production-ready. This document outlines the known issues, proposes a comprehensive user identity model, and provides a prioritized implementation plan.
-
-## Current State (Updated January 2026)
-
-### What Works ✅
-- Discord OAuth flow (server-mediated polling)
-- Google OAuth flow
-- JWT token generation and validation
-- User creation and display name setting
-- Auto-login with stored tokens
-- Basic game creation and play with OAuth users
-- Headshot fetching via public CDN (no auth required)
-- Logout button in lobby (preserves tokens for quick reconnect)
-- Environment (prod/qa) and user display in lobby
-- Game identity with userName = displayName (PR #4964 merged)
-
-### Known Issues
-
-#### 1. Game Identity Model Fragility (Deferred)
-**Status**: Accepted for now. PR #4964 merged with `userName = displayName`.
-
-**Current behavior**:
-- Games store `userNameToFactionId: Map[String, Int]`
-- For JWT users, this maps displayName → factionId
-- displayName is technically mutable (users could change it)
-- No migration path when displayName changes
-
-**Why this is acceptable**:
-1. We don't currently have a "change display name" feature
-2. The alternative (using userId) requires more extensive changes
-3. Can migrate to userId-based identity later if needed
-
-#### 2. In-Game Headshot Fetching ✅ FIXED
-**Solution**: Made the `eagle0-headshots` S3 bucket public and enabled CDN.
-- Client now fetches directly from `https://eagle0-headshots.sfo3.cdn.digitaloceanspaces.com/`
-- No authentication required
-- Works for both OAuth and Basic Auth users
-- Simpler architecture, no dependency on home Mac server
-
-#### 3. Logout from Lobby ✅ FIXED
-**Solution**: Added logout button to lobby UI (PR #4967).
-- Button disconnects from server and returns to connection screen
-- Intentionally does NOT clear OAuth tokens
-- Allows quick reconnect with same account without full OAuth flow
-
-#### 4. Display Name Uniqueness Not Enforced (Medium) - OPEN
-**Problem**: User was able to set displayName "nolen" when that name was already taken.
-
-**Root cause**: Unknown - needs investigation. Either:
-- The uniqueness check is buggy
-- The displayNameIndex wasn't populated correctly during user creation
-- Race condition during concurrent registrations
-
-#### 5. Admin Server Crashes ✅ FIXED
-**Solution**: PR #4964 sets `userName = displayName` for JWT users.
-
-#### 6. Intermittent "Expired" Errors During Login (Medium) - INVESTIGATING
-**Problem**: Users occasionally get "OAuth session expired" errors even when server logs show the callback succeeded.
-
-**Status**: Added diagnostic logging in PR #4974 to trace:
-- State creation in `getAuthUrl`
-- State lookup in `handleCallback`
-- Result lookup in `checkStatus`
-
-**Possible causes**:
-- State mismatch between client and server
-- Race condition in polling
-- Cleanup running at wrong time
-
-#### 7. Token Expiry Field Bug ✅ FIXED
-**Problem**: `CheckOAuthStatusResponse.expiresAt` was returning refresh token expiry (30 days) instead of access token expiry (7 days).
-
-**Solution**: Fixed in PR #4974 to calculate correct access token expiry.
-
----
-
-## Proposed User Identity Model
-
-### Design Principles
-
-1. **Stable Internal Identity**: `userId` (UUID) is the only key used for persistent associations
-2. **Display Name is Cosmetic**: Can change without breaking game associations
-3. **Backwards Compatibility**: Basic Auth continues to work for local development
-4. **Multi-Provider Support**: Users can link Discord, Google, and future providers
-5. **Avatar Flexibility**: Use OAuth avatar by default, support custom uploads later
-
-### Data Model
-
-```
-User {
-  userId: String (UUID)           // Primary key, immutable, used for all internal references
-  displayName: String             // Unique, user-visible, mutable with migration
-  displayNameLower: String        // Case-insensitive uniqueness
-  email: String                   // Primary email for account recovery/linking
-  avatarUrl: String               // Current avatar URL
-  avatarData: bytes               // Cached avatar for offline/fast access (future)
-  oauthIdentities: [OAuthIdentity]
-  createdAt: Timestamp
-  lastLoginAt: Timestamp
-  isAdmin: Boolean
-}
-
-OAuthIdentity {
-  provider: String                // "discord", "google", etc.
-  providerUserId: String          // Provider's user ID
-  providerEmail: String           // Email from this provider
-  avatarUrl: String               // Avatar from this provider
-  linkedAt: Timestamp
-}
-```
-
-### Identity Resolution Strategy
-
-The key question: **What should `AuthorizationUtils.userName` return?**
-
-#### Option A: userName = displayName (Current PR #4964)
-- **Pro**: Human-readable in logs, game saves, debugging
-- **Con**: Breaks if displayName changes
-- **Migration**: None needed now, complex later
-
-#### Option B: userName = userId (Recommended)
-- **Pro**: Stable identity, displayName changes are safe
-- **Con**: UUIDs in logs are ugly, need display name lookup for UI
-- **Migration**: Cleaner long-term, but breaking change for any existing OAuth games
-
-#### Option C: Hybrid with Migration Support
-- **userName** = userId for new games
-- **Legacy lookup** for old games by displayName
-- **Display layer** resolves userId → displayName for UI
-
-**Recommendation**: Option B with a display name resolution layer. The ugliness in logs is acceptable for the stability it provides. Implement a `UserService.resolveDisplayName(identifier: String): String` that returns displayName for UUIDs or the identifier itself for legacy usernames.
-
-### Account Linking Strategy
-
-#### Automatic Linking (Future)
-When a user logs in with a new OAuth provider:
-1. Check if the provider email matches an existing user's email
-2. If match found, prompt: "An account exists with this email. Link accounts?"
-3. If confirmed, add new OAuthIdentity to existing user
-4. If declined, create separate account (different email required)
-
-#### Manual Linking (MVP)
-1. User logs in with primary account
-2. User goes to Settings → Linked Accounts
-3. User clicks "Link Discord" or "Link Google"
-4. OAuth flow adds new identity to current user
-
-### Avatar/Headshot Strategy
-
-#### Phase 1: OAuth Avatars (MVP)
-- Store `avatarUrl` from OAuth provider during login
-- Server proxies avatar requests to avoid CORS issues
-- Cache avatars locally with TTL
-
-#### Phase 2: Avatar Caching
-- Download avatar to local storage on login
-- Serve from local storage for reliability
-- Refresh periodically or on login
-
-#### Phase 3: Custom Avatars (Future)
-- Allow users to upload custom avatar
-- Store in S3/DO Spaces
-- Custom avatar overrides OAuth avatar
-
----
-
-## Implementation Plan
-
-### Phase 1: Stabilization ✅ COMPLETE
-
-#### 1.1 Fix Display Name Uniqueness Bug - OPEN
-- [ ] Investigate why "nolen" was allowed when it existed
-- [ ] Add logging to `setDisplayName` to trace the issue
-- [ ] Ensure `displayNameIndex` is correctly maintained
-- [ ] Add unit tests for uniqueness enforcement
-
-#### 1.2 Add Logout Button to Lobby ✅ DONE
-- [x] Add "Logout" button to lobby UI
-- [x] Disconnect from server
-- [x] Navigate to connection screen
-- [x] Preserve OAuth tokens for quick reconnect (intentional change from original plan)
-
-#### 1.3 Merge PR #4964 (userName = displayName) ✅ DONE
-- [x] Merged - games work with OAuth users
-- [x] Documented limitation (games break if displayName changes)
-
-#### 1.4 Fix Headshot Fetching ✅ DONE
-- [x] Made eagle0-headshots bucket public
-- [x] Client fetches directly from CDN
-- [x] No authentication required
-
-#### 1.5 Add Lobby Status Display ✅ DONE
-- [x] Show environment (prod/qa) in lobby
-- [x] Show current user in lobby (OAuth displayName or classic username)
-
-### Phase 2: Remaining Work (Priority Order)
-
-#### 2.1 Diagnose Intermittent "Expired" Errors - IN PROGRESS
-- [x] Add diagnostic logging (PR #4974)
-- [ ] Deploy and reproduce the issue
-- [ ] Analyze logs to identify root cause
-- [ ] Implement fix based on findings
-
-#### 2.2 Fix Display Name Uniqueness
-- [ ] Investigate UserService.setDisplayName logic
-- [ ] Check displayNameIndex population
-- [ ] Add logging to trace the issue
-- [ ] Fix the bug and add tests
-
-#### 2.3 Wire Up Lobby UI in Unity
-- [ ] Connect `lobbyEnvironmentText` to TextMeshProUGUI in scene
-- [ ] Connect `lobbyUserText` to TextMeshProUGUI in scene
-
-#### 2.4 Implement Token Refresh During Gameplay
-- [ ] Implement `RefreshToken` RPC on server (currently throws UNIMPLEMENTED)
-- [ ] Store refresh tokens server-side for validation
-- [ ] Add proactive refresh in client before token expires
-- [ ] Handle refresh during reconnection attempts
-
-### Phase 3: Nice-to-Haves (Future)
-
-#### 3.1 Proactive Token Refresh
-- [ ] Monitor token expiry in client
-- [ ] Refresh automatically when < 5 minutes remaining
-- [ ] Update TokenStorage with new access token
-
-#### 3.2 Better Error Messages
-- [ ] Distinguish between network errors and auth errors
-- [ ] Show user-friendly messages for OAuth failures
-- [ ] Add retry suggestions
-
-#### 3.3 Session Persistence Across Server Restarts
-- [ ] Move pendingOAuth from in-memory TrieMap to Redis/database
-- [ ] Move completedOAuth to Redis with TTL
-- [ ] Server can restart without breaking in-flight OAuth flows
-
-#### 3.4 Migrate to userId-based Game Identity (Deferred)
-- [ ] Change `AuthorizationUtils.userName` to return `userId` for JWT users
-- [ ] Add `UserService.resolveDisplayName(id: String): String` for UI display
-- [ ] Update game UI to resolve userIds to displayNames
-- [ ] Existing Basic Auth games continue to work (userName is literal)
-
-#### 3.5 Display Name Change Support (Requires 3.4)
-- [ ] Add `ChangeDisplayName` RPC
-- [ ] Validate new name is unique
-- [ ] Update user record
-- [ ] No game migration needed (games use userId)
-
-### Phase 3: Multi-Provider Support (Future)
-
-#### 3.1 Account Linking UI
-- [ ] Add Settings page with "Linked Accounts" section
-- [ ] Show currently linked providers
-- [ ] "Link Another Account" button triggers OAuth flow
-- [ ] `LinkOAuthProvider` RPC adds identity to current user
-
-#### 3.2 Login Provider Selection
-- [ ] If user has multiple providers, any can be used to login
-- [ ] All resolve to same userId
-- [ ] Session shows which provider was used
-
-#### 3.3 Account Merging (Complex)
-- [ ] Handle case where user created separate accounts
-- [ ] Merge game history, stats, etc.
-- [ ] Delete duplicate user record
-- [ ] This is complex - may defer or not implement
-
-### Phase 4: Enhanced Avatars (Future)
-
-#### 4.1 Avatar Caching
-- [ ] Download avatars to S3/DO Spaces on login
-- [ ] Serve from our CDN
-- [ ] Refresh on login if changed
-
-#### 4.2 Custom Avatar Upload
-- [ ] Upload endpoint with size/format validation
-- [ ] Store in S3/DO Spaces
-- [ ] Custom avatar overrides OAuth avatar
-
----
-
-## Technical Debt to Address
-
-1. **Context Propagation in Futures**: PR #4960 fixed `setDisplayName` and `getCurrentUser`, but audit all `Future` blocks that access `AuthorizationUtils`
-
-2. **Dual Auth Support**: The system supports both Basic Auth and JWT. Consider:
-   - Should Basic Auth be deprecated for production?
-   - Should it remain for local development only?
-   - How do Basic Auth users interact with OAuth users in the same game?
-
-3. **Token Refresh**: `RefreshToken` RPC throws UNIMPLEMENTED. Need to:
-   - Implement refresh token storage and validation
-   - Handle token refresh in client
-   - Consider refresh token rotation for security
-
-4. **Session Management**: No server-side session tracking. Consider:
-   - Track active sessions per user
-   - Allow "logout all devices"
-   - Detect concurrent logins
-
----
-
-## Open Questions
-
-1. **What happens when a Basic Auth user and OAuth user have the same name?**
-   - Currently possible - Basic Auth doesn't check UserService
-   - Could cause confusion in games
-   - Solution: Require OAuth for multiplayer? Or namespace Basic Auth names?
-
-2. **Should displayName changes be allowed?**
-   - With userId-based identity, it's safe
-   - But could cause confusion ("who is this new player?")
-   - Consider: rate limit changes, show "formerly known as" temporarily
-
-3. **How to handle OAuth provider account deletion?**
-   - User deletes their Discord account
-   - Their Eagle0 account still exists
-   - They can't login unless they linked another provider
-   - Solution: Encourage linking multiple providers, or add email/password fallback
-
-4. **Admin impersonation with OAuth**
-   - Currently works via X-Impersonate-User header
-   - Should this use userId or displayName?
-   - Probably userId for stability
-
----
-
-## Appendix: File Locations
-
-### Server (Scala)
-- `src/main/scala/net/eagle0/eagle/auth/UserService.scala` - User CRUD
-- `src/main/scala/net/eagle0/eagle/auth/JwtService.scala` - Token generation/validation
-- `src/main/scala/net/eagle0/eagle/auth/OAuthService.scala` - OAuth flow
-- `src/main/scala/net/eagle0/eagle/service/AuthServiceImpl.scala` - gRPC Auth service
-- `src/main/scala/net/eagle0/eagle/service/AuthorizationInterceptor.scala` - Auth middleware
-- `src/main/scala/net/eagle0/eagle/service/AuthorizationUtils.scala` - Context accessors
-
-### Client (C#)
-- `Assets/Auth/AuthClient.cs` - gRPC client for Auth service
-- `Assets/Auth/OAuthManager.cs` - OAuth flow orchestration
-- `Assets/Auth/TokenStorage.cs` - Persistent token storage
-- `Assets/Auth/JwtAuthInterceptor.cs` - Attaches JWT to requests
-
-### Protos
-- `src/main/protobuf/net/eagle0/eagle/api/auth.proto` - Auth service definition
-- `src/main/protobuf/net/eagle0/eagle/internal/user/user.proto` - User data model

docs/PROGRAMMATIC_MAP_GENERATION.md

@@ -0,0 +1,218 @@
+# Programmatic Map Image Generation
+
+## Overview
+
+Create a tool to programmatically regenerate the Eagle strategic map images with more equalized province sizes while preserving neighbor relationships. Also implement dynamic text rendering for province names that scales with zoom.
+
+## Current Map Assets
+
+| File | Description | Dimensions |
+|------|-------------|------------|
+| `Assets/Eagle/rawGray.gz.bytes` | Province ID lookup map (gzip compressed) | 3786 x 1834 |
+| `Assets/Eagle/map_bw_labels.png` | B&W map with baked-in province labels | 3786 x 1834, RGBA |
+| `Assets/Eagle/Materials/1.png` - `43.png` | Individual province mask images | 3786 x 1834, grayscale |
+
+## Province Data
+
+- 43 provinces defined in `src/main/resources/net/eagle0/eagle/province_map.tsv`
+- Each has: id, name, neighbors, neighborPositions, hexMapName
+- Problem provinces (too small): **Shumal** (id=1), **Kojaria** (id=39), **Usvol** (id=33), **Tumala** (id=35), **Chia** (id=43)
+
+## Goals
+
+1. **Equalize province sizes** - Reduce disparity so small provinces are easier to click
+2. **Preserve topology** - Maintain all neighbor relationships
+3. **Preserve coastline** - Keep ocean/land boundaries
+4. **Dynamic text rendering** - Province names scale with zoom level
+
+---
+
+## Part 1: Province Size Equalization Tool
+
+### Algorithm: Constrained Voronoi Relaxation
+
+1. **Extract current state from rawGray:**
+   - Calculate centroid of each province
+   - Calculate area (pixel count) of each province
+   - Identify ocean pixels (value 0 or 255)
+
+2. **Iterative relaxation:**
+   ```
+   For each iteration:
+     For each province:
+       Calculate target area (average of all provinces)
+       If province is too small:
+         Move centroid away from larger neighbors
+       If province is too large:
+         Move centroid toward smaller neighbors
+       Constraint: Don't break neighbor relationships
+   ```
+
+3. **Generate new boundaries:**
+   - Use weighted Voronoi diagram from relaxed centroids
+   - Weight by target area
+   - Mask with original coastline
+
+4. **Output new images:**
+   - New rawGray (province ID map)
+   - New province masks (1.png - 43.png)
+   - New B&W base map (derived from boundaries)
+
+### Implementation Options
+
+**Option A: Python Script (Recommended)**
+- Use numpy, scipy, PIL/Pillow
+- Can run offline, generate assets once
+- Easier to iterate and debug
+- Output: New image files to replace existing
+
+**Option B: Unity Editor Script**
+- C# with Unity's Texture2D
+- Integrated into build process
+- Slower, harder to debug
+
+### Tool Location
+`tools/map_generator/` or `scripts/generate_map.py`
+
+---
+
+## Part 2: Dynamic Province Name Rendering
+
+### Current State
+- Province names are baked into `map_bw_labels.png`
+- Not visible when zoomed out, too small when zoomed in
+- `SetUpCenterText()` in MapController shows selected/hovered province name in a fixed UI panel
+
+### New Approach
+
+1. **Create province label GameObjects:**
+   - One TextMeshPro label per province
+   - Position at province centroid
+   - Child of map content (moves with zoom/pan)
+
+2. **Dynamic scaling:**
+   - Scale inversely with zoom level
+   - At zoom 1.0: Show major provinces only (or none)
+   - At zoom 2.0+: Show all province names
+   - Font size adjusts to fit province area
+
+3. **Implementation:**
+   ```csharp
+   public class ProvinceLabelsController : MonoBehaviour {
+       public MapPinchZoomHandler zoomHandler;
+       public TextMeshProUGUI labelPrefab;
+
+       private Dictionary<int, TextMeshProUGUI> _labels;
+
+       void Update() {
+           float zoom = zoomHandler.CurrentZoom;
+           foreach (var label in _labels.Values) {
+               label.transform.localScale = Vector3.one / zoom;
+               label.gameObject.SetActive(zoom >= 1.5f);
+           }
+       }
+   }
+   ```
+
+4. **Province centroid data:**
+   - Add `centroid_x`, `centroid_y` columns to `province_map.tsv`
+   - Or calculate at runtime from rawGray
+
+---
+
+## Files to Create/Modify
+
+### New Files
+| File | Purpose |
+|------|---------|
+| `tools/map_generator/generate_map.py` | Python script to generate new map images |
+| `tools/map_generator/requirements.txt` | Python dependencies |
+| `Assets/Eagle/ProvinceLabelsController.cs` | Dynamic province name rendering |
+
+### Modified Files
+| File | Changes |
+|------|---------|
+| `Assets/Eagle/rawGray.gz.bytes` | Replaced with equalized version |
+| `Assets/Eagle/Materials/*.png` | Replaced province masks |
+| `Assets/Eagle/map_bw_labels.png` | Either: regenerated, or removed if using dynamic labels |
+| `province_map.tsv` | Add centroid columns |
+| `Assets/Gameplay.unity` | Add ProvinceLabelsController, label prefab instances |
+
+---
+
+## Verification
+
+1. **Visual inspection:**
+   - Compare old vs new province sizes
+   - Verify small provinces (Shumal, Kojaria, Usvol) are larger
+   - Verify neighbor relationships preserved
+
+2. **Functional testing:**
+   - Click on each province at various zoom levels
+   - Verify correct province is selected
+   - Verify province colors/weather still work
+
+3. **Label testing:**
+   - Zoom in/out, verify labels scale appropriately
+   - Pan around, verify labels move with map
+   - Verify labels don't overlap excessively
+
+---
+
+## Design Decisions
+
+1. **Equalization approach:** Reduce disparity only
+   - Make small provinces (Shumal, Kojaria, Usvol, etc.) 2-3x larger
+   - Minimal changes to large provinces
+   - Not targeting perfectly equal areas
+
+2. **Coastline:** Allow simplification
+   - Coastline can be smoothed/simplified as part of generation
+   - Voronoi edges are acceptable
+
+3. **Map style:** Solid fills with borders
+   - Clean, simple look
+   - Easier to generate programmatically
+   - Province boundaries rendered as dark lines
+
+---
+
+## Implementation Steps
+
+### Step 1: Python Map Generator Tool
+
+```
+tools/map_generator/
+├── generate_map.py      # Main script
+├── requirements.txt     # numpy, scipy, Pillow
+└── README.md           # Usage instructions
+```
+
+**Algorithm:**
+1. Load current rawGray.gz.bytes, decompress
+2. Calculate each province's centroid and area
+3. Identify land mask (non-ocean pixels)
+4. Run constrained Voronoi relaxation:
+   - Small provinces push neighbors away
+   - Large provinces pull neighbors in
+   - Stop when min province is >= 50% of average
+5. Generate weighted Voronoi from relaxed centroids
+6. Output:
+   - `rawGray_new.bytes` (province ID map)
+   - `1.png` - `43.png` (province masks)
+   - `map_bw.png` (solid fill + borders)
+   - `centroids.json` (for label positioning)
+
+### Step 2: Dynamic Province Labels (Unity)
+
+1. Create `ProvinceLabelsController.cs`
+2. Load centroids from JSON or calculate from rawGray
+3. Spawn TextMeshPro labels at each centroid
+4. Update label scale/visibility based on zoom
+
+### Step 3: Integration
+
+1. Replace asset files with generated versions
+2. Update `MapController` to use new assets
+3. Add `ProvinceLabelsController` to scene
+4. Remove baked label image dependency

docs/RENAMING_A_PROVINCE.md

@@ -0,0 +1,79 @@
+# Renaming a Province
+
+This document explains the steps required to rename a province in Eagle0.
+
+## Files to Modify
+
+### 1. Province Map TSV (Server Source of Truth)
+
+**File:** `src/main/resources/net/eagle0/eagle/province_map.tsv`
+
+This is the primary source of province data. Each row contains:
+- Province ID
+- Province name
+- Neighbor IDs
+- Neighbor directions
+- Province name (repeated)
+- Neighbor names (dot-separated)
+- Starting food
+
+You need to:
+1. Change the province name in its own row (columns 2 and 5)
+2. Update the neighbor name references in all neighboring provinces (column 6)
+
+Example: To rename "Fluria" to "NewName", you would need to update:
+- Line 26: The Fluria row itself
+- Lines 5, 10, 18, 24, 27, 38, 41: All provinces that list Fluria as a neighbor
+
+### 2. LLM Map Description
+
+**File:** `src/main/scala/net/eagle0/eagle/library/actions/llm_prompt_generators/MapDescription.scala`
+
+This file contains a hardcoded geographic description of the map used in LLM prompts for generating narrative text. Update any references to the old province name.
+
+### 3. Client Centroids JSON
+
+**File:** `src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Eagle/centroids.json`
+
+This JSON file contains province metadata used for map rendering (centroid positions, areas, orientations). Each entry has a `name` field that should be updated to match.
+
+Note: The actual province name displayed to players comes from the server via the `ProvinceView` proto, not from this file. However, this file should be kept in sync for consistency and because it may be used for map label positioning.
+
+### 4. Test Files
+
+**File:** `src/test/scala/net/eagle0/eagle/library/util/validations/RuntimeValidatorTest.scala`
+
+Update any test strings that reference the old province name.
+
+## How Province Names Flow to the Client
+
+Province names are sent from the Eagle server to the Unity client via the `ProvinceView` protobuf message:
+
+```protobuf
+message ProvinceView {
+    int32 id = 1;
+    string name = 6;  // <-- Province name sent from server
+    ...
+}
+```
+
+The server reads province names from `province_map.tsv` at startup. The client receives names through the proto and displays them via `province.Name` in C# code. This means:
+
+- Changing the TSV automatically updates what clients see
+- No C# code changes are needed (the code uses `province.Name` generically)
+- The `centroids.json` name field is for map rendering/positioning, not display
+
+## Files That Do NOT Need Changes
+
+- **Hero backstory TSV files** (`heroes.tsv`, `generated_heroes.tsv`) - These don't contain province name references
+- **C# client code** - Uses `province.Name` from the server proto, not hardcoded names
+- **Proto definitions** - No province names are hardcoded in protos
+
+## Checklist
+
+- [ ] Update `province_map.tsv` - province's own row
+- [ ] Update `province_map.tsv` - all neighbor references
+- [ ] Update `MapDescription.scala`
+- [ ] Update `centroids.json`
+- [ ] Update any test files with province name references
+- [ ] Build and run tests: `bazel test //src/test/scala/...`

docs/RULES_APPLE_WORKSPACE_SEPARATION.md

@@ -0,0 +1,150 @@
+# rules_apple Workspace Separation
+
+This document explains why `rules_apple` is built in a separate Bazel workspace (`sparkle_workspace/`) and what conditions need to be met before it can be reintegrated into the main workspace.
+
+## Background
+
+The main workspace cannot include `rules_apple` due to transitive dependency conflicts with `rules_swift`. Multiple dependencies require different major versions of `rules_swift`:
+
+| Dependency | rules_swift Version | Compatibility Level |
+|------------|---------------------|---------------------|
+| grpc | 3.x | 3 |
+| flatbuffers | 2.x | 2 |
+| rules_apple | 2.x | 2 |
+
+Bzlmod's `single_version_override` can force a single version, but compatibility levels 2 and 3 are incompatible. Forcing `rules_swift` 3.x (required for grpc) breaks `rules_apple` and `flatbuffers`.
+
+## Current Solution
+
+The `SparklePlugin` (the only component requiring `rules_apple`) is built in an isolated workspace:
+
+```
+sparkle_workspace/
+├── MODULE.bazel      # Minimal deps: apple_support, rules_apple, sparkle
+├── BUILD.bazel       # Builds SparklePlugin.bundle
+├── SparklePlugin.m   # Objective-C source
+├── Info.plist        # Bundle metadata
+└── external/
+    └── BUILD.sparkle # Build file for Sparkle framework
+```
+
+### How It Works
+
+1. **Build script**: `scripts/build_sparkle_plugin.sh` builds the plugin from the separate workspace
+2. **Output**: The built `SparklePlugin.bundle` is placed in `Assets/Plugins/macOS/`
+3. **CI integration**: `mac_build.yml` calls `inject_sparkle.sh` to embed Sparkle into the Mac app
+
+The main workspace uses `single_version_override` for `rules_swift` 3.x to satisfy grpc, and includes a comment noting that `rules_apple` is intentionally excluded.
+
+## What SparklePlugin Does
+
+SparklePlugin is a native macOS library that:
+- Initializes the [Sparkle](https://sparkle-project.org/) auto-update framework
+- Exposes C functions for Unity to call via P/Invoke:
+  - `SparklePlugin_Initialize`
+  - `SparklePlugin_CheckForUpdates`
+  - `SparklePlugin_CheckForUpdatesInBackground`
+  - `SparklePlugin_IsCheckingForUpdates`
+  - `SparklePlugin_GetAutomaticallyChecksForUpdates`
+  - `SparklePlugin_SetAutomaticallyChecksForUpdates`
+  - `SparklePlugin_IsRunningFromReadOnlyVolume`
+  - `SparklePlugin_ShowDMGWarning`
+
+## Conditions for Reintegration
+
+To move `rules_apple` back into the main workspace, **all** of the following must be true:
+
+### 1. rules_swift Version Alignment
+
+Check if grpc, flatbuffers, and rules_apple all support the same `rules_swift` major version:
+
+```bash
+# Check what rules_swift version each dependency requires
+bazel mod graph 2>&1 | grep -A2 "rules_swift"
+```
+
+Or check BCR directly:
+- https://registry.bazel.build/modules/grpc
+- https://registry.bazel.build/modules/flatbuffers
+- https://registry.bazel.build/modules/rules_apple
+
+**Test**: After updating versions, verify you can add this to MODULE.bazel without errors:
+```python
+bazel_dep(name = "rules_apple", version = "X.Y.Z")
+```
+
+### 2. Build Test
+
+If the dependency can be added, test that both the main build and SparklePlugin work:
+
+```bash
+# Main workspace builds
+bazel build //src/main/scala/net/eagle0/eagle:eagle_server
+bazel build //src/main/cpp/net/eagle0/shardok:shardok-server
+bazel build //ci:eagle_server_image
+
+# SparklePlugin builds (would move to main workspace)
+bazel build //sparkle:SparklePlugin  # After moving files
+```
+
+### 3. Files to Move
+
+When reintegrating, move these from `sparkle_workspace/` to the main workspace:
+
+| Source | Destination |
+|--------|-------------|
+| `sparkle_workspace/SparklePlugin.m` | `src/main/objc/net/eagle0/sparkle/SparklePlugin.m` |
+| `sparkle_workspace/Info.plist` | `src/main/objc/net/eagle0/sparkle/Info.plist` |
+| `sparkle_workspace/BUILD.bazel` | `src/main/objc/net/eagle0/sparkle/BUILD.bazel` |
+| `sparkle_workspace/external/BUILD.sparkle` | (inline into MODULE.bazel http_archive) |
+
+### 4. MODULE.bazel Changes
+
+Add to the main MODULE.bazel:
+
+```python
+bazel_dep(name = "rules_apple", version = "X.Y.Z", repo_name = "build_bazel_rules_apple")
+
+# Sparkle framework
+http_archive(
+    name = "sparkle",
+    build_file_content = """...""",  # Contents from external/BUILD.sparkle
+    sha256 = "...",
+    url = "https://github.com/sparkle-project/Sparkle/releases/download/...",
+)
+```
+
+Remove the `single_version_override` for `rules_swift` if no longer needed.
+
+### 5. Update Build Scripts
+
+- Update `scripts/build_sparkle_plugin.sh` to build from main workspace
+- Update `scripts/build_plugins.sh` if it references the separate workspace
+- Verify `mac_build.yml` still works
+
+### 6. Cleanup
+
+After successful integration:
+```bash
+rm -rf sparkle_workspace/
+```
+
+Update comments in MODULE.bazel that reference the separate workspace.
+
+## Version History
+
+| Date | Event |
+|------|-------|
+| 2026-02-04 | Separated sparkle_workspace (PR #5882) to enable Bazel 8 upgrade |
+| 2026-02-05 | Upgraded to Bazel 8.5.1 (PR #5883) |
+
+## Monitoring
+
+Periodically check if the upstream dependencies have aligned:
+
+1. **grpc releases**: https://github.com/grpc/grpc/releases
+2. **flatbuffers releases**: https://github.com/google/flatbuffers/releases
+3. **rules_apple releases**: https://github.com/bazelbuild/rules_apple/releases
+4. **BCR updates**: https://registry.bazel.build/
+
+When a new version of any of these is released, check if the `rules_swift` requirements have converged.

docs/SCALA3_MODERNIZATION.md

@@ -1,205 +0,0 @@
-# Scala 3 Modernization Guide
-
-## Overview
-This document outlines opportunities to modernize the Eagle0 codebase to use Scala 3 best practices and features. The migration to Scala 3 is complete, but the code still uses many Scala 2 patterns that can be improved.
-
-## Modernization Opportunities
-
-### 1. **Convert Sealed Traits to Enums** 🎯 HIGH IMPACT
-**Benefits**: Better performance, more concise syntax, improved exhaustiveness checking
-
-**Current pattern** (`ExternalTextGenerationCaller.scala:23-31`):
-```scala
-sealed trait ExternalTextGenerationError extends Error {
-  def message: String
-}
-case class ExternalTextGenerationRateLimitError(code: Int, message: String)
-    extends ExternalTextGenerationError
-case class ExternalTextGenerationHttpError(code: Int, message: String)
-    extends ExternalTextGenerationError
-case class ExternalTextGenerationTimeoutError(message: String)
-    extends ExternalTextGenerationError
-```
-
-**Scala 3 improvement**:
-```scala
-enum ExternalTextGenerationError extends Error:
-  case RateLimit(code: Int, message: String)
-  case Http(code: Int, message: String) 
-  case Timeout(message: String)
-  
-  def message: String = this match
-    case RateLimit(_, msg) => msg
-    case Http(_, msg) => msg
-    case Timeout(msg) => msg
-```
-
-**Files to check**:
-- `/src/main/scala/net/eagle0/common/llm_integration/ExternalTextGenerationCaller.scala`
-- `/src/main/scala/net/eagle0/eagle/model/action_result/generated_text_request/GeneratedTextRequestT.scala`
-- `/src/main/scala/net/eagle0/eagle/model/state/quest/concrete/QuestC.scala`
-
-### 2. **Convert Implicit Classes to Extension Methods** 🎯 HIGH IMPACT
-**Benefits**: Modern syntax, better IDE support, cleaner imports
-
-**Current pattern** (`MoreSeq.scala:23-26`):
-```scala
-implicit def SeqCollect[A, Repr[_]](coll: Repr[A])(implicit
-    itr: IsIterable[Repr[A]]
-): SeqCollect[A, Repr, itr.type] =
-  new SeqCollect[A, Repr, itr.type](coll, itr)
-```
-
-**Scala 3 improvement**:
-```scala
-extension [A, Repr[_]](coll: Repr[A])(using itr: IsIterable[Repr[A]])
-  def flatCollect[B](pf: PartialFunction[itr.A, Option[B]])(using Factory[B, Repr[B]]): Repr[B] =
-    Factory[B, Repr[B]].fromSpecific(itr(coll).collect(pf).flatten)
-    
-  def flatCollectFirst[B](pf: PartialFunction[itr.A, Option[B]]): Option[B] =
-    itr(coll).collect(pf).flatten.headOption
-```
-
-**Files to check**:
-- `/src/main/scala/net/eagle0/common/MoreSeq.scala`
-- `/src/main/scala/net/eagle0/eagle/library/util/command_choice_helpers/CommandChooser.scala`
-- `/src/main/scala/net/eagle0/eagle/service/new_game_creation/NewGameCreation.scala`
-- `/src/main/scala/net/eagle0/eagle/library/actions/applier/ActionResultProtoApplierImpl.scala`
-- `/src/main/scala/net/eagle0/eagle/service/new_game_creation/StartGameActionResultUtils.scala`
-- `/src/main/scala/net/eagle0/eagle/model/state/date/Date.scala`
-
-### 3. **Convert Implicit Parameters to Using Clauses** 🎯 MEDIUM IMPACT
-**Benefits**: Cleaner syntax, better tooling support, clearer intent
-
-**Current pattern**:
-```scala
-def method[T](value: T)(implicit ec: ExecutionContext): Future[T]
-def process[A](items: Seq[A])(implicit ord: Ordering[A]): Seq[A]
-```
-
-**Scala 3 improvement**:
-```scala
-def method[T](value: T)(using ExecutionContext): Future[T]
-def process[A](items: Seq[A])(using Ordering[A]): Seq[A]
-```
-
-**Files to check**:
-- `/src/main/scala/net/eagle0/common/MoreSeq.scala`
-- `/src/main/scala/net/eagle0/eagle/library/util/hero_name_fetcher/HeroNameFetcher.scala`
-- `/src/main/scala/net/eagle0/eagle/library/util/ShardokMapInfo.scala`
-- `/src/main/scala/net/eagle0/common/llm_integration/OpenAIChatCompletionsServiceImpl.scala`
-- `/src/main/scala/net/eagle0/common/llm_integration/ClaudeServiceImpl.scala`
-
-### 4. **Opaque Types for Type Safety** 🎯 MEDIUM IMPACT
-**Benefits**: Zero runtime cost, compile-time type safety, prevents mixing up similar types
-
-**Pattern to look for**: Type aliases that represent distinct concepts
-```scala
-// Instead of: type UserId = String, type GameId = String
-opaque type UserId = String
-object UserId:
-  def apply(s: String): UserId = s
-  extension (id: UserId) 
-    def value: String = id
-    def isValid: Boolean = id.nonEmpty && id.length > 3
-
-opaque type GameId = Long  
-object GameId:
-  def apply(l: Long): GameId = l
-  extension (id: GameId) def value: Long = id
-```
-
-**Candidates**: Look for simple type aliases and ID types throughout the codebase.
-
-### 5. **Inline Methods for Performance** 🎯 LOW IMPACT
-**Benefits**: Compile-time optimization, better performance for hot paths
-
-**Pattern**: Mark small, frequently-called methods as `inline`
-```scala
-inline def isValidId(id: String): Boolean = 
-  id.nonEmpty && id.length > 3
-
-inline def calculateScore(base: Int, multiplier: Double): Double = 
-  base * multiplier
-```
-
-**Candidates**: Small utility methods in performance-critical paths (AI calculations, game state updates).
-
-### 6. **Union Types Instead of Complex Hierarchies** 🎯 LOW IMPACT  
-**Benefits**: Simpler type definitions for either/or scenarios
-
-**Pattern**: Simple sealed traits with only case classes
-```scala
-// Instead of:
-sealed trait Result
-case class Success(value: String) extends Result  
-case class Error(message: String) extends Result
-
-// Consider:
-type Result = Success | Error
-case class Success(value: String)
-case class Error(message: String)
-```
-
-### 7. **Context Functions for Cleaner APIs** 🎯 LOW IMPACT
-**Benefits**: Cleaner API design, implicit context passing
-
-**Pattern**: Replace implicit function parameters
-```scala
-// Old
-type Handler = GameState => Unit
-def withGameState(gs: GameState)(handler: Handler): Unit = handler(gs)
-
-// New  
-type Handler = GameState ?=> Unit
-def withGameState(gs: GameState)(handler: Handler): Unit = 
-  given GameState = gs
-  handler
-```
-
-## Implementation Priority
-
-### Phase 1: Quick Wins (High Impact, Low Risk)
-1. **Convert Extension Methods** in `MoreSeq.scala` - immediate readability improvement
-2. **Update Using Clauses** - simple find/replace operation  
-3. **Convert Simple Sealed Traits to Enums** - start with error types
-
-### Phase 2: Type Safety Improvements  
-4. **Add Opaque Types** for IDs and measurements - improves type safety
-5. **Inline Performance-Critical Methods** - measure before/after impact
-
-### Phase 3: Advanced Features (Lower Priority)
-6. **Union Types** where appropriate - only for simple either/or cases
-7. **Context Functions** for complex API improvements
-
-## Implementation Guidelines
-
-### Style Consistency
-- **Keep curly braces**: Continue using Scala 2 style `{}` instead of indentation-based syntax
-- **Gradual adoption**: Modernize files as they're touched for other reasons
-- **Test thoroughly**: Each modernization should include verification that behavior is unchanged
-
-### Performance Considerations  
-- **Measure enum performance**: Verify that enum conversion actually improves performance in hot paths
-- **Benchmark inline methods**: Use profiling to confirm performance gains
-- **Consider compilation time**: Some features may increase compile time
-
-### Migration Strategy
-- **File-by-file approach**: Complete modernization of one file at a time
-- **Separate PRs**: Each modernization type should be its own PR for easier review
-- **Documentation**: Update this document as patterns are modernized
-
-## Success Criteria
-- [ ] All extension methods converted from implicit classes
-- [ ] All implicit parameters converted to using clauses  
-- [ ] Key sealed traits converted to enums where appropriate
-- [ ] Opaque types introduced for important ID types
-- [ ] Performance-critical methods marked as inline (with benchmarks)
-- [ ] No regression in functionality or performance
-- [ ] Code remains readable and maintainable
-
-## Notes
-- Focus on high-impact, low-risk improvements first
-- Each change should be driven by clear benefits (performance, readability, type safety)
-- Maintain backward compatibility where possible
-- Document any breaking changes clearly

docs/SMALL_EAGLE_TODO.md

@@ -0,0 +1,80 @@
+# The Small Eagle TODO
+
+## Goals
+
+Be able to support a small (10-50 user) private alpha, including with strangers.
+
+Larger set of goals in [The Big Eagle TODO](https://docs.google.com/document/d/17RTt3-4Wl2AAVMRLodaC3a84E4de6xuQTWBPvCRM484/edit?pli=1&tab=t.0), but most of that is not necessary for MVP.
+
+## Required
+
+### Gameplay Productionization
+
+- [x] ~~All functionality works on production eagle / shardok servers~~
+- [x] ~~Acceptable latency in all regions~~
+- [x] ~~Shardok performance similar to QA~~
+- [x] ~~Error logging & alerting~~
+- [x] ~~Fix long disconnects on deployments~~
+- [x] Fix the Mac installer
+- [x] ~~Still not reconnecting after deployments~~
+- [ ] Notify about client updates, button to come directly back
+- [x] Generatedtext healing
+- [x] Kill outstanding shardok requests when game is deleted
+
+### Other Productionization
+
+- [x] ~~Oauth sign-in~~
+  - [x] ~~Add Google, others?~~
+- [ ] User management
+  - [x] ~~Invite codes~~
+  - [ ] Link accounts
+  - [x] ~~Choose display name~~
+  - [x] ~~Just do account setup from the landing page?~~
+- [x] ~~Download client directly from DO, avoid basic auth/my home network~~
+- [x] Support plan (Discord + in-client bug reporting + email contact)
+
+### Alpha Tester Support
+
+- [x] Feedback channel (Discord server)
+- [x] Bug report form in Unity client (Settings > Report Bug, sends to Discord webhook)
+- [ ] Known issues doc (so testers don't report the same things)
+
+### IP / Legal
+
+- [x] Document and make available licenses for art & music (attributions panel)
+- [x] Required open source disclosures (attributions panel)
+- [x] Audit assets for anything we don't have rights to and replace it
+- [x] Replace heroes that are based on real 20th or 21st century people or IP
+- [x] ~~Privacy policy (collecting accounts, OAuth data, gameplay data)~~ (alpha notice on invite page/email)
+- [ ] Terms of service (basic liability protection) - defer until public release
+- [x] ~~Data deletion capability (user requests account removal)~~ (accounts.eagle0.net)
+
+### Basic Gameplay
+
+- [ ] Tutorial
+  - [x] In the Your Warlord panel, say what the profession is
+  - [x] ~~And separate panels for each profession when you encounter one~~
+  - [x] ~~Command tutorial for each command the first time it's clicked~~
+  - [x] ~~Time to recruit / expand~~
+    - [x] ~~And how expansion works~~
+  - [ ] Province events
+  - [x] Running low on food
+  - [x] ~~Time to swear brotherhood~~
+    - [x] ~~When you get large, or~~
+    - [x] ~~When you get a good candidate~~
+  - [ ] Shardok tutorial!
+- [ ] Basic Shardok AI stuff fixed
+- [ ] Lobby fixes
+- [ ] Have goals / ending
+  - [ ] Win condition: all other factions defeated
+  - [ ] Mid-game progression: King recognizes you as you gain power (generated events)
+- [ ] First-session onboarding (beyond mechanics tutorial)
+  - [ ] Narrative hook in first few minutes - why should I care about my warlord?
+  - [ ] Clear first-session goal ("try to capture your first province" or similar)
+  - [ ] Early small victory to build momentum
+  - [ ] Guided first scenario vs. overwhelming sandbox?
+
+## Nice to have
+
+- [x] "What's new" changelog (fetch JSON, show entries since last launch)
+- [ ] Windows code signing ([Azure Artifact Signing](https://azure.microsoft.com/en-us/products/artifact-signing/), ~$10/mo) to eliminate SmartScreen "unknown publisher" warning

docs/SPARKLE_DELTA_UPDATES.md

@@ -0,0 +1,568 @@
+# Sparkle Delta Updates Implementation Plan
+
+## Overview
+
+This document outlines the implementation plan for adding delta update support to the Eagle0 macOS auto-update system using Sparkle's BinaryDelta feature.
+
+### Current State
+- Full DMG downloads (~200MB) for every update
+- `mac_build_handler.go` creates DMG, signs it, uploads to S3, updates appcast.xml
+- Keeps last 10 versions in appcast, deletes older DMGs
+- Users must download full app even for small changes
+
+### Goals
+- Reduce update download size from ~200MB to ~10-30MB (85% reduction)
+- Maintain backward compatibility with full DMG downloads
+- Automatic fallback for users who are many versions behind
+
+## Sparkle Delta Update Architecture
+
+Sparkle supports binary delta updates through the `<sparkle:deltas>` element in the appcast. When a user updates, Sparkle:
+1. Checks if a delta patch exists from their current version to the new version
+2. If found, downloads the smaller delta patch instead of the full DMG
+3. Applies the patch locally to create the new app version
+4. Falls back to full DMG if no matching delta exists
+
+### Appcast XML Structure with Deltas
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle">
+  <channel>
+    <title>Eagle0</title>
+    <link>https://assets.eagle0.net/mac/appcast.xml</link>
+    <description>Eagle0 game updates</description>
+    <language>en</language>
+    <item>
+      <title>Version 1.0.9615</title>
+      <pubDate>Sun, 19 Jan 2026 12:00:00 -0800</pubDate>
+      <sparkle:version>9615</sparkle:version>
+      <sparkle:shortVersionString>1.0.9615</sparkle:shortVersionString>
+      <enclosure
+        url="https://assets.eagle0.net/mac/builds/eagle0-1.0.9615.dmg"
+        length="200000000"
+        type="application/octet-stream"
+        sparkle:edSignature="..." />
+      <sparkle:deltas>
+        <enclosure
+          url="https://assets.eagle0.net/mac/deltas/9614-9615.delta"
+          sparkle:deltaFrom="9614"
+          length="15000000"
+          type="application/octet-stream"
+          sparkle:edSignature="..." />
+        <enclosure
+          url="https://assets.eagle0.net/mac/deltas/9613-9615.delta"
+          sparkle:deltaFrom="9613"
+          length="18000000"
+          type="application/octet-stream"
+          sparkle:edSignature="..." />
+        <enclosure
+          url="https://assets.eagle0.net/mac/deltas/9612-9615.delta"
+          sparkle:deltaFrom="9612"
+          length="22000000"
+          type="application/octet-stream"
+          sparkle:edSignature="..." />
+      </sparkle:deltas>
+    </item>
+    <!-- older versions... -->
+  </channel>
+</rss>
+```
+
+## Implementation Plan
+
+### Phase 1: Add S3 Utility Functions
+
+**File:** `src/main/go/net/eagle0/util/aws/bucket_basics.go`
+
+Add two new functions to support delta generation:
+
+```go
+// ListObjectsWithPrefix returns all object keys matching the given prefix
+func (bb BucketBasics) ListObjectsWithPrefix(bucket, prefix string) ([]string, error) {
+    var keys []string
+    paginator := s3.NewListObjectsV2Paginator(bb.S3Client, &s3.ListObjectsV2Input{
+        Bucket: aws.String(bucket),
+        Prefix: aws.String(prefix),
+    })
+
+    for paginator.HasMorePages() {
+        page, err := paginator.NextPage(context.TODO())
+        if err != nil {
+            return nil, err
+        }
+        for _, obj := range page.Contents {
+            keys = append(keys, *obj.Key)
+        }
+    }
+    return keys, nil
+}
+
+// DownloadFile downloads an object to a local file path
+func (bb BucketBasics) DownloadFile(bucket, key, localPath string) error {
+    result, err := bb.S3Client.GetObject(context.TODO(), &s3.GetObjectInput{
+        Bucket: aws.String(bucket),
+        Key:    aws.String(key),
+    })
+    if err != nil {
+        return err
+    }
+    defer result.Body.Close()
+
+    file, err := os.Create(localPath)
+    if err != nil {
+        return err
+    }
+    defer file.Close()
+
+    _, err = io.Copy(file, result.Body)
+    return err
+}
+```
+
+### Phase 2: Store App Bundles for Delta Generation
+
+**File:** `src/main/go/net/eagle0/build/mac_build_handler/mac_build_handler.go`
+
+Add storage paths:
+```go
+var appsRoot = "mac/apps/"      // Zipped app bundles for delta generation
+var deltasRoot = "mac/deltas/"  // Delta patches
+```
+
+After DMG creation, upload the zipped app bundle:
+```go
+func uploadAppBundle(bb aws.BucketBasics, appPath string, buildNumber string) error {
+    appZipPath := filepath.Join("/tmp", fmt.Sprintf("eagle0-%s.app.zip", buildNumber))
+
+    // Create zip of app bundle using ditto (preserves metadata)
+    cmd := exec.Command("ditto", "-c", "-k", "--keepParent", appPath, appZipPath)
+    if output, err := cmd.CombinedOutput(); err != nil {
+        return fmt.Errorf("failed to zip app: %s: %w", string(output), err)
+    }
+    defer os.Remove(appZipPath)
+
+    // Upload to S3
+    remotePath := appsRoot + fmt.Sprintf("eagle0-%s.app.zip", buildNumber)
+    log.Printf("Uploading app bundle to S3: %s", remotePath)
+    return bb.UploadFilePublic(bucketName, remotePath, appZipPath)
+}
+```
+
+### Phase 3: Add Delta XML Structures
+
+**File:** `src/main/go/net/eagle0/build/mac_build_handler/mac_build_handler.go`
+
+Add new structs for delta representation:
+```go
+// Delta represents a delta patch from a previous version
+type Delta struct {
+    XMLName   xml.Name `xml:"enclosure"`
+    URL       string   `xml:"url,attr"`
+    DeltaFrom string   `xml:"sparkle:deltaFrom,attr"`
+    Length    int64    `xml:"length,attr"`
+    Type      string   `xml:"type,attr"`
+    EdSig     string   `xml:"sparkle:edSignature,attr"`
+}
+
+// Deltas wraps the sparkle:deltas element
+type Deltas struct {
+    XMLName xml.Name `xml:"sparkle:deltas"`
+    Items   []Delta  `xml:"enclosure"`
+}
+
+// Update Item struct to include Deltas
+type Item struct {
+    Title               string     `xml:"title"`
+    PubDate             string     `xml:"pubDate"`
+    SparkleVersion      string     `xml:"sparkle:version"`
+    SparkleShortVersion string     `xml:"sparkle:shortVersionString"`
+    Description         string     `xml:"description,omitempty"`
+    Enclosure           Enclosure  `xml:"enclosure"`
+    Deltas              *Deltas    `xml:"sparkle:deltas,omitempty"`
+}
+```
+
+### Phase 4: Generate Delta Patches
+
+**File:** `src/main/go/net/eagle0/build/mac_build_handler/mac_build_handler.go`
+
+```go
+// Maximum number of versions to generate deltas from
+const maxDeltaVersions = 5
+
+// generateDeltas creates delta patches from previous versions to the new version
+func generateDeltas(bb aws.BucketBasics, newBuildNumber string, newAppPath string, privateKeyPath string) ([]Delta, error) {
+    var deltas []Delta
+
+    // Ensure BinaryDelta tool is available
+    binaryDeltaPath, err := ensureBinaryDelta()
+    if err != nil {
+        return nil, fmt.Errorf("failed to get BinaryDelta: %w", err)
+    }
+
+    // List available app bundles
+    appKeys, err := bb.ListObjectsWithPrefix(bucketName, appsRoot+"eagle0-")
+    if err != nil {
+        log.Printf("Warning: failed to list app bundles: %v", err)
+        return deltas, nil // Continue without deltas
+    }
+
+    // Parse build numbers from keys and sort descending
+    var buildNumbers []string
+    for _, key := range appKeys {
+        // Extract build number from "mac/apps/eagle0-9614.app.zip"
+        base := filepath.Base(key)
+        if strings.HasPrefix(base, "eagle0-") && strings.HasSuffix(base, ".app.zip") {
+            bn := strings.TrimSuffix(strings.TrimPrefix(base, "eagle0-"), ".app.zip")
+            if bn != newBuildNumber {
+                buildNumbers = append(buildNumbers, bn)
+            }
+        }
+    }
+
+    // Sort descending (most recent first) and limit to maxDeltaVersions
+    sort.Sort(sort.Reverse(sort.StringSlice(buildNumbers)))
+    if len(buildNumbers) > maxDeltaVersions {
+        buildNumbers = buildNumbers[:maxDeltaVersions]
+    }
+
+    // Generate delta from each previous version
+    for _, oldBuild := range buildNumbers {
+        delta, err := generateSingleDelta(bb, binaryDeltaPath, oldBuild, newBuildNumber, newAppPath, privateKeyPath)
+        if err != nil {
+            log.Printf("Warning: failed to generate delta from %s: %v", oldBuild, err)
+            continue // Skip this delta but continue with others
+        }
+        deltas = append(deltas, delta)
+    }
+
+    return deltas, nil
+}
+
+func generateSingleDelta(bb aws.BucketBasics, binaryDeltaPath, oldBuild, newBuild, newAppPath, privateKeyPath string) (Delta, error) {
+    // Download old app bundle
+    oldAppZipKey := appsRoot + fmt.Sprintf("eagle0-%s.app.zip", oldBuild)
+    oldAppZipLocal := filepath.Join("/tmp", fmt.Sprintf("eagle0-%s.app.zip", oldBuild))
+    defer os.Remove(oldAppZipLocal)
+
+    if err := bb.DownloadFile(bucketName, oldAppZipKey, oldAppZipLocal); err != nil {
+        return Delta{}, fmt.Errorf("failed to download old app: %w", err)
+    }
+
+    // Unzip old app
+    oldAppDir := filepath.Join("/tmp", fmt.Sprintf("old-app-%s", oldBuild))
+    defer os.RemoveAll(oldAppDir)
+
+    cmd := exec.Command("ditto", "-x", "-k", oldAppZipLocal, oldAppDir)
+    if output, err := cmd.CombinedOutput(); err != nil {
+        return Delta{}, fmt.Errorf("failed to unzip old app: %s: %w", string(output), err)
+    }
+
+    oldAppPath := filepath.Join(oldAppDir, "eagle0.app")
+
+    // Generate delta
+    deltaPath := filepath.Join("/tmp", fmt.Sprintf("%s-%s.delta", oldBuild, newBuild))
+    defer os.Remove(deltaPath)
+
+    cmd = exec.Command(binaryDeltaPath, "create", oldAppPath, newAppPath, deltaPath)
+    if output, err := cmd.CombinedOutput(); err != nil {
+        return Delta{}, fmt.Errorf("failed to create delta: %s: %w", string(output), err)
+    }
+
+    // Get delta size
+    deltaSize, err := getFileSize(deltaPath)
+    if err != nil {
+        return Delta{}, fmt.Errorf("failed to get delta size: %w", err)
+    }
+    log.Printf("Delta %s->%s size: %d bytes (%.1f MB)", oldBuild, newBuild, deltaSize, float64(deltaSize)/1024/1024)
+
+    // Sign delta
+    signature, err := signWithSparkle(deltaPath, privateKeyPath)
+    if err != nil {
+        return Delta{}, fmt.Errorf("failed to sign delta: %w", err)
+    }
+
+    // Upload delta
+    deltaKey := deltasRoot + fmt.Sprintf("%s-%s.delta", oldBuild, newBuild)
+    if err := bb.UploadFilePublic(bucketName, deltaKey, deltaPath); err != nil {
+        return Delta{}, fmt.Errorf("failed to upload delta: %w", err)
+    }
+
+    deltaURL := fmt.Sprintf("https://assets.eagle0.net/%s", deltaKey)
+    return Delta{
+        URL:       deltaURL,
+        DeltaFrom: oldBuild,
+        Length:    deltaSize,
+        Type:      "application/octet-stream",
+        EdSig:     signature,
+    }, nil
+}
+
+func ensureBinaryDelta() (string, error) {
+    binaryDeltaPath := "/tmp/sparkle-cache/Sparkle-2.6.4/bin/BinaryDelta"
+
+    if _, err := os.Stat(binaryDeltaPath); os.IsNotExist(err) {
+        log.Println("Sparkle BinaryDelta not found, downloading...")
+        cmd := exec.Command("bash", "-c", `
+            mkdir -p /tmp/sparkle-cache
+            curl -sL https://github.com/sparkle-project/Sparkle/releases/download/2.6.4/Sparkle-2.6.4.tar.xz | tar -xJ -C /tmp/sparkle-cache
+        `)
+        if output, err := cmd.CombinedOutput(); err != nil {
+            return "", fmt.Errorf("failed to download Sparkle: %s: %w", string(output), err)
+        }
+    }
+
+    return binaryDeltaPath, nil
+}
+```
+
+### Phase 5: Update Main Deploy Flow
+
+**File:** `src/main/go/net/eagle0/build/mac_build_handler/mac_build_handler.go`
+
+Modify `main()` to integrate delta generation:
+
+```go
+func main() {
+    // ... existing argument parsing ...
+
+    // Create DMG (existing)
+    if err := createDMG(appPath, dmgPath, "Eagle0"); err != nil {
+        log.Fatalf("Failed to create DMG: %v", err)
+    }
+
+    // ... existing DMG upload ...
+
+    if privateKeyPath != "" {
+        // Upload app bundle for future delta generation (NEW)
+        log.Println("Uploading app bundle for delta generation...")
+        if err := uploadAppBundle(bb, appPath, buildNumber); err != nil {
+            log.Printf("Warning: failed to upload app bundle: %v", err)
+            // Continue - delta generation is optional
+        }
+
+        // Generate deltas from previous versions (NEW)
+        log.Println("Generating delta patches...")
+        deltas, err := generateDeltas(bb, buildNumber, appPath, privateKeyPath)
+        if err != nil {
+            log.Printf("Warning: failed to generate deltas: %v", err)
+        } else {
+            log.Printf("Generated %d delta patches", len(deltas))
+        }
+
+        // Update appcast with deltas
+        log.Println("Updating appcast.xml...")
+        appcast, err := fetchAppcast(bb)
+        if err != nil {
+            log.Fatalf("Failed to fetch appcast: %v", err)
+        }
+
+        // Create new item with deltas
+        newItem := Item{
+            Title:               fmt.Sprintf("Version %s", version),
+            PubDate:             time.Now().Format(time.RFC1123Z),
+            SparkleVersion:      buildNumber,
+            SparkleShortVersion: version,
+            Description:         "",
+            Enclosure: Enclosure{
+                URL:    downloadURL,
+                Length: fileSize,
+                Type:   "application/octet-stream",
+                EdSig:  signature,
+            },
+        }
+
+        // Add deltas if any were generated
+        if len(deltas) > 0 {
+            newItem.Deltas = &Deltas{Items: deltas}
+        }
+
+        // ... rest of appcast handling ...
+    }
+}
+```
+
+### Phase 6: Cleanup Old Artifacts
+
+**File:** `src/main/go/net/eagle0/build/mac_build_handler/mac_build_handler.go`
+
+When pruning old versions from appcast, also delete associated artifacts:
+
+```go
+// In the appcast pruning section, after removing old items:
+if len(appcast.Channel.Items) > 10 {
+    oldItems := appcast.Channel.Items[10:]
+    for _, item := range oldItems {
+        oldBuild := item.SparkleVersion
+
+        // Delete old DMG (existing)
+        dmgKey := strings.TrimPrefix(item.Enclosure.URL, "https://assets.eagle0.net/")
+        log.Printf("Deleting old build: %s", dmgKey)
+        bb.DeleteObject(bucketName, dmgKey)
+
+        // Delete old app bundle (NEW)
+        appKey := appsRoot + fmt.Sprintf("eagle0-%s.app.zip", oldBuild)
+        log.Printf("Deleting old app bundle: %s", appKey)
+        bb.DeleteObject(bucketName, appKey)
+
+        // Delete deltas TO this version (NEW)
+        deltaKeys, _ := bb.ListObjectsWithPrefix(bucketName, deltasRoot)
+        for _, key := range deltaKeys {
+            if strings.HasSuffix(key, fmt.Sprintf("-%s.delta", oldBuild)) {
+                log.Printf("Deleting old delta: %s", key)
+                bb.DeleteObject(bucketName, key)
+            }
+        }
+    }
+    appcast.Channel.Items = appcast.Channel.Items[:10]
+}
+```
+
+## S3 Storage Structure
+
+After implementation, the S3 bucket will have this structure:
+
+```
+eagle0-windows/
+├── mac/
+│   ├── appcast.xml                    # Update feed with delta info
+│   ├── builds/                        # Full DMG downloads
+│   │   ├── eagle0-1.0.9620.dmg
+│   │   ├── eagle0-1.0.9619.dmg
+│   │   ├── ...
+│   │   └── eagle0-latest.dmg          # Symlink to latest
+│   ├── apps/                          # Zipped app bundles (NEW)
+│   │   ├── eagle0-9620.app.zip
+│   │   ├── eagle0-9619.app.zip
+│   │   ├── eagle0-9618.app.zip
+│   │   ├── eagle0-9617.app.zip
+│   │   └── eagle0-9616.app.zip        # Keep last 5 for delta gen
+│   └── deltas/                        # Delta patches (NEW)
+│       ├── 9619-9620.delta
+│       ├── 9618-9620.delta
+│       ├── 9617-9620.delta
+│       ├── 9616-9620.delta
+│       ├── 9615-9620.delta
+│       ├── 9618-9619.delta
+│       ├── 9617-9619.delta
+│       └── ...
+```
+
+## Storage Impact Analysis
+
+### Current Storage (without deltas)
+- 10 DMGs × 200MB = **~2GB**
+
+### Estimated Storage (with deltas)
+- 10 DMGs × 200MB = 2GB
+- 5 app bundles × 150MB = 0.75GB (zip compression)
+- ~25 delta files × 20MB avg = 0.5GB
+- **Total: ~3.25GB**
+
+### Trade-offs
+- **+1.25GB storage** (~60% increase)
+- **-170MB per user update** (~85% bandwidth savings)
+- Break-even: ~8 user updates to recoup storage cost
+
+## Bandwidth Savings
+
+| Scenario | Without Deltas | With Deltas | Savings |
+|----------|---------------|-------------|---------|
+| 1 version behind | 200MB | ~15MB | 92% |
+| 2 versions behind | 200MB | ~20MB | 90% |
+| 3 versions behind | 200MB | ~25MB | 87% |
+| 5 versions behind | 200MB | ~35MB | 82% |
+| 6+ versions behind | 200MB | 200MB (full) | 0% |
+
+## Migration Strategy
+
+The implementation is backward-compatible and requires no changes to existing clients:
+
+1. **First deploy after implementation:**
+   - Stores app bundle for the first time
+   - No deltas generated (no previous app bundles exist)
+   - Appcast has no `<sparkle:deltas>` element
+
+2. **Second deploy:**
+   - Generates delta from previous version
+   - Appcast now has `<sparkle:deltas>` with one entry
+   - Users on previous version get delta update
+
+3. **Subsequent deploys:**
+   - Generate deltas from last 5 versions
+   - Users within 5 versions get delta updates
+   - Users more than 5 versions behind get full DMG
+
+4. **Client behavior:**
+   - Sparkle automatically checks for matching delta
+   - Falls back to full DMG if no delta matches
+   - No client code changes required
+
+## Error Handling
+
+The implementation handles failures gracefully:
+
+1. **S3 list/download fails:** Skip delta generation, use full DMG
+2. **BinaryDelta fails for one version:** Log warning, continue with other versions
+3. **Signing fails:** Skip that delta, continue with others
+4. **Upload fails:** Skip that delta, continue with others
+
+The deploy never fails due to delta issues - deltas are optional enhancements.
+
+## Verification Plan
+
+### Manual Testing
+
+1. **Deploy version N:**
+   - Verify app bundle uploaded to `mac/apps/eagle0-N.app.zip`
+   - Verify appcast has no deltas (first deploy)
+
+2. **Deploy version N+1:**
+   - Verify delta generated at `mac/deltas/N-(N+1).delta`
+   - Verify appcast contains `<sparkle:deltas>` element
+   - Verify delta signature is valid
+
+3. **Test update from N to N+1:**
+   - Install version N manually
+   - Check for updates
+   - Monitor download size in Player.log (should be ~15-30MB, not 200MB)
+   - Verify app updated successfully
+
+4. **Test fresh install:**
+   - Download latest DMG directly
+   - Verify installation works normally
+
+5. **Test fallback scenario:**
+   - Install a version more than 5 versions behind
+   - Update should download full DMG
+
+### Automated Verification
+
+Add to CI workflow (optional):
+```yaml
+- name: Verify delta generation
+  run: |
+    # Check app bundle exists
+    aws s3 ls s3://eagle0-windows/mac/apps/ | grep eagle0-${BUILD_NUMBER}.app.zip
+
+    # Check deltas exist (after second deploy)
+    aws s3 ls s3://eagle0-windows/mac/deltas/ | head -5
+
+    # Verify appcast has deltas
+    curl -s https://assets.eagle0.net/mac/appcast.xml | grep "sparkle:deltas"
+```
+
+## Security Considerations
+
+1. **All deltas are EdDSA signed:** Same signature verification as full DMG
+2. **BinaryDelta is Sparkle's official tool:** Well-audited, production-ready
+3. **App bundles in S3 are public:** Same as DMGs, no additional exposure
+4. **Cleanup removes old artifacts:** No indefinite storage of old versions
+
+## Future Enhancements
+
+1. **Parallel delta generation:** Generate multiple deltas concurrently
+2. **Delta size threshold:** Skip uploading deltas larger than X% of full DMG
+3. **Delta metrics:** Track delta download rates vs full DMG
+4. **Configurable delta count:** Allow adjusting how many versions to keep

docs/TUTORIAL_BATTLE_SYSTEM.md

@@ -0,0 +1,240 @@
+# Tutorial Battle System
+
+This document describes the tutorial battle system for first-time players. The system provides a scripted introductory battle that teaches combat basics while telling a story.
+
+---
+
+## Overview
+
+When a new player starts their first game in tutorial mode, they experience:
+
+1. **Narrative Intro** - Story screens introducing the scenario
+2. **Immediate Battle** - Skip strategic map, start directly in combat
+3. **Scripted Flee** - Enemy flees when player is "on the ropes"
+4. **Reinforcements** - Allied heroes arrive mid-battle
+5. **Heroes Join** - Reinforcement heroes join player's faction after battle
+
+---
+
+## Battle Configuration
+
+### Defender (Player - John Ranil)
+- **Heroes**: John Ranil + 2 random vassals (3 total)
+- **Units**:
+  - 2x Light Infantry (300 troops each, 60 training/armament)
+  - 1x Longbowmen (200 troops, 60 training/armament)
+- **Province**: 14 (Onmaa) with 40 support, 500 gold, 3000 food
+- **Restriction**: Cannot flee (must defend)
+
+### Attacker (Ikhaan Tarn)
+- **Heroes**: Ikhaan Tarn + 2 sworn brothers (3 total)
+- **Units**:
+  - 1x Heavy Cavalry (600 troops, 80 training/armament)
+  - 1x Heavy Infantry (500 troops, 80 training/armament)
+  - 1x Longbowmen (300 troops, 80 training/armament)
+- **Origin Province**: 32
+
+### Flee Trigger
+Attacker flees when ANY of these conditions are met:
+- Player loses 1 unit
+- 5 rounds have passed
+
+### Reinforcements
+When Tarn flees, these heroes arrive as player reinforcements:
+- Elena Fyar
+- Hedrick
+- The Boulder
+
+---
+
+## Implementation Architecture
+
+### Phase 1: Narrative Intro System
+
+**Proto Changes:**
+- `game_state_view.proto`: Added `TutorialNarrativeScreen` message and `pending_narrative_screens` field
+- `game_parameters.proto`: Added `TutorialNarrativeScreen` and `tutorial_narrative_screens` field
+
+**Unity Client:**
+- `NarrativeScreenController.cs`: Modal screen with title, body text, optional image
+- `EagleGameController.cs`: Checks for pending narrative screens on game start
+
+**Narrative Content** (defined in `tutorial_game_parameters.json`):
+```
+Screen 1: "The Engineer of Onmaa" - Player backstory
+Screen 2: "The Traitor Arrives" - Tarn's attack
+Screen 3: "Defend Your Home" - Call to action
+```
+
+### Phase 2: Auto-Start Battle
+
+**Configuration:**
+- `tutorial_game_parameters.json`: Contains `tutorialBattle` config with attacker, target, flee conditions
+- `game_parameters.proto`: `TutorialBattleConfig` message
+
+**Game Creation:**
+- `NewGameCreation.scala`: `setupTutorialBattle()` method creates:
+  - `HostileArmyGroup` with `Attacking` status (bypasses decision phase)
+  - `Army` for defender
+  - Both added to target province
+
+**Battle Creation:**
+- When round advances to `BattleRequest` phase, `RequestBattlesAction` automatically creates the `ShardokBattle`
+
+### Phase 3: Scripted Flee Mechanism
+
+**C++ Component:**
+- `TutorialBattleController.hpp/cpp`: Controller for scripted battle logic
+
+**Key Methods:**
+```cpp
+// Check all events and execute triggered actions (called at end of each round)
+std::vector<ActionResult> CheckAndExecuteEvents(
+    const GameStateW& state,
+    const SettingsGetter& settings,
+    const std::shared_ptr<RandomGenerator>& randomGenerator);
+```
+
+**Integration:**
+- `ShardokEngine.cpp`: Calls `CheckAndExecuteEvents()` at end of each round in `HandlePlayerTurnEnd()`
+- Events fire in config order, each event fires at most once
+
+### Phase 4: Mid-Battle Reinforcements
+
+**Action Types** (in `action_type.proto`):
+- `TUTORIAL_ENEMY_FLED = 78`
+- `TUTORIAL_REINFORCEMENTS_ARRIVED = 79`
+
+**Implementation (TODO):**
+- When scripted flee triggers, create reinforcement units in defender's reserves
+- Units have `UnitStatus_RESERVE_UNIT` status
+- Reinforcements enter battle on subsequent turns
+
+### Phase 5: Tutorial Popups
+
+**Content Definitions** (in `TutorialContentDefinitions.cs`):
+- `tutorial_battle_started`: "Defend your province!"
+- `tutorial_enemy_fled`: "The enemy retreats!"
+- `tutorial_reinforcements_arrived`: "Allies have arrived!"
+- `tutorial_battle_victory`: Victory celebration
+
+**Trigger Integration:**
+- `TutorialTriggerRegistry.cs`: Handles tutorial action types from `ActionResultView`
+- `ShardokGameController.cs`: Detects tutorial events and triggers popups
+
+### Phase 6: Post-Battle Hero Joining
+
+**Implementation (TODO):**
+- `ResolveBattleAction.scala`: Check if battle was tutorial and defender won
+- Create `TutorialHeroJoined` action results adding reinforcement heroes to player faction
+- Set appropriate loyalty, vigor, location for joined heroes
+
+---
+
+## File Summary
+
+### New Files
+| File | Purpose |
+|------|---------|
+| `TutorialBattleController.hpp/cpp` | C++ scripted flee and reinforcement logic |
+| `NarrativeScreenController.cs` | Unity narrative screen display |
+
+### Modified Files
+| File | Changes |
+|------|---------|
+| `tutorial_game_parameters.json` | Battle configuration and narrative content |
+| `game_state_view.proto` | Narrative screens field |
+| `game_parameters.proto` | Tutorial battle config |
+| `player_info.proto` | Tutorial battle flags for Shardok |
+| `action_type.proto` | Tutorial action types |
+| `NewGameCreation.scala` | Auto-start battle setup |
+| `EagleGameController.cs` | Narrative display integration |
+| `TutorialContentDefinitions.cs` | Battle tutorial content |
+| `TutorialTriggerRegistry.cs` | Tutorial event triggers |
+
+---
+
+## Remaining Implementation
+
+### Disable Player Flee
+In `FleeCommandFactory.cpp`:
+- Check if tutorial mode is enabled
+- If defender, don't offer flee commands
+
+### Reinforcement Units
+In `TutorialBattleController::ExecuteScriptedFlee()`:
+- Create `Unit` objects for Elena Fyar, Hedrick, The Boulder
+- Add to defender's reserve units
+- Generate `TUTORIAL_REINFORCEMENTS_ARRIVED` action
+
+### Post-Battle Hero Joining
+In Eagle's battle resolution:
+- Detect tutorial battle completion
+- Create heroes in player's faction with proper stats
+- Generate notification action results
+
+---
+
+## Testing Checklist
+
+- [ ] New user sees narrative screens before battle
+- [ ] Battle starts immediately after narratives (no strategic map)
+- [ ] Player has correct units (3 heroes, 3 battalions)
+- [ ] Attacker has correct units (3 heroes, 3 battalions)
+- [ ] Player cannot flee
+- [ ] Tarn flees after player loses 1 unit
+- [ ] Tarn flees after 5 rounds (if no units lost)
+- [ ] Reinforcements appear when Tarn flees
+- [ ] Tutorial popups appear at correct moments
+- [ ] Reinforcement heroes join faction after battle victory
+
+---
+
+## Configuration Reference
+
+### tutorial_game_parameters.json
+```json
+{
+  "tutorialBattle": {
+    "attackerFactionHead": "Ikhaan Tarn",
+    "targetProvinceId": 14,
+    "fleeAfterDefenderUnitsLost": 1,
+    "fleeAfterRounds": 5,
+    "reinforcements": ["Elena Fyar", "Hedrick", "The Boulder"]
+  },
+  "tutorialNarrativeScreens": [
+    { "title": "...", "bodyText": "...", "imagePath": "" }
+  ]
+}
+```
+
+### TutorialBattleConfig Proto (Shardok)
+```protobuf
+message TutorialBattleConfig {
+    bool enabled = 1;
+    repeated TutorialEvent events = 2;
+    repeated UnitInitialSize initial_sizes = 3;  // For damage tracking
+}
+
+message TutorialEvent {
+    string event_id = 1;
+    TutorialTrigger trigger = 2;
+    TutorialAction action = 3;
+}
+
+message TutorialTrigger {
+    oneof trigger_type {
+        RoundTrigger after_round = 1;
+        UnitsLostTrigger units_lost = 2;
+        DamageTakenTrigger damage_taken = 3;
+        UnitKilledTrigger unit_killed = 4;
+    }
+}
+
+message TutorialAction {
+    oneof action_type {
+        FleeAction flee = 1;
+        ReinforcementsAction reinforcements = 2;  // Uses CommonUnit
+    }
+}
+```

docs/ai-quest-completion.md

@@ -0,0 +1,113 @@
+# AI Quest Completion Behavior
+
+This document describes which quests the AI attempts to complete proactively to recruit unaffiliated heroes.
+
+## Overview
+
+The AI attempts to complete quests via `FulfillQuestsCommandSelector`, which is invoked by `MidGameAIClient.chosenFulfillEasyQuestsCommand`. The AI only considers quests from unaffiliated heroes in provinces ruled by a faction leader.
+
+## Quests the AI Actively Completes
+
+### Diplomacy Quests
+
+| Quest | Handler | Conditions |
+|-------|---------|------------|
+| `AllianceQuest` | `AllianceQuestCommandChooser` | Target faction must meet trust conditions for alliance and not already be in an alliance |
+| `TruceWithFactionQuest` | `TruceWithFactionQuestCommandChooser` | Target faction must meet trust conditions for truce |
+| `TruceCountQuest` | `TruceCountQuestCommandChooser` | Picks a random faction that meets trust conditions and isn't already in a truce/alliance |
+
+### Resource Giving Quests
+
+| Quest | Handler | Notes |
+|-------|---------|-------|
+| `AlmsToProvinceQuest` | `AlmsToProvinceQuestCommandChooser` | Gives food to the specified province |
+| `AlmsAcrossRealmQuest` | `AlmsAcrossRealmQuestCommandChooser` | Gives food from the province with the largest surplus |
+| `GiveToHeroesInProvinceQuest` | `GiveToHeroesInProvinceQuestCommandChooser` | Gives gold to the hero with the lowest loyalty in the specified province |
+| `GiveToHeroesAcrossRealmQuest` | `GiveToHeroesAcrossRealmQuestCommandChooser` | Gives gold from the province with the most gold available |
+
+### Province Development Quests
+
+| Quest | Handler | Notes |
+|-------|---------|-------|
+| `ImproveAgricultureQuest` | `ImproveQuestCommandChooser` | Issues an Improve command with Agriculture type |
+| `ImproveEconomyQuest` | `ImproveQuestCommandChooser` | Issues an Improve command with Economy type |
+| `ImproveInfrastructureQuest` | `ImproveQuestCommandChooser` | Issues an Improve command with Infrastructure type |
+
+### Other Quests
+
+| Quest | Handler | Conditions |
+|-------|---------|------------|
+| `DismissSpecificVassalQuest` | `DismissSpecificVassalCommandChooser` | Only if province has more than 2 heroes AND the unaffiliated hero's power >= target hero's power * `RequiredPowerMultiplierForDismiss` |
+
+## Quests the AI Does Not Attempt to Complete
+
+The following quests have no handler in `FulfillQuestsCommandSelector` and must be completed naturally through gameplay:
+
+### Combat/Military Quests
+- `DefeatFactionQuest` - Defeat a specific faction
+- `GrandArmyQuest` - Accumulate a large number of troops
+- `UpgradeBattalionQuest` - Upgrade a battalion to minimum armament/training
+- `WinBattleOutnumberedQuest` - Win a battle while outnumbered
+- `WinBattlesQuest` - Win a number of battles
+- `RescueImprisonedLeaderQuest` - Rescue an imprisoned leader from another faction
+
+### Expansion Quests
+- `ExpandToProvincesQuest` - Expand to control a certain number of provinces
+- `SpecificExpansionQuest` - Conquer a specific province
+- `BorderSecurityQuest` - Have troops in a border province
+
+### Prisoner Quests
+- `ExecutePrisonerQuest` - Execute a specific prisoner
+- `ExilePrisonerQuest` - Exile a specific prisoner
+- `ReleasePrisonerQuest` - Release a specific prisoner
+- `ReturnPrisonerQuest` - Return a prisoner to their faction
+- `ReleaseAllPrisonersQuest` - Release all prisoners
+
+### Province Order Quests
+- `DevelopProvincesQuest` - Maintain provinces in Develop order for months
+- `MobilizeProvincesQuest` - Maintain provinces in Mobilize order for months
+- `RestProvinceQuest` - Use the Rest command in a specific province
+
+### Reconnaissance Quests
+- `ReconProvincesQuest` - Reconnoiter a number of provinces
+- `ReconSpecificProvincesQuest` - Reconnoiter specific provinces
+
+### Economic Quests
+- `TotalDevelopmentQuest` - Achieve total development level in a province
+- `WealthQuest` - Accumulate gold and food
+- `SpendOnFeastsQuest` - Spend gold on feasts
+- `SendSuppliesQuest` - Send food to a specific province
+- `RepairDevastationQuest` - Repair devastation
+
+### Special Event Quests
+- `SuppressRiotByForceQuest` - Suppress a riot by force
+- `FightBeastsAloneQuest` - Fight beasts alone
+- `StartBlizzardQuest` - Start a blizzard in a province
+- `StartEpidemicQuest` - Start an epidemic in a province
+- `ApprehendOutlawQuest` - Apprehend an outlaw hero
+
+### Miscellaneous
+- `BattalionDiversityQuest` - Have diverse battalion types
+- `SwearBrotherhoodWithHeroQuest` - Swear brotherhood with a specific hero
+- `BetrayAllyQuest` - Betray an allied faction
+
+## Implementation Details
+
+The quest completion logic is located in:
+- `FulfillQuestsCommandSelector.scala` - Main entry point, iterates through choosers
+- `quest_command_selectors/` - Individual quest handlers
+
+Each chooser extends either:
+- `QuestCommandChooser` - For quests requiring randomness
+- `DeterministicQuestCommandChooser` - For quests with deterministic command selection
+
+The AI prioritizes quests in the order they appear in `FulfillQuestsCommandSelector.choosers`:
+1. Alliance
+2. TruceWithFaction
+3. Improve (Agriculture/Economy/Infrastructure)
+4. AlmsToProvince
+5. GiveToHeroesInProvince
+6. AlmsAcrossRealm
+7. GiveToHeroesAcrossRealm
+8. TruceCount
+9. DismissSpecificVassal

docs/eliminate-battalion-backstory-updates.md

@@ -0,0 +1,230 @@
+# Plan: Eliminate Battalion Backstory LLM Updates
+
+## Goal
+
+Dramatically reduce LLM request volume by eliminating battalion backstory updates. Battalions will retain:
+- An **initial backstory** (generated once when created)
+- A **history of events** (structured data, not LLM-generated prose)
+
+The history will be fed into other LLM updates (hero backstories, chronicle) but will no longer be regenerated into prose for each battalion.
+
+## Current System Overview
+
+### Data Flow
+```
+Battalion Created → Initial Backstory LLM Request → Text stored
+                                    ↓
+Battalion participates in events → Events accumulated → Update LLM Request → New text version
+                                    ↓
+BattalionView.backstoryTextId → Client displays on hover
+```
+
+### Event Types (8 total)
+Events are structured data already captured in `EventForBattalionBackstory`:
+- OrganizedTroops, SuppressedBeasts, ApprehendedOutlaws, FoughtInBattle
+- SuppressedRiot, Trained, Armed, SurvivedStarvation
+
+Each event has date, province, hero, and event-specific details.
+
+### Key Files
+
+| Component | File |
+|-----------|------|
+| Unity Display | `Assets/Eagle/HeroesAndBattalionsPanelController.cs` |
+| View Proto | `views/battalion_view.proto` |
+| View Filter | `BattalionViewFilter.scala` |
+| Update Action | `BattalionBackstoryUpdateAction.scala` |
+| Update Generator | `BattalionBackstoryUpdateActionGenerator.scala` |
+| Update Prompt | `BattalionBackstoryUpdatePromptGenerator.scala` |
+| Event-to-Text | `BattalionBackstoryUpdatePromptGenerator.textForEvent()` |
+| BattalionDescriptions | `BattalionDescriptions.scala` (used in other LLM prompts) |
+
+---
+
+## Stage 1: Stop Displaying Battalion Backstories in Client
+
+**Goal:** Remove the UI that shows battalion backstory text on hover.
+
+### Files to Modify
+
+**`Assets/Eagle/HeroesAndBattalionsPanelController.cs`**
+- In `BattalionLongHoverRowChanged()` (lines 143-169):
+  - Remove or comment out the backstory text population
+  - Keep the header/name display, remove `battalionPopupPanelBackstory.TextId = ...`
+
+**Unity Scene/Prefab**
+- Hide or remove the `battalionPopupPanelBackstory` UI element
+
+### Verification
+- [ ] Battalion hover popup no longer shows backstory text
+- [ ] No errors when hovering over battalions
+- [ ] Other battalion info (name, type, size) still displays
+
+---
+
+## Stage 2: Stop Populating Backstory in BattalionView
+
+**Goal:** Stop sending backstory text ID to the client.
+
+### Files to Modify
+
+**`BattalionViewFilter.scala`**
+- In `filteredBattalionViewBelongingToPlayer()`:
+  - Set `backstoryTextId = ""` instead of `battalion.backstoryTextId`
+- In `limitedBattalionView()`:
+  - Same change
+
+### Verification
+- [ ] BattalionView messages have empty backstoryTextId
+- [ ] Client handles empty backstoryTextId gracefully (Stage 1 should have removed the display)
+
+---
+
+## Stage 3: Remove backstory_text_id from BattalionView Proto
+
+**Goal:** Clean up the proto schema.
+
+### Files to Modify
+
+**`views/battalion_view.proto`**
+- Remove field: `string backstory_text_id = 7;`
+- Mark field 7 as reserved to prevent reuse
+
+**`Assets/Eagle/HeroesAndBattalionsPanelController.cs`**
+- Remove any remaining references to `BackstoryTextId`
+
+**`BattalionViewFilter.scala`**
+- Remove `backstoryTextId` from view construction
+
+### Verification
+- [ ] Proto compiles
+- [ ] C# client compiles without BackstoryTextId references
+- [ ] Full test suite passes
+
+---
+
+## Stage 4: Replace Backstory Usage in BattalionDescriptions
+
+**Goal:** When other LLM prompts need battalion context, use initial backstory + structured history instead of the latest LLM-generated prose.
+
+### Current Usage in `BattalionDescriptions.scala`
+
+```scala
+def backstoryText(): TextGenerationResult =
+  battalion.backstoryVersions.lastOption
+    .map(v => clientTextStore.getText(v.textId))
+    .getOrElse(TextGenerationSuccess(""))
+
+def fullDescription(): String =
+  s"${battalion.name} is $description. $backstoryText"
+```
+
+### New Approach
+
+Create `historyDescription()` that:
+1. Gets initial backstory (first version's text, if available)
+2. Appends structured event history using the same `textForEvent()` logic from `BattalionBackstoryUpdatePromptGenerator`
+
+```scala
+def historyDescription(): String = {
+  val initialBackstory = battalion.backstoryVersions.headOption
+    .map(v => clientTextStore.getText(v.textId))
+    .collect { case TextGenerationSuccess(text) => text }
+    .getOrElse("")
+
+  val eventHistory = battalion.backstoryEvents
+    .map(textForEvent)  // Reuse existing event-to-text conversion
+    .mkString(" ")
+
+  if eventHistory.isEmpty then initialBackstory
+  else s"$initialBackstory $eventHistory"
+}
+```
+
+### Files to Modify
+
+**`BattalionDescriptions.scala`**
+- Add `historyDescription()` method
+- Update `fullDescription()` to use `historyDescription()` instead of `backstoryText()`
+- Keep `textForEvent()` logic (move from `BattalionBackstoryUpdatePromptGenerator` if needed)
+
+**Move/refactor `textForEvent()`**
+- Currently in `BattalionBackstoryUpdatePromptGenerator.scala` (lines 78-262)
+- Move to `BattalionDescriptions.scala` or a shared utility
+- This converts events to human-readable text without LLM
+
+### Verification
+- [ ] Other LLM prompts that use `BattalionDescriptions` still get meaningful context
+- [ ] Chronicle updates include battalion history
+- [ ] Hero backstory updates include relevant battalion history
+
+---
+
+## Stage 5: Stop Generating Battalion Backstory Updates
+
+**Goal:** Remove the LLM request generation entirely.
+
+### Files to Modify
+
+**`BattalionBackstoryUpdateActionGenerator.scala`**
+- Return empty Vector instead of generating actions
+- Or delete the file entirely
+
+**`BattalionBackstoryUpdateAction.scala`**
+- Delete or mark as deprecated
+
+**`BattalionBackstoryUpdatePromptGenerator.scala`**
+- Delete or keep only `textForEvent()` if moved
+
+**`LlmResolver.scala`**
+- Remove case for `BattalionBackstoryUpdateRequest`
+- Optionally throw error if somehow called
+
+**`EndPlayerCommandsPhaseAction.scala`** (and other callers)
+- Find where `BattalionBackstoryUpdateActionGenerator` is called
+- Remove those calls
+
+### Files to Search for Callers
+```bash
+grep -r "BattalionBackstoryUpdateAction" src/
+```
+
+### Verification
+- [ ] No `BattalionBackstoryUpdateRequest` LLM requests generated
+- [ ] Battalions still accumulate events (for history description)
+- [ ] Full test suite passes
+- [ ] Game runs without errors
+
+---
+
+## Future Considerations
+
+### Keep or Remove Initial Backstory Generation?
+The initial backstory (`BattalionInitialBackstoryRequest`) is generated once per battalion. Options:
+1. **Keep it** - Low volume, provides flavor text for history
+2. **Remove it** - Use a template-based approach instead
+
+Recommendation: Keep for now, evaluate later based on volume.
+
+### Event History Cleanup
+Events currently accumulate forever on battalions. Consider:
+- Capping event history length
+- Summarizing old events
+- Only keeping "significant" events
+
+### Affected Tests
+Search for tests that verify backstory update behavior:
+```bash
+bazel query 'tests(//src/test/scala/...) intersect rdeps(//src/test/scala/..., //src/main/scala/net/eagle0/eagle/library/actions/impl/action:battalion_backstory_update_action)'
+```
+
+---
+
+## Summary of LLM Request Reduction
+
+| Request Type | Current Volume | After Change |
+|--------------|---------------|--------------|
+| BattalionInitialBackstoryRequest | 1 per battalion | 1 per battalion (unchanged) |
+| BattalionBackstoryUpdateRequest | ~N per battalion per game | **0** |
+
+For a typical game with ~50 battalions and ~20 rounds, this could eliminate **hundreds** of LLM requests.

docs/province-event-3d-effects.md

@@ -0,0 +1,93 @@
+# Province Event 3D Effects
+
+Ideas for replacing 2D shader-based province event effects with 3D particle systems.
+
+## Current State
+
+| Event | Effect Type | Notes |
+|-------|-------------|-------|
+| Festival | 3D particles | Complete |
+| Epidemic | 3D particles | Complete (rising skulls + green haze) |
+| Blizzard | 2D shader | Not visible on unowned (white) provinces |
+| Drought | 2D shader | |
+| Flood | 2D shader | |
+| Beasts | None | Tricky - can be any animal or human |
+
+## Proposed 3D Effects
+
+### Blizzard
+
+- Falling snowflakes with slight blue tint (ensures visibility on white backgrounds)
+- Diagonal wind-blown particles to convey harsh weather
+- Swirling vortex effect near ground level
+- Frosty sparkle/glitter particles for magical winter feel
+
+### Drought
+
+- Rising dust/sand particles (tan/brown coloring)
+- Small dust devils (spinning particle columns)
+- Shimmering golden particles rising to suggest heat distortion
+- Dried leaves/debris blowing across the province
+
+### Flood
+
+- Rain falling (blue-tinted streaks or droplets)
+- Water splashes/ripples rising from ground
+- Mist/spray particles hovering low
+- Floating debris particles (leaves, sticks)
+
+### Beasts
+
+This is challenging since "beasts" can represent any dangerous creature. Universal approaches:
+
+- **Circling vultures/crows overhead** - Predators attract scavengers; works for any beast type and is visually distinctive
+- Dust clouds suggesting movement at province edges
+- Glowing eyes appearing/disappearing in shadows
+- Stylized claw/scratch mark effects
+- Paw prints materializing on the ground
+- Red "danger" aura pulsing from ground level
+
+The vultures/crows approach is recommended as the most universal solution.
+
+## Implementation Status
+
+Controllers have been created for all 4 event types:
+- `ProvinceBlizzardController.cs` - ready, needs prefab
+- `ProvinceDroughtController.cs` - ready, needs prefab
+- `ProvinceFloodController.cs` - ready, needs prefab
+- `ProvinceBeastsController.cs` - ready, needs prefab
+
+### Prefabs Needed
+
+Create these prefabs in `Assets/Eagle/Effects/`:
+
+1. **BlizzardEffect.prefab**
+   - Particle System with falling snowflakes
+   - Blue-tinted particles for visibility on white
+   - Diagonal velocity for wind effect
+   - RectTransform for UI positioning
+
+2. **DroughtEffect.prefab**
+   - Particle System with rising dust particles
+   - Tan/brown coloring
+   - Upward velocity
+   - Optional spinning sub-emitters for dust devils
+
+3. **FloodEffect.prefab**
+   - Particle System with falling rain streaks
+   - Blue tint
+   - Fast downward velocity
+   - Optional splash sub-emitter
+
+4. **BeastsEffect.prefab**
+   - Particle System with bird silhouettes
+   - Circular orbit motion around center
+   - Black/dark particles
+   - Could use a crow/vulture sprite texture
+
+### Scene Setup
+
+Wire up in `Gameplay.unity`:
+1. Add controller components to the Map GameObject
+2. Assign `mapContainer`, `centroidsJson` (shared with other controllers)
+3. Assign the effect prefab for each controller

docs/scala3-reflection-issues.md

@@ -1,310 +0,0 @@
-# Scala 3 Migration: Reflection Issues Found
-
-This document catalogs all reflection-related problems discovered during the Scala 2.13.16 → Scala 3.7.2 migration of the Eagle0 codebase.
-
-## Summary
-
-The migration revealed several categories of reflection issues that needed to be addressed for Scala 3 compatibility:
-
-1. **Scala 2 Runtime Reflection API** - No longer available in Scala 3
-2. **Settings System Reflection** - Custom reflection for loading settings singletons 
-3. **json4s Automatic Case Class Extraction** - Uses reflection that fails with Scala 3 metaprogramming classes
-4. **ScalaTest Exception Handling** - Syntax changes affecting exception variable binding
-
-## 1. Scala 2 Runtime Reflection (FIXED)
-
-### Issue
-Tests using `scala.reflect.runtime.universe` fail because this reflection API doesn't exist in Scala 3.
-
-### Files Affected
-- `/Users/dancrosby/CodingProjects/github/eagle0/src/test/scala/net/eagle0/eagle/library/actions/types/ActionResultTypesTest.scala`
-
-### Error
-```scala
-import scala.reflect.runtime.universe  // Not available in Scala 3
-```
-
-### Solution Applied
-**Deleted the test entirely** as it was redundant. The test was verifying that auto-generated Scala objects (created by Bazel from proto enum values) matched their source proto values - something already guaranteed by the build system. Since the objects are generated directly from the proto definitions, this test provided no value.
-
-**Files deleted:**
-- `src/test/scala/net/eagle0/eagle/library/actions/types/ActionResultTypesTest.scala`
-
-## 2. Settings System Reflection (FIXED)
-
-### Issue
-Custom `SettingsLoader` class used reflection to access Scala object singletons, but the reflection pattern changed between Scala 2 and Scala 3.
-
-### Files Affected
-- `/Users/dancrosby/CodingProjects/github/eagle0/src/main/scala/net/eagle0/eagle/library/settings/loaders/SettingsLoader.scala`
-
-### Error
-```
-java.lang.NoSuchMethodException: net.eagle0.eagle.library.settings.ApprehendOutlawVigorCost$.MODULE$
-```
-
-### Root Cause
-In Scala 2, singleton objects are accessed via `ClassName$.MODULE$()`, but in Scala 3, they're accessed directly via `ClassName$` field. Additionally, `scala.reflect.runtime.universe` is not available in Scala 3.
-
-### Solution Applied
-**Completely eliminated reflection** by auto-generating the entire `SettingsLoader.scala` file from BUILD.bazel definitions:
-
-1. **Created generator**: `src/main/go/net/eagle0/build/settings_loader_generator/settings_loader_generator.go` - parses BUILD.bazel and generates complete SettingsLoader.scala with pattern matching for all 272 settings
-
-2. **Added genrule**: In `src/main/scala/net/eagle0/eagle/library/settings/loaders/BUILD.bazel`:
-```python
-genrule(
-    name = "settings_loader_src",
-    srcs = ["//src/main/scala/net/eagle0/eagle/library/settings:BUILD.bazel"],
-    outs = ["SettingsLoader.scala"],
-    cmd = "$(location //src/main/go/net/eagle0/build/settings_loader_generator) $(location //src/main/scala/net/eagle0/eagle/library/settings:BUILD.bazel) > $@",
-    tools = ["//src/main/go/net/eagle0/build/settings_loader_generator"],
-)
-```
-
-3. **Result**: SettingsLoader now uses compile-time pattern matching instead of reflection:
-```scala
-private def settingObjectForKey(key: String): Any = key match {
-  case "ActionVigorCost" => ActionVigorCost
-  case "BaseFoodBuyPrice" => BaseFoodBuyPrice
-  // ... all 272 settings auto-generated
-  case _ => throw NoSuchSettingException(key)
-}
-```
-
-### Benefits
-- **No reflection** - Completely Scala 3 compatible
-- **Maintainable** - New settings automatically included when added to BUILD.bazel
-- **Performance** - Pattern matching is faster than reflection
-- **Type-safe** - Compile-time checking of all settings
-
-## 3. json4s Reflection Issues (MULTIPLE LOCATIONS)
-
-### 3.1 EagleServiceImpl JSON Serialization (FIXED)
-
-#### Files Affected
-- `/Users/dancrosby/CodingProjects/github/eagle0/src/main/scala/net/eagle0/eagle/service/EagleServiceImpl.scala`
-
-#### Error
-```
-java.lang.NoClassDefFoundError: scala/quoted/staging/package$
-```
-
-#### Root Cause
-json4s automatic case class serialization uses reflection that tries to access Scala 3 metaprogramming classes (`scala.quoted.staging.package$`) which aren't available at runtime.
-
-#### Solution Applied
-Replaced automatic json4s serialization with ScalaPB's built-in JSON support:
-
-```scala
-// Old (reflection-based):
-// implicit val formats: DefaultFormats.type = DefaultFormats
-// write(actionResultView)
-
-// New (ScalaPB JSON support):
-import scalapb.json4s.JsonFormat
-JsonFormat.toJsonString(actionResultView.toProto)
-```
-
-### 3.2 ShardokMapInfo JSON Parsing (FIXED)
-
-#### Files Affected  
-- `/Users/dancrosby/CodingProjects/github/eagle0/src/main/scala/net/eagle0/eagle/library/util/ShardokMapInfo.scala` (Line 44)
-
-#### Error
-```
-java.lang.NoClassDefFoundError: scala/quoted/staging/package$
-at org.json4s.reflect.ScalaSigReader$.readConstructor(ScalaSigReader.scala:42)
-```
-
-#### Root Cause
-The line `val extracted = parsedJson.extract[List[ShardokMapInfo]]` uses json4s automatic case class extraction which relies on reflection.
-
-#### Solution Applied
-Replaced automatic extraction with manual JSON parsing:
-
-```scala
-// OLD (reflection-based):
-val extracted = parsedJson.extract[List[ShardokMapInfo]]
-
-// NEW (manual parsing, no reflection):
-val extracted = parsedJson match {
-  case JArray(items) => items.map { item =>
-    val name = (item \ "name").extract[String]
-    val castleCount = (item \ "castleCount").extract[Int] 
-    val positions = (item \ "positions").extract[Map[Int, Int]]
-    ShardokMapInfo(name, castleCount, positions)
-  }
-  case _ => throw new Exception("Expected JSON array for map info")
-}
-```
-
-#### Testing
-The fix was verified - `attack_command_chooser_test` now passes successfully.
-
-### 3.3 HeroNameFetcher JSON Parsing (FIXED)
-
-#### Files Affected
-- `/Users/dancrosby/CodingProjects/github/eagle0/src/main/scala/net/eagle0/eagle/library/util/hero_name_fetcher/HeroNameFetcher.scala`
-
-#### Issue  
-Case class extraction `parsedJson.extract[ResponseBody]` uses reflection that may fail in Scala 3.
-
-#### Solution Applied
-Replaced automatic case class extraction with manual JSON parsing:
-
-```scala
-// OLD (reflection-based):
-val parsedJson = json.parse(src.getLines().mkString)
-parsedJson.extract[ResponseBody]
-
-// NEW (manual parsing, no reflection):
-parsedJson \ "names" match {
-  case JArray(nameArray) => 
-    nameArray.map { nameObj =>
-      val id = (nameObj \ "id").extract[String]
-      val name = (nameObj \ "name").extract[String]
-      NameResponse(id, name)
-    }.toVector
-  case _ => throw new Exception("Expected 'names' array in response")
-}
-```
-
-#### Testing
-The fix was verified - HeroNameFetcher now builds successfully without reflection.
-
-### 3.4 Other json4s Usage Analysis
-
-#### Files with json4s extraction:
-- **✅ SAFE**: OpenAI/Claude Services - Only extract simple types (`String`, `Int`) - no reflection
-- **✅ FIXED**: `HeroNameFetcher.scala` - Replaced `extract[ResponseBody]` with manual parsing (no reflection)
-- **⚠️ POTENTIAL ISSUES** (not currently causing failures but should be monitored):
-  - `JsonUtils.scala`: `extract[Map[String, Vector[String]]]` - complex type extraction
-  - `HexMapJsonUtils.scala`: `extract[List[JObject]]` - may be problematic
-
-#### Recommendation
-Apply the same manual parsing pattern to remaining case class extractions if they cause runtime failures during Scala 3 migration.
-
-## 4. ScalaTest Exception Handling Syntax (FIXED)
-
-### Issue
-Scala 3 changed how exception variables are bound in ScalaTest's `the[Exception] thrownBy {...}` construct.
-
-### Files Affected
-**70+ test files** across the codebase using exception testing patterns.
-
-### Error Pattern
-```
-Not found: ex
-```
-
-### Root Cause
-In Scala 2: `the[Exception] thrownBy { ... }` automatically creates an `ex` variable.
-In Scala 3: The exception variable must be explicitly bound.
-
-### Solution Applied
-Added explicit variable binding across all affected test files:
-
-```scala
-// Old Scala 2 syntax:
-the[EagleCommandException] thrownBy {
-  // test code
-}
-ex.getMessage shouldBe "expected message"
-
-// New Scala 3 syntax:
-val ex = the[EagleCommandException] thrownBy {
-  // test code  
-}
-ex.getMessage shouldBe "expected message"
-```
-
-### Script Used
-Created and ran a systematic fix script that processed 70+ files:
-
-```bash
-# Pattern to find and fix exception handling
-find . -name "*.scala" -exec sed -i '' 's/the\[\([^]]*\)\] thrownBy {/val ex = the[\1] thrownBy {/g' {} \;
-```
-
-## 5. ScalaTest Import Changes (FIXED)
-
-### Issue
-Scala 3 requires different imports for ScalaTest matchers.
-
-### Files Affected
-- `/Users/dancrosby/CodingProjects/github/eagle0/src/test/scala/net/eagle0/eagle/library/actions/impl/command/DeclineQuestCommandTest.scala`
-
-### Error
-```
-value convertToAnyShouldWrapper is not a member of object org.scalatest.matchers.should.Matchers
-```
-
-### Solution Applied
-Changed from specific imports to wildcard import:
-
-```scala
-// Old:
-import org.scalatest.matchers.should.Matchers.{convertToAnyShouldWrapper, the}
-
-// New:
-import org.scalatest.matchers.should.Matchers.*
-```
-
-## 6. Mock Framework Issues (FIXED)
-
-### Issue
-ScalaMock had type inference issues with Scala 3 for classes with constructor parameters.
-
-### Files Affected
-- `/Users/dancrosby/CodingProjects/github/eagle0/src/test/scala/net/eagle0/eagle/library/EngineImplTest.scala`
-
-### Error
-```
-Found: Vector
-Required: Vector[net.eagle0.eagle.library.util.hero_generator.hero_with_name.HeroWithName]
-```
-
-### Root Cause
-Mock framework couldn't properly infer types for `mock[HeroGenerator]` where `HeroGenerator` has constructor parameters.
-
-### Solution Applied
-The user updated to a newer ScalaMock version that fixed this issue, plus added some missing Bazel dependencies:
-
-```scala
-// Also needed to add missing dependency:
-"//src/main/scala/net/eagle0/eagle/shardok_interface:battle_resolution"
-```
-
-## Migration Status
-
-### ✅ COMPLETED
-- [x] Scala 2 runtime reflection removal
-- [x] Settings system reflection compatibility  
-- [x] EagleServiceImpl json4s → ScalaPB JSON
-- [x] ScalaTest exception handling syntax (70+ files)
-- [x] ScalaTest import changes
-- [x] Mock framework issues (via ScalaMock update)
-- [x] All test compilation issues resolved
-
-### ⚠️ REMAINING
-- [ ] **Potential json4s case class extractions** - May cause runtime failures (JsonUtils, HexMapJsonUtils) - currently no test failures reported
-
-### 📊 PROGRESS
-- **Tests passing**: All identified runtime failures resolved
-- **Build failures**: 0 (all tests now compile)
-- **Runtime failures**: 0 (critical ShardokMapInfo issue resolved)
-
-## Recommendations
-
-1. **✅ COMPLETED**: ShardokMapInfo json4s reflection issue resolved with manual parsing
-2. **Monitor remaining json4s usage**: Watch for runtime failures in HeroNameFetcher, JsonUtils, and HexMapJsonUtils during full Scala 3 migration
-3. **Consider ScalaPB for new JSON needs**: For new functionality, prefer ScalaPB's JSON support to avoid reflection entirely
-4. **Apply manual parsing pattern**: If other json4s case class extractions cause runtime failures, use the same manual parsing approach demonstrated in ShardokMapInfo
-
-## Key Learnings
-
-- **Scala 3 reflection changes**: Major differences in singleton object access patterns
-- **json4s compatibility**: Automatic case class extraction doesn't work well with Scala 3 metaprogramming
-- **ScalaPB advantage**: Using ScalaPB's JSON support avoids reflection issues entirely
-- **Systematic approach**: Many issues followed patterns that could be fixed with scripts across multiple files

external/BUILD.bazel

@@ -0,0 +1,5 @@
+# Export BUILD files for use with http_archive build_file attribute
+exports_files([
+    "BUILD.gtl",
+    "BUILD.llvm_mingw",
+])

external/BUILD.llvm_mingw

@@ -0,0 +1,48 @@
+# LLVM MinGW toolchain for Windows cross-compilation
+# Provides x86_64-w64-mingw32 target compiler and libraries
+
+package(default_visibility = ["//visibility:public"])
+
+filegroup(
+    name = "all_files",
+    srcs = glob(["**/*"]),
+)
+
+# Compiler binaries
+filegroup(
+    name = "compiler_files",
+    srcs = glob([
+        "bin/x86_64-w64-mingw32-*",
+        "bin/clang*",
+        "bin/llvm-*",
+        "bin/lld*",
+    ]),
+)
+
+# Windows x86_64 sysroot (headers and libraries)
+filegroup(
+    name = "windows_x86_64_sysroot",
+    srcs = glob([
+        "x86_64-w64-mingw32/**/*",
+        "generic-w64-mingw32/include/**/*",
+    ]),
+)
+
+# All library files needed for linking
+filegroup(
+    name = "linker_files",
+    srcs = glob([
+        "bin/x86_64-w64-mingw32-*",
+        "bin/lld*",
+        "bin/ld.lld*",
+        "lib/**/*",
+        "x86_64-w64-mingw32/lib/**/*",
+    ]),
+)
+
+# The main C compiler wrapper script path for CGO
+# CGO needs CC to point to the cross-compiler
+exports_files([
+    "bin/x86_64-w64-mingw32-clang",
+    "bin/x86_64-w64-mingw32-clang++",
+])

go.mod

@@ -11,6 +11,8 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.72.2
 	github.com/golang-jwt/jwt/v5 v5.2.1
 	github.com/google/uuid v1.6.0
+	github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6
+	golang.org/x/sys v0.28.0
 	google.golang.org/grpc v1.68.0
 	google.golang.org/protobuf v1.36.3
 )

go.sum

@@ -41,6 +41,10 @@ github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6
 github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6 h1:VQpB2SpK88C6B5lPHTuSZKb2Qee1QWwiFlC5CKY4AW0=
+github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6/go.mod h1:yE65LFCeWf4kyWD5re+h4XNvOHJEXOCOuJZ4v8l5sgk=
+golang.org/x/sys v0.28.0 h1:Fksou7UEQUWlKvIdsqzJmUmCX3cZuD2+P3XyyzwMhlA=
+golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/text v0.25.0 h1:qVyWApTSYLk/drJRO5mDlNYskwQznZmkpV2c8q9zls4=
 golang.org/x/text v0.25.0/go.mod h1:WEdwpYrmk1qmdHvhkSTNPm3app7v4rsT8F2UD6+VHIA=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=

nginx/nginx.conf

@@ -39,7 +39,7 @@ http {
     server {
         listen 80;
         listen [::]:80;
-        server_name prod.eagle0.net;
+        server_name prod.eagle0.net eagle0.net;
 
         # Let's Encrypt challenge
         location /.well-known/acme-challenge/ {
@@ -57,7 +57,7 @@ http {
         listen 443 ssl;
         listen [::]:443 ssl;
         http2 on;
-        server_name prod.eagle0.net;
+        server_name prod.eagle0.net eagle0.net;
 
         # SSL certificates (managed by certbot)
         ssl_certificate /etc/letsencrypt/live/prod.eagle0.net/fullchain.pem;
@@ -112,6 +112,20 @@ http {
             proxy_set_header X-Real-IP $remote_addr;
         }
 
+        # Apple OAuth callback (Apple uses POST with form_post response mode)
+        location /oauth/apple/callback {
+            proxy_pass http://auth:8080;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+        }
+
+        # Steam OAuth callback (Steam uses OpenID 2.0)
+        location /oauth/steam/callback {
+            proxy_pass http://auth:8080;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+        }
+
         # Invitation landing page (proxied to Go auth service)
         location /invite/ {
             proxy_pass http://auth:8080;
@@ -119,6 +133,13 @@ http {
             proxy_set_header X-Real-IP $remote_addr;
         }
 
+        # Credits/attributions page (proxied to Go auth service)
+        location /credits {
+            proxy_pass http://auth:8080;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+        }
+
         # Health check endpoint
         location /health {
             access_log off;
@@ -248,4 +269,44 @@ http {
             proxy_set_header X-Forwarded-Proto $scheme;
         }
     }
+
+    # HTTP server for Accounts Console (Let's Encrypt + redirect)
+    server {
+        listen 80;
+        listen [::]:80;
+        server_name accounts.prod.eagle0.net accounts.eagle0.net;
+
+        location /.well-known/acme-challenge/ {
+            root /var/www/certbot;
+        }
+
+        location / {
+            return 301 https://$host$request_uri;
+        }
+    }
+
+    # HTTPS server for Accounts Console (user self-service portal)
+    server {
+        listen 443 ssl;
+        listen [::]:443 ssl;
+        server_name accounts.prod.eagle0.net accounts.eagle0.net;
+
+        ssl_certificate /etc/letsencrypt/live/accounts.eagle0.net/fullchain.pem;
+        ssl_certificate_key /etc/letsencrypt/live/accounts.eagle0.net/privkey.pem;
+
+        ssl_protocols TLSv1.2 TLSv1.3;
+        ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
+        ssl_prefer_server_ciphers off;
+        ssl_session_timeout 1d;
+        ssl_session_cache shared:SSL:10m;
+        ssl_session_tickets off;
+
+        location / {
+            proxy_pass http://admin:8080;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
 }

scripts/build_mac_plugin.sh

@@ -8,3 +8,6 @@ ZIP_LOCATION=$(bazel cquery --config=mactools --output=files @net_eagle0_unity_g
 /usr/bin/unzip -o $ZIP_LOCATION -d src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins/
 
 /usr/bin/plutil -convert xml1 src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins/DarwinGodiceBundle.bundle/Contents/Info.plist
+
+/bin/echo "building sparkle plugin"
+./scripts/build_sparkle_plugin.sh

scripts/build_protos.sh

@@ -2,7 +2,67 @@
 
 set -euxo pipefail
 
-/bin/echo "build protos"
-mkdir -p src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins/Eagle0Protos/
-dotnet build src/main/csharp/net/eagle0/clients/unity/eagle0/protos/protos.csproj \
-    -o src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins/Eagle0Protos/
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+UNITY_ROOT="$REPO_ROOT/src/main/csharp/net/eagle0/clients/unity/eagle0"
+OUTPUT_DIR="$UNITY_ROOT/Assets/GeneratedProtos"
+
+# All C# protobuf generation targets
+TARGETS=(
+    "//src/main/protobuf/net/eagle0/common:common_csharp_proto_srcs"
+    "//src/main/protobuf/net/eagle0/shardok/storage:storage_csharp_proto_srcs"
+    "//src/main/protobuf/net/eagle0/shardok/common:common_csharp_proto_srcs"
+    "//src/main/protobuf/net/eagle0/shardok/api:api_csharp_proto_srcs"
+    "//src/main/protobuf/net/eagle0/eagle/common:common_csharp_proto_srcs"
+    "//src/main/protobuf/net/eagle0/eagle/views:views_csharp_proto_srcs"
+    "//src/main/protobuf/net/eagle0/eagle/api:api_csharp_proto_srcs"
+    "//src/main/protobuf/net/eagle0/eagle/api:api_csharp_grpc_srcs"
+    "//src/main/protobuf/net/eagle0/eagle/api/command/util:util_csharp_proto_srcs"
+)
+
+# Subdirectory for each target (avoids filename collisions across packages)
+SUBDIRS=(
+    "net/eagle0/common"
+    "net/eagle0/shardok/storage"
+    "net/eagle0/shardok/common"
+    "net/eagle0/shardok/api"
+    "net/eagle0/eagle/common"
+    "net/eagle0/eagle/views"
+    "net/eagle0/eagle/api"
+    "net/eagle0/eagle/api"
+    "net/eagle0/eagle/api/command/util"
+)
+
+/bin/echo "Building C# protobuf sources..."
+bazel build "${TARGETS[@]}"
+
+/bin/echo "Syncing generated .cs files to $OUTPUT_DIR..."
+
+# Stage new files in a temp directory, then rsync to preserve timestamps
+# on unchanged files. This avoids triggering Unity reimport when protos
+# haven't changed, saving ~7 minutes of script recompilation.
+STAGING_DIR=$(mktemp -d)
+trap "rm -rf '$STAGING_DIR'" EXIT
+
+for i in "${!TARGETS[@]}"; do
+    target="${TARGETS[$i]}"
+    subdir="${SUBDIRS[$i]}"
+
+    # Convert target label to bazel-bin path
+    # //src/main/protobuf/net/eagle0/common:common_csharp_proto_srcs
+    # -> bazel-bin/src/main/protobuf/net/eagle0/common/common_csharp_proto_srcs
+    target_path="${target#//}"
+    pkg="${target_path%%:*}"
+    name="${target_path##*:}"
+    bin_dir="$REPO_ROOT/bazel-bin/$pkg/$name"
+
+    dest_dir="$STAGING_DIR/$subdir"
+    mkdir -p "$dest_dir"
+    find "$bin_dir" -name "*.cs" -exec cp {} "$dest_dir/" \;
+done
+
+# Sync only changed files and delete removed ones; --checksum compares
+# content not timestamps so unchanged files keep their original mtime.
+mkdir -p "$OUTPUT_DIR"
+rsync -rc --delete "$STAGING_DIR/" "$OUTPUT_DIR/"
+
+/bin/echo "Done. Generated C# proto sources in $OUTPUT_DIR"

scripts/build_sparkle_plugin.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#
+# Build the SparklePlugin native library for Unity using Bazel
+#
+# The SparklePlugin is built in a separate Bazel workspace (sparkle_workspace/)
+# to avoid rules_swift version conflicts between grpc and rules_apple.
+#
+# Usage: build_sparkle_plugin.sh [output_dir]
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+OUTPUT_DIR="${1:-$PROJECT_ROOT/src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins/macOS}"
+
+echo "=== Building SparklePlugin with Bazel (from sparkle_workspace) ==="
+
+# Build in the separate sparkle_workspace to avoid dependency conflicts
+cd "$PROJECT_ROOT/sparkle_workspace"
+bazel build //:SparklePlugin
+
+# Get the zip path from bazel
+ZIP_PATH=$(bazel cquery --output=files //:SparklePlugin 2>/dev/null)
+
+echo "=== Extracting SparklePlugin.bundle ==="
+mkdir -p "$OUTPUT_DIR"
+rm -rf "$OUTPUT_DIR/SparklePlugin.bundle"
+unzip -o "$ZIP_PATH" -d "$OUTPUT_DIR/"
+
+# Convert Info.plist from binary to XML format (Unity requires XML)
+/usr/bin/plutil -convert xml1 "$OUTPUT_DIR/SparklePlugin.bundle/Contents/Info.plist"
+
+echo "=== SparklePlugin built successfully ==="
+ls -la "$OUTPUT_DIR/SparklePlugin.bundle/"

scripts/check_build_deps.sh

@@ -0,0 +1,150 @@
+#!/bin/bash
+# Check BUILD.bazel dependency constraints
+# This script enforces architectural boundaries in the codebase.
+#
+# Usage:
+#   ./scripts/check_build_deps.sh           # Check all rules
+#   ./scripts/check_build_deps.sh --ci      # CI mode (fail on any violation)
+#   ./scripts/check_build_deps.sh --count   # Just count current violations (for tracking progress)
+#   ./scripts/check_build_deps.sh --strict  # Same as --ci (strict enforcement)
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$REPO_ROOT"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+MODE="${1:-check}"
+EXIT_CODE=0
+
+# Cache for expensive bazel query results
+LIBRARY_DEPS_CACHE=""
+MAIN_DEPS_CACHE=""
+
+# Get deps of library/ (cached)
+get_library_deps() {
+    if [ -z "$LIBRARY_DEPS_CACHE" ]; then
+        LIBRARY_DEPS_CACHE=$(bazel query 'deps(//src/main/scala/net/eagle0/eagle/library/...)' 2>/dev/null || true)
+    fi
+    echo "$LIBRARY_DEPS_CACHE"
+}
+
+# Get deps of src/main (cached)
+get_main_deps() {
+    if [ -z "$MAIN_DEPS_CACHE" ]; then
+        MAIN_DEPS_CACHE=$(bazel query 'deps(//src/main/...)' 2>/dev/null || true)
+    fi
+    echo "$MAIN_DEPS_CACHE"
+}
+
+# Rule 1: src/main should not depend on src/test
+check_main_depends_on_test() {
+    echo -e "${YELLOW}Checking: src/main should not depend on src/test...${NC}"
+
+    violations=$(get_main_deps | grep "^//src/test/" || true)
+
+    if [ -n "$violations" ]; then
+        echo -e "${RED}VIOLATION: src/main depends on src/test:${NC}"
+        echo "$violations"
+        return 1
+    else
+        echo -e "${GREEN}✓ No violations${NC}"
+        return 0
+    fi
+}
+
+# Rule 2: library/ should not depend on Scala proto types
+# C++/Go proto deps are allowed (they're build-time deps for map generation tools)
+check_library_depends_on_scala_proto() {
+    echo -e "${YELLOW}Checking: library/ should not depend on Scala proto types...${NC}"
+
+    violations=$(get_library_deps | grep "^//src/main/protobuf/.*_scala_proto$" || true)
+    if [ -z "$violations" ]; then
+        count=0
+    else
+        count=$(echo "$violations" | grep -c "^//" || true)
+    fi
+
+    if [ "$count" -gt 0 ]; then
+        echo -e "${RED}VIOLATION: Found $count Scala proto dependencies in library/:${NC}"
+        echo "$violations"
+        return 1
+    else
+        echo -e "${GREEN}✓ No Scala proto dependencies in library/${NC}"
+        return 0
+    fi
+}
+
+# Rule 3: library/ should not depend on proto_converters
+# Proto conversions should happen at service boundaries, not in library code
+check_library_depends_on_proto_converters() {
+    echo -e "${YELLOW}Checking: library/ should not depend on proto_converters...${NC}"
+
+    violations=$(get_library_deps | grep "^//src/main/scala/net/eagle0/eagle/model/proto_converters/" || true)
+
+    if [ -n "$violations" ]; then
+        count=$(echo "$violations" | wc -l | tr -d ' ')
+        echo -e "${RED}VIOLATION: library/ depends on $count proto_converters targets:${NC}"
+        echo "$violations"
+        echo ""
+        echo "Proto conversions should happen at service boundaries (ShardokInterfaceGrpcClient,"
+        echo "EagleServiceImpl, etc.), not in library code."
+        return 1
+    else
+        echo -e "${GREEN}✓ No proto_converters dependencies in library/${NC}"
+        return 0
+    fi
+}
+
+# Count proto deps for informational purposes
+count_proto_deps() {
+    echo -e "${YELLOW}=== Proto dependency counts ===${NC}"
+
+    library_deps=$(get_library_deps)
+    scala_proto_results=$(echo "$library_deps" | grep "^//src/main/protobuf/.*_scala_proto$" || true)
+    if [ -z "$scala_proto_results" ]; then
+        scala_proto_count=0
+    else
+        scala_proto_count=$(echo "$scala_proto_results" | wc -l | tr -d ' ')
+    fi
+    echo "library/ Scala proto deps: $scala_proto_count"
+
+    # C++/Go proto deps are expected (map generation tools)
+    all_proto_count=$(echo "$library_deps" | grep -c "^//src/main/protobuf/" || echo "0")
+    echo "library/ all proto deps (includes C++/Go build tools): $all_proto_count"
+}
+
+echo "=== BUILD.bazel Dependency Check ==="
+echo ""
+
+case "$MODE" in
+    --count)
+        count_proto_deps
+        ;;
+    --ci|--strict)
+        check_main_depends_on_test || EXIT_CODE=1
+        check_library_depends_on_scala_proto || EXIT_CODE=1
+        check_library_depends_on_proto_converters || EXIT_CODE=1
+        ;;
+    *)
+        check_main_depends_on_test || EXIT_CODE=1
+        check_library_depends_on_scala_proto || EXIT_CODE=1
+        check_library_depends_on_proto_converters || EXIT_CODE=1
+        echo ""
+        count_proto_deps
+        ;;
+esac
+
+echo ""
+if [ $EXIT_CODE -eq 0 ]; then
+    echo -e "${GREEN}=== All checks passed ===${NC}"
+else
+    echo -e "${RED}=== Some checks failed ===${NC}"
+fi
+
+exit $EXIT_CODE

scripts/codesign_mac_app.sh

@@ -5,24 +5,58 @@
 #
 # Environment variables:
 #   SIGNING_IDENTITY - The signing identity (default: "Developer ID Application")
-#   KEYCHAIN_PASSWORD - Password to unlock the build keychain (optional)
+#   KEYCHAIN_PASSWORD - Password to unlock the keychain (optional, CI only)
+#   KEYCHAIN_NAME - Name of the keychain containing the signing certificate (optional, CI only)
+#                   When set, looks for certificate in this specific keychain.
+#                   When not set, searches all keychains (local dev mode).
 
 set -euxo pipefail
 
 APP_PATH="$1"
 ENTITLEMENTS_PATH="${2:-}"
 SIGNING_IDENTITY="${SIGNING_IDENTITY:-Developer ID Application}"
+# KEYCHAIN_NAME is set by CI workflow - don't set a default here so we can detect if we're in CI
 
 if [ ! -d "$APP_PATH" ]; then
     echo "ERROR: App not found at $APP_PATH"
     exit 1
 fi
 
-# Unlock keychain if password provided
-if [ -n "${KEYCHAIN_PASSWORD:-}" ]; then
-    security unlock-keychain -p "$KEYCHAIN_PASSWORD" build.keychain || true
+# Unlock keychain if password and keychain name are provided (CI environment)
+if [ -n "${KEYCHAIN_PASSWORD:-}" ] && [ -n "${KEYCHAIN_NAME:-}" ]; then
+    security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_NAME" || true
 fi
 
+# Get the SHA-1 hash of the signing certificate
+# Using the hash avoids "ambiguous" errors when the same identity exists in multiple keychains
+# We look in the build keychain specifically if KEYCHAIN_NAME is set (CI environment)
+# Otherwise fall back to searching all keychains (local dev)
+
+if [ -n "${KEYCHAIN_NAME:-}" ]; then
+    # CI environment: look for certificate in the build keychain specifically
+    KEYCHAIN_PATH="$HOME/Library/Keychains/${KEYCHAIN_NAME}-db"
+    echo "Looking for signing identity in build keychain: $KEYCHAIN_PATH"
+    echo "Available identities in build keychain:"
+    security find-identity -v -p codesigning "$KEYCHAIN_PATH"
+
+    CERT_HASH=$(security find-identity -v -p codesigning "$KEYCHAIN_PATH" | grep -E '^\s+[0-9]+\)' | head -1 | awk '{print $2}')
+else
+    # Local dev: search all keychains
+    echo "Available codesigning identities:"
+    security find-identity -v -p codesigning
+
+    CERT_HASH=$(security find-identity -v -p codesigning | grep -E '^\s+[0-9]+\)' | head -1 | awk '{print $2}')
+fi
+
+if [ -z "$CERT_HASH" ]; then
+    echo "ERROR: No valid signing identity found"
+    exit 1
+fi
+echo "Using certificate hash: $CERT_HASH"
+
+# Use the hash as the signing identity to avoid ambiguity
+SIGNING_IDENTITY="$CERT_HASH"
+
 echo "=== Signing nested components first ==="
 
 # Sign all dylibs
@@ -39,32 +73,51 @@ find "$APP_PATH" -name "*.bundle" -print0 | while IFS= read -r -d '' item; do
         --sign "$SIGNING_IDENTITY" "$item"
 done
 
-# Sign XPC services (inside Sparkle framework)
+# Sign XPC services (but skip ones inside Sparkle.framework - they're already signed)
 find "$APP_PATH" -name "*.xpc" -print0 | while IFS= read -r -d '' item; do
+    if [[ "$item" == *"Sparkle.framework"* ]]; then
+        echo "Skipping Sparkle XPC service (pre-signed): $item"
+        continue
+    fi
     echo "Signing XPC service: $item"
     codesign --force --verify --verbose --timestamp --options runtime \
         --sign "$SIGNING_IDENTITY" "$item"
 done
 
-# Sign nested apps (like Sparkle's Updater.app)
+# Sign nested apps (but skip ones inside Sparkle.framework - they're already signed)
 find "$APP_PATH" -path "*/Frameworks/*.app" -print0 | while IFS= read -r -d '' item; do
+    if [[ "$item" == *"Sparkle.framework"* ]]; then
+        echo "Skipping Sparkle nested app (pre-signed): $item"
+        continue
+    fi
     echo "Signing nested app: $item"
     codesign --force --verify --verbose --timestamp --options runtime \
         --sign "$SIGNING_IDENTITY" "$item"
 done
 
-# Sign standalone executables inside frameworks (like Autoupdate)
+# Sign standalone executables inside frameworks (but skip Sparkle.framework internals)
 find "$APP_PATH" -path "*/Frameworks/*/Versions/*/Autoupdate" -type f -print0 | while IFS= read -r -d '' item; do
+    if [[ "$item" == *"Sparkle.framework"* ]]; then
+        echo "Skipping Sparkle executable (pre-signed): $item"
+        continue
+    fi
     echo "Signing executable: $item"
     codesign --force --verify --verbose --timestamp --options runtime \
         --sign "$SIGNING_IDENTITY" "$item"
 done
 
 # Sign all frameworks (after their contents are signed)
+# Use --deep for Sparkle.framework to handle its XPC services
 find "$APP_PATH" -name "*.framework" -print0 | while IFS= read -r -d '' item; do
-    echo "Signing framework: $item"
-    codesign --force --verify --verbose --timestamp --options runtime \
-        --sign "$SIGNING_IDENTITY" "$item"
+    if [[ "$item" == *"Sparkle.framework" ]]; then
+        echo "Signing Sparkle framework with --deep: $item"
+        codesign --deep --force --verify --verbose --timestamp --options runtime \
+            --sign "$SIGNING_IDENTITY" "$item"
+    else
+        echo "Signing framework: $item"
+        codesign --force --verify --verbose --timestamp --options runtime \
+            --sign "$SIGNING_IDENTITY" "$item"
+    fi
 done
 
 echo "=== Signing main app bundle ==="

scripts/deploy-blue-green.sh

@@ -35,6 +35,7 @@ WARMUP_SCRIPT="${SCRIPT_DIR}/warmup-eagle.sh"
 SAVES_DIR="${APP_DIR}/saves"
 FLUSH_MARKER="${SAVES_DIR}/.flush_complete"
 DEPLOYMENT_IN_PROGRESS="${SAVES_DIR}/.deployment_in_progress"
+ACTIVE_INSTANCE_FILE="${APP_DIR}/.active-instance"
 
 # Colors for output
 RED='\033[0;31m'
@@ -264,7 +265,8 @@ main() {
     fi
 
     # Recreate nginx to pick up new config
-    docker compose -f "${COMPOSE_FILE}" up -d --force-recreate nginx
+    # Use --no-deps to prevent cascading to auth (which has secrets not available here)
+    docker compose -f "${COMPOSE_FILE}" up -d --force-recreate --no-deps nginx
 
     # Verify nginx picked up the correct config
     local nginx_backend
@@ -297,6 +299,10 @@ main() {
     create_flush_marker "${deploy_id}" "eagle-${staging}"
     log_info "[DEPLOY:${deploy_id}] Flush marker created - server will auto-invalidate stale cache"
 
+    # Write active instance file for eagle-exec helper
+    echo "eagle-${staging}" > "${ACTIVE_INSTANCE_FILE}"
+    log_info "[DEPLOY:${deploy_id}] Active instance file updated: eagle-${staging}"
+
     # Update .env for admin service
     local env_file="${APP_DIR}/.env"
     if [ "$staging" = "green" ]; then
@@ -311,9 +317,22 @@ main() {
         echo "JFR_SIDECAR_ADDR=jfr-sidecar:8081" >> "${env_file}"
     fi
 
-    # Restart admin to pick up new .env
+    # Restart admin to pick up new .env and ensure latest image
+    # Use --no-deps to prevent cascading to auth (which has secrets not available here)
     log_info "Restarting admin service..."
-    docker compose -f "${COMPOSE_FILE}" up -d --force-recreate admin
+    docker compose -f "${COMPOSE_FILE}" up -d --force-recreate --no-deps admin
+
+    # Verify admin container is running
+    sleep 3
+    if ! docker inspect admin-server --format '{{.State.Running}}' 2>/dev/null | grep -q "true"; then
+        log_error "Admin container failed to start!"
+        log_error "Container logs:"
+        docker logs admin-server --tail 20 2>&1 || true
+        log_error "Container inspect:"
+        docker inspect admin-server 2>&1 | head -50 || true
+        exit 1
+    fi
+    log_info "Admin service restarted successfully"
 
     # Clean up old instance
     log_info "Cleaning up old eagle-${active}..."

scripts/downloadTsvs.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 
 curl -L "https://docs.google.com/spreadsheets/d/1DHEsiv4cY4gE6AX3sVH82K__mpBD1aznIYCQwQxA_F0/export?gid=0&format=tsv" | tr -d '\r' > /tmp/names.tsv
-bazel run //src/main/scala/net/eagle0/util:name_list_checker -- /tmp/names.tsv > src/main/resources/net/eagle0/names.tsv
+bazel run //src/main/scala/net/eagle0/util:name_list_checker -- /tmp/names.tsv > /dev/null
 bazel run //src/main/scala/net/eagle0/util:name_list_json_maker -- /tmp/names.tsv > src/main/resources/net/eagle0/names.json
 curl -L "https://docs.google.com/spreadsheets/d/1NhvG73HKyVE36yGpkV2oJiSIXoNqQOYTr5ArLnucYL0/export?gid=0&format=tsv" | tr -d '\r' > src/main/resources/net/eagle0/shardok/battalionTypes.tsv
 curl -L "https://docs.google.com/spreadsheets/d/1pNWiyxIks2wJ1v7jRLFD24zrKHG2AfhC-nkWmQKQGN4/export?gid=0&format=tsv" | tr -d '\r' > src/main/resources/net/eagle0/eagle/heroes.tsv

scripts/eagle-exec.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+#
+# Helper to run docker exec against the active Eagle instance.
+# Reads the active instance from /opt/eagle0/.active-instance (set by deploy-blue-green.sh).
+#
+# Usage:
+#   eagle-exec printenv GEMINI_API_KEY
+#   eagle-exec jcmd 1 VM.flags
+#   eagle-exec sh    # Get a shell
+#
+# To create an alias, add to ~/.bashrc:
+#   alias eagle-exec='/opt/eagle0/scripts/eagle-exec.sh'
+#
+
+set -euo pipefail
+
+APP_DIR="${APP_DIR:-/opt/eagle0}"
+ACTIVE_FILE="${APP_DIR}/.active-instance"
+
+# Read active instance from file, with fallback
+if [ -f "$ACTIVE_FILE" ]; then
+    ACTIVE=$(cat "$ACTIVE_FILE")
+else
+    # Fallback: check which container is actually running
+    if docker inspect --format='{{.State.Running}}' eagle-blue 2>/dev/null | grep -q true; then
+        ACTIVE="eagle-blue"
+    elif docker inspect --format='{{.State.Running}}' eagle-green 2>/dev/null | grep -q true; then
+        ACTIVE="eagle-green"
+    else
+        ACTIVE=""
+    fi
+fi
+
+if [ -z "$ACTIVE" ]; then
+    echo "Error: No active Eagle instance found" >&2
+    exit 1
+fi
+
+if [ $# -eq 0 ]; then
+    echo "Active instance: $ACTIVE"
+    echo "Usage: $0 <command> [args...]"
+    echo "Example: $0 printenv GEMINI_API_KEY"
+    exit 0
+fi
+
+exec docker exec "$ACTIVE" "$@"

scripts/eagle-logs.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+#
+# Helper to tail logs from the active Eagle instance.
+# Reads the active instance from /opt/eagle0/.active-instance (set by deploy-blue-green.sh).
+#
+# Usage:
+#   eagle-logs           # Tail logs (follow mode)
+#   eagle-logs -n 100    # Show last 100 lines and follow
+#   eagle-logs --no-follow -n 50   # Show last 50 lines without following
+#
+# To create an alias, add to ~/.bashrc:
+#   alias eagle-logs='/opt/eagle0/scripts/eagle-logs.sh'
+#
+
+set -euo pipefail
+
+APP_DIR="${APP_DIR:-/opt/eagle0}"
+ACTIVE_FILE="${APP_DIR}/.active-instance"
+
+# Read active instance from file, with fallback
+if [ -f "$ACTIVE_FILE" ]; then
+    ACTIVE=$(cat "$ACTIVE_FILE")
+else
+    # Fallback: check which container is actually running
+    if docker inspect --format='{{.State.Running}}' eagle-blue 2>/dev/null | grep -q true; then
+        ACTIVE="eagle-blue"
+    elif docker inspect --format='{{.State.Running}}' eagle-green 2>/dev/null | grep -q true; then
+        ACTIVE="eagle-green"
+    else
+        ACTIVE=""
+    fi
+fi
+
+if [ -z "$ACTIVE" ]; then
+    echo "Error: No active Eagle instance found" >&2
+    exit 1
+fi
+
+# Default to follow mode if no args provided
+if [ $# -eq 0 ]; then
+    exec docker logs -f "$ACTIVE"
+else
+    exec docker logs "$@" "$ACTIVE"
+fi

scripts/eagle-restart.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+#
+# Restart the active Eagle instance.
+# Reads the active instance from /opt/eagle0/.active-instance (set by deploy-blue-green.sh).
+#
+# This is useful when you need Eagle to reload game state from persistence
+# (e.g., after a rewind) without doing a full blue-green deployment.
+#
+# Usage:
+#   eagle-restart              # Restart active instance, wait for healthy
+#   eagle-restart --no-wait    # Restart without waiting for health check
+#
+# To create an alias, add to ~/.bashrc:
+#   alias eagle-restart='/opt/eagle0/scripts/eagle-restart.sh'
+#
+
+set -euo pipefail
+
+APP_DIR="${APP_DIR:-/opt/eagle0}"
+ACTIVE_FILE="${APP_DIR}/.active-instance"
+HEALTH_TIMEOUT=120  # seconds
+
+# Read active instance from file, with fallback
+if [ -f "$ACTIVE_FILE" ]; then
+    ACTIVE=$(cat "$ACTIVE_FILE")
+else
+    # Fallback: check which container is actually running
+    if docker inspect --format='{{.State.Running}}' eagle-blue 2>/dev/null | grep -q true; then
+        ACTIVE="eagle-blue"
+    elif docker inspect --format='{{.State.Running}}' eagle-green 2>/dev/null | grep -q true; then
+        ACTIVE="eagle-green"
+    else
+        ACTIVE=""
+    fi
+fi
+
+if [ -z "$ACTIVE" ]; then
+    echo "Error: No active Eagle instance found" >&2
+    exit 1
+fi
+
+NO_WAIT=false
+if [ "${1:-}" = "--no-wait" ]; then
+    NO_WAIT=true
+fi
+
+echo "Restarting ${ACTIVE}..."
+docker restart "$ACTIVE"
+
+if [ "$NO_WAIT" = true ]; then
+    echo "Restart initiated. Not waiting for health check."
+    exit 0
+fi
+
+echo "Waiting for ${ACTIVE} to become healthy (timeout: ${HEALTH_TIMEOUT}s)..."
+elapsed=0
+while [ $elapsed -lt $HEALTH_TIMEOUT ]; do
+    health=$(docker inspect --format='{{.State.Health.Status}}' "$ACTIVE" 2>/dev/null || echo "unknown")
+    if [ "$health" = "healthy" ]; then
+        echo "${ACTIVE} is healthy after ${elapsed}s."
+        exit 0
+    fi
+    sleep 2
+    elapsed=$((elapsed + 2))
+    # Print progress every 10 seconds
+    if [ $((elapsed % 10)) -eq 0 ]; then
+        echo "  ...${elapsed}s (status: ${health})"
+    fi
+done
+
+echo "Warning: ${ACTIVE} did not become healthy within ${HEALTH_TIMEOUT}s (status: ${health})" >&2
+echo "Check logs with: eagle-logs" >&2
+exit 1

scripts/generate_changelog.sh

@@ -373,6 +373,115 @@ send_email_fastmail() {
     echo "Email sent successfully"
 }
 
+# Generate player-friendly "What's New" summary
+# This creates a short summary suitable for in-game display
+generate_whats_new_summary() {
+    local pr_file="$1"
+    local output_file="/tmp/eagle0_whats_new_$$.txt"
+
+    echo "Generating player-friendly What's New summary..." >&2
+
+    # Create a prompt for player-facing summary
+    local prompt_file="/tmp/eagle0_whats_new_prompt_$$.txt"
+
+    cat > "$prompt_file" <<'WHATS_NEW_PROMPT'
+Based on these merged PRs, write a SHORT player-friendly summary.
+Focus only on changes players will notice. Ignore internal/technical changes.
+
+Output format (exactly this format, no markdown, no extra text):
+TITLE: (5-10 words describing the main change)
+DESCRIPTION: (1-2 sentences, what players can now do differently)
+CATEGORY: (one of: feature, improvement, fix, content)
+
+If there are multiple notable player-visible changes, pick the single most important one.
+If there are no player-visible changes at all, output exactly: NONE
+
+Examples of good output:
+TITLE: Bug Reporting
+DESCRIPTION: You can now report bugs directly from the Settings menu.
+CATEGORY: feature
+
+TITLE: Faster Reconnection
+DESCRIPTION: The game now reconnects more smoothly after network interruptions.
+CATEGORY: improvement
+
+Here are the merged PRs:
+
+WHATS_NEW_PROMPT
+
+    cat "$pr_file" >> "$prompt_file"
+
+    # Use Claude CLI to generate the summary
+    if ! command -v claude &> /dev/null; then
+        echo "NONE"
+        rm -f "$prompt_file"
+        return
+    fi
+
+    cat "$prompt_file" | claude --print > "$output_file" 2>/dev/null
+
+    rm -f "$prompt_file"
+
+    # Check if the output is NONE
+    if grep -q "^NONE$" "$output_file"; then
+        echo "NONE"
+        rm -f "$output_file"
+        return
+    fi
+
+    # Return the output
+    cat "$output_file"
+    rm -f "$output_file"
+}
+
+# URL encode a string for use in query parameters
+urlencode() {
+    local string="$1"
+    local strlen=${#string}
+    local encoded=""
+    local pos c o
+
+    for (( pos=0 ; pos<strlen ; pos++ )); do
+        c=${string:$pos:1}
+        case "$c" in
+            [-_.~a-zA-Z0-9] ) o="${c}" ;;
+            * )               printf -v o '%%%02x' "'$c"
+        esac
+        encoded+="${o}"
+    done
+    echo "${encoded}"
+}
+
+# Open the admin console with pre-populated what's new content
+open_whats_new_preview() {
+    local title="$1"
+    local description="$2"
+    local category="$3"
+
+    local encoded_title=$(urlencode "$title")
+    local encoded_desc=$(urlencode "$description")
+    local encoded_cat=$(urlencode "$category")
+
+    local preview_url="https://admin.eagle0.net/whats-new?preview=true&title=${encoded_title}&description=${encoded_desc}&category=${encoded_cat}"
+
+    echo ""
+    echo "=== What's New Preview ==="
+    echo "Title: $title"
+    echo "Description: $description"
+    echo "Category: $category"
+    echo ""
+    echo "Opening admin console preview..."
+
+    # Open the URL in the default browser
+    if [[ "$(uname)" == "Darwin" ]]; then
+        open "$preview_url"
+    elif command -v xdg-open &> /dev/null; then
+        xdg-open "$preview_url"
+    else
+        echo "Preview URL: $preview_url"
+    fi
+}
+
 # Update the tag to mark this run
 update_tag() {
     echo "Updating $TAG_NAME tag..."
@@ -462,6 +571,26 @@ main() {
 
         # Update tag for next run
         update_tag
+
+        # Generate player-friendly What's New summary and open admin preview
+        echo ""
+        echo "Generating What's New summary for in-game display..."
+        whats_new_output=$(generate_whats_new_summary "$pr_file")
+
+        if [[ "$whats_new_output" != "NONE" ]]; then
+            # Parse the output
+            title=$(echo "$whats_new_output" | grep "^TITLE:" | sed 's/^TITLE:[[:space:]]*//')
+            description=$(echo "$whats_new_output" | grep "^DESCRIPTION:" | sed 's/^DESCRIPTION:[[:space:]]*//')
+            category=$(echo "$whats_new_output" | grep "^CATEGORY:" | sed 's/^CATEGORY:[[:space:]]*//')
+
+            if [[ -n "$title" && -n "$description" ]]; then
+                open_whats_new_preview "$title" "$description" "$category"
+            else
+                echo "Could not parse What's New output, skipping preview"
+            fi
+        else
+            echo "No player-visible changes detected, skipping What's New preview"
+        fi
     fi
 
     echo ""

scripts/inject_sparkle.sh

@@ -27,33 +27,59 @@ if [ -z "${SPARKLE_EDDSA_PUBLIC_KEY:-}" ]; then
     exit 1
 fi
 
-# Download Sparkle if not cached
+# Always use a fresh Sparkle download to avoid cache corruption issues
 SPARKLE_DIR="$SPARKLE_CACHE_DIR/Sparkle-$SPARKLE_VERSION"
-if [ ! -d "$SPARKLE_DIR/Sparkle.framework" ]; then
-    echo "=== Downloading Sparkle $SPARKLE_VERSION ==="
-    mkdir -p "$SPARKLE_CACHE_DIR"
-    SPARKLE_URL="https://github.com/sparkle-project/Sparkle/releases/download/${SPARKLE_VERSION}/Sparkle-${SPARKLE_VERSION}.tar.xz"
-    curl -L "$SPARKLE_URL" | tar -xJ -C "$SPARKLE_CACHE_DIR"
-    mv "$SPARKLE_CACHE_DIR/Sparkle-$SPARKLE_VERSION" "$SPARKLE_DIR" 2>/dev/null || true
-    # If the extracted directory doesn't match version pattern, it may just be "Sparkle"
-    if [ ! -d "$SPARKLE_DIR" ]; then
-        mkdir -p "$SPARKLE_DIR"
-        mv "$SPARKLE_CACHE_DIR/Sparkle.framework" "$SPARKLE_DIR/" 2>/dev/null || true
-        mv "$SPARKLE_CACHE_DIR/bin" "$SPARKLE_DIR/" 2>/dev/null || true
-    fi
+echo "=== Clearing Sparkle cache and downloading fresh copy ==="
+rm -rf "$SPARKLE_DIR"
+mkdir -p "$SPARKLE_DIR"
+
+SPARKLE_URL="https://github.com/sparkle-project/Sparkle/releases/download/${SPARKLE_VERSION}/Sparkle-${SPARKLE_VERSION}.tar.xz"
+echo "Downloading from: $SPARKLE_URL"
+curl -L "$SPARKLE_URL" -o /tmp/sparkle.tar.xz
+tar -xJf /tmp/sparkle.tar.xz -C "$SPARKLE_DIR"
+rm /tmp/sparkle.tar.xz
+
+# Show what was extracted
+echo "=== Extracted contents ==="
+ls -la "$SPARKLE_DIR/"
+
+# The tarball extracts files directly, not into a subdirectory
+# Verify the framework has proper symlink structure
+echo "=== Verifying Sparkle.framework structure ==="
+ls -la "$SPARKLE_DIR/Sparkle.framework/"
+
+if [ ! -L "$SPARKLE_DIR/Sparkle.framework/Sparkle" ]; then
+    echo "ERROR: Sparkle.framework/Sparkle is not a symlink"
+    file "$SPARKLE_DIR/Sparkle.framework/Sparkle"
+    exit 1
 fi
 
+if [ ! -L "$SPARKLE_DIR/Sparkle.framework/Versions/Current" ]; then
+    echo "ERROR: Sparkle.framework/Versions/Current is not a symlink"
+    ls -la "$SPARKLE_DIR/Sparkle.framework/Versions/"
+    exit 1
+fi
+
+echo "Sparkle framework structure verified OK"
+
 echo "=== Injecting Sparkle framework ==="
 FRAMEWORKS_DIR="$APP_PATH/Contents/Frameworks"
 mkdir -p "$FRAMEWORKS_DIR"
 
-# Copy Sparkle framework
-cp -R "$SPARKLE_DIR/Sparkle.framework" "$FRAMEWORKS_DIR/"
+# Remove any existing Sparkle.framework in the app
+rm -rf "$FRAMEWORKS_DIR/Sparkle.framework"
 
-# Also copy the XPC services if present
-if [ -d "$SPARKLE_DIR/Sparkle.framework/Versions/B/XPCServices" ]; then
-    echo "Sparkle XPC services present"
+# Copy Sparkle framework (use ditto to preserve symlinks and bundle structure)
+ditto "$SPARKLE_DIR/Sparkle.framework" "$FRAMEWORKS_DIR/Sparkle.framework"
+
+# Verify the copied framework still has proper structure
+echo "=== Verifying copied Sparkle.framework structure ==="
+ls -la "$FRAMEWORKS_DIR/Sparkle.framework/"
+if [ ! -L "$FRAMEWORKS_DIR/Sparkle.framework/Sparkle" ]; then
+    echo "ERROR: Copied framework lost symlink structure"
+    exit 1
 fi
+echo "Copied framework structure OK"
 
 echo "=== Updating Info.plist ==="
 PLIST_PATH="$APP_PATH/Contents/Info.plist"
@@ -69,8 +95,9 @@ PLIST_PATH="$APP_PATH/Contents/Info.plist"
 /usr/libexec/PlistBuddy -c "Add :SUEnableAutomaticChecks bool true" "$PLIST_PATH"
 
 # Set bundle version from git for Sparkle version comparison
-VERSION=$(git describe --tags --always 2>/dev/null || echo "1.0.0")
+# Use commit count for automatic incrementing versions (e.g., 1.0.9548)
 BUILD_NUMBER=$(git rev-list --count HEAD 2>/dev/null || echo "1")
+VERSION="1.0.${BUILD_NUMBER}"
 
 echo "Setting version: $VERSION (build $BUILD_NUMBER)"
 /usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString $VERSION" "$PLIST_PATH" 2>/dev/null || \
@@ -83,7 +110,7 @@ echo "=== Adding URL scheme for invitation codes ==="
 /usr/libexec/PlistBuddy -c "Delete :CFBundleURLTypes" "$PLIST_PATH" 2>/dev/null || true
 /usr/libexec/PlistBuddy -c "Add :CFBundleURLTypes array" "$PLIST_PATH"
 /usr/libexec/PlistBuddy -c "Add :CFBundleURLTypes:0 dict" "$PLIST_PATH"
-/usr/libexec/PlistBuddy -c "Add :CFBundleURLTypes:0:CFBundleURLName string 'com.Shardok-Games.eagle0'" "$PLIST_PATH"
+/usr/libexec/PlistBuddy -c "Add :CFBundleURLTypes:0:CFBundleURLName string 'net.eagle0.eagle0'" "$PLIST_PATH"
 /usr/libexec/PlistBuddy -c "Add :CFBundleURLTypes:0:CFBundleURLSchemes array" "$PLIST_PATH"
 /usr/libexec/PlistBuddy -c "Add :CFBundleURLTypes:0:CFBundleURLSchemes:0 string 'eagle0'" "$PLIST_PATH"
 

scripts/notarize_wait.sh

@@ -50,22 +50,34 @@ if [ "$STATUS" != "Accepted" ]; then
     exit 1
 fi
 
+echo "=== Verifying code signature before stapling ==="
+if ! codesign --verify --deep --strict "$APP_PATH" 2>&1; then
+    echo "ERROR: Code signature verification failed - app may have been damaged during transfer"
+    echo "Attempting to show signature details:"
+    codesign -dvvv "$APP_PATH" 2>&1 || true
+    exit 1
+fi
+echo "Code signature verified successfully"
+
 echo "=== Stapling notarization ticket to app ==="
-# Retry stapling - Apple's CloudKit can have a brief delay after notarization completes
-MAX_STAPLE_ATTEMPTS=5
+# Retry stapling - Apple's CloudKit can take several minutes to propagate the ticket
+MAX_STAPLE_ATTEMPTS=10
+STAPLE_WAIT_SECONDS=30
 STAPLE_ATTEMPT=1
 while [ $STAPLE_ATTEMPT -le $MAX_STAPLE_ATTEMPTS ]; do
     echo "Stapling attempt $STAPLE_ATTEMPT/$MAX_STAPLE_ATTEMPTS..."
-    if xcrun stapler staple "$APP_PATH"; then
+    if STAPLE_OUTPUT=$(xcrun stapler staple "$APP_PATH" 2>&1); then
+        echo "$STAPLE_OUTPUT"
         echo "Stapling successful"
         break
     fi
+    echo "Stapler output: $STAPLE_OUTPUT"
     if [ $STAPLE_ATTEMPT -eq $MAX_STAPLE_ATTEMPTS ]; then
-        echo "ERROR: Stapling failed after $MAX_STAPLE_ATTEMPTS attempts"
+        echo "ERROR: Stapling failed after $MAX_STAPLE_ATTEMPTS attempts (total wait: $((MAX_STAPLE_ATTEMPTS * STAPLE_WAIT_SECONDS)) seconds)"
         exit 1
     fi
-    echo "Stapling failed, waiting 10 seconds before retry..."
-    sleep 10
+    echo "Stapling failed, waiting $STAPLE_WAIT_SECONDS seconds before retry..."
+    sleep $STAPLE_WAIT_SECONDS
     STAPLE_ATTEMPT=$((STAPLE_ATTEMPT + 1))
 done
 

sparkle_workspace/.bazelversion

@@ -0,0 +1 @@
+7.7.1

sparkle_workspace/.gitignore

@@ -0,0 +1,2 @@
+# Bazel symlinks
+bazel-*

sparkle_workspace/BUILD.bazel

@@ -0,0 +1,44 @@
+load("@build_bazel_rules_apple//apple:macos.bzl", "macos_bundle")
+
+# Native Sparkle plugin for Unity
+# This plugin initializes Sparkle auto-updater at runtime
+objc_library(
+    name = "sparkle_plugin_lib",
+    srcs = ["SparklePlugin.m"],
+    copts = [
+        "-fmodules",
+        "-fobjc-arc",
+        "-fvisibility=default",  # Export symbols for Unity P/Invoke
+    ],
+    sdk_frameworks = ["Foundation"],
+    deps = ["@sparkle//:Sparkle"],
+)
+
+macos_bundle(
+    name = "SparklePlugin",
+    bundle_id = "net.eagle0.SparklePlugin",
+    bundle_name = "SparklePlugin",
+    infoplists = ["Info.plist"],
+    linkopts = [
+        # Export symbols for Unity P/Invoke
+        "-exported_symbol",
+        "_SparklePlugin_Initialize",
+        "-exported_symbol",
+        "_SparklePlugin_CheckForUpdates",
+        "-exported_symbol",
+        "_SparklePlugin_CheckForUpdatesInBackground",
+        "-exported_symbol",
+        "_SparklePlugin_IsCheckingForUpdates",
+        "-exported_symbol",
+        "_SparklePlugin_GetAutomaticallyChecksForUpdates",
+        "-exported_symbol",
+        "_SparklePlugin_SetAutomaticallyChecksForUpdates",
+        "-exported_symbol",
+        "_SparklePlugin_IsRunningFromReadOnlyVolume",
+        "-exported_symbol",
+        "_SparklePlugin_ShowDMGWarning",
+    ],
+    minimum_os_version = "10.13",
+    visibility = ["//visibility:public"],
+    deps = [":sparkle_plugin_lib"],
+)

sparkle_workspace/Info.plist

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleDevelopmentRegion</key>
+    <string>en</string>
+    <key>CFBundleExecutable</key>
+    <string>SparklePlugin</string>
+    <key>CFBundleIdentifier</key>
+    <string>net.eagle0.SparklePlugin</string>
+    <key>CFBundleInfoDictionaryVersion</key>
+    <string>6.0</string>
+    <key>CFBundleName</key>
+    <string>SparklePlugin</string>
+    <key>CFBundlePackageType</key>
+    <string>BNDL</string>
+    <key>CFBundleShortVersionString</key>
+    <string>1.0</string>
+    <key>CFBundleVersion</key>
+    <string>1</string>
+</dict>
+</plist>

sparkle_workspace/MODULE.bazel

@@ -0,0 +1,28 @@
+module(name = "sparkle_workspace")
+
+# Minimal dependencies for building SparklePlugin
+# This workspace is isolated from the main workspace to avoid
+# rules_swift version conflicts between grpc and rules_apple
+
+bazel_dep(name = "apple_support", version = "1.21.1", repo_name = "build_bazel_apple_support")
+bazel_dep(name = "rules_apple", version = "4.3.3", repo_name = "build_bazel_rules_apple")
+
+# Register Apple CC toolchain for Objective-C compilation
+apple_cc_configure = use_extension(
+    "@build_bazel_apple_support//crosstool:setup.bzl",
+    "apple_cc_configure_extension",
+)
+use_repo(apple_cc_configure, "local_config_apple_cc")
+
+# Sparkle framework for macOS auto-updates
+http_archive = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+SPARKLE_VERSION = "2.6.4"
+
+http_archive(
+    name = "sparkle",
+    build_file = "//:external/BUILD.sparkle",
+    sha256 = "50612a06038abc931f16011d7903b8326a362c1074dabccb718404ce8e585f0b",
+    strip_prefix = "",
+    url = "https://github.com/sparkle-project/Sparkle/releases/download/%s/Sparkle-%s.tar.xz" % (SPARKLE_VERSION, SPARKLE_VERSION),
+)

sparkle_workspace/MODULE.bazel.lock

@@ -0,0 +1,451 @@
+{
+  "lockFileVersion": 13,
+  "registryFileHashes": {
+    "https://bcr.bazel.build/bazel_registry.json": "8a28e4aff06ee60aed2a8c281907fb8bcbf3b753c91fb5a5c57da3215d5b3497",
+    "https://bcr.bazel.build/modules/abseil-cpp/20210324.2/MODULE.bazel": "7cd0312e064fde87c8d1cd79ba06c876bd23630c83466e9500321be55c96ace2",
+    "https://bcr.bazel.build/modules/abseil-cpp/20211102.0/MODULE.bazel": "70390338f7a5106231d20620712f7cccb659cd0e9d073d1991c038eb9fc57589",
+    "https://bcr.bazel.build/modules/abseil-cpp/20230125.1/MODULE.bazel": "89047429cb0207707b2dface14ba7f8df85273d484c2572755be4bab7ce9c3a0",
+    "https://bcr.bazel.build/modules/abseil-cpp/20230802.0.bcr.1/MODULE.bazel": "1c8cec495288dccd14fdae6e3f95f772c1c91857047a098fad772034264cc8cb",
+    "https://bcr.bazel.build/modules/abseil-cpp/20230802.0/MODULE.bazel": "d253ae36a8bd9ee3c5955384096ccb6baf16a1b1e93e858370da0a3b94f77c16",
+    "https://bcr.bazel.build/modules/abseil-cpp/20230802.1/MODULE.bazel": "fa92e2eb41a04df73cdabeec37107316f7e5272650f81d6cc096418fe647b915",
+    "https://bcr.bazel.build/modules/abseil-cpp/20240116.1/MODULE.bazel": "37bcdb4440fbb61df6a1c296ae01b327f19e9bb521f9b8e26ec854b6f97309ed",
+    "https://bcr.bazel.build/modules/abseil-cpp/20240116.1/source.json": "9be551b8d4e3ef76875c0d744b5d6a504a27e3ae67bc6b28f46415fd2d2957da",
+    "https://bcr.bazel.build/modules/apple_support/1.11.1/MODULE.bazel": "1843d7cd8a58369a444fc6000e7304425fba600ff641592161d9f15b179fb896",
+    "https://bcr.bazel.build/modules/apple_support/1.15.1/MODULE.bazel": "a0556fefca0b1bb2de8567b8827518f94db6a6e7e7d632b4c48dc5f865bc7c85",
+    "https://bcr.bazel.build/modules/apple_support/1.21.1/MODULE.bazel": "5809fa3efab15d1f3c3c635af6974044bac8a4919c62238cce06acee8a8c11f1",
+    "https://bcr.bazel.build/modules/apple_support/1.23.1/MODULE.bazel": "53763fed456a968cf919b3240427cf3a9d5481ec5466abc9d5dc51bc70087442",
+    "https://bcr.bazel.build/modules/apple_support/1.23.1/source.json": "d888b44312eb0ad2c21a91d026753f330caa48a25c9b2102fae75eb2b0dcfdd2",
+    "https://bcr.bazel.build/modules/bazel_features/1.1.1/MODULE.bazel": "27b8c79ef57efe08efccbd9dd6ef70d61b4798320b8d3c134fd571f78963dbcd",
+    "https://bcr.bazel.build/modules/bazel_features/1.11.0/MODULE.bazel": "f9382337dd5a474c3b7d334c2f83e50b6eaedc284253334cf823044a26de03e8",
+    "https://bcr.bazel.build/modules/bazel_features/1.15.0/MODULE.bazel": "d38ff6e517149dc509406aca0db3ad1efdd890a85e049585b7234d04238e2a4d",
+    "https://bcr.bazel.build/modules/bazel_features/1.17.0/MODULE.bazel": "039de32d21b816b47bd42c778e0454217e9c9caac4a3cf8e15c7231ee3ddee4d",
+    "https://bcr.bazel.build/modules/bazel_features/1.18.0/MODULE.bazel": "1be0ae2557ab3a72a57aeb31b29be347bcdc5d2b1eb1e70f39e3851a7e97041a",
+    "https://bcr.bazel.build/modules/bazel_features/1.19.0/MODULE.bazel": "59adcdf28230d220f0067b1f435b8537dd033bfff8db21335ef9217919c7fb58",
+    "https://bcr.bazel.build/modules/bazel_features/1.21.0/MODULE.bazel": "675642261665d8eea09989aa3b8afb5c37627f1be178382c320d1b46afba5e3b",
+    "https://bcr.bazel.build/modules/bazel_features/1.27.0/MODULE.bazel": "621eeee06c4458a9121d1f104efb80f39d34deff4984e778359c60eaf1a8cb65",
+    "https://bcr.bazel.build/modules/bazel_features/1.28.0/MODULE.bazel": "4b4200e6cbf8fa335b2c3f43e1d6ef3e240319c33d43d60cc0fbd4b87ece299d",
+    "https://bcr.bazel.build/modules/bazel_features/1.3.0/MODULE.bazel": "cdcafe83ec318cda34e02948e81d790aab8df7a929cec6f6969f13a489ccecd9",
+    "https://bcr.bazel.build/modules/bazel_features/1.30.0/MODULE.bazel": "a14b62d05969a293b80257e72e597c2da7f717e1e69fa8b339703ed6731bec87",
+    "https://bcr.bazel.build/modules/bazel_features/1.30.0/source.json": "b07e17f067fe4f69f90b03b36ef1e08fe0d1f3cac254c1241a1818773e3423bc",
+    "https://bcr.bazel.build/modules/bazel_features/1.4.1/MODULE.bazel": "e45b6bb2350aff3e442ae1111c555e27eac1d915e77775f6fdc4b351b758b5d7",
+    "https://bcr.bazel.build/modules/bazel_skylib/1.0.3/MODULE.bazel": "bcb0fd896384802d1ad283b4e4eb4d718eebd8cb820b0a2c3a347fb971afd9d8",
+    "https://bcr.bazel.build/modules/bazel_skylib/1.1.1/MODULE.bazel": "1add3e7d93ff2e6998f9e118022c84d163917d912f5afafb3058e3d2f1545b5e",
+    "https://bcr.bazel.build/modules/bazel_skylib/1.2.0/MODULE.bazel": "44fe84260e454ed94ad326352a698422dbe372b21a1ac9f3eab76eb531223686",
+    "https://bcr.bazel.build/modules/bazel_skylib/1.2.1/MODULE.bazel": "f35baf9da0efe45fa3da1696ae906eea3d615ad41e2e3def4aeb4e8bc0ef9a7a",
+    "https://bcr.bazel.build/modules/bazel_skylib/1.3.0/MODULE.bazel": "20228b92868bf5cfc41bda7afc8a8ba2a543201851de39d990ec957b513579c5",
+    "https://bcr.bazel.build/modules/bazel_skylib/1.4.1/MODULE.bazel": "a0dcb779424be33100dcae821e9e27e4f2901d9dfd5333efe5ac6a8d7ab75e1d",
+    "https://bcr.bazel.build/modules/bazel_skylib/1.4.2/MODULE.bazel": "3bd40978e7a1fac911d5989e6b09d8f64921865a45822d8b09e815eaa726a651",
+    "https://bcr.bazel.build/modules/bazel_skylib/1.5.0/MODULE.bazel": "32880f5e2945ce6a03d1fbd588e9198c0a959bb42297b2cfaf1685b7bc32e138",
+    "https://bcr.bazel.build/modules/bazel_skylib/1.6.1/MODULE.bazel": "8fdee2dbaace6c252131c00e1de4b165dc65af02ea278476187765e1a617b917",
+    "https://bcr.bazel.build/modules/bazel_skylib/1.7.0/MODULE.bazel": "0db596f4563de7938de764cc8deeabec291f55e8ec15299718b93c4423e9796d",
+    "https://bcr.bazel.build/modules/bazel_skylib/1.7.1/MODULE.bazel": "3120d80c5861aa616222ec015332e5f8d3171e062e3e804a2a0253e1be26e59b",
+    "https://bcr.bazel.build/modules/bazel_skylib/1.7.1/source.json": "f121b43eeefc7c29efbd51b83d08631e2347297c95aac9764a701f2a6a2bb953",
+    "https://bcr.bazel.build/modules/buildozer/7.1.2/MODULE.bazel": "2e8dd40ede9c454042645fd8d8d0cd1527966aa5c919de86661e62953cd73d84",
+    "https://bcr.bazel.build/modules/buildozer/7.1.2/source.json": "c9028a501d2db85793a6996205c8de120944f50a0d570438fcae0457a5f9d1f8",
+    "https://bcr.bazel.build/modules/google_benchmark/1.8.2/MODULE.bazel": "a70cf1bba851000ba93b58ae2f6d76490a9feb74192e57ab8e8ff13c34ec50cb",
+    "https://bcr.bazel.build/modules/googletest/1.11.0/MODULE.bazel": "3a83f095183f66345ca86aa13c58b59f9f94a2f81999c093d4eeaa2d262d12f4",
+    "https://bcr.bazel.build/modules/googletest/1.14.0.bcr.1/MODULE.bazel": "22c31a561553727960057361aa33bf20fb2e98584bc4fec007906e27053f80c6",
+    "https://bcr.bazel.build/modules/googletest/1.14.0.bcr.1/source.json": "41e9e129f80d8c8bf103a7acc337b76e54fad1214ac0a7084bf24f4cd924b8b4",
+    "https://bcr.bazel.build/modules/googletest/1.14.0/MODULE.bazel": "cfbcbf3e6eac06ef9d85900f64424708cc08687d1b527f0ef65aa7517af8118f",
+    "https://bcr.bazel.build/modules/jsoncpp/1.9.5/MODULE.bazel": "31271aedc59e815656f5736f282bb7509a97c7ecb43e927ac1a37966e0578075",
+    "https://bcr.bazel.build/modules/jsoncpp/1.9.5/source.json": "4108ee5085dd2885a341c7fab149429db457b3169b86eb081fa245eadf69169d",
+    "https://bcr.bazel.build/modules/libpfm/4.11.0/MODULE.bazel": "45061ff025b301940f1e30d2c16bea596c25b176c8b6b3087e92615adbd52902",
+    "https://bcr.bazel.build/modules/nlohmann_json/3.6.1/MODULE.bazel": "6f7b417dcc794d9add9e556673ad25cb3ba835224290f4f848f8e2db1e1fca74",
+    "https://bcr.bazel.build/modules/nlohmann_json/3.6.1/source.json": "f448c6e8963fdfa7eb831457df83ad63d3d6355018f6574fb017e8169deb43a9",
+    "https://bcr.bazel.build/modules/platforms/0.0.10/MODULE.bazel": "8cb8efaf200bdeb2150d93e162c40f388529a25852b332cec879373771e48ed5",
+    "https://bcr.bazel.build/modules/platforms/0.0.11/MODULE.bazel": "0daefc49732e227caa8bfa834d65dc52e8cc18a2faf80df25e8caea151a9413f",
+    "https://bcr.bazel.build/modules/platforms/0.0.11/source.json": "f7e188b79ebedebfe75e9e1d098b8845226c7992b307e28e1496f23112e8fc29",
+    "https://bcr.bazel.build/modules/platforms/0.0.4/MODULE.bazel": "9b328e31ee156f53f3c416a64f8491f7eb731742655a47c9eec4703a71644aee",
+    "https://bcr.bazel.build/modules/platforms/0.0.5/MODULE.bazel": "5733b54ea419d5eaf7997054bb55f6a1d0b5ff8aedf0176fef9eea44f3acda37",
+    "https://bcr.bazel.build/modules/platforms/0.0.6/MODULE.bazel": "ad6eeef431dc52aefd2d77ed20a4b353f8ebf0f4ecdd26a807d2da5aa8cd0615",
+    "https://bcr.bazel.build/modules/platforms/0.0.7/MODULE.bazel": "72fd4a0ede9ee5c021f6a8dd92b503e089f46c227ba2813ff183b71616034814",
+    "https://bcr.bazel.build/modules/platforms/0.0.8/MODULE.bazel": "9f142c03e348f6d263719f5074b21ef3adf0b139ee4c5133e2aa35664da9eb2d",
+    "https://bcr.bazel.build/modules/platforms/0.0.9/MODULE.bazel": "4a87a60c927b56ddd67db50c89acaa62f4ce2a1d2149ccb63ffd871d5ce29ebc",
+    "https://bcr.bazel.build/modules/protobuf/21.7/MODULE.bazel": "a5a29bb89544f9b97edce05642fac225a808b5b7be74038ea3640fae2f8e66a7",
+    "https://bcr.bazel.build/modules/protobuf/27.0/MODULE.bazel": "7873b60be88844a0a1d8f80b9d5d20cfbd8495a689b8763e76c6372998d3f64c",
+    "https://bcr.bazel.build/modules/protobuf/29.0-rc2/MODULE.bazel": "6241d35983510143049943fc0d57937937122baf1b287862f9dc8590fc4c37df",
+    "https://bcr.bazel.build/modules/protobuf/29.0-rc3/MODULE.bazel": "33c2dfa286578573afc55a7acaea3cada4122b9631007c594bf0729f41c8de92",
+    "https://bcr.bazel.build/modules/protobuf/29.0-rc3/source.json": "c16a6488fb279ef578da7098e605082d72ed85fc8d843eaae81e7d27d0f4625d",
+    "https://bcr.bazel.build/modules/protobuf/3.19.0/MODULE.bazel": "6b5fbb433f760a99a22b18b6850ed5784ef0e9928a72668b66e4d7ccd47db9b0",
+    "https://bcr.bazel.build/modules/protobuf/3.19.6/MODULE.bazel": "9233edc5e1f2ee276a60de3eaa47ac4132302ef9643238f23128fea53ea12858",
+    "https://bcr.bazel.build/modules/pybind11_bazel/2.11.1/MODULE.bazel": "88af1c246226d87e65be78ed49ecd1e6f5e98648558c14ce99176da041dc378e",
+    "https://bcr.bazel.build/modules/pybind11_bazel/2.11.1/source.json": "be4789e951dd5301282729fe3d4938995dc4c1a81c2ff150afc9f1b0504c6022",
+    "https://bcr.bazel.build/modules/re2/2023-09-01/MODULE.bazel": "cb3d511531b16cfc78a225a9e2136007a48cf8a677e4264baeab57fe78a80206",
+    "https://bcr.bazel.build/modules/re2/2023-09-01/source.json": "e044ce89c2883cd957a2969a43e79f7752f9656f6b20050b62f90ede21ec6eb4",
+    "https://bcr.bazel.build/modules/rules_android/0.1.1/MODULE.bazel": "48809ab0091b07ad0182defb787c4c5328bd3a278938415c00a7b69b50c4d3a8",
+    "https://bcr.bazel.build/modules/rules_android/0.1.1/source.json": "e6986b41626ee10bdc864937ffb6d6bf275bb5b9c65120e6137d56e6331f089e",
+    "https://bcr.bazel.build/modules/rules_apple/4.3.3/MODULE.bazel": "c5c2c4adeeac5f3f2f9b7f16abfa8be7ffefa596171d0d92bed4cae9ade0a498",
+    "https://bcr.bazel.build/modules/rules_apple/4.3.3/source.json": "3cb1d69c8243ffcc42ecbf84ae8b9cccd7b1e2f091b0aee5a3e9c9a45267f312",
+    "https://bcr.bazel.build/modules/rules_cc/0.0.1/MODULE.bazel": "cb2aa0747f84c6c3a78dad4e2049c154f08ab9d166b1273835a8174940365647",
+    "https://bcr.bazel.build/modules/rules_cc/0.0.10/MODULE.bazel": "ec1705118f7eaedd6e118508d3d26deba2a4e76476ada7e0e3965211be012002",
+    "https://bcr.bazel.build/modules/rules_cc/0.0.11/MODULE.bazel": "9f249c5624a4788067b96b8b896be10c7e8b4375dc46f6d8e1e51100113e0992",
+    "https://bcr.bazel.build/modules/rules_cc/0.0.13/MODULE.bazel": "0e8529ed7b323dad0775ff924d2ae5af7640b23553dfcd4d34344c7e7a867191",
+    "https://bcr.bazel.build/modules/rules_cc/0.0.15/MODULE.bazel": "6704c35f7b4a72502ee81f61bf88706b54f06b3cbe5558ac17e2e14666cd5dcc",
+    "https://bcr.bazel.build/modules/rules_cc/0.0.16/MODULE.bazel": "7661303b8fc1b4d7f532e54e9d6565771fea666fbdf839e0a86affcd02defe87",
+    "https://bcr.bazel.build/modules/rules_cc/0.0.2/MODULE.bazel": "6915987c90970493ab97393024c156ea8fb9f3bea953b2f3ec05c34f19b5695c",
+    "https://bcr.bazel.build/modules/rules_cc/0.0.6/MODULE.bazel": "abf360251023dfe3efcef65ab9d56beefa8394d4176dd29529750e1c57eaa33f",
+    "https://bcr.bazel.build/modules/rules_cc/0.0.8/MODULE.bazel": "964c85c82cfeb6f3855e6a07054fdb159aced38e99a5eecf7bce9d53990afa3e",
+    "https://bcr.bazel.build/modules/rules_cc/0.0.9/MODULE.bazel": "836e76439f354b89afe6a911a7adf59a6b2518fafb174483ad78a2a2fde7b1c5",
+    "https://bcr.bazel.build/modules/rules_cc/0.1.2/MODULE.bazel": "557ddc3a96858ec0d465a87c0a931054d7dcfd6583af2c7ed3baf494407fd8d0",
+    "https://bcr.bazel.build/modules/rules_cc/0.1.2/source.json": "53fcb09b5816c83ca60d9d7493faf3bfaf410dfc2f15deb52d6ddd146b8d43f0",
+    "https://bcr.bazel.build/modules/rules_foreign_cc/0.9.0/MODULE.bazel": "c9e8c682bf75b0e7c704166d79b599f93b72cfca5ad7477df596947891feeef6",
+    "https://bcr.bazel.build/modules/rules_fuzzing/0.5.2/MODULE.bazel": "40c97d1144356f52905566c55811f13b299453a14ac7769dfba2ac38192337a8",
+    "https://bcr.bazel.build/modules/rules_fuzzing/0.5.2/source.json": "c8b1e2c717646f1702290959a3302a178fb639d987ab61d548105019f11e527e",
+    "https://bcr.bazel.build/modules/rules_java/4.0.0/MODULE.bazel": "5a78a7ae82cd1a33cef56dc578c7d2a46ed0dca12643ee45edbb8417899e6f74",
+    "https://bcr.bazel.build/modules/rules_java/5.3.5/MODULE.bazel": "a4ec4f2db570171e3e5eb753276ee4b389bae16b96207e9d3230895c99644b86",
+    "https://bcr.bazel.build/modules/rules_java/6.5.2/MODULE.bazel": "1d440d262d0e08453fa0c4d8f699ba81609ed0e9a9a0f02cd10b3e7942e61e31",
+    "https://bcr.bazel.build/modules/rules_java/7.10.0/MODULE.bazel": "530c3beb3067e870561739f1144329a21c851ff771cd752a49e06e3dc9c2e71a",
+    "https://bcr.bazel.build/modules/rules_java/7.12.2/MODULE.bazel": "579c505165ee757a4280ef83cda0150eea193eed3bef50b1004ba88b99da6de6",
+    "https://bcr.bazel.build/modules/rules_java/7.2.0/MODULE.bazel": "06c0334c9be61e6cef2c8c84a7800cef502063269a5af25ceb100b192453d4ab",
+    "https://bcr.bazel.build/modules/rules_java/7.6.1/MODULE.bazel": "2f14b7e8a1aa2f67ae92bc69d1ec0fa8d9f827c4e17ff5e5f02e91caa3b2d0fe",
+    "https://bcr.bazel.build/modules/rules_java/7.6.5/MODULE.bazel": "481164be5e02e4cab6e77a36927683263be56b7e36fef918b458d7a8a1ebadb1",
+    "https://bcr.bazel.build/modules/rules_java/8.3.2/MODULE.bazel": "7336d5511ad5af0b8615fdc7477535a2e4e723a357b6713af439fe8cf0195017",
+    "https://bcr.bazel.build/modules/rules_java/8.5.1/MODULE.bazel": "d8a9e38cc5228881f7055a6079f6f7821a073df3744d441978e7a43e20226939",
+    "https://bcr.bazel.build/modules/rules_java/8.5.1/source.json": "db1a77d81b059e0f84985db67a22f3f579a529a86b7997605be3d214a0abe38e",
+    "https://bcr.bazel.build/modules/rules_jvm_external/4.4.2/MODULE.bazel": "a56b85e418c83eb1839819f0b515c431010160383306d13ec21959ac412d2fe7",
+    "https://bcr.bazel.build/modules/rules_jvm_external/5.1/MODULE.bazel": "33f6f999e03183f7d088c9be518a63467dfd0be94a11d0055fe2d210f89aa909",
+    "https://bcr.bazel.build/modules/rules_jvm_external/5.2/MODULE.bazel": "d9351ba35217ad0de03816ef3ed63f89d411349353077348a45348b096615036",
+    "https://bcr.bazel.build/modules/rules_jvm_external/6.3/MODULE.bazel": "c998e060b85f71e00de5ec552019347c8bca255062c990ac02d051bb80a38df0",
+    "https://bcr.bazel.build/modules/rules_jvm_external/6.3/source.json": "6f5f5a5a4419ae4e37c35a5bb0a6ae657ed40b7abc5a5189111b47fcebe43197",
+    "https://bcr.bazel.build/modules/rules_kotlin/1.9.6/MODULE.bazel": "d269a01a18ee74d0335450b10f62c9ed81f2321d7958a2934e44272fe82dcef3",
+    "https://bcr.bazel.build/modules/rules_kotlin/1.9.6/source.json": "2faa4794364282db7c06600b7e5e34867a564ae91bda7cae7c29c64e9466b7d5",
+    "https://bcr.bazel.build/modules/rules_license/0.0.3/MODULE.bazel": "627e9ab0247f7d1e05736b59dbb1b6871373de5ad31c3011880b4133cafd4bd0",
+    "https://bcr.bazel.build/modules/rules_license/0.0.7/MODULE.bazel": "088fbeb0b6a419005b89cf93fe62d9517c0a2b8bb56af3244af65ecfe37e7d5d",
+    "https://bcr.bazel.build/modules/rules_license/1.0.0/MODULE.bazel": "a7fda60eefdf3d8c827262ba499957e4df06f659330bbe6cdbdb975b768bb65c",
+    "https://bcr.bazel.build/modules/rules_license/1.0.0/source.json": "a52c89e54cc311196e478f8382df91c15f7a2bfdf4c6cd0e2675cc2ff0b56efb",
+    "https://bcr.bazel.build/modules/rules_pkg/0.7.0/MODULE.bazel": "df99f03fc7934a4737122518bb87e667e62d780b610910f0447665a7e2be62dc",
+    "https://bcr.bazel.build/modules/rules_pkg/1.0.1/MODULE.bazel": "5b1df97dbc29623bccdf2b0dcd0f5cb08e2f2c9050aab1092fd39a41e82686ff",
+    "https://bcr.bazel.build/modules/rules_pkg/1.0.1/source.json": "bd82e5d7b9ce2d31e380dd9f50c111d678c3bdaca190cb76b0e1c71b05e1ba8a",
+    "https://bcr.bazel.build/modules/rules_proto/4.0.0/MODULE.bazel": "a7a7b6ce9bee418c1a760b3d84f83a299ad6952f9903c67f19e4edd964894e06",
+    "https://bcr.bazel.build/modules/rules_proto/5.3.0-21.7/MODULE.bazel": "e8dff86b0971688790ae75528fe1813f71809b5afd57facb44dad9e8eca631b7",
+    "https://bcr.bazel.build/modules/rules_proto/6.0.2/MODULE.bazel": "ce916b775a62b90b61888052a416ccdda405212b6aaeb39522f7dc53431a5e73",
+    "https://bcr.bazel.build/modules/rules_proto/6.0.2/source.json": "17a2e195f56cb28d6bbf763e49973d13890487c6945311ed141e196fb660426d",
+    "https://bcr.bazel.build/modules/rules_python/0.10.2/MODULE.bazel": "cc82bc96f2997baa545ab3ce73f196d040ffb8756fd2d66125a530031cd90e5f",
+    "https://bcr.bazel.build/modules/rules_python/0.22.1/MODULE.bazel": "26114f0c0b5e93018c0c066d6673f1a2c3737c7e90af95eff30cfee38d0bbac7",
+    "https://bcr.bazel.build/modules/rules_python/0.23.1/MODULE.bazel": "49ffccf0511cb8414de28321f5fcf2a31312b47c40cc21577144b7447f2bf300",
+    "https://bcr.bazel.build/modules/rules_python/0.25.0/MODULE.bazel": "72f1506841c920a1afec76975b35312410eea3aa7b63267436bfb1dd91d2d382",
+    "https://bcr.bazel.build/modules/rules_python/0.28.0/MODULE.bazel": "cba2573d870babc976664a912539b320cbaa7114cd3e8f053c720171cde331ed",
+    "https://bcr.bazel.build/modules/rules_python/0.31.0/MODULE.bazel": "93a43dc47ee570e6ec9f5779b2e64c1476a6ce921c48cc9a1678a91dd5f8fd58",
+    "https://bcr.bazel.build/modules/rules_python/0.4.0/MODULE.bazel": "9208ee05fd48bf09ac60ed269791cf17fb343db56c8226a720fbb1cdf467166c",
+    "https://bcr.bazel.build/modules/rules_python/1.3.0/MODULE.bazel": "8361d57eafb67c09b75bf4bbe6be360e1b8f4f18118ab48037f2bd50aa2ccb13",
+    "https://bcr.bazel.build/modules/rules_python/1.3.0/source.json": "25932f917cd279c7baefa6cb1d3fa8750a7a29de522024449b19af6eab51f4a0",
+    "https://bcr.bazel.build/modules/rules_shell/0.2.0/MODULE.bazel": "fda8a652ab3c7d8fee214de05e7a9916d8b28082234e8d2c0094505c5268ed3c",
+    "https://bcr.bazel.build/modules/rules_shell/0.3.0/MODULE.bazel": "de4402cd12f4cc8fda2354fce179fdb068c0b9ca1ec2d2b17b3e21b24c1a937b",
+    "https://bcr.bazel.build/modules/rules_shell/0.3.0/source.json": "c55ed591aa5009401ddf80ded9762ac32c358d2517ee7820be981e2de9756cf3",
+    "https://bcr.bazel.build/modules/rules_swift/1.16.0/MODULE.bazel": "4a09f199545a60d09895e8281362b1ff3bb08bbde69c6fc87aff5b92fcc916ca",
+    "https://bcr.bazel.build/modules/rules_swift/2.4.0/MODULE.bazel": "1639617eb1ede28d774d967a738b4a68b0accb40650beadb57c21846beab5efd",
+    "https://bcr.bazel.build/modules/rules_swift/2.4.0/source.json": "a6577f57f9febbdc015a01f2a8f3487422032f134d6c61d18ed8e8ca3b9acc7c",
+    "https://bcr.bazel.build/modules/stardoc/0.5.1/MODULE.bazel": "1a05d92974d0c122f5ccf09291442580317cdd859f07a8655f1db9a60374f9f8",
+    "https://bcr.bazel.build/modules/stardoc/0.5.3/MODULE.bazel": "c7f6948dae6999bf0db32c1858ae345f112cacf98f174c7a8bb707e41b974f1c",
+    "https://bcr.bazel.build/modules/stardoc/0.7.0/MODULE.bazel": "05e3d6d30c099b6770e97da986c53bd31844d7f13d41412480ea265ac9e8079c",
+    "https://bcr.bazel.build/modules/stardoc/0.7.2/MODULE.bazel": "fc152419aa2ea0f51c29583fab1e8c99ddefd5b3778421845606ee628629e0e5",
+    "https://bcr.bazel.build/modules/stardoc/0.7.2/source.json": "58b029e5e901d6802967754adf0a9056747e8176f017cfe3607c0851f4d42216",
+    "https://bcr.bazel.build/modules/swift_argument_parser/1.3.1.1/MODULE.bazel": "5e463fbfba7b1701d957555ed45097d7f984211330106ccd1352c6e0af0dcf91",
+    "https://bcr.bazel.build/modules/swift_argument_parser/1.3.1.1/source.json": "32bd87e5f4d7acc57c5b2ff7c325ae3061d5e242c0c4c214ae87e0f1c13e54cb",
+    "https://bcr.bazel.build/modules/upb/0.0.0-20220923-a547704/MODULE.bazel": "7298990c00040a0e2f121f6c32544bab27d4452f80d9ce51349b1a28f3005c43",
+    "https://bcr.bazel.build/modules/zlib/1.2.11/MODULE.bazel": "07b389abc85fdbca459b69e2ec656ae5622873af3f845e1c9d80fe179f3effa0",
+    "https://bcr.bazel.build/modules/zlib/1.2.12/MODULE.bazel": "3b1a8834ada2a883674be8cbd36ede1b6ec481477ada359cd2d3ddc562340b27",
+    "https://bcr.bazel.build/modules/zlib/1.3.1.bcr.3/MODULE.bazel": "af322bc08976524477c79d1e45e241b6efbeb918c497e8840b8ab116802dda79",
+    "https://bcr.bazel.build/modules/zlib/1.3.1.bcr.3/source.json": "2be409ac3c7601245958cd4fcdff4288be79ed23bd690b4b951f500d54ee6e7d",
+    "https://bcr.bazel.build/modules/zlib/1.3.1/MODULE.bazel": "751c9940dcfe869f5f7274e1295422a34623555916eb98c174c1e945594bf198"
+  },
+  "selectedYankedVersions": {},
+  "moduleExtensions": {
+    "@@rules_java~//java:rules_java_deps.bzl%compatibility_proxy": {
+      "general": {
+        "bzlTransitiveDigest": "C4xqrMy1wN4iuTN6Z2eCm94S5XingHhD6uwrIXvCxVI=",
+        "usagesDigest": "pwHZ+26iLgQdwvdZeA5wnAjKnNI3y6XO2VbhOTeo5h8=",
+        "recordedFileInputs": {},
+        "recordedDirentsInputs": {},
+        "envVariables": {},
+        "generatedRepoSpecs": {
+          "compatibility_proxy": {
+            "bzlFile": "@@rules_java~//java:rules_java_deps.bzl",
+            "ruleClassName": "_compatibility_proxy_repo_rule",
+            "attributes": {}
+          }
+        },
+        "recordedRepoMappingEntries": [
+          [
+            "rules_java~",
+            "bazel_tools",
+            "bazel_tools"
+          ]
+        ]
+      }
+    },
+    "@@rules_kotlin~//src/main/starlark/core/repositories:bzlmod_setup.bzl%rules_kotlin_extensions": {
+      "general": {
+        "bzlTransitiveDigest": "eecmTsmdIQveoA97hPtH3/Ej/kugbdCI24bhXIXaly8=",
+        "usagesDigest": "aJF6fLy82rR95Ff5CZPAqxNoFgOMLMN5ImfBS0nhnkg=",
+        "recordedFileInputs": {},
+        "recordedDirentsInputs": {},
+        "envVariables": {},
+        "generatedRepoSpecs": {
+          "com_github_jetbrains_kotlin_git": {
+            "bzlFile": "@@rules_kotlin~//src/main/starlark/core/repositories:compiler.bzl",
+            "ruleClassName": "kotlin_compiler_git_repository",
+            "attributes": {
+              "urls": [
+                "https://github.com/JetBrains/kotlin/releases/download/v1.9.23/kotlin-compiler-1.9.23.zip"
+              ],
+              "sha256": "93137d3aab9afa9b27cb06a824c2324195c6b6f6179d8a8653f440f5bd58be88"
+            }
+          },
+          "com_github_jetbrains_kotlin": {
+            "bzlFile": "@@rules_kotlin~//src/main/starlark/core/repositories:compiler.bzl",
+            "ruleClassName": "kotlin_capabilities_repository",
+            "attributes": {
+              "git_repository_name": "com_github_jetbrains_kotlin_git",
+              "compiler_version": "1.9.23"
+            }
+          },
+          "com_github_google_ksp": {
+            "bzlFile": "@@rules_kotlin~//src/main/starlark/core/repositories:ksp.bzl",
+            "ruleClassName": "ksp_compiler_plugin_repository",
+            "attributes": {
+              "urls": [
+                "https://github.com/google/ksp/releases/download/1.9.23-1.0.20/artifacts.zip"
+              ],
+              "sha256": "ee0618755913ef7fd6511288a232e8fad24838b9af6ea73972a76e81053c8c2d",
+              "strip_version": "1.9.23-1.0.20"
+            }
+          },
+          "com_github_pinterest_ktlint": {
+            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
+            "ruleClassName": "http_file",
+            "attributes": {
+              "sha256": "01b2e0ef893383a50dbeb13970fe7fa3be36ca3e83259e01649945b09d736985",
+              "urls": [
+                "https://github.com/pinterest/ktlint/releases/download/1.3.0/ktlint"
+              ],
+              "executable": true
+            }
+          },
+          "rules_android": {
+            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
+            "ruleClassName": "http_archive",
+            "attributes": {
+              "sha256": "cd06d15dd8bb59926e4d65f9003bfc20f9da4b2519985c27e190cddc8b7a7806",
+              "strip_prefix": "rules_android-0.1.1",
+              "urls": [
+                "https://github.com/bazelbuild/rules_android/archive/v0.1.1.zip"
+              ]
+            }
+          }
+        },
+        "recordedRepoMappingEntries": [
+          [
+            "rules_kotlin~",
+            "bazel_tools",
+            "bazel_tools"
+          ]
+        ]
+      }
+    },
+    "@@rules_python~//python/uv:uv.bzl%uv": {
+      "general": {
+        "bzlTransitiveDigest": "Xpqjnjzy6zZ90Es9Wa888ZLHhn7IsNGbph/e6qoxzw8=",
+        "usagesDigest": "qI5PVlIum/YAnGJg5oXGHzDkMFWt2aNSUZY4G8PBbic=",
+        "recordedFileInputs": {},
+        "recordedDirentsInputs": {},
+        "envVariables": {},
+        "generatedRepoSpecs": {
+          "uv": {
+            "bzlFile": "@@rules_python~//python/uv/private:uv_toolchains_repo.bzl",
+            "ruleClassName": "uv_toolchains_repo",
+            "attributes": {
+              "toolchain_type": "'@@rules_python~//python/uv:uv_toolchain_type'",
+              "toolchain_names": [
+                "none"
+              ],
+              "toolchain_implementations": {
+                "none": "'@@rules_python~//python:none'"
+              },
+              "toolchain_compatible_with": {
+                "none": [
+                  "@platforms//:incompatible"
+                ]
+              },
+              "toolchain_target_settings": {}
+            }
+          }
+        },
+        "recordedRepoMappingEntries": [
+          [
+            "rules_python~",
+            "platforms",
+            "platforms"
+          ]
+        ]
+      }
+    },
+    "@@rules_swift~//swift:extensions.bzl%non_module_deps": {
+      "general": {
+        "bzlTransitiveDigest": "l+Zu+SMObRQy3DG2LEw0eGVPkYRnyVj+M1QyR5AAFmM=",
+        "usagesDigest": "l2vIL7SL4tJqHIVLWd78Y/ym+r0II64lmvoX8o+0Bb0=",
+        "recordedFileInputs": {},
+        "recordedDirentsInputs": {},
+        "envVariables": {},
+        "generatedRepoSpecs": {
+          "com_github_apple_swift_protobuf": {
+            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
+            "ruleClassName": "http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-protobuf/archive/1.20.2.tar.gz"
+              ],
+              "sha256": "3fb50bd4d293337f202d917b6ada22f9548a0a0aed9d9a4d791e6fbd8a246ebb",
+              "strip_prefix": "swift-protobuf-1.20.2/",
+              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_protobuf/BUILD.overlay"
+            }
+          },
+          "com_github_grpc_grpc_swift": {
+            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
+            "ruleClassName": "http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/grpc/grpc-swift/archive/1.16.0.tar.gz"
+              ],
+              "sha256": "58b60431d0064969f9679411264b82e40a217ae6bd34e17096d92cc4e47556a5",
+              "strip_prefix": "grpc-swift-1.16.0/",
+              "build_file": "@@rules_swift~//third_party:com_github_grpc_grpc_swift/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_docc_symbolkit": {
+            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
+            "ruleClassName": "http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-docc-symbolkit/archive/refs/tags/swift-5.10-RELEASE.tar.gz"
+              ],
+              "sha256": "de1d4b6940468ddb53b89df7aa1a81323b9712775b0e33e8254fa0f6f7469a97",
+              "strip_prefix": "swift-docc-symbolkit-swift-5.10-RELEASE",
+              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_docc_symbolkit/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_nio": {
+            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
+            "ruleClassName": "http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-nio/archive/2.42.0.tar.gz"
+              ],
+              "sha256": "e3304bc3fb53aea74a3e54bd005ede11f6dc357117d9b1db642d03aea87194a0",
+              "strip_prefix": "swift-nio-2.42.0/",
+              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_nio/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_nio_http2": {
+            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
+            "ruleClassName": "http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-nio-http2/archive/1.26.0.tar.gz"
+              ],
+              "sha256": "f0edfc9d6a7be1d587e5b403f2d04264bdfae59aac1d74f7d974a9022c6d2b25",
+              "strip_prefix": "swift-nio-http2-1.26.0/",
+              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_nio_http2/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_nio_transport_services": {
+            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
+            "ruleClassName": "http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-nio-transport-services/archive/1.15.0.tar.gz"
+              ],
+              "sha256": "f3498dafa633751a52b9b7f741f7ac30c42bcbeb3b9edca6d447e0da8e693262",
+              "strip_prefix": "swift-nio-transport-services-1.15.0/",
+              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_nio_transport_services/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_nio_extras": {
+            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
+            "ruleClassName": "http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-nio-extras/archive/1.4.0.tar.gz"
+              ],
+              "sha256": "4684b52951d9d9937bb3e8ccd6b5daedd777021ef2519ea2f18c4c922843b52b",
+              "strip_prefix": "swift-nio-extras-1.4.0/",
+              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_nio_extras/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_log": {
+            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
+            "ruleClassName": "http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-log/archive/1.4.4.tar.gz"
+              ],
+              "sha256": "48fe66426c784c0c20031f15dc17faf9f4c9037c192bfac2f643f65cb2321ba0",
+              "strip_prefix": "swift-log-1.4.4/",
+              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_log/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_nio_ssl": {
+            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
+            "ruleClassName": "http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-nio-ssl/archive/2.23.0.tar.gz"
+              ],
+              "sha256": "4787c63f61dd04d99e498adc3d1a628193387e41efddf8de19b8db04544d016d",
+              "strip_prefix": "swift-nio-ssl-2.23.0/",
+              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_nio_ssl/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_collections": {
+            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
+            "ruleClassName": "http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-collections/archive/1.0.4.tar.gz"
+              ],
+              "sha256": "d9e4c8a91c60fb9c92a04caccbb10ded42f4cb47b26a212bc6b39cc390a4b096",
+              "strip_prefix": "swift-collections-1.0.4/",
+              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_collections/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_atomics": {
+            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
+            "ruleClassName": "http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-atomics/archive/1.1.0.tar.gz"
+              ],
+              "sha256": "1bee7f469f7e8dc49f11cfa4da07182fbc79eab000ec2c17bfdce468c5d276fb",
+              "strip_prefix": "swift-atomics-1.1.0/",
+              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_atomics/BUILD.overlay"
+            }
+          },
+          "build_bazel_rules_swift_index_import": {
+            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
+            "ruleClassName": "http_archive",
+            "attributes": {
+              "build_file": "@@rules_swift~//third_party:build_bazel_rules_swift_index_import/BUILD.overlay",
+              "canonical_id": "index-import-5.8",
+              "urls": [
+                "https://github.com/MobileNativeFoundation/index-import/releases/download/5.8.0.1/index-import.tar.gz"
+              ],
+              "sha256": "28c1ffa39d99e74ed70623899b207b41f79214c498c603915aef55972a851a15"
+            }
+          },
+          "build_bazel_rules_swift_local_config": {
+            "bzlFile": "@@rules_swift~//swift/internal:swift_autoconfiguration.bzl",
+            "ruleClassName": "swift_autoconfiguration",
+            "attributes": {}
+          }
+        },
+        "recordedRepoMappingEntries": [
+          [
+            "rules_swift~",
+            "bazel_tools",
+            "bazel_tools"
+          ]
+        ]
+      }
+    }
+  }
+}

sparkle_workspace/SparklePlugin.m

@@ -0,0 +1,141 @@
+//
+// SparklePlugin.m
+// Native macOS plugin for Unity to initialize Sparkle auto-updates
+//
+// Copyright 2026 Dan Crosby
+//
+
+#import <AppKit/AppKit.h>
+#import <Sparkle/Sparkle.h>
+#include <sys/mount.h>
+
+// The updater controller - retained for the lifetime of the app
+static SPUStandardUpdaterController *updaterController = nil;
+
+// Export macro for Unity P/Invoke
+#define EXPORT __attribute__((visibility("default")))
+
+// Called from Unity to initialize Sparkle
+// This should be called once at app startup
+EXPORT void SparklePlugin_Initialize(void) {
+    if (updaterController != nil) {
+        NSLog(@"SparklePlugin: Already initialized");
+        return;
+    }
+
+    NSLog(@"SparklePlugin: Initializing Sparkle auto-updater");
+
+    // Log Info.plist configuration
+    NSBundle *mainBundle = [NSBundle mainBundle];
+    NSString *feedURL = [mainBundle objectForInfoDictionaryKey:@"SUFeedURL"];
+    NSString *publicKey = [mainBundle objectForInfoDictionaryKey:@"SUPublicEDKey"];
+    NSString *version = [mainBundle objectForInfoDictionaryKey:@"CFBundleShortVersionString"];
+    NSString *buildNumber = [mainBundle objectForInfoDictionaryKey:@"CFBundleVersion"];
+    NSNumber *autoCheck = [mainBundle objectForInfoDictionaryKey:@"SUEnableAutomaticChecks"];
+
+    NSLog(@"SparklePlugin: App version: %@ (build %@)", version ?: @"(not set)", buildNumber ?: @"(not set)");
+    NSLog(@"SparklePlugin: Feed URL: %@", feedURL ?: @"(not set)");
+    NSLog(@"SparklePlugin: Public key: %@", publicKey ? @"(set)" : @"(not set)");
+    NSLog(@"SparklePlugin: Auto-check enabled in plist: %@", autoCheck ?: @"(not set)");
+
+    // Create the updater controller with automatic update checking enabled
+    // The feed URL and public key are read from Info.plist (SUFeedURL, SUPublicEDKey)
+    updaterController = [[SPUStandardUpdaterController alloc]
+        initWithStartingUpdater:YES
+        updaterDelegate:nil
+        userDriverDelegate:nil];
+
+    if (updaterController != nil) {
+        NSLog(@"SparklePlugin: Sparkle initialized successfully");
+        NSLog(@"SparklePlugin: Auto-check currently: %@",
+              [[updaterController updater] automaticallyChecksForUpdates] ? @"enabled" : @"disabled");
+        NSLog(@"SparklePlugin: Last update check: %@",
+              [[updaterController updater] lastUpdateCheckDate] ?: @"never");
+    } else {
+        NSLog(@"SparklePlugin: Failed to initialize Sparkle");
+    }
+}
+
+// Manually trigger an update check (shows UI)
+EXPORT void SparklePlugin_CheckForUpdates(void) {
+    if (updaterController == nil) {
+        NSLog(@"SparklePlugin: Not initialized, call Initialize first");
+        return;
+    }
+
+    NSLog(@"SparklePlugin: Checking for updates");
+    [updaterController checkForUpdates:nil];
+}
+
+// Check for updates silently in background (no UI unless update found)
+EXPORT void SparklePlugin_CheckForUpdatesInBackground(void) {
+    if (updaterController == nil) {
+        NSLog(@"SparklePlugin: Not initialized, call Initialize first");
+        return;
+    }
+
+    NSLog(@"SparklePlugin: Checking for updates in background");
+    [[updaterController updater] checkForUpdatesInBackground];
+}
+
+// Returns 1 if an update check is in progress, 0 otherwise
+EXPORT int SparklePlugin_IsCheckingForUpdates(void) {
+    if (updaterController == nil) {
+        return 0;
+    }
+    return [[updaterController updater] sessionInProgress] ? 1 : 0;
+}
+
+// Returns 1 if automatic update checks are enabled, 0 otherwise
+EXPORT int SparklePlugin_GetAutomaticallyChecksForUpdates(void) {
+    if (updaterController == nil) {
+        return 0;
+    }
+    return [[updaterController updater] automaticallyChecksForUpdates] ? 1 : 0;
+}
+
+// Enable or disable automatic update checks
+EXPORT void SparklePlugin_SetAutomaticallyChecksForUpdates(int enabled) {
+    if (updaterController == nil) {
+        NSLog(@"SparklePlugin: Not initialized");
+        return;
+    }
+    [[updaterController updater] setAutomaticallyChecksForUpdates:(enabled != 0)];
+}
+
+// Check if app is running from a read-only filesystem (e.g., mounted DMG)
+// Returns 1 if read-only, 0 if writable
+EXPORT int SparklePlugin_IsRunningFromReadOnlyVolume(void) {
+    NSBundle *mainBundle = [NSBundle mainBundle];
+    NSString *bundlePath = [mainBundle bundlePath];
+
+    struct statfs fsInfo;
+    if (statfs([bundlePath fileSystemRepresentation], &fsInfo) == 0) {
+        BOOL isReadOnly = (fsInfo.f_flags & MNT_RDONLY) != 0;
+        NSLog(@"SparklePlugin: Bundle path: %@, read-only: %@", bundlePath, isReadOnly ? @"YES" : @"NO");
+        return isReadOnly ? 1 : 0;
+    }
+
+    NSLog(@"SparklePlugin: Failed to check filesystem for %@", bundlePath);
+    return 0; // Assume writable if we can't check
+}
+
+// Show a dialog telling user to drag app out of DMG
+EXPORT void SparklePlugin_ShowDMGWarning(void) {
+    NSLog(@"SparklePlugin: Showing DMG warning dialog");
+
+    dispatch_async(dispatch_get_main_queue(), ^{
+        NSAlert *alert = [[NSAlert alloc] init];
+        [alert setMessageText:@"Please install Eagle0 first"];
+        [alert setInformativeText:
+                @"Eagle0 is running from the disk image (DMG). "
+                 "To play, please drag Eagle0 to your Applications folder first, "
+                 "then launch it from there.\n\n"
+                 "The app will now quit."];
+        [alert setAlertStyle:NSAlertStyleCritical];
+        [alert addButtonWithTitle:@"Quit"];
+
+        [alert runModal];
+        [NSApp terminate:nil];
+    });
+}

sparkle_workspace/WORKSPACE.bazel

@@ -0,0 +1,3 @@
+# This file marks sparkle_workspace as a separate Bazel workspace.
+# It prevents Bazel from looking up to the parent directory's workspace.
+# The actual dependencies are defined in MODULE.bazel (bzlmod).

sparkle_workspace/external/BUILD.sparkle

@@ -0,0 +1,8 @@
+load("@build_bazel_rules_apple//apple:apple.bzl", "apple_dynamic_framework_import")
+
+# Import pre-built Sparkle framework
+apple_dynamic_framework_import(
+    name = "Sparkle",
+    framework_imports = glob(["Sparkle.framework/**"]),
+    visibility = ["//visibility:public"],
+)

src/main/cpp/net/eagle0/shardok/ai/ShardokAIClient.cpp

@@ -20,6 +20,9 @@
 #include <sstream>
 #endif
 
+#include <set>
+#include <unordered_map>
+
 #include "AIAttackerStrategySelector.hpp"
 #include "AIConfig.hpp"
 #include "AIDefenderStrategySelector.hpp"
@@ -171,8 +174,117 @@ auto ShardokAIClient::StandardChooseCommandIndex(
     //     }
     // }
 
-    assert(commandCount == realAvailableCommands->size());
     // Verify that the AI's guessed state produces the same available commands as reality
+    if (commandCount != realAvailableCommands->size()) {
+        fprintf(stderr,
+                "AI command count mismatch: guessed=%zu real=%zu player=%d round=%d\n",
+                commandCount,
+                realAvailableCommands->size(),
+                playerId,
+                guessedState->current_round());
+
+        const auto maxDump = std::max(commandCount, realAvailableCommands->size());
+        for (size_t i = 0; i < maxDump; i++) {
+            const auto *realName = i < realAvailableCommands->size()
+                                           ? net::eagle0::shardok::common::CommandType_Name(
+                                                     (*realAvailableCommands)[i]->GetCommandType())
+                                                     .c_str()
+                                           : "(none)";
+            const auto *guessedName = i < commandCount
+                                              ? net::eagle0::shardok::common::CommandType_Name(
+                                                        (*guessedCommands)[i]->GetCommandType())
+                                                        .c_str()
+                                              : "(none)";
+            const int realActor = i < realAvailableCommands->size()
+                                          ? (*realAvailableCommands)[i]->GetActorUnitId()
+                                          : -1;
+            const int guessedActor =
+                    i < commandCount ? (*guessedCommands)[i]->GetActorUnitId() : -1;
+            const int realRow = i < realAvailableCommands->size()
+                                        ? (*realAvailableCommands)[i]->GetTargetRow()
+                                        : -1;
+            const int realCol = i < realAvailableCommands->size()
+                                        ? (*realAvailableCommands)[i]->GetTargetColumn()
+                                        : -1;
+            const int guessedRow = i < commandCount ? (*guessedCommands)[i]->GetTargetRow() : -1;
+            const int guessedCol = i < commandCount ? (*guessedCommands)[i]->GetTargetColumn() : -1;
+            fprintf(stderr,
+                    "  [%zu] real: %s unit=%d (%d,%d)  guessed: %s unit=%d (%d,%d)\n",
+                    i,
+                    realName,
+                    realActor,
+                    realRow,
+                    realCol,
+                    guessedName,
+                    guessedActor,
+                    guessedRow,
+                    guessedCol);
+        }
+
+        // Find positions in real commands that are missing from guessed commands
+        // Group by unit to find the missing position per unit
+        std::unordered_map<int, std::set<std::pair<int, int>>> realPositions;
+        std::unordered_map<int, std::set<std::pair<int, int>>> guessedPositions;
+        for (size_t i = 0; i < realAvailableCommands->size(); i++) {
+            const auto &cmd = (*realAvailableCommands)[i];
+            realPositions[cmd->GetActorUnitId()].emplace(
+                    cmd->GetTargetRow(),
+                    cmd->GetTargetColumn());
+        }
+        for (size_t i = 0; i < commandCount; i++) {
+            const auto &cmd = (*guessedCommands)[i];
+            guessedPositions[cmd->GetActorUnitId()].emplace(
+                    cmd->GetTargetRow(),
+                    cmd->GetTargetColumn());
+        }
+        for (const auto &[unitId, positions] : realPositions) {
+            for (const auto &[row, col] : positions) {
+                if (!guessedPositions[unitId].contains({row, col})) {
+                    fprintf(stderr,
+                            "  Missing from guessed: unit=%d pos=(%d,%d)",
+                            unitId,
+                            row,
+                            col);
+                    const Coords missingCoords(row, col);
+                    const auto *occupant = guessedState.GetOccupant(missingCoords);
+                    if (occupant) {
+                        fprintf(stderr,
+                                " -> guessed occupant: unit_id=%d player=%d status=%d "
+                                "loc=(%d,%d) hidden=%d battalion_size=%d\n",
+                                occupant->unit_id(),
+                                occupant->player_id(),
+                                static_cast<int>(occupant->status()),
+                                occupant->location().row(),
+                                occupant->location().column(),
+                                occupant->hidden(),
+                                occupant->battalion().size());
+                    } else {
+                        fprintf(stderr, " -> no occupant in guessed state\n");
+                    }
+                }
+            }
+        }
+
+        // Dump all guessed state units for full picture
+        fprintf(stderr, "  Guessed state units (%u total):\n", guessedState->units()->size());
+        for (size_t i = 0; i < guessedState->units()->size(); i++) {
+            const auto *u = guessedState->units()->Get(static_cast<unsigned int>(i));
+            fprintf(stderr,
+                    "    unit_id=%d player=%d status=%d loc=(%d,%d) hidden=%d "
+                    "starting_pos_idx=%d\n",
+                    u->unit_id(),
+                    u->player_id(),
+                    static_cast<int>(u->status()),
+                    u->location().row(),
+                    u->location().column(),
+                    u->hidden(),
+                    u->starting_position_index());
+        }
+
+        throw ShardokInternalErrorException(
+                "AI command count mismatch: guessed=" + std::to_string(commandCount) +
+                " real=" + std::to_string(realAvailableCommands->size()));
+    }
     for (size_t i = 0; i < commandCount; i++) {
         CheckCommand((*realAvailableCommands)[i], (*guessedCommands)[i]);
     }

src/main/cpp/net/eagle0/shardok/ai/score/private/AbstractAIScoreCalculator.cpp

@@ -93,7 +93,8 @@ auto AbstractAIScoreCalculator::CalculateUnitsScoreComponents(
             case net::eagle0::shardok::storage::fb::UnitStatus_OUTLAWED_UNIT:
             case net::eagle0::shardok::storage::fb::UnitStatus_RESERVE_UNIT:
             case net::eagle0::shardok::storage::fb::UnitStatus_RETREATED_UNIT:
-            case net::eagle0::shardok::storage::fb::UnitStatus_RESERVED_SLOT: break;
+            case net::eagle0::shardok::storage::fb::UnitStatus_RESERVED_SLOT:
+            case net::eagle0::shardok::storage::fb::UnitStatus_PENDING_REINFORCEMENT: break;
 
             case net::eagle0::shardok::storage::fb::UnitStatus_UNKNOWN_UNIT:
                 throw ShardokInternalErrorException("Unknown unit status");

src/main/cpp/net/eagle0/shardok/library/AvailableCommandsFactory.cpp

@@ -56,13 +56,18 @@ public:
           commandFactories(CommandFactoriesList(settings).GetFactories()),
           playerSetupCommandFactory(settings) {}
 
-    [[nodiscard]] auto GetPlayerSetupCommands(const GameStateW &gameState, PlayerId playerId) const
+    [[nodiscard]] auto GetPlayerSetupCommands(
+            const GameStateW &gameState,
+            PlayerId playerId,
+            const std::optional<std::vector<Coords>> &reinforcementPositions) const
             -> CommandListSPtr override;
 
     [[nodiscard]] auto GetAvailableCommands(
             const GameStateW &gameState,
             PlayerId player,
-            bool includeFollowUps) const -> CommandListSPtr override;
+            bool includeFollowUps,
+            const std::optional<std::vector<Coords>> &reinforcementPositions) const
+            -> CommandListSPtr override;
 };
 
 auto AvailableCommandsFactory::MakeAvailableCommandsFactory(const SettingsGetter &settings)
@@ -72,9 +77,14 @@ auto AvailableCommandsFactory::MakeAvailableCommandsFactory(const SettingsGetter
 
 auto AvailableCommandsFactoryImpl::GetPlayerSetupCommands(
         const GameStateW &gameState,
-        const PlayerId playerId) const -> CommandListSPtr {
+        const PlayerId playerId,
+        const std::optional<std::vector<Coords>> &reinforcementPositions) const -> CommandListSPtr {
     CommandList previewCommands{};
-    playerSetupCommandFactory.AddAvailablePlayerSetupCommands(previewCommands, playerId, gameState);
+    playerSetupCommandFactory.AddAvailablePlayerSetupCommands(
+            previewCommands,
+            playerId,
+            gameState,
+            reinforcementPositions);
 
     return make_shared<CommandList>(previewCommands);
 }
@@ -168,12 +178,14 @@ void AvailableCommandsFactoryImpl::AddAvailableCommandsForOneUnit(
 auto AvailableCommandsFactoryImpl::GetAvailableCommands(
         const GameStateW &gameState,
         PlayerId playerId,
-        bool includeFollowUps) const -> CommandListSPtr {
+        bool includeFollowUps,
+        const std::optional<std::vector<Coords>> &reinforcementPositions) const -> CommandListSPtr {
     CommandList commands{};
 
     vector<AdjacentTile> adjacentTiles;
 
-    playerSetupCommandFactory.AddAvailablePlayerSetupCommands(commands, playerId, gameState);
+    playerSetupCommandFactory
+            .AddAvailablePlayerSetupCommands(commands, playerId, gameState, reinforcementPositions);
     if (!commands.empty()) return make_shared<CommandList>(commands);
 
     for (const Unit *unit : *gameState->units()) {

src/main/cpp/net/eagle0/shardok/library/AvailableCommandsFactory.hpp

@@ -9,8 +9,12 @@
 #ifndef AvailableCommandsFactory_hpp
 #define AvailableCommandsFactory_hpp
 
+#include <optional>
+#include <vector>
+
 #include "src/main/cpp/net/eagle0/shardok/library/GameStateW.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/ShardokCommand.hpp"
+#include "src/main/cpp/net/eagle0/shardok/library/map/Coordinates.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/settings/GameSettings.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/unit/Unit.hpp"
 
@@ -29,12 +33,16 @@ public:
 
     [[nodiscard]] virtual auto GetPlayerSetupCommands(
             const GameStateW &gameState,
-            PlayerId playerId) const -> CommandListSPtr = 0;
+            PlayerId playerId,
+            const std::optional<std::vector<Coords>> &reinforcementPositions = std::nullopt) const
+            -> CommandListSPtr = 0;
 
     [[nodiscard]] virtual auto GetAvailableCommands(
             const GameStateW &gameState,
             PlayerId player,
-            bool includeFollowUps) const -> CommandListSPtr = 0;
+            bool includeFollowUps,
+            const std::optional<std::vector<Coords>> &reinforcementPositions = std::nullopt) const
+            -> CommandListSPtr = 0;
 };
 }  // namespace shardok
 

src/main/cpp/net/eagle0/shardok/library/BUILD.bazel

@@ -27,6 +27,7 @@ cc_library(
         "//src/main/cpp/net/eagle0/shardok/library/actions:update_game_status_action",
         "//src/main/cpp/net/eagle0/shardok/library/actions:update_opponent_knowledge_action",
         "//src/main/cpp/net/eagle0/shardok/library/fb_helpers:game_state_helpers",
+        "//src/main/cpp/net/eagle0/shardok/library/tutorial:tutorial_battle_controller",
         "//src/main/cpp/net/eagle0/shardok/library/util:game_state_validator",
         "//src/main/cpp/net/eagle0/shardok/library/view_filters:action_result_filter",
         "//src/main/cpp/net/eagle0/shardok/library/view_filters:game_state_filter",
@@ -57,6 +58,7 @@ cc_library(
         "//src/main/cpp/net/eagle0/shardok/library/actions:new_round_action",
         "//src/main/cpp/net/eagle0/shardok/library/command_factories:command_factories_list",
         "//src/main/cpp/net/eagle0/shardok/library/commands:end_turn_command",
+        "//src/main/cpp/net/eagle0/shardok/library/map:coordinates",
         "//src/main/cpp/net/eagle0/shardok/library/settings:game_settings",
         "//src/main/cpp/net/eagle0/shardok/library/unit",
         "//src/main/cpp/net/eagle0/shardok/library/util:hex_map_utils",

src/main/cpp/net/eagle0/shardok/library/ShardokEngine.cpp

@@ -286,21 +286,49 @@ void ShardokEngine::HandlePlayerTurnEnd(const std::shared_ptr<RandomGenerator> &
                                          true /* atEndOfRound */)
                                          .Execute(gameState, randomGenerator));
 
-        ApplyAndAddActionResults(
-                UpdateOpponentKnowledgeAction(settingsGetter).Execute(gameState, randomGenerator));
+        // Check for tutorial events at end of round
+        if (!GameIsOver() && tutorialController_.IsEnabled()) {
+            auto tutorialEventResults = tutorialController_.CheckAndExecuteEvents(
+                    gameState,
+                    settingsGetter,
+                    randomGenerator);
 
-        ApplyAndAddActionResults(
-                NewRoundAction(gameState, settingsGetter).Execute(gameState, randomGenerator));
+            if (!tutorialEventResults.actionResults.empty()) {
+                ApplyAndAddActionResults(tutorialEventResults.actionResults);
 
-        ApplyAndAddActionResults(
-                StartPlayerTurnAction(gameState, UNCONTROLLED_PLAYER_ID, settingsGetter)
-                        .Execute(gameState, randomGenerator));
+                // Update game status after tutorial events (e.g., attackers fled, defender wins)
+                ApplyAndAddActionResults(UpdateGameStatusAction(
+                                                 GetCurrentGameState(),
+                                                 criticalTileCoords,
+                                                 settingsGetter,
+                                                 true /* atEndOfRound */)
+                                                 .Execute(gameState, randomGenerator));
 
-        ApplyAndAddActionResults(PerformUndeadCommandsAction(gameState, settingsGetter)
-                                         .Execute(gameState, randomGenerator));
+                // If tutorial events ended the game, don't start new round
+                if (GameIsOver()) { return; }
 
-        ApplyAndAddActionResults(StartPlayerTurnAction(gameState, 0, settingsGetter)
-                                         .Execute(gameState, randomGenerator));
+                // If reinforcement placement is needed, pause the turn flow
+                if (tutorialEventResults.reinforcementPlacement.has_value()) {
+                    pendingReinforcementPlacement_ = tutorialEventResults.reinforcementPlacement;
+
+                    // Set state to REINFORCEMENT_PLACEMENT
+                    ActionResultProto placementStateAction{};
+                    placementStateAction.set_type(
+                            net::eagle0::shardok::common::TUTORIAL_REINFORCEMENTS_ARRIVED);
+                    placementStateAction.mutable_game_status()->set_state(
+                            GameStatusProto::State::GameStatus_State_REINFORCEMENT_PLACEMENT);
+                    *placementStateAction.mutable_game_status()->mutable_description() =
+                            "Place your reinforcements!";
+                    // Set current player to the reinforcement recipient
+                    placementStateAction.mutable_next_player()->set_value(
+                            pendingReinforcementPlacement_->playerId);
+                    ApplyAndAddActionResult(placementStateAction);
+                    return;
+                }
+            }
+        }
+
+        ResumeAfterReinforcementPlacement(randomGenerator);
 
     } else {
         const auto updateAction = UpdateGameStatusAction(
@@ -316,6 +344,27 @@ void ShardokEngine::HandlePlayerTurnEnd(const std::shared_ptr<RandomGenerator> &
     }
 }
 
+void ShardokEngine::ResumeAfterReinforcementPlacement(
+        const std::shared_ptr<RandomGenerator> &randomGenerator) {
+    pendingReinforcementPlacement_ = std::nullopt;
+
+    ApplyAndAddActionResults(
+            UpdateOpponentKnowledgeAction(settingsGetter).Execute(gameState, randomGenerator));
+
+    ApplyAndAddActionResults(
+            NewRoundAction(gameState, settingsGetter).Execute(gameState, randomGenerator));
+
+    ApplyAndAddActionResults(
+            StartPlayerTurnAction(gameState, UNCONTROLLED_PLAYER_ID, settingsGetter)
+                    .Execute(gameState, randomGenerator));
+
+    ApplyAndAddActionResults(PerformUndeadCommandsAction(gameState, settingsGetter)
+                                     .Execute(gameState, randomGenerator));
+
+    ApplyAndAddActionResults(StartPlayerTurnAction(gameState, 0, settingsGetter)
+                                     .Execute(gameState, randomGenerator));
+}
+
 void ShardokEngine::PostPlacementCommands(
         const PlayerId player,
         const vector<UnitPlacementInfo> &placementInfos,
@@ -324,8 +373,15 @@ void ShardokEngine::PostPlacementCommands(
         throw ShardokClientErrorException("Posting for a player who's not the current player ID!");
     }
 
-    const auto placementCommands =
-            availableCommandsFactory->GetPlayerSetupCommands(gameState, player);
+    const auto reinforcementPositions =
+            pendingReinforcementPlacement_.has_value()
+                    ? std::optional<std::vector<Coords>>(
+                              pendingReinforcementPlacement_->startingPositions)
+                    : std::nullopt;
+    const auto placementCommands = availableCommandsFactory->GetPlayerSetupCommands(
+            gameState,
+            player,
+            reinforcementPositions);
 
     // first make sure they're all valid and there are no duplicates
     for (size_t i = 0; i < placementInfos.size(); i++) {
@@ -365,6 +421,19 @@ void ShardokEngine::PostPlacementCommands(
         }
     }
 
+    // If we were in reinforcement placement, check if all units are now placed
+    if (pendingReinforcementPlacement_.has_value()) {
+        const auto reserveUnits =
+                ReserveUnitsForPlayer(gameState->units(), pendingReinforcementPlacement_->playerId);
+        if (reserveUnits.empty()) {
+            // All reinforcements placed — resume the turn flow
+            ResumeAfterReinforcementPlacement(randomGenerator);
+            return;
+        }
+        // Still have units to place — stay in REINFORCEMENT_PLACEMENT state
+        return;
+    }
+
     const auto updateAction = UpdateGameStatusAction(
             GetCurrentGameState(),
             criticalTileCoords,
@@ -563,10 +632,16 @@ auto ShardokEngine::GetAvailableCommandProtos(const PlayerId playerId, const boo
 auto ShardokEngine::UncachedGetAvailableCommands(
         const PlayerId playerId,
         const bool includeFollowUps) const -> CommandListSPtr {
+    const auto reinforcementPositions =
+            pendingReinforcementPlacement_.has_value()
+                    ? std::optional<std::vector<Coords>>(
+                              pendingReinforcementPlacement_->startingPositions)
+                    : std::nullopt;
     return availableCommandsFactory->GetAvailableCommands(
             gameState,
             playerId,
-            /* includeFollowUps=*/includeFollowUps);
+            /* includeFollowUps=*/includeFollowUps,
+            reinforcementPositions);
 }
 
 void AddUnits(vector<net::eagle0::shardok::storage::ResolvedUnit> &to, const Units &from) {
@@ -598,6 +673,7 @@ void AddUnits(vector<net::eagle0::shardok::storage::ResolvedUnit> &to, const Uni
             case net::eagle0::shardok::storage::fb::UnitStatus_RESERVE_UNIT:
             case net::eagle0::shardok::storage::fb::UnitStatus_NEVER_ENTERED_UNIT:
             case net::eagle0::shardok::storage::fb::UnitStatus_RESERVED_SLOT:
+            case net::eagle0::shardok::storage::fb::UnitStatus_PENDING_REINFORCEMENT:
                 ru.set_status(
                         net::eagle0::shardok::storage::ResolvedUnit_UnitStatus_NEVER_ENTERED_UNIT);
                 break;

src/main/cpp/net/eagle0/shardok/library/ShardokEngine.hpp

@@ -20,6 +20,7 @@
 #include "src/main/cpp/net/eagle0/shardok/library/fb_helpers/GameStateHelpers.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/map/CoordsSet.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/settings/GameSettings.hpp"
+#include "src/main/cpp/net/eagle0/shardok/library/tutorial/TutorialBattleController.hpp"
 #include "src/main/protobuf/net/eagle0/shardok/api/action_result_view.pb.h"
 #include "src/main/protobuf/net/eagle0/shardok/api/game_state_view.pb.h"
 #include "src/main/protobuf/net/eagle0/shardok/api/unit_view.pb.h"
@@ -36,6 +37,7 @@ using net::eagle0::shardok::api::UnitView;
 using PlayerInfoProto = net::eagle0::shardok::common::PlayerInfo;
 using net::eagle0::shardok::storage::ShardokActionWithResultingState;
 using HexMapProto = net::eagle0::shardok::common::HexMap;
+using TutorialBattleConfigProto = net::eagle0::common::TutorialBattleConfig;
 
 class ShardokEngine {
 private:
@@ -52,6 +54,9 @@ private:
 
     const CoordsSet criticalTileCoords;
 
+    TutorialBattleController tutorialController_;
+    std::optional<ReinforcementPlacementInfo> pendingReinforcementPlacement_;
+
     mutable CommandListSPtr cachedAvailableCommands{};
 
     void ApplyAndAddActionResult(const ActionResult &result);
@@ -72,6 +77,7 @@ private:
     }
 
     void HandlePlayerTurnEnd(const std::shared_ptr<RandomGenerator> &randomGenerator);
+    void ResumeAfterReinforcementPlacement(const std::shared_ptr<RandomGenerator> &randomGenerator);
     [[nodiscard]] auto UncachedGetAvailableCommands(PlayerId playerId, bool includeFollowUps) const
             -> CommandListSPtr;
 
@@ -197,6 +203,17 @@ public:
 
     [[nodiscard]] auto GetGameSettings() const -> GameSettingsSPtr { return gameSettings; }
 
+    /// Configure the tutorial battle controller (call after construction if needed)
+    void SetTutorialBattleConfig(const TutorialBattleConfigProto &config) {
+        tutorialController_ = TutorialBattleController(config);
+    }
+
+    /// Returns the pending reinforcement placement info, if any.
+    [[nodiscard]] auto GetPendingReinforcementPlacement() const
+            -> const std::optional<ReinforcementPlacementInfo> & {
+        return pendingReinforcementPlacement_;
+    }
+
     static inline auto GameIsOver(const fb::GameStatus *status) -> bool {
         return (status->state() == net::eagle0::shardok::storage::fb::GameStatus_::State_VICTORY);
     }