Ignore native plugin .meta files in gitignore

Unity creates .meta files for the native plugins which should also
be ignored since the plugins are built at CI time.

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

.github/workflows/artifact_storage_check.yml

@@ -0,0 +1,37 @@
+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:"
+            gh api "repos/${{ github.repository }}/actions/artifacts" \
+              --paginate -q '.artifacts[] | "\(.size_in_bytes)\t\(.name)\t\(.created_at)"' | \
+              sort -rn | head -20 | \
+              awk -F'\t' '{printf "%d MB\t%s\t%s\n", $1/1024/1024, $2, $3}'
+            exit 1
+          fi
+
+          echo "Storage is within acceptable limits."

.github/workflows/auth_build.yml

@@ -24,7 +24,7 @@ permissions:
 
 jobs:
   build-auth:
-    runs-on: self-hosted
+    runs-on: [self-hosted, bazel]
     outputs:
       image_tag: ${{ steps.push-auth.outputs.image_tag }}
     steps:
@@ -104,6 +104,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 +120,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 +127,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_test.yml

@@ -26,13 +26,15 @@ permissions:
 
 jobs:
   test:
-    runs-on: self-hosted
+    runs-on: [self-hosted, bazel]
 
     steps:
     - name: Checkout repository
       uses: actions/checkout@v4
       with:
         lfs: false
+    - name: Check BUILD.bazel dependencies
+      run: ./scripts/check_build_deps.sh --strict
     - name: Run tests
       id: test
       continue-on-error: true
@@ -75,6 +77,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 +85,7 @@ jobs:
         name: failed-test-logs
         path: failed_test_logs/
         if-no-files-found: ignore
+        retention-days: 5
     - name: Fail if tests failed
       if: steps.test.outcome == 'failure'
       run: exit 1

.github/workflows/build_protos_test.yml

@@ -1,21 +0,0 @@
-name: Build Protos
-
-on:
-  pull_request:
-    paths:
-      - "src/main/protobuf/**"
-
-permissions:
-  contents: read
-
-jobs:
-  build:
-    runs-on: self-hosted
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          lfs: false
-      - name: Run tests
-        run: ./scripts/build_protos.sh

.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/client_presigner.yml

@@ -1,35 +0,0 @@
-name: Client Presigner
-
-on:
-  push:
-    branches: [ "main" ]
-    paths:
-      - ".github/workflows/client_presigner.yml"
-      - "src/main/go/net/eagle0/client_download/**"
-      - "src/main/go/net/eagle0/util/**"
-  pull_request:
-    paths:
-      - ".github/workflows/client_presigner.yml"
-      - "src/main/go/net/eagle0/client_download/**"
-      - "src/main/go/net/eagle0/util/**"
-
-permissions:
-  contents: read
-
-jobs:
-  client-presigner:
-    runs-on: self-hosted
-
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          lfs: false
-          clean: false
-      - name: Build Client Presigner
-        run: bazel build --platforms=@io_bazel_rules_go//go/toolchain:linux_amd64 //src/main/go/net/eagle0/client_download
-      - name: Archive presigner binary
-        if: success() || failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: client_download
-          path: bazel-bin/src/main/go/net/eagle0/client_download/client_download_/client_download

.github/workflows/docker_build.yml

@@ -4,10 +4,16 @@ on:
   push:
     branches: [ "main" ]
     paths:
-      - 'src/main/cpp/**'
+      # Note: C++ changes trigger shardok_arm64_build.yml instead
+      # Note: Auth changes trigger auth_build.yml instead
       - 'src/main/go/**'
+      - '!src/main/go/net/eagle0/authservice/**'
+      - '!src/main/go/net/eagle0/authcli/**'
       - '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'
@@ -33,11 +39,11 @@ permissions:
 jobs:
   # Single consolidated build job - builds all images with one bazel invocation
   # This uses 1 runner slot instead of 4, and Bazel parallelizes internally
+  # NOTE: Must run on a runner with the bazel label to ensure consistent Bazel cache
   build-all:
-    runs-on: self-hosted
+    runs-on: [self-hosted, bazel]
     outputs:
       eagle_image_tag: ${{ steps.push-images.outputs.eagle_image_tag }}
-      shardok_image_tag: ${{ steps.push-images.outputs.shardok_image_tag }}
       admin_image_tag: ${{ steps.push-images.outputs.admin_image_tag }}
       jfr_sidecar_image_tag: ${{ steps.push-images.outputs.jfr_sidecar_image_tag }}
     steps:
@@ -52,13 +58,12 @@ jobs:
           set -ex
 
           # Build ALL images in a single bazel command - Bazel parallelizes internally
-          # This is much more efficient than 4 separate GitHub Actions jobs
-          echo "=== Building all Docker images ==="
+          # Note: Shardok is built separately for ARM64 and deployed to Hetzner
+          echo "=== Building Docker images ==="
           bazel build \
             --platforms=//:linux_x86_64 \
             --extra_toolchains=@llvm_toolchain_linux//:all \
             //ci:eagle_server_image \
-            //ci:shardok_server_image \
             //ci:admin_server_image \
             //ci:jfr_sidecar_image \
             //src/main/go/net/eagle0/warmup:warmup_linux_amd64
@@ -69,35 +74,18 @@ jobs:
 
           # Save all image paths before any other bazel command changes bazel-bin symlink
           EAGLE_PATH=$(readlink -f bazel-bin/ci/eagle_server_image)
-          SHARDOK_PATH=$(readlink -f bazel-bin/ci/shardok_server_image)
           ADMIN_PATH=$(readlink -f bazel-bin/ci/admin_server_image)
           JFR_PATH=$(readlink -f bazel-bin/ci/jfr_sidecar_image)
 
           echo "eagle_path=$EAGLE_PATH" >> $GITHUB_OUTPUT
-          echo "shardok_path=$SHARDOK_PATH" >> $GITHUB_OUTPUT
           echo "admin_path=$ADMIN_PATH" >> $GITHUB_OUTPUT
           echo "jfr_path=$JFR_PATH" >> $GITHUB_OUTPUT
 
           echo "=== Image paths ==="
           echo "Eagle: $EAGLE_PATH"
-          echo "Shardok: $SHARDOK_PATH"
           echo "Admin: $ADMIN_PATH"
           echo "JFR Sidecar: $JFR_PATH"
 
-          # Verify Shardok binary is ELF (Linux) format
-          echo "=== Verifying Shardok binary format ==="
-          BINARY_TAR="bazel-bin/ci/shardok_binary_layer.tar"
-          if [ -f "$BINARY_TAR" ]; then
-            MAGIC=$(tar -xOf "$BINARY_TAR" app/shardok-server 2>/dev/null | head -c 4 | xxd -p)
-            echo "Binary magic in tar: $MAGIC"
-            if [ "$MAGIC" = "7f454c46" ]; then
-              echo "SUCCESS: Binary is ELF format (Linux)"
-            else
-              echo "ERROR: Binary is NOT ELF format!"
-              exit 1
-            fi
-          fi
-
       - name: Login to DigitalOcean Container Registry
         if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.push_images == 'true')
         env:
@@ -143,14 +131,6 @@ jobs:
           $CRANE copy "$EAGLE_TAG" "registry.digitalocean.com/eagle0/eagle-server:latest"
           echo "eagle_image_tag=$EAGLE_TAG" >> $GITHUB_OUTPUT
 
-          # Push Shardok image
-          SHARDOK_IMAGE="${{ steps.build-all.outputs.shardok_path }}"
-          SHARDOK_TAG="registry.digitalocean.com/eagle0/shardok-server:${GIT_SHA}"
-          echo "Pushing Shardok: $SHARDOK_TAG"
-          $CRANE push "$SHARDOK_IMAGE" "$SHARDOK_TAG"
-          $CRANE copy "$SHARDOK_TAG" "registry.digitalocean.com/eagle0/shardok-server:latest"
-          echo "shardok_image_tag=$SHARDOK_TAG" >> $GITHUB_OUTPUT
-
           # Push Admin image
           ADMIN_IMAGE="${{ steps.build-all.outputs.admin_path }}"
           ADMIN_TAG="registry.digitalocean.com/eagle0/admin-server:${GIT_SHA}"
@@ -170,13 +150,12 @@ jobs:
           echo "=== All images pushed successfully ==="
 
   deploy:
-    runs-on: self-hosted
+    runs-on: [self-hosted, bazel]
     needs: [build-all]
     if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.push_images == 'true')
     environment: production
     env:
       EAGLE_IMAGE: ${{ needs.build-all.outputs.eagle_image_tag }}
-      SHARDOK_IMAGE: ${{ needs.build-all.outputs.shardok_image_tag }}
       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 }}
@@ -189,6 +168,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 }}
       SHARDOK_ADDRESS: ${{ secrets.SHARDOK_ADDRESS }}
       SHARDOK_AUTH_TOKEN: ${{ secrets.SHARDOK_AUTH_TOKEN }}
       SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
@@ -219,7 +206,7 @@ jobs:
           # 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
 
@@ -228,7 +215,6 @@ jobs:
           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/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: |
@@ -236,63 +222,95 @@ jobs:
           set -ex
           cd /opt/eagle0
 
-          # Environment variables passed via heredoc
-          EAGLE_IMAGE="${EAGLE_IMAGE}"
-          SHARDOK_IMAGE="${SHARDOK_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 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 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}"
 
           # 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}" \
-            "SHARDOK_IMAGE=\${SHARDOK_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, \$SHARDOK_IMAGE, \$ADMIN_IMAGE, \$JFR_SIDECAR_IMAGE"
+          echo "Using images: \$EAGLE_IMAGE, \$ADMIN_IMAGE, \$JFR_SIDECAR_IMAGE"
 
           # Install crane for pulling OCI images
           echo "Installing crane..."
@@ -304,9 +322,6 @@ jobs:
           echo "Pulling Eagle image..."
           ./crane pull "\${EAGLE_IMAGE}" eagle.tar && docker load -i eagle.tar && rm eagle.tar
 
-          echo "Pulling Shardok image..."
-          ./crane pull "\${SHARDOK_IMAGE}" shardok.tar && docker load -i shardok.tar && rm shardok.tar
-
           echo "Pulling Admin image..."
           ./crane pull "\${ADMIN_IMAGE}" admin.tar && docker load -i admin.tar && rm admin.tar
 
@@ -319,18 +334,43 @@ jobs:
 
           echo "All images pulled successfully"
 
-          # Recreate shardok (stateless, safe to restart anytime)
-          docker compose -f docker-compose.prod.yml up -d --no-deps --force-recreate shardok
+          # =================================================================
+          # 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)
+
+          # 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
+          docker rm shardok-server 2>/dev/null || true
 
           # 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

.github/workflows/installer_build.yml

@@ -14,10 +14,11 @@ on:
 
 permissions:
   contents: read
+  actions: write  # Required to delete artifacts after deploy
 
 jobs:
   build-installer:
-    runs-on: self-hosted
+    runs-on: [self-hosted, bazel]
 
     steps:
       - uses: actions/checkout@v4
@@ -55,6 +56,7 @@ jobs:
         with:
           name: eagle-installer
           path: ./installer-output/EagleInstaller.exe
+          retention-days: 1
 
       - name: Verify installer exists
         if: success()
@@ -108,4 +110,20 @@ jobs:
           bazel run //src/main/go/net/eagle0/build/manifest_manager:manifest_manager -- installer /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
+          # The installer is deployed to S3, so artifacts are redundant
+          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/mac_build.yml

@@ -6,13 +6,18 @@ on:
     paths:
       - ".github/workflows/mac_build.yml"
       - "src/main/csharp/net/eagle0/clients/unity/**"
-      - "src/main/proto/**"
+      - "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_protos.sh"
       - "scripts/build_mac_plugin.sh"
       - "scripts/inject_sparkle.sh"
       - "scripts/codesign_mac_app.sh"
-      - "scripts/notarize_mac_app.sh"
+      - "scripts/notarize_submit.sh"
+      - "scripts/notarize_wait.sh"
       - "ci/github_actions/build_mac.sh"
       - "ci/github_actions/build_unity_mac.sh"
       - "ci/mac/**"
@@ -20,11 +25,17 @@ on:
     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/inject_sparkle.sh"
       - "scripts/codesign_mac_app.sh"
-      - "scripts/notarize_mac_app.sh"
+      - "scripts/notarize_submit.sh"
+      - "scripts/notarize_wait.sh"
       - "ci/github_actions/build_mac.sh"
       - "ci/github_actions/build_unity_mac.sh"
       - "ci/mac/**"
@@ -38,28 +49,37 @@ on:
 
 permissions:
   contents: read
+  actions: write  # Required to delete artifacts after deploy
 
 jobs:
-  mac-unity:
-    runs-on: self-hosted
+  build-and-sign:
+    runs-on: [self-hosted, macOS, unity-mac]
+    outputs:
+      submission_id: ${{ steps.notarize-submit.outputs.submission_id }}
+      should_deploy: ${{ steps.check-deploy.outputs.should_deploy }}
 
     steps:
       - uses: actions/checkout@v4
         with:
           lfs: true
-          clean: false
+          clean: true  # Remove untracked files like old SparklePlugin.bundle
           fetch-depth: 0  # For version numbering from git history
 
       - name: Pull LFS files
         run: git lfs pull
 
       - name: Restore Library/
+        env:
+          UNITY_CACHE_PLATFORM: mac
         run: ./ci/github_actions/restore_library.sh
 
       - name: Build Mac Unity
         run: ./ci/github_actions/build_unity_mac.sh "/tmp/eagle0/eagle0MAC"
 
       - name: Persist Library/
+        if: success()
+        env:
+          UNITY_CACHE_PLATFORM: mac
         run: ./ci/github_actions/persist_library.sh
 
       - name: Inject Sparkle Framework
@@ -70,8 +90,21 @@ jobs:
           chmod +x ./scripts/inject_sparkle.sh
           ./scripts/inject_sparkle.sh "/tmp/eagle0/eagle0MAC/eagle0.app"
 
+      - name: Check if should deploy
+        id: check-deploy
+        run: |
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" && "${{ github.event.inputs.skip_signing }}" == "true" ]]; then
+            echo "should_deploy=false" >> $GITHUB_OUTPUT
+          elif [[ "${{ github.event_name }}" == "push" && "${{ github.ref }}" == "refs/heads/main" ]]; then
+            echo "should_deploy=true" >> $GITHUB_OUTPUT
+          elif [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+            echo "should_deploy=true" >> $GITHUB_OUTPUT
+          else
+            echo "should_deploy=false" >> $GITHUB_OUTPUT
+          fi
+
       - name: Import Code Signing Certificate
-        if: success() && ((github.event_name == 'workflow_dispatch' && github.event.inputs.skip_signing != 'true') || (github.event_name == 'push' && github.ref == 'refs/heads/main'))
+        if: success() && steps.check-deploy.outputs.should_deploy == 'true'
         env:
           MACOS_CERTIFICATE: ${{ secrets.MACOS_CERTIFICATE }}
           MACOS_CERTIFICATE_PWD: ${{ secrets.MACOS_CERTIFICATE_PWD }}
@@ -101,25 +134,125 @@ jobs:
           rm certificate.p12
 
       - name: Code Sign App
-        if: success() && ((github.event_name == 'workflow_dispatch' && github.event.inputs.skip_signing != 'true') || (github.event_name == 'push' && github.ref == 'refs/heads/main'))
+        if: success() && steps.check-deploy.outputs.should_deploy == 'true'
         env:
           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"
 
-      - name: Notarize App
-        if: success() && ((github.event_name == 'workflow_dispatch' && github.event.inputs.skip_signing != 'true') || (github.event_name == 'push' && github.ref == 'refs/heads/main'))
+      - name: Submit for Notarization
+        id: notarize-submit
+        if: success() && steps.check-deploy.outputs.should_deploy == 'true'
         env:
           APPLE_ID: ${{ secrets.APPLE_ID }}
           APP_SPECIFIC_PASSWORD: ${{ secrets.APP_SPECIFIC_PASSWORD }}
           TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
         run: |
-          chmod +x ./scripts/notarize_mac_app.sh
-          ./scripts/notarize_mac_app.sh "/tmp/eagle0/eagle0MAC/eagle0.app"
+          chmod +x ./scripts/notarize_submit.sh
+          ./scripts/notarize_submit.sh "/tmp/eagle0/eagle0MAC/eagle0.app" >> $GITHUB_OUTPUT
+
+      - name: Cleanup Keychain
+        if: always()
+        run: |
+          security delete-keychain build.keychain 2>/dev/null || true
+
+      - name: Zip signed app for artifact
+        if: success() && steps.check-deploy.outputs.should_deploy == 'true'
+        run: |
+          cd /tmp/eagle0/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
+          retention-days: 1
+
+      - name: Archive Build Log
+        if: success() || failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: editor_mac.log
+          path: /tmp/eagle0/editor_mac.log
+          retention-days: 5
+
+  wait-notarization:
+    needs: build-and-sign
+    if: needs.build-and-sign.outputs.should_deploy == 'true'
+    runs-on: [self-hosted, macOS, notarize]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: scripts
+
+      - name: Clean download directory
+        run: rm -rf /tmp/eagle0/eagle0MAC
+
+      - name: Download signed app
+        uses: actions/download-artifact@v4
+        with:
+          name: signed-mac-app
+          path: /tmp/eagle0/eagle0MAC
+
+      - name: Unzip signed app
+        run: |
+          cd /tmp/eagle0/eagle0MAC
+          ditto -x -k eagle0.app.zip .
+          rm eagle0.app.zip
+          ls -la /tmp/eagle0/eagle0MAC/eagle0.app/
+
+      - name: Wait for Notarization and Staple
+        env:
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APP_SPECIFIC_PASSWORD: ${{ secrets.APP_SPECIFIC_PASSWORD }}
+          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"
+
+      - name: Zip notarized app for artifact
+        run: |
+          cd /tmp/eagle0/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
+          retention-days: 1
+
+  deploy:
+    needs: [build-and-sign, wait-notarization]
+    if: needs.build-and-sign.outputs.should_deploy == 'true'
+    runs-on: [self-hosted, macOS, unity-mac]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # For version numbering
+
+      - name: Clean download directory
+        run: rm -rf /tmp/eagle0/eagle0MAC
+
+      - name: Download notarized app
+        uses: actions/download-artifact@v4
+        with:
+          name: notarized-mac-app
+          path: /tmp/eagle0/eagle0MAC
+
+      - name: Unzip notarized app
+        run: |
+          cd /tmp/eagle0/eagle0MAC
+          ditto -x -k eagle0.app.zip .
+          rm eagle0.app.zip
 
       - name: Deploy Mac Build
-        if: success() && ((github.event_name == 'workflow_dispatch' && github.event.inputs.skip_signing != 'true') || (github.event_name == 'push' && github.ref == 'refs/heads/main'))
         env:
           ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY_ID }}
           SECRET_KEY: ${{ secrets.SECRET_KEY }}
@@ -130,25 +263,60 @@ jobs:
           echo "$SPARKLE_EDDSA_PRIVATE_KEY" > "$SPARKLE_PRIVATE_KEY_PATH"
           chmod 600 "$SPARKLE_PRIVATE_KEY_PATH"
 
-          VERSION=$(git describe --tags --always)
+          # 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"
+
+          # Use commit count for automatic incrementing versions (e.g., 1.0.9548)
           BUILD_NUMBER=$(git rev-list --count HEAD)
+          VERSION="1.0.${BUILD_NUMBER}"
 
           bazel run //src/main/go/net/eagle0/build/mac_build_handler:mac_build_handler -- \
             "/tmp/eagle0/eagle0MAC/eagle0.app" \
             "$VERSION" \
             "$BUILD_NUMBER" \
+            "$BACKGROUND_PATH" \
             "$SPARKLE_PRIVATE_KEY_PATH"
 
           rm "$SPARKLE_PRIVATE_KEY_PATH"
 
-      - name: Cleanup Keychain
-        if: always()
+      - name: Delete this run's Mac app artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
-          security delete-keychain build.keychain 2>/dev/null || true
+          # Delete only this run's artifacts to avoid conflicts with concurrent builds
+          for artifact_name in signed-mac-app notarized-mac-app; do
+            echo "Fetching $artifact_name artifacts for run ${{ github.run_id }}..."
+            artifact_ids=$(gh api "repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/artifacts" \
+              -q ".artifacts[] | select(.name == \"$artifact_name\") | .id")
+            for id in $artifact_ids; do
+              echo "Deleting artifact ID: $id"
+              gh api -X DELETE "repos/${{ github.repository }}/actions/artifacts/$id" || true
+            done
+          done
+          echo "Cleanup complete"
 
-      - name: Archive Build Log
-        if: success() || failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: editor_mac.log
-          path: /tmp/eagle0/editor_mac.log
+  # Cleanup job runs regardless of success/failure to prevent artifact accumulation
+  cleanup:
+    needs: [build-and-sign, wait-notarization, deploy]
+    if: always()
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Delete this run's Mac app artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Clean up only this run's artifacts to avoid conflicts with concurrent builds
+          for artifact_name in signed-mac-app notarized-mac-app; do
+            echo "Fetching $artifact_name artifacts for run ${{ github.run_id }}..."
+            artifact_ids=$(gh api "repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/artifacts" \
+              -q ".artifacts[] | select(.name == \"$artifact_name\") | .id")
+            for id in $artifact_ids; do
+              echo "Deleting artifact ID: $id"
+              gh api -X DELETE "repos/${{ github.repository }}/actions/artifacts/$id" || true
+            done
+          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

@@ -24,7 +24,7 @@ permissions:
 
 jobs:
   build-shardok-arm64:
-    runs-on: self-hosted
+    runs-on: [self-hosted, bazel]
     outputs:
       image_tag: ${{ steps.push-shardok.outputs.image_tag }}
     steps:
@@ -159,7 +159,7 @@ jobs:
           echo "Also tagged as: registry.digitalocean.com/eagle0/shardok-server:arm64-latest"
 
   deploy-hetzner:
-    runs-on: self-hosted
+    runs-on: [self-hosted, bazel]
     needs: [build-shardok-arm64]
     if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.push_images == 'true')
     environment: production

.github/workflows/shardok_build.yml

@@ -28,7 +28,7 @@ permissions:
 
 jobs:
   build:
-    runs-on: self-hosted
+    runs-on: [self-hosted, bazel]
 
     steps:
       - name: Checkout repository

.github/workflows/unity_build.yml

@@ -6,7 +6,11 @@ on:
     paths:
       - ".github/workflows/unity_build.yml"
       - "src/main/csharp/net/eagle0/clients/unity/**"
-      - "src/main/proto/**"
+      - "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/**"
       - "scripts/build_protos.sh"
       - "scripts/build_plugins.sh"
       - "scripts/build_windows_plugin.sh"
@@ -15,13 +19,16 @@ on:
       - "ci/github_actions/persist_library.sh"
       - "MODULE.bazel"
       - "WORKSPACE"
-      - "src/main/proto/net/eagle0/eagle/**/BUILD.bazel"
   workflow_dispatch:
   pull_request:
     paths:
       - ".github/workflows/unity_build.yml"
       - "src/main/csharp/net/eagle0/clients/unity/**"
-      - "src/main/proto/**"
+      - "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/**"
       - "scripts/build_protos.sh"
       - "scripts/build_plugins.sh"
       - "scripts/build_windows_plugin.sh"
@@ -30,27 +37,31 @@ on:
       - "ci/github_actions/persist_library.sh"
       - "MODULE.bazel"
       - "WORKSPACE"
-      - "src/main/proto/**/BUILD.bazel"
 
 permissions:
   contents: read
 
 jobs:
   windows-unity:
-    runs-on: self-hosted
+    runs-on: [self-hosted, macOS, unity-windows]
 
     steps:
       - uses: actions/checkout@v4
         with:
           lfs: true
-          clean: false
+          clean: true  # Remove untracked files from previous builds
       - name: Pull lfs files
         run: git lfs pull
       - name: Restore Library/
+        env:
+          UNITY_CACHE_PLATFORM: windows
         run: ./ci/github_actions/restore_library.sh
       - name: Build Windows unity
         run: ./ci/github_actions/build_unity.sh "/tmp/eagle0/eagle0WIN"
       - name: Persist Library/
+        if: success()
+        env:
+          UNITY_CACHE_PLATFORM: windows
         run: ./ci/github_actions/persist_library.sh
       - name: Deploy Windows unity
         if: success() && github.ref == 'refs/heads/main' && github.event_name == 'push'
@@ -87,4 +98,5 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: editor_win.log
-          path: /tmp/eagle0/editor_win.log
+          path: /tmp/eagle0/editor_win.log
+          retention-days: 5

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",
+    ],
+)

DEPROTO_PLAN.md

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

MODULE.bazel

@@ -130,6 +130,13 @@ bazel_dep(name = "apple_support", version = "1.21.1", repo_name = "build_bazel_a
 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")
 
+# 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
 #
@@ -293,6 +300,17 @@ http_archive(
     ],
 )
 
+# Sparkle framework for macOS auto-updates
+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),
+)
+
 # Busybox static binary for Docker health checks (provides nc, wget, etc.)
 # Primary: DigitalOcean Spaces (public, reliable)
 # Fallback: busybox.net (can be unreliable/slow)

MODULE.bazel.lock

@@ -396,7 +396,7 @@
     "@@apple_support~//crosstool:setup.bzl%apple_cc_configure_extension": {
       "general": {
         "bzlTransitiveDigest": "Z3yAd66IJL0GAZUTSeMOjoHiE1SZPPwiIs/XQui5BvE=",
-        "usagesDigest": "tl3VVeQX3Hzh7FhM2gjnkCwEJpRMlY5S6a850WY/xvc=",
+        "usagesDigest": "DqQsfZN5lA8z+nLEEY+EpKGzQ8M73mDm/A8lofDSyus=",
         "recordedFileInputs": {},
         "recordedDirentsInputs": {},
         "envVariables": {},

ci/github_actions/build_unity.sh

@@ -9,9 +9,6 @@ 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"

ci/github_actions/build_unity_mac.sh

@@ -7,8 +7,8 @@ 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
 

ci/github_actions/persist_library.sh

@@ -1,12 +1,25 @@
 #!/bin/bash
+#
+# Persist Unity Library/ cache to persistent storage
+#
+# Environment variables:
+#   UNITY_CACHE_PLATFORM - Platform identifier (e.g., "mac", "windows")
+#                          Defaults to "mac" if not set
+#
+# Note: Library/Bee/ is excluded because it contains DAG files with hardcoded
+# file paths that become stale when project files change. This prevents
+# "Data at the root level is invalid" XML errors from stale references.
 
 set -uxo pipefail
 
-/bin/echo "persist Library/"
+PLATFORM="${UNITY_CACHE_PLATFORM:-mac}"
+CACHE_DIR="/tmp/eagle0/Library-${PLATFORM}"
+
+/bin/echo "persist Library/ to $CACHE_DIR (excluding Bee/)"
 
 # 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/
+/usr/bin/rsync -rtlDvq --exclude='Bee/' src/main/csharp/net/eagle0/clients/unity/eagle0/Library/ "$CACHE_DIR/"
 rsync_exit=$?
 
 if [ $rsync_exit -eq 0 ]; then

ci/github_actions/restore_library.sh

@@ -1,7 +1,16 @@
 #!/bin/bash
+#
+# Restore Unity Library/ cache from persistent storage
+#
+# Environment variables:
+#   UNITY_CACHE_PLATFORM - Platform identifier (e.g., "mac", "windows")
+#                          Defaults to "mac" if not set
 
 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/
+PLATFORM="${UNITY_CACHE_PLATFORM:-mac}"
+CACHE_DIR="/tmp/eagle0/Library-${PLATFORM}"
+
+/bin/echo "restore Library/ from $CACHE_DIR"
+/bin/mkdir -p "$CACHE_DIR"
+/usr/bin/rsync -rtlDvq "$CACHE_DIR/" src/main/csharp/net/eagle0/clients/unity/eagle0/Library/

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)
-EAGLE_IMAGE=registry.digitalocean.com/eagle0/eagle-server:latest
-SHARDOK_IMAGE=registry.digitalocean.com/eagle0/shardok-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
-SHARDOK_ADDRESS=shardok:40042
-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

@@ -1,11 +1,13 @@
 # Docker Compose for production deployment
 #
 # Local testing:
-#   Build images: bazel run //ci:eagle_server_load && bazel run //ci:shardok_server_load && bazel run //ci:auth_server_load
+#   Build images: bazel run //ci:eagle_server_load && bazel run //ci:auth_server_load
 #   Run: docker compose -f docker-compose.prod.yml up
 #
 # Production deployment:
 #   Run: docker compose -f docker-compose.prod.yml up -d
+#
+# Note: Shardok runs on Hetzner ARM64 server, deployed via shardok_arm64_build.yml workflow.
 
 services:
   # Blue-green deployment: eagle-blue is the primary (production) instance
@@ -19,7 +21,7 @@ services:
       - "--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:
@@ -30,10 +32,9 @@ services:
       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:-}"
-      # Auth token for remote Shardok on Hetzner (only used when shardok address contains .eagle0.net)
+      # 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.)
       EAGLE_SAVE_DIR: "/app/saves"
@@ -45,9 +46,8 @@ 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:
-      - shardok
       - auth
     restart: unless-stopped
     logging:
@@ -70,7 +70,7 @@ services:
       - "--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:
@@ -81,9 +81,8 @@ services:
       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"
@@ -94,9 +93,8 @@ 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:
-      - shardok
       - auth
     restart: "no"  # Don't auto-restart during deployment
     logging:
@@ -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
@@ -162,30 +170,8 @@ services:
       retries: 3
       start_period: 10s
 
-  shardok:
-    image: ${SHARDOK_IMAGE:-registry.digitalocean.com/eagle0/shardok-server:latest}
-    container_name: shardok-server
-    mem_limit: 1g
-    memswap_limit: 1g  # Prevent swap, OOM-kill cleanly instead
-    ports:
-      - "40042:40042"
-      - "40052:40052"
-    environment:
-      SHARDOK_RESOURCES_PATH: "/app/resources"
-      SHARDOK_MAPS_PATH: "/app/resources/maps"
-      SHARDOK_EAGLE_INTERFACE_ADDRESS: "0.0.0.0:40042"
-    restart: unless-stopped
-    logging:
-      driver: "json-file"
-      options:
-        max-size: "100m"
-        max-file: "5"
-    healthcheck:
-      test: ["CMD-SHELL", "nc -z localhost 40042 || exit 1"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 10s
+  # Note: Shardok runs on Hetzner ARM64 server, not in this docker-compose.
+  # Configure SHARDOK_ADDRESS to point to the Hetzner instance.
 
   nginx:
     image: nginx:alpine

docs/DEPROTO_PLAN.md

@@ -33,7 +33,26 @@
 
 ---
 
-## Current State
+## Current State (January 2026)
+
+### Summary
+
+| Area | Proto Imports | Status |
+|------|---------------|--------|
+| AI (`/ai/`) | **0** | ✅ **Complete** |
+| Actions (`/library/actions/impl/action/`) | **0** | ✅ **Complete** |
+| Commands (`/library/actions/impl/command/`) | **0** | ✅ **Complete** |
+| Availability (`/library/actions/availability/`) | **0** | ✅ **Complete** (Hostility migrated) |
+| Command Choice Helpers (`/library/util/command_choice_helpers/`) | **0** | ✅ **Complete** (Hostility migrated) |
+| View Filters (`/library/util/view_filters/`) | **1** | Keep (boundary code for battles) |
+| Other Utilities (`/library/util/`) | **0** | ✅ **Complete** (Hostility migrated) |
+| NewGameCreation (`/service/new_game_creation/`) | **0** | ✅ **Complete** (except input GameParameters proto) |
+| LLM Prompt Generators (`/library/actions/llm_prompt_generators/`) | **0** | ✅ **Complete** (all 4 files migrated) |
+| Root Library (`/library/`) | **1** | ✅ **Mostly Complete** (only GameHistory for Shardok boundary) |
+
+**Total: 2 files with proto imports in library/** - all are boundary code (expected)
+
+**Note:** The `bazel query` for proto dependencies returns many targets because it includes transitive dependencies. All non-boundary library code is now protoless.
 
 ### Completed Phases
 
@@ -43,346 +62,290 @@
 | 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 5: Action Base Classes | **Complete** | All actions converted to T-type base classes |
+| Phase 5b-d: RoundPhaseAdvancer | **Complete** | Uses Scala GameState throughout |
+| Phase 6: Core Engine | **Complete** | ActionResultApplier, RandomStateSequencer protoless |
+| Phase 6b: CommandFactory | **Complete** | Uses Scala SelectedCommand and AvailableCommand |
+| Phase 6c: AI Clients | **Complete** | AIClient, command choosers all protoless |
+| Phase 6d: CommandSelection | **Complete** | Renamed ScalaCommandSelection → CommandSelection |
 
-### Phase 5c/5d Progress (Complete)
+### Recent Completions (PRs #5326-#5390)
 
-`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
+1. **CommandFactory protoless** - Now accepts/returns Scala `SelectedCommand` types
+2. **AI clients protoless** - `AIClient`, `MidGameAIClient`, all command choosers use Scala types
+3. **CommandSelection cleanup** - Deleted legacy proto-based `CommandSelection`, renamed `ScalaCommandSelection` → `CommandSelection`
+4. **AvailableCommandsFactory protoless** - Returns Scala `OneProvinceAvailableCommands`
+5. **All CommandChoiceHelpers protoless** - All selector/chooser files converted
+6. **ChronicleEventGenerator protoless** (PR #5332) - Removed last proto enum import from Actions layer
+7. **ProvinceUtils protoless** (PR #5333) - Converted to use Scala `BattalionType`
+8. **FactionViewFilter protoless** (PR #5334) - Returns Scala `FactionView`, converts to proto at edge
+9. **HeroViewFilter protoless** (PR #5336) - Returns Scala `HeroView`, converts to proto at edge
+10. **ProvinceViewFilter protoless** (PR #5341) - `ProvinceView.knownEvents` uses Scala `ProvinceEvent`, converts at edge
+11. **StatWithConditionUtils & ProvinceEventUtils protoless** (PR #5342) - Deleted unused proto overloads
+12. **IncomingArmyUtils protoless** (PR #5348) - Deleted unused `stats()` method
+13. **RansomOfferHelpers deleted** (PR #5351) - Deleted unused dead code file
+14. **MapGenerator protoless** (PR #5373) - Returns Scala types instead of proto
+15. **Remove proto ActionResult from Engine layer** (PR #5378) - Engine uses Scala `ActionResultT`
+16. **NewGameCreation protoless** (PR #5381) - Uses Scala types throughout, no proto conversion
+17. **PersistedHistory Scala API** (PR #5390) - New `apply` overload accepts `Vector[ActionResultT]` directly
+18. **Remove proto types from LLM prompt generators** (PR #5444) - All 4 prompt generator files use Scala types
+19. **Engine API protoless** - `ActionResultFilter`, `Engine`, `EngineImpl` return Scala `ActionResultView`
 
 ---
 
-## Phase 6: Migrate to ActionResultT Consumers
+## Remaining Work
 
-### Objective
+### Phase 7: View Filters ✅ Complete
 
-Eliminate internal consumption of `ActionResultProto`. Everything inside the engine should work with `ActionResultT`.
+| File | Status | Migration Path |
+|------|--------|----------------|
+| `FactionViewFilter.scala` | ✅ **Complete** | Returns Scala `FactionView` (PR #5334) |
+| `HeroViewFilter.scala` | ✅ **Complete** | Returns Scala `HeroView` (PR #5336) |
+| `ProvinceViewFilter.scala` | ✅ **Complete** | Returns Scala `ProvinceView` with Scala events (PR #5341) |
+| `GameStateViewFilter.scala` | ✅ **Complete** | Returns Scala `GameStateView`, converted at boundary |
+| `GameStateViewDiffer.scala` | ✅ **Complete** | Uses Scala diff types internally, converted at boundary |
+| `BattleFilter.scala` | Keep | Uses `ShardokBattleView` (boundary code for battles) |
 
-### Current Flow (Proto-Heavy)
-```
-Action.execute()
-    → ActionResultT
-    → ActionResultProtoConverter.toProto()
-    → ActionResultProto
-    → ActionResultProtoApplierImpl.applyActionResults()
-    → GameStateProto
-    → GameStateConverter.fromProto()
-    → GameStateC
-```
+**Pattern established**: Create Scala view type → Create converter → Update filter to return Scala type → Convert at edge.
 
-### Target Flow (T-Types Throughout)
-```
-Action.execute()
-    → ActionResultT
-    → ActionResultApplier.applyActionResults()
-    → GameStateC
+### Phase 8: LLM Prompt Generators ✅ Complete
 
-    (Proto conversion only at boundaries)
-```
+**Status**: All 4 files migrated to use Scala types
 
-### Key Files to Convert
+| File | Migration | Notes |
+|------|-----------|-------|
+| `BattalionDescriptions.scala` | ✅ **Complete** | Removed proto `BattalionTypeId`, `Battalion`, `BattalionView`; now uses Scala `BattalionTypeId`, `BattalionT`, `BattalionView` |
+| `ChronicleEventTextGenerator.scala` | ✅ **Complete** | Removed proto `EventForChronicle.*`; now uses Scala `ChronicleEvent` sealed trait |
+| `GeneratorUtilities.scala` | ✅ **Complete** | Removed proto `Date`; now uses Scala `Date` |
+| `QuestEndedGeneratorUtilities.scala` | ✅ **Complete** | Removed proto `BattalionTypeId`, `UnaffiliatedHeroQuest.*`; now uses Scala `QuestT`/`QuestC` types |
 
-**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.
+Also updated:
+- `ChronicleUpdatePromptGenerator.scala` - Removed `ChronicleEventConverter` usage
+- `HeroBackstoryUpdatePromptGenerator.scala` - Removed `BattalionViewConverter` and `QuestConverter` usage
+- `QuestFailedPromptGenerator.scala` - Removed `QuestConverter` usage
+- `QuestFulfilledPromptGenerator.scala` - Removed `QuestConverter` usage
 
-**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.
+### Phase 8b: Hostility Proto Migration ✅ Complete
 
-**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.
+**Status**: All 4 files migrated to use Scala `Hostility` enum
 
-**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.
+| File | Migration |
+|------|-----------|
+| `AvailableAttackDecisionCommandFactory.scala` | ✅ Uses Scala `Hostility` |
+| `AvailableFreeForAllDecisionCommandFactory.scala` | ✅ Uses Scala `Hostility` |
+| `AttackDecisionCommandChooser.scala` | ✅ Uses Scala `Hostility` |
+| `FactionUtils.scala` | ✅ Uses Scala `Hostility` |
 
-**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 approach**: Created Scala `Hostility` sealed trait with `Allied`, `Neutral`, `Hostile`, `Self` cases.
 
-**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
+### Phase 8c: Engine API Protoless ✅ Complete
 
-**RandomStateSequencer Migration Progress** (PR #4679 introduced protoless `RandomStateSequencer`):
+**Status**: Engine API now returns Scala types; proto conversion moved to gRPC boundary
 
-| 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) |
+| File | Migration |
+|------|-----------|
+| `ActionResultView.scala` | ✅ NEW - Scala case class for action result views |
+| `ActionResultViewConverter.scala` | ✅ NEW - Converts Scala → Proto at boundary |
+| `ActionResultFilter.scala` | ✅ Returns Scala `ActionResultView` |
+| `Engine.scala` | ✅ Returns Scala `ActionResultView` |
+| `EngineImpl.scala` | ✅ Returns Scala `ActionResultView` |
+| `HumanPlayerClientConnectionState.scala` | ✅ Converts to proto at gRPC boundary |
 
-**TCommandFactory Extraction** (PR #4684):
+**Migration approach**: Created Scala `ActionResultView` case class, updated filter to return Scala type, moved proto conversion to `HumanPlayerClientConnectionState` which is the gRPC boundary.
 
-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.
+### Phase 9: Remaining Utilities ✅ Complete
 
-- `TCommandFactory` - lightweight trait with just `makeTCommand`
-- `CommandFactory extends TCommandFactory` - maintains backward compatibility
-- Actions accepting command factories now use `TCommandFactory` type for better testability
+| File | Proto Usage | Migration Path |
+|------|-------------|----------------|
+| `ProvinceEventUtils.scala` | ✅ **0** | Deleted unused proto overloads (PR #5342) |
+| `StatWithConditionUtils.scala` | ✅ **0** | Deleted unused proto overloads (PR #5342) |
+| `MapGenerator.scala` | ✅ **0** | Returns Scala types (PR #5373) |
+| `IncomingArmyUtils.scala` | ✅ **0** | Deleted unused `stats()` method (PR #5348) |
+| `GameStateViewDiffer.scala` | ✅ **0** | Uses Scala diff types, converts at boundary |
 
-**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** | | |
+### Phase 10: History APIs ✅ Complete
 
 **Completed:**
-- ✅ `ChronicleEventGenerator` converted to return Scala `ChronicleEvent` types directly
-- ✅ `CommandChoiceHelpers` migrated to Scala types
-- ✅ `ResolveBattleAction` refactored to use Scala GameState and ActionResultApplier (PR #5048)
+- `ActionWithResultingState` now has `scalaActionResult` property (lazy converted from proto)
+- `ActionResultFilter.includeForPlayer` uses Scala types (`ActionResultT`, `NotificationT`, `ActionResultType`)
+- `GameHistory.withNewResultsScala` preserves both Scala `GameState` and `ActionResultT` to avoid re-conversion
+- `PersistedHistory.apply` now accepts `Vector[ActionResultT]` directly (PR #5390)
+- `NewGameCreation` is fully protoless (PR #5381)
 
-### 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
+**Note:** History internals still use proto for persistence (expected - proto is good for disk serialization).
 
 ---
 
-## Phase 7: Clean Up Legacy Utilities
+## Architecture Summary
 
-### Objective
-Remove remaining direct proto imports from utility classes.
+### Fully Protoless Areas ✅
 
-### Files to Modify
+- **AI layer** (`/ai/`) - All AI clients and command choosers
+- **Actions** (`/library/actions/impl/action/`) - All 52 action files
+- **Commands** (`/library/actions/impl/command/`) - CommandFactory and all commands
+- **Availability** (`/library/actions/availability/`) - AvailableCommandsFactory and all factories
+- **Command helpers** (`/library/util/command_choice_helpers/`) - All selectors and choosers
+- **Core types** - `CommandSelection`, `SelectedCommand`, `AvailableCommand`, `OneProvinceAvailableCommands`
+- **View types** - `FactionView`, `HeroView`, `ProvinceView`, `ActionResultView` (return Scala, convert at edge)
+- **Engine API** - `Engine`, `EngineImpl`, `ActionResultFilter` return Scala types
 
-| 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 |
+### Proto at Boundaries (Expected) ✅
 
-### 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
+- `GameController.scala` - Client communication
+- `HumanPlayerClientConnectionState.scala` - Converts Scala `ActionResultView` to proto for gRPC
+- `GameStateViewFilter.scala` - Converts Scala views to proto for client
 - `*Converter.scala` - Explicit conversion utilities
-- `*Loader.scala` - File loading utilities
+- `PersistedHistory.scala` - Disk persistence
 
-### Expected No Proto Usage (Verify)
-- `/library/actions/impl/` - Pure Scala models
-- `/library/util/` - Pure Scala models (except loaders)
-- `/model/state/` - Pure Scala models
+### Remaining Proto Usage
+
+- BattleFilter (1 import) - Keep (Shardok battle view boundary)
+- GameHistory (Shardok protos) - Keep (Shardok integration boundary)
 
 ---
 
-## Open Questions
+## Estimated Remaining Effort
 
-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.
+| Component | Files | Status |
+|-----------|-------|--------|
+| View Filters | 0 | ✅ Complete |
+| Utility files | 0 | ✅ Complete |
+| History APIs | 0 | ✅ Complete |
+| LLM Prompt Generators | 0 | ✅ Complete |
+| LLM Request Generators | 0 | ✅ Complete |
+| Hostility Migration | 0 | ✅ Complete |
+| Engine API | 0 | ✅ Complete (Engine returns Scala types) |
+| Root Library (boundary) | 2 | Keep (GameHistory + BattleFilter for Shardok boundary) |
+| **Total non-boundary** | **0** | ✅ **All library code protoless!** |
 
 ---
 
 ## 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
+- [x] Zero proto imports in `/ai/`
+- [x] Zero proto imports in `/library/actions/impl/command/`
+- [x] Zero proto imports in `/library/actions/availability/` (Hostility migrated)
+- [x] Zero proto imports in `/library/util/command_choice_helpers/` (Hostility migrated)
+- [x] Zero proto imports in `/library/actions/impl/action/`
+- [x] Zero proto imports in `/library/util/view_filters/` (except BattleFilter boundary code)
+- [x] Zero proto imports in `/library/util/` (FactionUtils uses Scala Hostility)
+- [x] Zero proto imports in `/service/new_game_creation/` (except input GameParameters)
+- [x] Zero proto imports in `/library/actions/llm_prompt_generators/`
+- [x] Zero proto imports in `/library/actions/llm_request_generators/`
 
 ### Architecture
-- [ ] Clear separation: Scala models (internal) vs Proto (boundaries)
-- [ ] Converters as the only bridge between domains
-- [ ] No "proto creep" into business logic
+- [x] Clear separation: Scala models (internal) vs Proto (boundaries)
+- [x] Converters as the only bridge between domains
+- [x] CommandFactory accepts/returns Scala types
+- [x] AI layer fully protoless
+- [x] FactionViewFilter returns Scala types
+- [x] HeroViewFilter returns Scala types
+- [x] ProvinceViewFilter returns Scala types
+- [x] All view filters return Scala types
+- [x] NewGameCreation uses Scala types
+- [x] PersistedHistory accepts Scala types for new games
+- [x] LLM layer uses Scala types
+- [x] Hostility enum migrated to Scala
+- [x] Engine API returns Scala types (ActionResultView)
+- [x] No "proto creep" into business logic
+
+---
+
+## Open Questions
+
+1. **LLM Prompt Generators**: Should these accept Scala types directly, or is it acceptable to have proto usage here since they're generating text (not core game logic)?
+
+2. ~~**GameStateViewDiffer**: This works with view protos for client updates. Should it remain proto-based since it's generating client-facing data?~~ **Resolved**: GameStateViewDiffer now uses Scala types internally (`GameStateViewDiff`, `ProvinceViewDiff`, etc.) and converts to proto at the boundary in `ActionResultFilter`.
+
+3. **History Serialization**: Keep proto for persistence (good for schema evolution) or consider alternatives?
+
+---
+
+## Proto Import Inventory (Detailed)
+
+**Current: 2 files with direct proto imports in library/** (as of 2026-01-19)
+
+The `bazel query` command reports 167 proto dependencies, but this includes transitive dependencies. The actual files with direct proto imports are listed below.
+
+### Files with Proto Imports
+
+```bash
+# Verified with:
+grep -rl "import net.eagle0.eagle\.\(internal\|common\|api\|views\)\.\|import net.eagle0.shardok\.\|import net.eagle0.common.hostility" \
+  src/main/scala/net/eagle0/eagle/library/ --include="*.scala"
+```
+
+### Boundary Code (Keep Proto) - 2 files
+
+| File | Proto Imports | Notes |
+|------|---------------|-------|
+| `GameHistory.scala` | `ShardokActionResultView`, `ShardokAvailableCommands`, `ShardokActionResult` | Shardok integration boundary |
+| `BattleFilter.scala` | `ShardokBattleView` | Battle view boundary |
+
+### Library Files Made Protoless (Phase 8c)
+
+| File | Previous Proto Usage | Now |
+|------|---------------------|-----|
+| `Engine.scala` | `ActionResultView` proto | ✅ Returns Scala `ActionResultView` |
+| `EngineImpl.scala` | `ActionResultView` proto | ✅ Returns Scala `ActionResultView` |
+| `ActionResultFilter.scala` | `ActionResultTypeProto`, `ActionResultView`, `GameStateViewDiffProto` | ✅ Returns Scala types, no proto imports |
+
+### Hostility Proto - 4 files (Phase 8b) ✅ Complete
+
+All files now use Scala `Hostility` enum (`net.eagle0.eagle.model.state.Hostility`).
+
+| File | Status |
+|------|--------|
+| `AvailableAttackDecisionCommandFactory.scala` | ✅ Uses `FactionUtils` (no direct Hostility import) |
+| `AvailableFreeForAllDecisionCommandFactory.scala` | ✅ Uses `FactionUtils` (no direct Hostility import) |
+| `AttackDecisionCommandChooser.scala` | ✅ Uses Scala `Hostility` |
+| `FactionUtils.scala` | ✅ Uses Scala `Hostility` |
+
+### LLM Prompt Generators - 4 files (Phase 8) ✅ Complete
+
+All files now use Scala types instead of proto.
+
+| File | Migration |
+|------|-----------|
+| `BattalionDescriptions.scala` | ✅ Uses Scala `BattalionTypeId`, `BattalionT`, `BattalionView` |
+| `ChronicleEventTextGenerator.scala` | ✅ Uses Scala `ChronicleEvent` sealed trait |
+| `GeneratorUtilities.scala` | ✅ Uses Scala `Date` |
+| `QuestEndedGeneratorUtilities.scala` | ✅ Uses Scala `QuestT`/`QuestC` types |
+
+### Summary by Directory
+
+| Directory | Files with Proto | Status |
+|-----------|------------------|--------|
+| `ai/` | 0 | ✅ Clean |
+| `actions/availability/` | 0 | ✅ Clean (Hostility migrated) |
+| `actions/impl/action/` | 0 | ✅ Clean |
+| `actions/impl/command/` | 0 | ✅ Clean |
+| `actions/llm_prompt_generators/` | 0 | ✅ Clean (all migrated) |
+| `util/command_choice_helpers/` | 0 | ✅ Clean (Hostility migrated) |
+| `util/view_filters/` | 1 | Keep (BattleFilter boundary) |
+| `util/faction_utils/` | 0 | ✅ Clean (Hostility migrated) |
+| Root (`library/`) | 1 | Keep (GameHistory for Shardok boundary) |
+| **Total** | **2** | |
+
+---
+
+## 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`, 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
+4. Delete `Legacy*` files when no longer needed
+
+### Deleted Legacy Files (no production callers)
+- `LegacyProvinceDistances`
+- `LegacyBattalionSuitability`
+- `LegacyFoodConsumptionUtils`
+- `LegacyHandleRiotUtils`

docs/TUTORIAL_CONTENT.md

@@ -0,0 +1,181 @@
+# Tutorial Content Guide
+
+This document defines all tutorial content. Edit this to refine the text, then update `TutorialContentDefinitions.cs` to match.
+
+---
+
+## Onboarding Sequence
+
+Shown to first-time players. Guides them through the basics of strategic and tactical gameplay.
+
+| Step | ID | Display | Trigger | Title | Description |
+|------|-----|---------|---------|-------|-------------|
+| 1 | `welcome` | Modal | Auto (game start) | Welcome to Eagle0 | Command your armies, recruit heroes, and conquer provinces in this turn-based strategy game.<br><br>Let's walk through the basics! |
+| 2 | `select_province` | Overlay | Completes on: `province_selected` | The Strategic Map | This is your kingdom. Each colored region is a province.<br><br>Tap a province you control (shown in your color) to see what you can do there. |
+| 3 | `province_panel` | Modal | Button click | Province Information | This panel shows province details: its name, terrain, any armies present, and the commands available to you.<br><br>Commands let you move troops, recruit heroes, and more. |
+| 4 | `try_march` | Overlay | Completes on: `command_issued` | Issue a Command | Try issuing a March command to move your army to an adjacent province.<br><br>Select a destination and confirm the order. |
+| 5 | `turn_cycle` | Modal | Button click | The Turn Cycle | Eagle0 uses simultaneous turns. All players give orders at the same time, then turns resolve together.<br><br>When all players are ready, the server processes everyone's commands and shows the results. |
+| 6 | `wait_for_battle` | Hidden | Completes on: `first_battle_available` | *(none)* | *(Invisible step - waits for a battle to become available)* |
+| 7 | `battle_intro` | Modal | Button click | Battle Time! | When armies collide, you'll fight tactical battles on a hex grid.<br><br>You command individual units - infantry, cavalry, archers, and heroes with special abilities. |
+| 8 | `enter_battle` | Overlay | Completes on: `battle_entered` | Enter the Battle | Tap the Battle button to enter tactical combat. |
+| 9 | `tactical_overview` | Modal | Button click | Tactical Combat | Each unit has movement points and attack power. Position your troops wisely!<br><br>Units attack adjacent enemies. Flanking (attacking from multiple sides) deals bonus damage. |
+| 10 | `move_unit` | Overlay | Completes on: `battle_action` | Move Your Units | Tap one of your units to select it, then tap a highlighted hex to move there.<br><br>Blue hexes show where you can move. |
+| 11 | `attack_enemy` | Overlay | Completes on: `battle_action` | Attack! | Move next to an enemy unit, then tap the enemy to attack.<br><br>Red highlights show valid attack targets. |
+| 12 | `end_turn` | Overlay | Completes on: `turn_ended` | End Your Turn | When you've moved all units or want to pass, tap End Turn.<br><br>The enemy will then take their turn. |
+| 13 | `complete` | Modal | Button click (no skip) | You're Ready! | You now know the basics of Eagle0!<br><br>Explore diplomacy, recruit powerful heroes, and conquer the realm. Good luck, commander! |
+
+### Notes on Onboarding Flow
+
+- Steps 1-5 cover strategic gameplay
+- Step 6 is invisible - just waits for a battle
+- Steps 7-12 cover tactical combat
+- Step 13 celebrates completion
+
+**Questions to consider:**
+- Should we skip tactical tutorial if player skips to first battle themselves?
+- Should there be a "skip all" option visible from step 1?
+- Is the step order correct for typical first-game flow?
+
+---
+
+## Strategic Contextual Tutorials
+
+Triggered when players encounter features for the first time.
+
+### Diplomacy Introduction
+| Field | Value |
+|-------|-------|
+| ID | `diplomacy_intro` |
+| Trigger | `diplomacy_available` (diplomacy commands appear) |
+| Display | Modal |
+| Title | Diplomacy |
+| Description | You can negotiate with other factions!<br><br>Offer alliances, declare war, or propose tribute. Your diplomatic choices shape the realm. |
+
+### Hero Recruitment
+| Field | Value |
+|-------|-------|
+| ID | `hero_recruitment` |
+| Trigger | `hero_recruitment_available` (free heroes detected) |
+| Display | Modal |
+| Title | Heroes Available |
+| Description | Free heroes wander the realm seeking a lord to serve.<br><br>Recruit them to lead your armies! Heroes have unique abilities and grow stronger with experience. |
+
+### Weather Control
+| Field | Value |
+|-------|-------|
+| ID | `weather_control` |
+| Trigger | `weather_control_available` (weather command appears) |
+| Display | Overlay |
+| Title | Weather Magic |
+| Description | Your mages can influence the weather!<br><br>Rain slows movement, storms disrupt enemies, and clear skies speed your march. |
+
+### Prisoner Management
+| Field | Value |
+|-------|-------|
+| ID | `prisoner_management` |
+| Trigger | `prisoner_command_issued` (player uses prisoner command) |
+| Display | Modal |
+| Title | Prisoners Captured |
+| Description | You've captured enemy soldiers!<br><br>You can ransom them for gold, recruit them into your army, or execute them as a warning. |
+
+---
+
+## Tactical Contextual Tutorials
+
+Triggered during battles when players encounter spells, terrain, or abilities.
+
+### Lightning Bolt Spell
+| Field | Value |
+|-------|-------|
+| ID | `spell_lightning` |
+| Trigger | `spell_lightning_available` |
+| Display | Tooltip |
+| Title | Lightning Bolt |
+| Description | Your mage can cast Lightning Bolt!<br><br>This spell strikes a single target for heavy damage. Great for eliminating key enemy units. |
+
+### Meteor Strike Spell
+| Field | Value |
+|-------|-------|
+| ID | `spell_meteor` |
+| Trigger | `spell_meteor_available` |
+| Display | Modal |
+| Title | Meteor Strike |
+| Description | Meteor is a devastating area spell!<br><br>It takes a turn to cast: first select target, then it lands next turn. Plan ahead! |
+
+### Holy Wave Spell
+| Field | Value |
+|-------|-------|
+| ID | `spell_holywave` |
+| Trigger | `spell_holywave_available` |
+| Display | Tooltip |
+| Title | Holy Wave |
+| Description | Holy Wave heals your units and damages undead!<br><br>Position your troops carefully to maximize its effect. |
+
+### Raise Dead Spell
+| Field | Value |
+|-------|-------|
+| ID | `spell_raisedead` |
+| Trigger | `spell_raisedead_available` |
+| Display | Modal |
+| Title | Raise Dead |
+| Description | Dark magic can raise fallen soldiers as undead!<br><br>They fight for you, but beware - they may crumble if your necromancer falls. |
+
+### Fire Terrain
+| Field | Value |
+|-------|-------|
+| ID | `terrain_fire` |
+| Trigger | `terrain_fire_encountered` (fire damage occurs) |
+| Display | Tooltip |
+| Title | Fire Hazard |
+| Description | Fire spreads across the battlefield!<br><br>Units in burning hexes take damage. Use fire to block enemy routes or avoid it yourself. |
+
+### Water Crossing
+| Field | Value |
+|-------|-------|
+| ID | `terrain_water` |
+| Trigger | `terrain_water_encountered` (water crossing attempted) |
+| Display | Tooltip |
+| Title | Water Crossing |
+| Description | Units can cross shallow water, but it's risky.<br><br>Crossing takes extra movement and may fail. Some units swim better than others. |
+
+### Cavalry Charge
+| Field | Value |
+|-------|-------|
+| ID | `ability_charge` |
+| Trigger | `ability_charge_available` |
+| Display | Overlay |
+| Title | Cavalry Charge |
+| Description | Your cavalry can Charge!<br><br>Charging deals bonus damage based on distance traveled. Use open terrain for maximum impact. |
+
+---
+
+## Display Modes
+
+| Mode | Description | Use For |
+|------|-------------|---------|
+| **Modal** | Full popup with dimmed background, blocks interaction | Important concepts, multi-paragraph explanations |
+| **Overlay** | Semi-transparent overlay, can highlight UI elements | Guiding player to interact with specific UI |
+| **Tooltip** | Small popup near target element | Quick tips, less important info |
+| **Hint** | Pulsing dot indicator only | Subtle suggestions |
+| **None** | Invisible, just waits for event | Transition steps |
+
+---
+
+## Adding New Tutorials
+
+1. Add entry to this document
+2. Update `TutorialContentDefinitions.cs`:
+   - For onboarding: add to `CreateOnboardingSequence()`
+   - For contextual: add to `RegisterStrategicTutorials()` or `RegisterTacticalTutorials()`
+3. Ensure trigger event exists in `TutorialTriggerRegistry.cs`
+4. Test the flow
+
+---
+
+## Content Guidelines
+
+- Keep descriptions to 2-3 short paragraphs max
+- Use `<br><br>` for paragraph breaks (renders as newlines in Unity)
+- Avoid jargon - explain game terms when first introduced
+- Be encouraging, not condescending
+- Focus on "what to do" not exhaustive "how it works"

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"],
+)

nginx/nginx.conf

@@ -27,11 +27,10 @@ http {
     # This prevents stale IP caching when containers restart
     resolver 127.0.0.11 valid=10s ipv6=off;
 
-    # Eagle backend address - configured via variable for blue-green deployments
-    # Using a variable makes nginx resolve the hostname at request time, not config load time
-    # This allows nginx to reload even when the backend is temporarily down
-    # For blue-green deployments, this is switched between eagle-blue:40032 and eagle-green:40032
-    # by scripts/deploy-blue-green.sh, then nginx is reloaded with 'nginx -s reload'
+    # Eagle backend - blue-green deployment with variable-based routing
+    # Uses a variable so nginx only resolves the configured backend (not all backends).
+    # This allows nginx to start/reload even when the inactive backend is stopped.
+    # The deploy script updates this map, then recreates nginx.
     map $host $eagle_backend {
         default "eagle-blue:40032";
     }
@@ -77,7 +76,7 @@ http {
             # Rate limiting
             limit_req zone=grpc_limit burst=50 nodelay;
 
-            # gRPC proxy - uses variable for blue-green deployment support
+            # gRPC proxy - uses variable for blue-green deployment
             grpc_pass grpc://$eagle_backend;
 
             # Timeouts for long-running streams
@@ -113,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;

scripts/build_deps_baseline.txt

@@ -0,0 +1,3 @@
+# BUILD dependency baseline - updated Sun Jan 18 16:17:22 PST 2026
+# Do not increase these numbers - only decrease!
+library_proto_deps=167

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_sparkle_plugin.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+#
+# Build the SparklePlugin native library for Unity using Bazel
+#
+# 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 ==="
+
+bazel build --config=mactools //src/main/objc/net/eagle0/sparkle:SparklePlugin
+
+# Get the zip path from bazel
+ZIP_PATH=$(bazel cquery --config=mactools --output=files //src/main/objc/net/eagle0/sparkle: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,158 @@
+#!/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  # Fail if proto deps in library/ exceed baseline
+#
+# The baseline for proto deps is stored in scripts/build_deps_baseline.txt
+# Update it with: ./scripts/check_build_deps.sh --update-baseline
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+BASELINE_FILE="$SCRIPT_DIR/build_deps_baseline.txt"
+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
+
+# Get baseline proto count (default to a high number if no baseline exists)
+get_baseline() {
+    if [ -f "$BASELINE_FILE" ]; then
+        grep "^library_proto_deps=" "$BASELINE_FILE" | cut -d= -f2
+    else
+        echo "999999"  # No baseline = don't fail
+    fi
+}
+
+# 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=$(bazel query 'deps(//src/main/...) intersect //src/test/...' 2>/dev/null || 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 src/main/protobuf
+# Note: This rule is aspirational - there are currently many violations as part of ongoing deproto effort
+check_library_depends_on_proto() {
+    echo -e "${YELLOW}Checking: library/ should not depend on src/main/protobuf...${NC}"
+
+    violations=$(bazel query 'deps(//src/main/scala/net/eagle0/eagle/library/...) intersect //src/main/protobuf/...' 2>/dev/null || true)
+    count=$(echo "$violations" | grep -c "^//" || echo "0")
+
+    if [ "$count" -gt 0 ]; then
+        echo -e "${YELLOW}Found $count proto dependencies in library/ (deproto in progress)${NC}"
+        if [ "$MODE" == "--count" ]; then
+            echo "$violations" | head -20
+            if [ "$count" -gt 20 ]; then
+                echo "... and $((count - 20)) more"
+            fi
+        fi
+        # Don't fail on this rule yet - it's aspirational
+        return 0
+    else
+        echo -e "${GREEN}✓ No proto dependencies in library/${NC}"
+        return 0
+    fi
+}
+
+# Count proto deps for tracking deproto progress
+count_proto_deps() {
+    echo -e "${YELLOW}=== Proto dependency counts ===${NC}"
+
+    library_count=$(bazel query 'deps(//src/main/scala/net/eagle0/eagle/library/...) intersect //src/main/protobuf/...' 2>/dev/null | grep -c "^//" || echo "0")
+    echo "library/: $library_count proto dependencies"
+
+    baseline=$(get_baseline)
+    if [ "$baseline" != "999999" ]; then
+        echo "baseline: $baseline"
+        if [ "$library_count" -lt "$baseline" ]; then
+            echo -e "${GREEN}↓ Reduced by $((baseline - library_count)) from baseline${NC}"
+        elif [ "$library_count" -gt "$baseline" ]; then
+            echo -e "${RED}↑ Increased by $((library_count - baseline)) from baseline${NC}"
+        fi
+    fi
+}
+
+# Check if proto deps exceed baseline (for strict mode)
+check_proto_baseline() {
+    library_count=$(bazel query 'deps(//src/main/scala/net/eagle0/eagle/library/...) intersect //src/main/protobuf/...' 2>/dev/null | grep -c "^//" || echo "0")
+    baseline=$(get_baseline)
+
+    echo -e "${YELLOW}Checking: proto deps in library/ should not exceed baseline...${NC}"
+    echo "Current: $library_count, Baseline: $baseline"
+
+    if [ "$library_count" -gt "$baseline" ]; then
+        echo -e "${RED}VIOLATION: Proto dependencies increased from $baseline to $library_count${NC}"
+        echo "Run './scripts/check_build_deps.sh --count' to see which protos are used"
+        return 1
+    else
+        echo -e "${GREEN}✓ Proto deps at or below baseline${NC}"
+        return 0
+    fi
+}
+
+# Update baseline file
+update_baseline() {
+    library_count=$(bazel query 'deps(//src/main/scala/net/eagle0/eagle/library/...) intersect //src/main/protobuf/...' 2>/dev/null | grep -c "^//" || echo "0")
+
+    echo "# BUILD dependency baseline - updated $(date)" > "$BASELINE_FILE"
+    echo "# Do not increase these numbers - only decrease!" >> "$BASELINE_FILE"
+    echo "library_proto_deps=$library_count" >> "$BASELINE_FILE"
+
+    echo -e "${GREEN}Updated baseline: library_proto_deps=$library_count${NC}"
+}
+
+echo "=== BUILD.bazel Dependency Check ==="
+echo ""
+
+case "$MODE" in
+    --count)
+        count_proto_deps
+        ;;
+    --ci)
+        check_main_depends_on_test || EXIT_CODE=1
+        check_library_depends_on_proto || EXIT_CODE=1
+        ;;
+    --strict)
+        check_main_depends_on_test || EXIT_CODE=1
+        check_proto_baseline || EXIT_CODE=1
+        ;;
+    --update-baseline)
+        update_baseline
+        ;;
+    *)
+        check_main_depends_on_test || EXIT_CODE=1
+        check_library_depends_on_proto
+        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

@@ -39,32 +39,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

@@ -2,14 +2,21 @@
 #
 # Blue-Green Deployment Script for Eagle Server
 #
-# This script performs a zero-downtime deployment by:
-# 1. Starting the new version on a staging port (green)
-# 2. Waiting for it to become healthy
-# 3. Running warmup traffic to pre-heat the JIT
-# 4. Stopping the old version (blue) - which flushes state to storage
-# 5. Switching nginx to route traffic to green
-# 6. Users reconnect, triggering lazy game loading from fresh storage
-# 7. Cleaning up
+# This script performs a zero-downtime deployment with state consistency:
+# 1. Create .deployment_in_progress marker (signals deployment started)
+# 2. Start the staging instance (green) with new image
+# 3. Run warmup/smoke tests against staging (warms JIT)
+# 4. Switch nginx to staging (zero downtime - users immediately route to staging)
+# 5. Stop the active instance (blue) - blocks until flush completes
+# 6. Create .flush_complete marker (signals disk state is fresh)
+#
+# The flush marker coordination ensures green never serves stale game data:
+# - When users reconnect to green and trigger lazy-load, the code checks for markers
+# - If .deployment_in_progress exists, lazy-load WAITS for .flush_complete
+# - Once blue's flush completes and marker is created, lazy-load proceeds with fresh data
+#
+# Key insight: nginx switches to green BEFORE blue stops, achieving zero downtime.
+# Users who trigger lazy-load during blue's shutdown will wait for the flush marker.
 #
 # Usage: ./deploy-blue-green.sh [NEW_IMAGE_TAG]
 #
@@ -25,6 +32,9 @@ APP_DIR="${APP_DIR:-/opt/eagle0}"
 NGINX_CONF="${APP_DIR}/nginx/nginx.conf"
 COMPOSE_FILE="${APP_DIR}/docker-compose.prod.yml"
 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"
 
 # Colors for output
 RED='\033[0;31m'
@@ -36,15 +46,57 @@ log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
 log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
 log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
 
-# Determine which instance is currently active
-get_active_instance() {
-    if grep -q "eagle-blue:40032" "${NGINX_CONF}"; then
+# Marker file operations use docker exec because saves directory is owned by root (Docker).
+# We run commands inside a container that has the saves directory mounted.
+create_deployment_marker() {
+    local deploy_id=$1
+    local container=$2  # Container to use for file operations
+    docker exec "${container}" rm -f /app/saves/.flush_complete
+    docker exec "${container}" sh -c "echo '${deploy_id}' > /app/saves/.deployment_in_progress"
+}
+
+create_flush_marker() {
+    local deploy_id=$1
+    local container=$2  # Container to use for file operations
+    docker exec "${container}" sh -c "echo '${deploy_id}' > /app/saves/.flush_complete"
+    docker exec "${container}" rm -f /app/saves/.deployment_in_progress
+}
+
+cleanup_markers_on_failure() {
+    local container=$1  # Container to use for file operations
+    docker exec "${container}" rm -f /app/saves/.deployment_in_progress 2>/dev/null || true
+    docker exec "${container}" touch /app/saves/.flush_complete 2>/dev/null || true
+}
+
+remove_stale_deployment_marker() {
+    # Try any running eagle container
+    local container
+    container=$(docker ps --filter "name=eagle-" --format "{{.Names}}" | head -1)
+    if [ -n "${container}" ]; then
+        docker exec "${container}" rm -f /app/saves/.deployment_in_progress 2>/dev/null || true
+    fi
+}
+
+# Determine which instance is currently running (not from nginx config)
+get_running_instance() {
+    local blue_running green_running
+    blue_running=$(docker inspect --format='{{.State.Running}}' eagle-blue 2>/dev/null || echo "false")
+    green_running=$(docker inspect --format='{{.State.Running}}' eagle-green 2>/dev/null || echo "false")
+
+    if [ "$blue_running" = "true" ] && [ "$green_running" = "true" ]; then
+        # Both running - use nginx config to determine primary
+        if grep -q "server eagle-blue:40032;" "${NGINX_CONF}" | head -1 | grep -qv backup; then
+            echo "blue"
+        else
+            echo "green"
+        fi
+    elif [ "$blue_running" = "true" ]; then
         echo "blue"
-    elif grep -q "eagle-green:40032" "${NGINX_CONF}"; then
+    elif [ "$green_running" = "true" ]; then
         echo "green"
     else
-        log_error "Cannot determine active instance from nginx config"
-        exit 1
+        # Neither running - default to blue (first deploy or recovery)
+        echo "none"
     fi
 }
 
@@ -120,31 +172,48 @@ main() {
     local registry="registry.digitalocean.com/eagle0/eagle-server"
     local new_image="${registry}:${new_tag}"
 
+    # Generate deployment ID for log correlation with server logs
+    local deploy_id
+    deploy_id=$(date +%s)
+    local deploy_start_time=$deploy_id
+
+    log_info "========================================="
     log_info "Starting blue-green deployment"
+    log_info "Deployment ID: ${deploy_id}"
     log_info "New image: ${new_image}"
+    log_info "========================================="
 
     cd "${APP_DIR}"
 
-    # Determine current active instance
-    local active=$(get_active_instance)
+    # Determine current active instance (need this before creating marker)
+    local active=$(get_running_instance)
     local staging
-    if [ "$active" = "blue" ]; then
+    if [ "$active" = "blue" ] || [ "$active" = "none" ]; then
         staging="green"
+        active="blue"  # Normalize "none" to "blue" for first deploy
     else
         staging="blue"
     fi
 
-    log_info "Active instance: eagle-${active}"
-    log_info "Staging instance: eagle-${staging}"
+    # Step 1: Signal deployment in progress
+    log_info "[DEPLOY:${deploy_id}] Step 1: Signaling deployment in progress..."
+    # Use active container for marker operations (it's the one currently running)
+    if [ "$active" != "none" ] && docker ps --filter "name=eagle-${active}" --format "{{.Names}}" | grep -q .; then
+        create_deployment_marker "${deploy_id}" "eagle-${active}"
+        log_info "[DEPLOY:${deploy_id}] Deployment marker created via eagle-${active}"
+    else
+        log_warn "[DEPLOY:${deploy_id}] No running container to create marker (first deploy?)"
+    fi
 
     # Pull the new image (with retry for intermittent registry issues)
     if ! pull_with_retry "${new_image}" 3; then
         log_error "Failed to pull new image, aborting deployment"
+        cleanup_markers_on_failure "eagle-${active}"
         exit 1
     fi
 
-    # Start staging instance with new image (and its jfr-sidecar)
-    log_info "Starting eagle-${staging} with new image..."
+    # Step 2: Start staging instance with new image
+    log_info "Step 2: Starting eagle-${staging} with new image..."
     if [ "$staging" = "green" ]; then
         EAGLE_IMAGE_NEW="${new_image}" docker compose -f "${COMPOSE_FILE}" --profile blue-green up -d eagle-green jfr-sidecar-green
     else
@@ -155,11 +224,11 @@ main() {
     if ! wait_for_healthy "eagle-${staging}" 90; then
         log_error "Staging instance failed health check, aborting deployment"
         docker compose -f "${COMPOSE_FILE}" stop "eagle-${staging}"
-        docker compose -f "${COMPOSE_FILE}" rm -f "eagle-${staging}"
+        cleanup_markers_on_failure "eagle-${active}"
         exit 1
     fi
 
-    # Run warmup/smoke test
+    # Step 3: Run warmup/smoke test
     local staging_port
     if [ "$staging" = "green" ]; then
         staging_port=40034
@@ -167,12 +236,12 @@ main() {
         staging_port=40032
     fi
 
-    log_info "Running warmup against eagle-${staging}..."
+    log_info "Step 3: Running warmup against eagle-${staging}..."
     if [ -x "${WARMUP_SCRIPT}" ]; then
         if ! "${WARMUP_SCRIPT}" "localhost:${staging_port}"; then
             log_error "Warmup/smoke test failed, aborting deployment"
             docker compose -f "${COMPOSE_FILE}" stop "eagle-${staging}"
-            docker compose -f "${COMPOSE_FILE}" rm -f "eagle-${staging}"
+            cleanup_markers_on_failure "eagle-${active}"
             exit 1
         fi
     else
@@ -180,29 +249,56 @@ main() {
         log_warn "JIT will be cold on first requests"
     fi
 
-    # Backup games.e0es BEFORE stopping the active instance
-    # Critical: The old server may wipe games.e0es on shutdown if it doesn't have the merge fix
-    local backup_timestamp
-    backup_timestamp=$(date +%Y%m%d_%H%M%S)
-    log_info "Creating S3 backup of games.e0es (backup_${backup_timestamp})..."
-    if command -v s3cmd &> /dev/null; then
-        if s3cmd put "${APP_DIR}/saves/games.e0es" "s3://eagle0/eagle/save/backups/games.e0es.${backup_timestamp}" 2>/dev/null; then
-            log_info "Backup created: s3://eagle0/eagle/save/backups/games.e0es.${backup_timestamp}"
-        else
-            log_warn "S3 backup failed (s3cmd put), continuing deployment"
-        fi
-    else
-        log_warn "s3cmd not found, skipping S3 backup"
-    fi
+    # Step 4: Switch nginx to staging BEFORE stopping active
+    # This achieves zero downtime - users immediately route to staging.
+    # Any lazy-loads will wait for the flush marker (created in step 6).
+    local nginx_switch_start
+    nginx_switch_start=$(date +%s)
+    log_info "[DEPLOY:${deploy_id}] Step 4: Switching nginx to eagle-${staging}..."
 
-    # Prepare nginx config and .env files
-    log_info "Updating nginx config to point to eagle-${staging}..."
+    # Update nginx config (variable-based routing)
     if [ "$staging" = "green" ]; then
         sed -i.bak 's/eagle-blue:40032/eagle-green:40032/g' "${NGINX_CONF}"
     else
         sed -i.bak 's/eagle-green:40032/eagle-blue:40032/g' "${NGINX_CONF}"
     fi
 
+    # Recreate nginx to pick up new config
+    # 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
+    nginx_backend=$(docker exec nginx grep -o 'eagle-[a-z]*:40032' /etc/nginx/nginx.conf | head -1 || echo "unknown")
+    if [ "$nginx_backend" = "eagle-${staging}:40032" ]; then
+        log_info "[DEPLOY:${deploy_id}] Verified: nginx routing to eagle-${staging}"
+    else
+        log_error "[DEPLOY:${deploy_id}] nginx config mismatch! Expected eagle-${staging}:40032, got ${nginx_backend}"
+        exit 1
+    fi
+    log_info "[DEPLOY:${deploy_id}] Traffic switched to eagle-${staging} (lazy-loads will wait for flush marker)"
+    local nginx_switch_end
+    nginx_switch_end=$(date +%s)
+
+    # Step 5: Stop active instance (blocks until exit, ensuring flush completes)
+    # Users may be lazy-loading on staging during this time - they'll wait for the marker.
+    local flush_start
+    flush_start=$(date +%s)
+    log_info "[DEPLOY:${deploy_id}] Step 5: Stopping eagle-${active} (waiting for flush)..."
+    docker compose -f "${COMPOSE_FILE}" stop "eagle-${active}"
+    local flush_end
+    flush_end=$(date +%s)
+    local flush_duration=$((flush_end - flush_start))
+    log_info "[DEPLOY:${deploy_id}] eagle-${active} stopped, flush completed in ${flush_duration}s"
+
+    # Step 6: Create flush marker - signals that disk state is fresh
+    # Any waiting lazy-loads on staging will now proceed with fresh data.
+    # The Eagle server automatically detects the flush marker update and invalidates any stale cached games.
+    log_info "[DEPLOY:${deploy_id}] Step 6: Creating flush marker..."
+    create_flush_marker "${deploy_id}" "eagle-${staging}"
+    log_info "[DEPLOY:${deploy_id}] Flush marker created - server will auto-invalidate stale cache"
+
+    # Update .env for admin service
     local env_file="${APP_DIR}/.env"
     if [ "$staging" = "green" ]; then
         log_info "Updating .env for green instance..."
@@ -216,110 +312,37 @@ main() {
         echo "JFR_SIDECAR_ADDR=jfr-sidecar:8081" >> "${env_file}"
     fi
 
-    # === CRITICAL SECTION: Minimize time between nginx switch and blue stop ===
-    # This reduces the window where users might get stale game data.
-    # Order matters:
-    # 1. Switch nginx to green (blue still running as fallback)
-    # 2. Immediately stop blue (flushes state to disk)
-    # 3. Users reconnecting to green will lazy-load fresh data from disk
-
-    # Recreate nginx to pick up new config from bind-mounted volume
-    # IMPORTANT: We must use --force-recreate, not restart, because:
-    # - 'restart' doesn't refresh bind-mounted files (keeps cached config)
-    # - 'reload' doesn't force DNS re-resolution in Docker
-    log_info "Switching traffic to eagle-${staging}..."
-    docker compose -f "${COMPOSE_FILE}" up -d --force-recreate nginx
-
-    # Verify nginx picked up the correct config
-    local nginx_backend
-    nginx_backend=$(docker exec nginx grep -o 'eagle-[a-z]*:40032' /etc/nginx/nginx.conf | head -1)
-    if [ "$nginx_backend" != "eagle-${staging}:40032" ]; then
-        log_error "nginx config mismatch! Expected eagle-${staging}:40032, got ${nginx_backend}"
-        log_error "This should not happen - investigate bind mount issues"
-        exit 1
-    fi
-    log_info "Traffic now routing to eagle-${staging}"
-
-    # Immediately stop the old instance to flush state to disk
-    # This minimizes the window where green might lazy-load stale data
-    log_info "Stopping eagle-${active} (flushing state to storage)..."
-    docker compose -f "${COMPOSE_FILE}" stop "eagle-${active}"
-
-    # Brief pause to ensure disk flush completes before any lazy loads
-    log_info "Waiting for state flush to complete..."
-    sleep 3
-
-    # === END CRITICAL SECTION ===
-
     # Restart admin to pick up new .env
+    # 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
 
-    # Clean up old instance and its jfr-sidecar (in background, not critical path)
-    log_info "Cleaning up old eagle-${active} container..."
-    docker compose -f "${COMPOSE_FILE}" rm -f "eagle-${active}" &
+    # Clean up old instance
+    log_info "Cleaning up old eagle-${active}..."
+    docker compose -f "${COMPOSE_FILE}" rm -f "eagle-${active}" 2>/dev/null || true
+
+    # Stop the old jfr-sidecar (it can't attach to removed container anyway)
     if [ "$active" = "green" ]; then
-        docker compose -f "${COMPOSE_FILE}" rm -f "jfr-sidecar-green" 2>/dev/null &
+        docker compose -f "${COMPOSE_FILE}" stop "jfr-sidecar-green" 2>/dev/null || true
+        docker compose -f "${COMPOSE_FILE}" rm -f "jfr-sidecar-green" 2>/dev/null || true
     else
-        docker compose -f "${COMPOSE_FILE}" rm -f "jfr-sidecar" 2>/dev/null &
-    fi
-    wait
-
-    log_info "Deployment complete!"
-    log_info "Active instance: eagle-${staging}"
-}
-
-# Ensure s3cmd is installed and configured for S3 backups
-ensure_s3cmd() {
-    # Install s3cmd if not present
-    if ! command -v s3cmd &> /dev/null; then
-        log_info "Installing s3cmd for S3 backups..."
-        if command -v pip3 &> /dev/null; then
-            pip3 install --quiet s3cmd
-        elif command -v pip &> /dev/null; then
-            pip install --quiet s3cmd
-        elif command -v apt-get &> /dev/null; then
-            sudo apt-get update -qq && sudo apt-get install -y -qq s3cmd
-        else
-            log_warn "Cannot install s3cmd (no pip or apt-get), S3 backups will be skipped"
-            return 1
-        fi
-
-        if ! command -v s3cmd &> /dev/null; then
-            log_warn "s3cmd installation failed, S3 backups will be skipped"
-            return 1
-        fi
-        log_info "s3cmd installed successfully"
+        docker compose -f "${COMPOSE_FILE}" stop "jfr-sidecar" 2>/dev/null || true
+        docker compose -f "${COMPOSE_FILE}" rm -f "jfr-sidecar" 2>/dev/null || true
     fi
 
-    # Configure s3cmd for DigitalOcean Spaces if not already configured
-    local s3cfg="${HOME}/.s3cfg"
-    if [ ! -f "${s3cfg}" ]; then
-        # Load credentials from .env
-        local env_file="${APP_DIR}/.env"
-        if [ -f "${env_file}" ]; then
-            # shellcheck source=/dev/null
-            source "${env_file}"
-        fi
+    local deploy_end_time
+    deploy_end_time=$(date +%s)
+    local total_duration=$((deploy_end_time - deploy_start_time))
+    local user_wait_window=$((flush_end - nginx_switch_end))
 
-        if [ -z "${DO_SPACES_ACCESS_KEY:-}" ] || [ -z "${DO_SPACES_SECRET_KEY:-}" ]; then
-            log_warn "DO_SPACES_ACCESS_KEY or DO_SPACES_SECRET_KEY not set, S3 backups will be skipped"
-            return 1
-        fi
-
-        log_info "Configuring s3cmd for DigitalOcean Spaces..."
-        cat > "${s3cfg}" << EOF
-[default]
-access_key = ${DO_SPACES_ACCESS_KEY}
-secret_key = ${DO_SPACES_SECRET_KEY}
-host_base = sfo3.digitaloceanspaces.com
-host_bucket = %(bucket)s.sfo3.digitaloceanspaces.com
-use_https = True
-EOF
-        log_info "s3cmd configured successfully"
-    fi
-
-    return 0
+    log_info ""
+    log_info "========================================="
+    log_info "[DEPLOY:${deploy_id}] Deployment complete!"
+    log_info "  Active instance: eagle-${staging}"
+    log_info "  Total duration: ${total_duration}s"
+    log_info "  Flush duration: ${flush_duration}s"
+    log_info "  Max user wait window: ${user_wait_window}s"
+    log_info "========================================="
 }
 
 # Check for required tools
@@ -344,8 +367,17 @@ check_requirements() {
         exit 1
     fi
 
-    # Ensure s3cmd is available for backups (non-fatal if it fails)
-    ensure_s3cmd || true
+    # Ensure saves directory exists
+    if [ ! -d "${SAVES_DIR}" ]; then
+        log_info "Creating saves directory at ${SAVES_DIR}"
+        mkdir -p "${SAVES_DIR}"
+    fi
+
+    # Clean up any stale deployment-in-progress marker from a previous failed deploy
+    if [ -f "${DEPLOYMENT_IN_PROGRESS}" ]; then
+        log_warn "Found stale deployment-in-progress marker, removing it"
+        remove_stale_deployment_marker
+    fi
 }
 
 # Run

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

scripts/notarize_mac_app.sh

@@ -46,8 +46,8 @@ STATUS=$(echo "$SUBMIT_OUTPUT" | grep "^  status:" | awk '{print $2}')
 echo "Submission ID: $SUBMISSION_ID"
 echo "Status: $STATUS"
 
-# Clean up the zip
-rm "$ZIP_PATH"
+# Clean up the zip (use -f to avoid failure if already deleted)
+rm -f "$ZIP_PATH"
 
 if [ "$STATUS" != "Accepted" ]; then
     echo "=== Notarization failed! Fetching log for details ==="

scripts/notarize_submit.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+#
+# Submit a macOS .app bundle to Apple for notarization (no waiting)
+# Usage: notarize_submit.sh <app_path>
+# Outputs: submission_id=<id> to stdout (for GitHub Actions)
+#
+# Environment variables (required):
+#   APPLE_ID - Apple Developer account email
+#   APP_SPECIFIC_PASSWORD - App-specific password for notarytool
+#   TEAM_ID - Apple Developer Team ID
+
+set -euo pipefail
+
+APP_PATH="$1"
+
+if [ ! -d "$APP_PATH" ]; then
+    echo "ERROR: App not found at $APP_PATH" >&2
+    exit 1
+fi
+
+if [ -z "${APPLE_ID:-}" ] || [ -z "${APP_SPECIFIC_PASSWORD:-}" ] || [ -z "${TEAM_ID:-}" ]; then
+    echo "ERROR: Required environment variables not set" >&2
+    echo "  APPLE_ID: ${APPLE_ID:-<not set>}" >&2
+    echo "  APP_SPECIFIC_PASSWORD: ${APP_SPECIFIC_PASSWORD:+<set>}" >&2
+    echo "  TEAM_ID: ${TEAM_ID:-<not set>}" >&2
+    exit 1
+fi
+
+# Create ZIP for notarization submission
+ZIP_PATH="${APP_PATH%.app}.zip"
+echo "=== Creating ZIP for notarization: $ZIP_PATH ===" >&2
+ditto -c -k --keepParent "$APP_PATH" "$ZIP_PATH"
+
+echo "=== Submitting to Apple for notarization ===" >&2
+SUBMIT_OUTPUT=$(xcrun notarytool submit "$ZIP_PATH" \
+    --apple-id "$APPLE_ID" \
+    --password "$APP_SPECIFIC_PASSWORD" \
+    --team-id "$TEAM_ID" 2>&1)
+
+echo "$SUBMIT_OUTPUT" >&2
+
+# Extract submission ID
+SUBMISSION_ID=$(echo "$SUBMIT_OUTPUT" | grep "id:" | head -1 | awk '{print $2}')
+
+if [ -z "$SUBMISSION_ID" ]; then
+    echo "ERROR: Failed to get submission ID" >&2
+    exit 1
+fi
+
+# Clean up the zip
+rm "$ZIP_PATH"
+
+echo "Submission ID: $SUBMISSION_ID" >&2
+
+# Output for GitHub Actions
+echo "submission_id=$SUBMISSION_ID"

scripts/notarize_wait.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+#
+# Wait for Apple notarization to complete and staple the ticket
+# Usage: notarize_wait.sh <submission_id> <app_path>
+#
+# Environment variables (required):
+#   APPLE_ID - Apple Developer account email
+#   APP_SPECIFIC_PASSWORD - App-specific password for notarytool
+#   TEAM_ID - Apple Developer Team ID
+
+set -euo pipefail
+
+SUBMISSION_ID="$1"
+APP_PATH="$2"
+
+if [ -z "$SUBMISSION_ID" ]; then
+    echo "ERROR: submission_id is required" >&2
+    exit 1
+fi
+
+if [ ! -d "$APP_PATH" ]; then
+    echo "ERROR: App not found at $APP_PATH" >&2
+    exit 1
+fi
+
+if [ -z "${APPLE_ID:-}" ] || [ -z "${APP_SPECIFIC_PASSWORD:-}" ] || [ -z "${TEAM_ID:-}" ]; then
+    echo "ERROR: Required environment variables not set" >&2
+    exit 1
+fi
+
+echo "=== Waiting for notarization of submission $SUBMISSION_ID ==="
+WAIT_OUTPUT=$(xcrun notarytool wait "$SUBMISSION_ID" \
+    --apple-id "$APPLE_ID" \
+    --password "$APP_SPECIFIC_PASSWORD" \
+    --team-id "$TEAM_ID" 2>&1) || true
+
+echo "$WAIT_OUTPUT"
+
+# Extract status (look for "  status:" to avoid matching "Current status:")
+STATUS=$(echo "$WAIT_OUTPUT" | grep "^  status:" | awk '{print $2}')
+
+echo "Status: $STATUS"
+
+if [ "$STATUS" != "Accepted" ]; then
+    echo "=== Notarization failed! Fetching log for details ==="
+    xcrun notarytool log "$SUBMISSION_ID" \
+        --apple-id "$APPLE_ID" \
+        --password "$APP_SPECIFIC_PASSWORD" \
+        --team-id "$TEAM_ID"
+    exit 1
+fi
+
+echo "=== Stapling notarization ticket to app ==="
+# Retry stapling - Apple's CloudKit can have a brief delay after notarization completes
+MAX_STAPLE_ATTEMPTS=5
+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
+        echo "Stapling successful"
+        break
+    fi
+    if [ $STAPLE_ATTEMPT -eq $MAX_STAPLE_ATTEMPTS ]; then
+        echo "ERROR: Stapling failed after $MAX_STAPLE_ATTEMPTS attempts"
+        exit 1
+    fi
+    echo "Stapling failed, waiting 10 seconds before retry..."
+    sleep 10
+    STAPLE_ATTEMPT=$((STAPLE_ATTEMPT + 1))
+done
+
+echo "=== Verifying notarization ==="
+xcrun stapler validate "$APP_PATH"
+spctl --assess --type exec -v "$APP_PATH"
+
+echo "Notarization complete: $APP_PATH"

src/main/csharp/net/eagle0/clients/unity/eagle0/Assembly-CSharp.csproj

@@ -87,7 +87,6 @@
     <Compile Include="Assets/Modern UI Pack/Scripts/Demo/LaunchURL.cs" />
     <Compile Include="Assets/Shardok/HexCoordinates.cs" />
     <Compile Include="Assets/Eagle/Table Rows/OrganizeTroopsTableRow.cs" />
-    <Compile Include="Assets/Bluetooth/PickerRowController.cs" />
     <Compile Include="Assets/TouchHandler.cs" />
     <Compile Include="Assets/Eagle/CommandSelectors/TravelCommandSelector.cs" />
     <Compile Include="Assets/Eagle/ConnectionStatusUI.cs" />
@@ -98,7 +97,6 @@
     <Compile Include="Assets/HoveringTooltipTextProvider.cs" />
     <Compile Include="Assets/Eagle/CommandSelectors/util/KeyModifiedAmount.cs" />
     <Compile Include="Assets/HoveringTooltip.cs" />
-    <Compile Include="Assets/Bluetooth/DiceInterface.cs" />
     <Compile Include="Assets/ButtonColors.cs" />
     <Compile Include="Assets/Eagle/MapController.cs" />
     <Compile Include="Assets/common/DisclosureTriangle.cs" />
@@ -151,10 +149,8 @@
     <Compile Include="Assets/Eagle/GeneratedTextUpdater.cs" />
     <Compile Include="Assets/Eagle/Notifications/ARNNotifications/OutlawApprehendedDetailsNotificationGenerator.cs" />
     <Compile Include="Assets/Shardok/HexMetrics.cs" />
-    <Compile Include="Assets/Bluetooth/OneDiceRollController.cs" />
     <Compile Include="Assets/Modern UI Pack/Scripts/Switch/SwitchManager.cs" />
     <Compile Include="Assets/Eagle/Notifications/ARNNotifications/ProvinceHeldDetailsNotificationGenerator.cs" />
-    <Compile Include="Assets/Bluetooth/DieInfo.cs" />
     <Compile Include="Assets/common/ResourceFetcher.cs" />
     <Compile Include="Assets/Tutorial/Content/TutorialStep.cs" />
     <Compile Include="Assets/Auth/AuthClient.cs" />
@@ -162,10 +158,10 @@
     <Compile Include="Assets/Eagle/Notifications/RiotSuppressedNotificationGenerator.cs" />
     <Compile Include="Assets/Modern UI Pack/Scripts/Modal Window/ModalWindowManagerEditor.cs" />
     <Compile Include="Assets/common/GUIUtils/AutoScrollingText.cs" />
-    <Compile Include="Assets/Bluetooth/NativeDiceInterfaceImports.cs" />
     <Compile Include="Assets/Eagle/Notifications/ProvinceConqueredNotificationGenerator.cs" />
     <Compile Include="Assets/Eagle/Table Rows/ExtraTroopsRowController.cs" />
     <Compile Include="Assets/Auth/JwtAuthInterceptor.cs" />
+    <Compile Include="Assets/Tutorial/Content/TutorialContentDefinitions.cs" />
     <Compile Include="Assets/Eagle/CommandPanelController.cs" />
     <Compile Include="Assets/Eagle/Notifications/ARNNotifications/ShatteredArmyDetailsNotificationGenerator.cs" />
     <Compile Include="Assets/Shardok/TurnHistoryPanelController.cs" />
@@ -207,10 +203,10 @@
     <Compile Include="Assets/Eagle/Notifications/ARNNotifications/RansomRejectedDetailsNotificationGenerator.cs" />
     <Compile Include="Assets/Eagle/FactionsTableController.cs" />
     <Compile Include="Assets/Modern UI Pack/Scripts/Slider/RangeSlider.cs" />
+    <Compile Include="Assets/Tutorial/UI/TutorialOverlayBuilder.cs" />
     <Compile Include="Assets/Eagle/CommandSelectors/ExileVassalCommandSelector.cs" />
     <Compile Include="Assets/Tutorial/TutorialState.cs" />
     <Compile Include="Assets/Modern UI Pack/Scripts/Button/ButtonManagerBasicWithIconEditor.cs" />
-    <Compile Include="Assets/Bluetooth/DiceVectors.cs" />
     <Compile Include="Assets/Modern UI Pack/Scripts/UI Manager/UIManagerProgressBarLoop.cs" />
     <Compile Include="Assets/Eagle/MovingArmiesTableController.cs" />
     <Compile Include="Assets/ConnectionHandler/ConnectionHandler.cs" />
@@ -231,9 +227,11 @@
     <Compile Include="Assets/Eagle/CommandSelectors/DiplomacyCommandSelector.cs" />
     <Compile Include="Assets/Tutorial/Triggers/TutorialTriggerRegistry.cs" />
     <Compile Include="Assets/Eagle/CommandSelectors/ResolveBreakAllianceCommandSelector.cs" />
+    <Compile Include="Assets/common/WindowFocusManager.cs" />
     <Compile Include="Assets/Eagle/CommandSelectors/ResolveAllianceCommandSelector.cs" />
     <Compile Include="Assets/Eagle/Notifications/ARNNotifications/WithdrewForTruceDetailsNotificationGenerator.cs" />
     <Compile Include="Assets/Eagle/CommandSelectors/MarchCommandSelector.cs" />
+    <Compile Include="Assets/Tutorial/TutorialTargetRegistry.cs" />
     <Compile Include="Assets/Eagle/CommandSelectors/TrainCommandSelector.cs" />
     <Compile Include="Assets/Eagle/CustomFileLogger.cs" />
     <Compile Include="Assets/Eagle/Notifications/ARNNotifications/InvitationAcceptedDetailsNotificationGenerator.cs" />
@@ -267,7 +265,6 @@
     <Compile Include="Assets/Shardok/AnimationTestController.cs" />
     <Compile Include="Assets/Eagle/CommandSelectors/TradeCommandSelector.cs" />
     <Compile Include="Assets/Eagle/Table Rows/DominionTableRowController.cs" />
-    <Compile Include="Assets/Bluetooth/RollPanelController.cs" />
     <Compile Include="Assets/Shardok/ChargeAnimator.cs" />
     <Compile Include="Assets/Eagle/ClientTextProvider.cs" />
     <Compile Include="Assets/Modern UI Pack/Scripts/UI Manager/UIManager.cs" />
@@ -302,6 +299,7 @@
     <Compile Include="Assets/Shardok/ControlAnimator.cs" />
     <Compile Include="Assets/Modern UI Pack/Scripts/Horizontal Selector/HorizontalSelector.cs" />
     <Compile Include="Assets/Eagle/Table Rows/OrganizeTroopsResultRow.cs" />
+    <Compile Include="Assets/Eagle/SparkleUpdater.cs" />
     <Compile Include="Assets/Modern UI Pack/Scripts/Slider/SliderManagerEditor.cs" />
     <Compile Include="Assets/Eagle/Notifications/ARNNotifications/SwearBrotherhoodDetailsNotificationGenerator.cs" />
     <Compile Include="Assets/Eagle/PersistentClientConnection.cs" />
@@ -320,10 +318,10 @@
     <Compile Include="Assets/Shardok/ShardokGameModel.cs" />
     <Compile Include="Assets/common/GUIUtils/GeneralClickDetector.cs" />
     <Compile Include="Assets/Modern UI Pack/Scripts/UI Manager/UIManagerContextMenu.cs" />
+    <Compile Include="Assets/Eagle/SparkleInitializer.cs" />
     <Compile Include="Assets/Eagle/Notifications/ARNNotifications/TruceAmbassadorImprisonedDetailsNotificationGenerator.cs" />
     <Compile Include="Assets/Modern UI Pack/Scripts/Button/ButtonManagerBasicWithIcon.cs" />
     <Compile Include="Assets/Tutorial/UI/TutorialHintIndicator.cs" />
-    <Compile Include="Assets/Bluetooth/UnityDieColors.cs" />
     <Compile Include="Assets/Eagle/CommandSelectors/OrganizeTroopsCommandSelector.cs" />
     <Compile Include="Assets/Shardok/ExtinguishAnimator.cs" />
     <Compile Include="Assets/Eagle/PanelPositions.cs" />
@@ -336,7 +334,6 @@
     <Compile Include="Assets/EagleConnection.cs" />
     <Compile Include="Assets/GUI Pro Kit Fantasy RPG/Scripts/CtrPanel.cs" />
     <Compile Include="Assets/UI/Scripts/SceneLoadTester.cs" />
-    <Compile Include="Assets/Bluetooth/RollFetcher.cs" />
     <Compile Include="Assets/Eagle/CommandSelectors/HandleRiotGiveCommandSelector.cs" />
     <Compile Include="Assets/Eagle/ProvinceUtils.cs" />
     <Compile Include="Assets/common/GUIUtils/ProvinceStatUtils.cs" />
@@ -370,16 +367,15 @@
     <Compile Include="Assets/Eagle/Notifications/ARNNotifications/SuppressBeastsFailedDetailsNotificationGenerator.cs" />
     <Compile Include="Assets/Terrain Hexes/Example Scene/BasicHexArranger.cs" />
     <Compile Include="Assets/Eagle/CommandSelectors/ManagePrisonersCommandSelector.cs" />
-    <Compile Include="Assets/Eagle/CommandSelectors/SendSuppliesCommandSelector.cs" />
+    <Compile Include="Assets/ConnectionHandler/StoredAccountButton.cs" />
     <Compile Include="Assets/Tutorial/UI/TutorialUIManager.cs" />
+    <Compile Include="Assets/Eagle/CommandSelectors/SendSuppliesCommandSelector.cs" />
     <Compile Include="Assets/Modern UI Pack/Scripts/Window/WindowManager.cs" />
-    <Compile Include="Assets/Auth/InvitationCodeManager.cs" />
     <Compile Include="Assets/Eagle/Notifications/ARNNotifications/CapturedHeroExiledDetailsNotificationGenerator.cs" />
     <Compile Include="Assets/Eagle/Notifications/ARNNotifications/SuppressBeastsSucceededNotificationGenerator.cs" />
     <Compile Include="Assets/Shardok/ReservesTableController.cs" />
     <Compile Include="Assets/Eagle/CommandSelectors/CommandSelector.cs" />
     <Compile Include="Assets/Eagle/CommandSelectors/RestCommandSelector.cs" />
-    <Compile Include="Assets/Bluetooth/DiceConfigurationPanelController.cs" />
     <Compile Include="Assets/Modern UI Pack/Scripts/UI Manager/UIManagerDropdown.cs" />
     <Compile Include="Assets/Modern UI Pack/Scripts/UI Manager/UIManagerButton.cs" />
     <Compile Include="Assets/common/GUIUtils/GUIUtils.cs" />