Add tutorial dialogues for riots and epidemics

Detect RiotOccurred and EpidemicTookEffect action results and trigger
narrative dialogues. Marek explains what riots and epidemics do, how to
prevent them, and how to recover.

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

.bazelrc

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

.bazelversion

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

.gitattributes

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

.github/workflows/artifact_storage_check.yml

@@ -27,10 +27,12 @@ jobs:
             echo "::error::Artifact storage is ${total_mb} MB, which exceeds the 500 MB threshold!"
             echo ""
             echo "Largest artifacts:"
+            # Save to temp file to avoid SIGPIPE/broken pipe errors with head
             gh api "repos/${{ github.repository }}/actions/artifacts" \
-              --paginate -q '.artifacts[] | "\(.size_in_bytes)\t\(.name)\t\(.created_at)"' | \
-              sort -rn | head -20 | \
+              --paginate -q '.artifacts[] | "\(.size_in_bytes)\t\(.name)\t\(.created_at)"' > /tmp/artifacts.txt
+            sort -rn /tmp/artifacts.txt | head -20 | \
               awk -F'\t' '{printf "%d MB\t%s\t%s\n", $1/1024/1024, $2, $3}'
+            rm -f /tmp/artifacts.txt
             exit 1
           fi
 

.github/workflows/auth_build.yml

@@ -9,7 +9,9 @@ on:
       - 'src/main/protobuf/net/eagle0/eagle/api/auth.proto'
       - 'src/main/protobuf/net/eagle0/eagle/api/admin/**'
       - 'src/main/protobuf/net/eagle0/eagle/internal/auth_internal.proto'
+      - 'src/main/resources/net/eagle0/attributions.json'
       - 'ci/BUILD.bazel'
+      - '.bazelrc'
       - '.github/workflows/auth_build.yml'
   workflow_dispatch:
     inputs:
@@ -39,7 +41,8 @@ jobs:
           set -ex
 
           # Build auth server image (Go binary has explicit goos/goarch in BUILD.bazel)
-          bazel build //ci:auth_server_image
+          # --stamp is needed for authservice x_defs (git commit, build time)
+          bazel build --stamp //ci:auth_server_image
 
           # Save the resolved path before any other bazel command changes bazel-bin symlink
           IMAGE_PATH=$(readlink -f bazel-bin/ci/auth_server_image)
@@ -76,8 +79,14 @@ jobs:
           # Build the push target to get crane in runfiles
           bazel build //ci:auth_server_push
 
-          # Use crane directly for push
-          CRANE="bazel-bin/ci/push_auth_server_push.sh.runfiles/rules_oci~~oci~oci_crane_darwin_arm64/crane"
+          # Find crane binary in runfiles (path varies by Bazel version)
+          RUNFILES="bazel-bin/ci/push_auth_server_push.sh.runfiles"
+          CRANE=$(find "$RUNFILES" -path "*darwin*" -name crane 2>/dev/null | head -1)
+          if [ -z "$CRANE" ] || [ ! -x "$CRANE" ]; then
+            echo "ERROR: crane not found in runfiles"
+            find "$RUNFILES" -name crane 2>/dev/null || echo "No crane found at all"
+            exit 1
+          fi
           echo "Using crane: $CRANE"
 
           # Push with SHA tag

.github/workflows/bazel_cache_cleanup.yml

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

.github/workflows/bazel_test.yml

@@ -8,6 +8,7 @@ on:
       - 'WORKSPACE'
       - 'MODULE.bazel'
       - 'BUILD.bazel'
+      - '.bazelrc'
       - '.github/workflows/bazel_test.yml'
       - '!src/main/csharp/**'
       - '!src/test/csharp/**'
@@ -17,24 +18,54 @@ on:
       - 'WORKSPACE'
       - 'MODULE.bazel'
       - 'BUILD.bazel'
+      - '.bazelrc'
       - '.github/workflows/bazel_test.yml'
       - '!src/main/csharp/**'
       - '!src/test/csharp/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 permissions:
   contents: read
 
 jobs:
-  test:
+  lint:
     runs-on: [self-hosted, bazel]
-
     steps:
+    - name: Clean workspace
+      run: |
+        git sparse-checkout disable 2>/dev/null || true
+        git config --local core.sparseCheckout false 2>/dev/null || true
+        git config --local --unset extensions.worktreeConfig 2>/dev/null || true
+        rm -f .git/info/sparse-checkout .git/config.worktree 2>/dev/null || true
     - name: Checkout repository
       uses: actions/checkout@v4
       with:
         lfs: false
     - name: Check BUILD.bazel dependencies
       run: ./scripts/check_build_deps.sh --strict
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 'lts/*'
+    - name: Check JavaScript syntax
+      run: node --check src/main/go/net/eagle0/admin_server/static/map_editor.js
+
+  test:
+    runs-on: [self-hosted, bazel]
+    steps:
+    - name: Clean workspace
+      run: |
+        git sparse-checkout disable 2>/dev/null || true
+        git config --local core.sparseCheckout false 2>/dev/null || true
+        git config --local --unset extensions.worktreeConfig 2>/dev/null || true
+        rm -f .git/info/sparse-checkout .git/config.worktree 2>/dev/null || true
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        lfs: false
     - name: Run tests
       run: bazel test --build_event_json_file=test.json //src/test/... //src/main/go/...
     - name: Collect failed test logs

.github/workflows/docker_build.yml

@@ -19,6 +19,7 @@ on:
       - 'src/main/resources/**'
       - 'ci/BUILD.bazel'
       - 'MODULE.bazel'
+      - '.bazelrc'
       - 'docker-compose.prod.yml'
       - 'nginx/**'
       - '.github/workflows/docker_build.yml'
@@ -30,13 +31,16 @@ on:
         default: 'false'
         type: boolean
 
-# Only allow one deployment at a time to prevent race conditions
+# Only allow one deployment at a time; queue new ones (never cancel a running deploy).
+# The build-all job checks if it's still the latest commit on main and skips if not,
+# so intermediate commits don't waste time building when a newer one is already queued.
 concurrency:
   group: docker-build-deploy
-  cancel-in-progress: false  # Don't cancel running deployments, queue new ones
+  cancel-in-progress: false
 
 permissions:
   contents: read
+  actions: read
 
 jobs:
   # Single consolidated build job - builds all images with one bazel invocation
@@ -49,30 +53,53 @@ jobs:
       admin_image_tag: ${{ steps.push-images.outputs.admin_image_tag }}
       jfr_sidecar_image_tag: ${{ steps.push-images.outputs.jfr_sidecar_image_tag }}
     steps:
+      - name: Skip if superseded
+        id: check-latest
+        run: |
+          # Check if there's a newer run of this workflow waiting in the queue.
+          # If so, skip this build — the queued run will deploy a newer commit.
+          QUEUED=$(curl -s -H "Authorization: Bearer $GH_TOKEN" \
+            "https://api.github.com/repos/${{ github.repository }}/actions/workflows/docker_build.yml/runs?status=queued" \
+            | python3 -c "import sys,json; runs=json.load(sys.stdin).get('workflow_runs',[]); print(len([r for r in runs if r['run_number'] > ${{ github.run_number }}]))")
+          if [ "$QUEUED" -gt 0 ]; then
+            echo "::notice::Skipping build — $QUEUED newer run(s) queued for this workflow"
+            echo "skip=true" >> $GITHUB_OUTPUT
+          fi
+        env:
+          GH_TOKEN: ${{ github.token }}
+
       - name: Checkout repository
+        if: steps.check-latest.outputs.skip != 'true'
         uses: actions/checkout@v4
         with:
           lfs: false
 
+      - name: Fetch LFS files needed for admin server
+        if: steps.check-latest.outputs.skip != 'true'
+        run: git lfs pull --include="src/main/go/net/eagle0/admin_server/static/tiles/*"
+
       - name: Build all Docker images
+        if: steps.check-latest.outputs.skip != 'true'
         id: build-all
         run: |
           set -ex
 
           # Build ALL images in a single bazel command - Bazel parallelizes internally
           # Note: Shardok is built separately for ARM64 and deployed to Hetzner
+          # --stamp is needed for admin_server x_defs (git commit, build time)
           echo "=== Building Docker images ==="
           bazel build \
+            --stamp \
             --platforms=//:linux_x86_64 \
             --extra_toolchains=@llvm_toolchain_linux//:all \
             //ci:eagle_server_image \
             //ci:admin_server_image \
             //ci:jfr_sidecar_image \
-            //src/main/go/net/eagle0/warmup:warmup_linux_amd64
+            //ci:warmup_tar
 
-          # Copy warmup binary to scripts/ for deployment
+          # Extract warmup binary from tar for deployment
           mkdir -p scripts/bin
-          cp bazel-bin/src/main/go/net/eagle0/warmup/warmup_linux_amd64_/warmup_linux_amd64 scripts/bin/warmup
+          tar -xf bazel-bin/ci/warmup_tar.tar -C scripts/bin --strip-components=1
 
           # Save all image paths before any other bazel command changes bazel-bin symlink
           EAGLE_PATH=$(readlink -f bazel-bin/ci/eagle_server_image)
@@ -88,8 +115,16 @@ jobs:
           echo "Admin: $ADMIN_PATH"
           echo "JFR Sidecar: $JFR_PATH"
 
+      - name: Upload warmup binary
+        if: steps.check-latest.outputs.skip != 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: warmup-binary
+          path: scripts/bin/warmup
+          retention-days: 1
+
       - name: Login to DigitalOcean Container Registry
-        if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.push_images == 'true')
+        if: steps.check-latest.outputs.skip != 'true' && (github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.push_images == 'true'))
         env:
           DO_TOKEN: ${{ secrets.DO_REGISTRY_TOKEN }}
         run: |
@@ -109,44 +144,59 @@ jobs:
 
           GIT_SHA=$(git rev-parse --short=8 HEAD)
 
-          # Get crane from push target runfiles
-          bazel build //ci:eagle_server_push
-          CRANE="bazel-bin/ci/push_eagle_server_push.sh.runfiles/rules_oci~~oci~oci_crane_darwin_arm64/crane"
-
-          if [ ! -e "$CRANE" ]; then
-            # Fallback: find any Darwin crane
-            RUNFILES="bazel-bin/ci/push_eagle_server_push.sh.runfiles"
-            CRANE=$(find "$RUNFILES" -path "*darwin*" -name crane 2>/dev/null | head -1)
+          # Get crane (cached across runs to avoid rebuilding bazel target)
+          CRANE_VERSION="v0.20.2"
+          CRANE_DIR="${HOME}/.local/bin"
+          CRANE="${CRANE_DIR}/crane"
+          if [ ! -x "$CRANE" ] || ! "$CRANE" version 2>/dev/null | grep -q "0.20.2"; then
+            echo "Installing crane ${CRANE_VERSION}..."
+            mkdir -p "$CRANE_DIR"
+            curl -sL "https://github.com/google/go-containerregistry/releases/download/${CRANE_VERSION}/go-containerregistry_Darwin_arm64.tar.gz" | tar xzf - -C "$CRANE_DIR" crane
+            chmod +x "$CRANE"
+          else
+            echo "Using cached crane at $CRANE"
           fi
 
-          if [ -z "$CRANE" ] || [ ! -e "$CRANE" ]; then
-            echo "ERROR: crane not found"
-            exit 1
-          fi
-          echo "Using crane: $CRANE"
-
-          # Push Eagle image
+          # Set up image paths and tags
           EAGLE_IMAGE="${{ steps.build-all.outputs.eagle_path }}"
           EAGLE_TAG="registry.digitalocean.com/eagle0/eagle-server:${GIT_SHA}"
-          echo "Pushing Eagle: $EAGLE_TAG"
-          $CRANE push "$EAGLE_IMAGE" "$EAGLE_TAG"
-          $CRANE copy "$EAGLE_TAG" "registry.digitalocean.com/eagle0/eagle-server:latest"
-          echo "eagle_image_tag=$EAGLE_TAG" >> $GITHUB_OUTPUT
-
-          # Push Admin image
           ADMIN_IMAGE="${{ steps.build-all.outputs.admin_path }}"
           ADMIN_TAG="registry.digitalocean.com/eagle0/admin-server:${GIT_SHA}"
-          echo "Pushing Admin: $ADMIN_TAG"
-          $CRANE push "$ADMIN_IMAGE" "$ADMIN_TAG"
-          $CRANE copy "$ADMIN_TAG" "registry.digitalocean.com/eagle0/admin-server:latest"
-          echo "admin_image_tag=$ADMIN_TAG" >> $GITHUB_OUTPUT
-
-          # Push JFR Sidecar image
           JFR_IMAGE="${{ steps.build-all.outputs.jfr_path }}"
           JFR_TAG="registry.digitalocean.com/eagle0/jfr-sidecar:${GIT_SHA}"
+
+          # Push all three images in parallel
+          echo "Pushing Eagle: $EAGLE_TAG"
+          $CRANE push "$EAGLE_IMAGE" "$EAGLE_TAG" &
+          PID_EAGLE=$!
+
+          echo "Pushing Admin: $ADMIN_TAG"
+          $CRANE push "$ADMIN_IMAGE" "$ADMIN_TAG" &
+          PID_ADMIN=$!
+
           echo "Pushing JFR Sidecar: $JFR_TAG"
-          $CRANE push "$JFR_IMAGE" "$JFR_TAG"
-          $CRANE copy "$JFR_TAG" "registry.digitalocean.com/eagle0/jfr-sidecar:latest"
+          $CRANE push "$JFR_IMAGE" "$JFR_TAG" &
+          PID_JFR=$!
+
+          # Wait for all pushes to complete
+          PUSH_FAILED=0
+          wait $PID_EAGLE || PUSH_FAILED=1
+          wait $PID_ADMIN || PUSH_FAILED=1
+          wait $PID_JFR   || PUSH_FAILED=1
+          if [ $PUSH_FAILED -ne 0 ]; then
+            echo "ERROR: One or more image pushes failed"
+            exit 1
+          fi
+          echo "All images pushed, tagging :latest..."
+
+          # Tag :latest in parallel
+          $CRANE copy "$EAGLE_TAG" "registry.digitalocean.com/eagle0/eagle-server:latest" &
+          $CRANE copy "$ADMIN_TAG" "registry.digitalocean.com/eagle0/admin-server:latest" &
+          $CRANE copy "$JFR_TAG" "registry.digitalocean.com/eagle0/jfr-sidecar:latest" &
+          wait
+
+          echo "eagle_image_tag=$EAGLE_TAG" >> $GITHUB_OUTPUT
+          echo "admin_image_tag=$ADMIN_TAG" >> $GITHUB_OUTPUT
           echo "jfr_sidecar_image_tag=$JFR_TAG" >> $GITHUB_OUTPUT
 
           echo "=== All images pushed successfully ==="
@@ -167,6 +217,9 @@ jobs:
       EAGLE_ENABLE_S3: ${{ secrets.EAGLE_ENABLE_S3 }}
       DO_SPACES_ACCESS_KEY: ${{ secrets.DO_SPACES_ACCESS_KEY }}
       DO_SPACES_SECRET_KEY: ${{ secrets.DO_SPACES_SECRET_KEY }}
+      # Admin server uses different credentials (for eagle0-assets bucket)
+      ADMIN_S3_ACCESS_KEY: ${{ secrets.ACCESS_KEY_ID }}
+      ADMIN_S3_SECRET_KEY: ${{ secrets.SECRET_KEY }}
       JWT_PRIVATE_KEY: ${{ secrets.JWT_PRIVATE_KEY }}
       DISCORD_CLIENT_ID: ${{ secrets.DISCORD_CLIENT_ID }}
       DISCORD_CLIENT_SECRET: ${{ secrets.DISCORD_CLIENT_SECRET }}
@@ -188,9 +241,13 @@ jobs:
       FASTMAIL_FROM_NAME: ${{ secrets.FASTMAIL_FROM_NAME }}
       DO_DROPLET_IP: ${{ secrets.DO_DROPLET_IP }}
       DO_REGISTRY_TOKEN: ${{ secrets.DO_REGISTRY_TOKEN }}
+      NOTIFY_SECRET: ${{ secrets.EAGLE_NOTIFY_SECRET }}
+      GITHUB_TOKEN_FOR_ADMIN: ${{ secrets.ADMIN_GITHUB_TOKEN }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          lfs: false
 
       - name: Setup SSH key
         run: |
@@ -199,11 +256,11 @@ jobs:
           chmod 600 ~/.ssh/deploy_key
           ssh-keyscan -H "$DO_DROPLET_IP" >> ~/.ssh/known_hosts 2>/dev/null || true
 
-      - name: Build warmup tool
-        run: |
-          bazel build //src/main/go/net/eagle0/warmup:warmup_linux_amd64
-          mkdir -p scripts/bin
-          cp bazel-bin/src/main/go/net/eagle0/warmup/warmup_linux_amd64_/warmup_linux_amd64 scripts/bin/warmup
+      - name: Download warmup binary
+        uses: actions/download-artifact@v4
+        with:
+          name: warmup-binary
+          path: scripts/bin/
 
       - name: Copy config files to droplet
         run: |
@@ -287,6 +344,8 @@ jobs:
           export EAGLE_ENABLE_S3="${EAGLE_ENABLE_S3:-false}"
           export DO_SPACES_ACCESS_KEY="${DO_SPACES_ACCESS_KEY}"
           export DO_SPACES_SECRET_KEY="${DO_SPACES_SECRET_KEY}"
+          export ADMIN_S3_ACCESS_KEY="${ADMIN_S3_ACCESS_KEY}"
+          export ADMIN_S3_SECRET_KEY="${ADMIN_S3_SECRET_KEY}"
           export JWT_PRIVATE_KEY="${JWT_PRIVATE_KEY}"
           export DISCORD_CLIENT_ID="${DISCORD_CLIENT_ID}"
           export DISCORD_CLIENT_SECRET="${DISCORD_CLIENT_SECRET}"
@@ -307,6 +366,8 @@ jobs:
           export FASTMAIL_FROM_EMAIL="${FASTMAIL_FROM_EMAIL}"
           export FASTMAIL_FROM_NAME="${FASTMAIL_FROM_NAME}"
           export DO_REGISTRY_TOKEN="${DO_REGISTRY_TOKEN}"
+          export NOTIFY_SECRET="${NOTIFY_SECRET}"
+          export GITHUB_TOKEN="${GITHUB_TOKEN_FOR_ADMIN}"
 
           # Check Docker has IPv6 support
           if ! cat /etc/docker/daemon.json 2>/dev/null | grep -q '"ip6tables"'; then
@@ -318,27 +379,34 @@ jobs:
 
           echo "Using images: \$EAGLE_IMAGE, \$ADMIN_IMAGE, \$JFR_SIDECAR_IMAGE"
 
-          # Install crane for pulling OCI images
-          echo "Installing crane..."
-          rm -f crane
-          curl -sL https://github.com/google/go-containerregistry/releases/download/v0.20.2/go-containerregistry_Linux_x86_64.tar.gz | tar xzf - crane
-          chmod +x crane
+          # Install crane for pulling OCI images (cached across deploys)
+          CRANE_VERSION="v0.20.2"
+          if [ ! -x crane ] || ! ./crane version 2>/dev/null | grep -q "0.20.2"; then
+            echo "Installing crane \${CRANE_VERSION}..."
+            rm -f crane
+            curl -sL "https://github.com/google/go-containerregistry/releases/download/\${CRANE_VERSION}/go-containerregistry_Linux_x86_64.tar.gz" | tar xzf - crane
+            chmod +x crane
+          else
+            echo "Using cached crane"
+          fi
 
-          # Pull and load all images
-          echo "Pulling Eagle image..."
-          ./crane pull "\${EAGLE_IMAGE}" eagle.tar && docker load -i eagle.tar && rm eagle.tar
+          # Pull all images in parallel, then load sequentially
+          echo "Pulling all images in parallel..."
+          ./crane pull "\${EAGLE_IMAGE}" eagle.tar &
+          ./crane pull "\${ADMIN_IMAGE}" admin.tar &
+          ./crane pull "\${JFR_SIDECAR_IMAGE}" jfr-sidecar.tar &
+          docker pull nginx:alpine &
+          docker pull certbot/certbot &
+          wait
 
-          echo "Pulling Admin image..."
-          ./crane pull "\${ADMIN_IMAGE}" admin.tar && docker load -i admin.tar && rm admin.tar
+          echo "Loading images..."
+          docker load -i eagle.tar && rm eagle.tar
+          docker load -i admin.tar && rm admin.tar
+          # Tag as :latest locally so docker-compose fallback uses correct image
+          docker tag "\${ADMIN_IMAGE}" registry.digitalocean.com/eagle0/admin-server:latest
+          docker load -i jfr-sidecar.tar && rm jfr-sidecar.tar
 
-          echo "Pulling JFR Sidecar image..."
-          ./crane pull "\${JFR_SIDECAR_IMAGE}" jfr-sidecar.tar && docker load -i jfr-sidecar.tar && rm jfr-sidecar.tar
-
-          # Pull other compose images
-          docker pull nginx:alpine || true
-          docker pull certbot/certbot || true
-
-          echo "All images pulled successfully"
+          echo "All images pulled and loaded successfully"
 
           # =================================================================
           # Verify Shardok connectivity before proceeding with deployment
@@ -382,7 +450,24 @@ jobs:
           docker compose -f docker-compose.prod.yml ps
           docker compose -f docker-compose.prod.yml images
 
-          # Cleanup
+          # Verify admin container is running the correct image
+          echo "=== Verifying admin container image ==="
+          ADMIN_RUNNING_DIGEST=\$(docker inspect admin-server --format '{{.Image}}')
+          ADMIN_EXPECTED_DIGEST=\$(docker inspect "\${ADMIN_IMAGE}" --format '{{.Id}}')
+          echo "Expected image: \${ADMIN_IMAGE}"
+          echo "Expected digest: \${ADMIN_EXPECTED_DIGEST}"
+          echo "Running digest:  \${ADMIN_RUNNING_DIGEST}"
+          if [ "\${ADMIN_RUNNING_DIGEST}" != "\${ADMIN_EXPECTED_DIGEST}" ]; then
+            echo "ERROR: Admin container is running wrong image!"
+            echo "Container entrypoint:"
+            docker inspect admin-server --format '{{.Config.Entrypoint}}'
+            exit 1
+          fi
+          echo "Admin image verification passed"
+
+          # Cleanup - remove old images to prevent disk full
           docker container prune -f
           docker image prune -f
+          # Remove images older than 24h (keeps recent images for rollback)
+          docker image prune -a -f --filter "until=24h" || true
           DEPLOY_SCRIPT

.github/workflows/eagle_build.yml

@@ -1,16 +1,7 @@
 name: Eagle Build
 
 on:
-  push:
-    branches: [ "main" ]
-    paths:
-      - 'src/main/scala/**'
-      - 'src/main/protobuf/net/eagle0/eagle/**'
-      - 'src/main/protobuf/net/eagle0/common/**'
-      - 'WORKSPACE'
-      - 'MODULE.bazel'
-      - 'BUILD.bazel'
-      - '.github/workflows/eagle_build.yml'
+  # Main pushes are covered by docker_build.yml which builds the same target
   pull_request:
     paths:
       - 'src/main/scala/**'
@@ -19,8 +10,13 @@ on:
       - 'WORKSPACE'
       - 'MODULE.bazel'
       - 'BUILD.bazel'
+      - '.bazelrc'
       - '.github/workflows/eagle_build.yml'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 permissions:
   contents: read
 

.github/workflows/ios_addressables_build.yml

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

.github/workflows/ios_testflight.yml

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

.github/workflows/mac_build.yml

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

.github/workflows/shardok_arm64_build.yml

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

.github/workflows/shardok_build.yml

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

.github/workflows/unity_build.yml

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

.gitignore

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

.pre-commit-config.yaml

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

CLAUDE.md

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

MODULE.bazel

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

ci/BUILD.bazel

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

ci/github_actions/archive_ios.sh

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

ci/github_actions/build_ios_addressables.sh

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

ci/github_actions/build_mac.sh

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

ci/github_actions/build_unity.sh

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

ci/github_actions/build_unity_ios.sh

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

ci/github_actions/build_unity_mac.sh

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

ci/github_actions/build_windows.sh

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

ci/github_actions/ensure_unity_installed.sh

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

ci/github_actions/persist_library.sh

@@ -1,33 +0,0 @@
-#!/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
-
-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 --exclude='Bee/' src/main/csharp/net/eagle0/clients/unity/eagle0/Library/ "$CACHE_DIR/"
-rsync_exit=$?
-
-if [ $rsync_exit -eq 0 ]; then
-    exit 0
-elif [ $rsync_exit -eq 23 ]; then
-    echo "Warning: rsync exited with 23 (some files vanished during copy). This is expected for Unity temp files."
-    exit 0
-else
-    echo "Error: rsync failed with exit code $rsync_exit"
-    exit $rsync_exit
-fi

ci/github_actions/restore_library.sh

@@ -1,16 +0,0 @@
-#!/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
-
-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/

ci/github_actions/upload_testflight.sh

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

ci/unity_version.sh

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

docker-compose.prod.yml

@@ -208,6 +208,19 @@ services:
       - "${JFR_SIDECAR_ADDR:-jfr-sidecar:8081}"  # Can be switched for blue-green
       - "--http-port"
       - "8080"
+      - "--maps-dir"
+      - "/app/maps"
+    environment:
+      # Secret for CI to authenticate client update notifications
+      NOTIFY_SECRET: "${NOTIFY_SECRET:-}"
+      # S3/Spaces credentials for What's New storage (uses eagle0-assets bucket)
+      DO_SPACES_ENDPOINT: "${DO_SPACES_ENDPOINT:-https://sfo3.digitaloceanspaces.com}"
+      DO_SPACES_ACCESS_KEY: "${ADMIN_S3_ACCESS_KEY:-}"
+      DO_SPACES_SECRET_KEY: "${ADMIN_S3_SECRET_KEY:-}"
+      # GitHub PAT for map editor PR creation (scoped to contents:write + pull_requests:write)
+      GITHUB_TOKEN: "${GITHUB_TOKEN:-}"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
     # No external port - accessed via nginx at admin.eagle0.net
     depends_on:
       - auth

docs/ADDING_NEW_QUESTS.md

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

docs/ADMIN_SERVER_ENHANCEMENTS.md

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

docs/ASSET_AUDIT.md

@@ -126,6 +126,27 @@ All 26 tracks have CC licenses with proper attribution:
 
 ---
 
+## 2b. Creative Commons Sound Effects
+
+**Location:** `Assets/Shardok/Sounds/`
+
+| File | Description | Artist | License | Source |
+|------|-------------|--------|---------|--------|
+| `rain_loop.ogg` | Rain falling on clay roof tiles (loopable) | aesqe | CC BY 4.0 | [Freesound #37618](https://freesound.org/people/aesqe/sounds/37618/) |
+| `blizzard_wind_loop.wav` | Wind draft loop (indoor recording, loops seamlessly) | nsstudios | CC BY 4.0 | [Freesound #651540](https://freesound.org/people/nsstudios/sounds/651540/) |
+| `thunder_distant.mp3` | Distant thunder rumble | LittleRainySeasons | CC BY 4.0 | [Freesound #351526](https://freesound.org/people/LittleRainySeasons/sounds/351526/) |
+| `thunder_loud.mp3` | Loud thunder clap | mokasza | CC BY 4.0 | [Freesound #810746](https://freesound.org/people/mokasza/sounds/810746/) |
+| `thunder_crack.wav` | Thunder crack | OneSoundToRuleThemAll | CC BY 4.0 | [Freesound #238796](https://freesound.org/people/OneSoundToRuleThemAll/sounds/238796/) |
+| `thunder_clap.wav` | Thunder clap | FreqMan | CC BY 4.0 | [Freesound #32544](https://freesound.org/people/FreqMan/sounds/32544/) |
+
+**Location:** `Assets/Shardok/soundEffects/`
+
+| File | Description | Artist | License | Source |
+|------|-------------|--------|---------|--------|
+| `runaway.mp3` | Medieval army running loop (gravel + metal/chain) | Yap_Audio_Production | CC BY 4.0 | [Freesound #218997](https://freesound.org/people/Yap_Audio_Production/sounds/218997/) |
+
+---
+
 ## 3. CC0 / Public Domain Assets
 
 ### SimpleFileBrowser Icons
@@ -155,26 +176,35 @@ All 26 tracks have CC licenses with proper attribution:
 - `undead_break_control.mp3`
 - `undead_grew.wav`
 
-**⚠️ MUST REPLACE:**
+**⚠️ MUST REPLACE (1 remaining):**
 - ~~`anybody.mp3`~~ - **REPLACED** (2026-01-23) with `Positive Effect 6.wav` from Magic Spells Sound Effects LITE
 - ~~`burnination.mp3`~~ - **REPLACED** (2026-01-23) with `Magic Element Fire 04.wav` from Medieval Combat Sounds
 - `failure_horn.mp3` - licensing issue, no replacement found in purchased assets
-- `runaway.mp3` - licensing issue, no replacement found in purchased assets
+- ~~`runaway.mp3`~~ - **REPLACED** (2026-01-27) with `MedievalArmyRunningLoop.mp3` from Freesound (CC BY 4.0)
 
-**Presumed from Unity Asset Store purchases (31 files):**
+**Verified from [Medieval Combat Sounds](https://assetstore.unity.com/packages/audio/sound-fx/medieval-combat-sounds-100465) (Unity Asset Store):**
+- `duel_challenged.wav` - **REPLACED** (2026-02-03) with `Weapon Draw Metal 1.wav` from Medieval Combat Sounds
+
+**Presumed from Unity Asset Store purchases (30 files):**
 Owner believes these are from: Fantasy Interface Sounds, Medieval Combat Sounds, Magic Spells Sound Effects LITE, and/or Medieval Battle Sound Pack.
 - `archery.mp3`, `battle_shout.mp3`, `boo.mp3`, `braved_water.mp3`
 - `build_bridge.mp3`, `build_bridge_failure.mp3`, `charge.mp3`
-- `dismiss_unit.mp3`, `duel_challenged.mp3`, `failure_horn.mp3`, `fear.mp3`, `fear_failed.mp3`
+- `dismiss_unit.mp3`, `failure_horn.mp3`, `fear.mp3`, `fear_failed.mp3`
 - `fire_extinguish.mp3`, `fire_spread.mp3`, `fire_start.mp3`, `fire_start_failure.mp3`
 - `freeze.mp3`, `holy_wave.mp3`, `holy_wave_damage.mp3`, `jail_door.mp3`, `lightning.mp3`
 - `melee.mp3`, `meteor.mp3`, `mind_control.mp3`, `move.mp3`, `move 1.mp3`
 - `raging_fire.mp3`, `reduce.mp3`, `repair.mp3`, `repair_failed.mp3`, `splash.mp3`
 
-### Free Icons
-- **Location:** `Assets/free_icons/`
-- **Count:** 8 PNG weather icons
-- **Status:** Verify "free" means commercially usable
+### ~~Free Icons~~ RESOLVED
+- **Location:** `Assets/free_icons/` - **DELETED** (2026-01-27)
+- **Resolution:** All icons replaced with equivalents from purchased Asset Store packs:
+  - `blizzard.png` → `16_blizzard_nobg.png` (4000_Fantasy_Icons)
+  - `rain.png` → `12_Magic_rain_nobg.png` (4000_Fantasy_Icons)
+  - `thunderstorm.png` → `27_Storm_nobg.png` (4000_Fantasy_Icons)
+  - `wind.png` → `23_Light_blow_nobg.png` (4000_Fantasy_Icons)
+  - `thermometer.png` → `startFire.png` (existing licensed asset)
+  - `snow.png` → `16_blizzard_nobg.png` (4000_Fantasy_Icons)
+  - `cloud.png`, `sun.png` → deleted (unused)
 
 ### ~~Terrain Hexes~~ VERIFIED
 - **Location:** `Assets/Terrain Hexes/`
@@ -216,26 +246,31 @@ NuGet packages in `Assets/Packages/` all include LICENSE.TXT files:
 
 ## Action Items
 
-### Must Verify Before Opening Public Access:
+### Must Replace Before Opening Public Access:
 
-1. ~~**Clip art images**~~ - **RESOLVED** (2025-01-23): Replaced with game-icons.net CC BY 3.0 icons
+1. ~~**Clip art images**~~ - **RESOLVED** (2026-01-23): Replaced with properly licensed alternatives
 
-2. **Shardok sound effects** - 3 files must be replaced:
-   - `anybody.mp3` - licensing issue
-   - `burnination.mp3` - licensing issue
-   - `runaway.mp3` - licensing issue
+2. ~~**Shardok sound effects**~~ - **ALL RESOLVED**:
+   - ~~`anybody.mp3`~~ - **REPLACED** (2026-01-23)
+   - ~~`burnination.mp3`~~ - **REPLACED** (2026-01-23)
+   - ~~`failure_horn.mp3`~~ - **REPLACED** (2026-01-27) with `Negative Effect 04.wav` from Magic Spells Sound Effects LITE
+   - ~~`runaway.mp3`~~ - **REPLACED** (2026-01-27) with Freesound CC BY 4.0
 
-   Remaining 31 files presumed from Asset Store purchases; 3 verified from Zombie Monster Undead Collection.
+### Low Priority (Verify):
 
-3. ~~**Terrain Hexes**~~ - **VERIFIED** (2026-01-23): Confirmed Unity Asset Store purchase
+3. **Dima Koltsov tracks** - 2 of 5 not verified: `Forest Queen Tale`, `Clouds` (presumed CC BY 4.0 like his other tracks)
 
-4. ~~**StrategyGameIcons**~~ - **VERIFIED** (2026-01-23): Unity Asset Store purchase (REXARD)
+### Already Resolved:
 
-5. ~~**Medieval: Victory Theme**~~ - **VERIFIED** (2026-01-23): CC0 Public Domain by RandomMind ([Chosic](https://www.chosic.com/download-audio/28492/))
+4. ~~**Free Icons**~~ - **RESOLVED** (2026-01-27): All replaced with Asset Store equivalents, folder deleted
 
-6. ~~**Dima Koltsov tracks**~~ - **MOSTLY VERIFIED** (2026-01-23): 3 of 5 confirmed CC BY 4.0 via YouTube. 2 remaining (Forest Queen Tale, Clouds) presumed same license.
+5. ~~**Terrain Hexes**~~ - **VERIFIED** (2026-01-23): Confirmed Unity Asset Store purchase
 
-7. ~~**Discord logo**~~ - **OK** (2026-01-23): Usage complies with Discord brand guidelines for "Login with Discord" button
+6. ~~**StrategyGameIcons**~~ - **VERIFIED** (2026-01-23): Unity Asset Store purchase (REXARD)
+
+7. ~~**Medieval: Victory Theme**~~ - **VERIFIED** (2026-01-23): CC0 Public Domain by RandomMind ([Chosic](https://www.chosic.com/download-audio/28492/))
+
+8. ~~**Discord logo**~~ - **OK** (2026-01-23): Usage complies with Discord brand guidelines for "Login with Discord" button
 
 ### Already Safe:
 
@@ -249,13 +284,23 @@ NuGet packages in `Assets/Packages/` all include LICENSE.TXT files:
 
 ## Recommendation
 
-Before public release:
+**Remaining before public release:**
 
-1. ~~Replace clip art images (`bridge.png`, `startFire.png`) with properly licensed alternatives~~ **DONE** - see Section 4
-2. ~~Verify source of `Assets/Shardok/soundEffects/` MP3s~~ **MOSTLY DONE** - 3 files flagged for replacement, rest presumed Asset Store
-3. ~~Verify source of `Assets/Terrain Hexes/`~~ **DONE** - confirmed Asset Store purchase
-4. ~~Verify source of `Assets/StrategyGameIcons/`~~ **DONE** - Unity Asset Store (REXARD)
-5. ~~Replace Dima Koltsov Audius tracks~~ **MOSTLY DONE** - 3/5 confirmed CC BY 4.0, 2 presumed same
-6. ~~Find source of Medieval: Victory Theme or replace~~ **DONE** - CC0 Public Domain by RandomMind
+None! All required items resolved.
+
+**Low priority:**
+
+2. Verify 2 Dima Koltsov tracks (`Forest Queen Tale`, `Clouds`) - presumed CC BY 4.0
+
+**Already resolved:**
+
+- ~~Clip art images~~ **DONE** - replaced with properly licensed alternatives
+- ~~Terrain Hexes~~ **DONE** - confirmed Asset Store purchase
+- ~~StrategyGameIcons~~ **DONE** - Unity Asset Store (REXARD)
+- ~~Medieval: Victory Theme~~ **DONE** - CC0 Public Domain
+- ~~3 other Dima Koltsov tracks~~ **DONE** - confirmed CC BY 4.0
+- ~~anybody.mp3, burnination.mp3~~ **DONE** - replaced
+- ~~free_icons~~ **DONE** - replaced with Asset Store equivalents
+- ~~failure_horn.mp3~~ **DONE** - replaced with Negative Effect 04.wav
 
 The bulk of your assets (95%+) are properly licensed Asset Store purchases or CC content.

docs/NEW_PROFESSION_PROPOSALS.md

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

docs/NOTIFICATION_DIFF_BATCHING.md

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

docs/OAUTH_GO_SERVICE_PLAN.md

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

docs/OAUTH_IMPLEMENTATION_PLAN.md

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

docs/OAUTH_NEXT_STEPS.md

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

docs/PROGRAMMATIC_MAP_GENERATION.md

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

docs/RENAMING_A_PROVINCE.md

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

docs/RULES_APPLE_WORKSPACE_SEPARATION.md

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

docs/SCALA3_MODERNIZATION.md

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

docs/SMALL_EAGLE_TODO.md

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

docs/TUTORIAL_BATTLE_SYSTEM.md

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

docs/TUTORIAL_CONTENT.md

@@ -149,6 +149,52 @@ Triggered during battles when players encounter spells, terrain, or abilities.
 
 ---
 
+## Post-Battle Dialogue (Narrative Dialogues)
+
+These fire after the first tutorial battle ends and the player returns to the strategic map. They use the narrative dialogue system (`DialogueManager` / `tutorial_strategic.json`) rather than the modal tutorial system.
+
+### Battle Aftermath
+| Field | Value |
+|-------|-------|
+| ID | `post_battle_aftermath` |
+| Trigger | `tutorial_battle_ended` (battle removed from RunningShardokGameModels) |
+| Speaker | Old Marek the Learned |
+| Panel Position | top |
+
+**Dialogue (Marek):**
+> That was closer than I'd like to admit. We held — barely. But Tarn... Tarn is gone. Not retreated — *gone*. The men say he vanished from the field. Some claim sorcery. Others say he slipped away in the chaos. Whatever the truth, no one can find him.
+>
+> But we captured some of his lieutenants. These are soldiers, Sadar — they followed orders, same as we once did. They're not to blame for Tarn's madness. See if you can bring them to our cause, or at least hold them until they come around.
+
+**Instructions:** *(none — Handle Captured Heroes UI is self-explanatory)*
+
+### Rebuild Support
+| Field | Value |
+|-------|-------|
+| ID | `post_battle_rebuild` |
+| Trigger | `tutorial_rebuild_support` (fires when available commands no longer include HandleCapturedHeroCommand) |
+| Speaker | Old Marek the Learned |
+| Panel Position | top |
+
+**Dialogue (Marek):**
+> Good. Now we need to rebuild our support here in Onmaa. The people are shaken — a battle on their doorstep will do that. We need them behind us if we're going to hold this province.
+>
+> Any of our heroes can develop the land or give alms to the people — nothing wins hearts faster than a full belly. Engineers like John Ranil are especially effective at improving a province, and paladins like Elena Fyar are the best at winning hearts. Either way, we need the people's support before the tax collectors come round in January.
+
+**Instructions:** Use **Improve** and **Give Alms** to raise Support. You must have at least **40** support in the province by January in order to collect gold and food in taxes.
+
+**Highlight targets:** `SupportField`
+
+### Implementation Notes
+
+- Both dialogues go in `tutorial_strategic.json`
+- Need new trigger events: `tutorial_battle_ended` and `tutorial_rebuild_support`
+- `tutorial_battle_ended` should fire when the tutorial battle is removed from `RunningShardokGameModels` in `EagleGameModel.ApplyGameStateViewDiff`
+- `tutorial_rebuild_support` should fire when available commands no longer include `HandleCapturedHeroCommand` (i.e. the captured heroes phase is done and the player has regular commands available)
+- The "rebuild" dialogue should highlight the Improve and Give Alms buttons in the command panel (requires registering them as highlight targets)
+
+---
+
 ## Display Modes
 
 | Mode | Description | Use For |

docs/ai-quest-completion.md

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

docs/eliminate-battalion-backstory-updates.md

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

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

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

docs/scala3-reflection-issues.md

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

external/BUILD.bazel

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

nginx/nginx.conf

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

scripts/build_protos.sh

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

scripts/build_sparkle_plugin.sh

@@ -2,6 +2,9 @@
 #
 # Build the SparklePlugin native library for Unity using Bazel
 #
+# The SparklePlugin is built in a separate Bazel workspace (sparkle_workspace/)
+# to avoid rules_swift version conflicts between grpc and rules_apple.
+#
 # Usage: build_sparkle_plugin.sh [output_dir]
 
 set -euo pipefail
@@ -11,12 +14,14 @@ 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 ==="
+echo "=== Building SparklePlugin with Bazel (from sparkle_workspace) ==="
 
-bazel build --config=mactools //src/main/objc/net/eagle0/sparkle:SparklePlugin
+# Build in the separate sparkle_workspace to avoid dependency conflicts
+cd "$PROJECT_ROOT/sparkle_workspace"
+bazel build //:SparklePlugin
 
 # Get the zip path from bazel
-ZIP_PATH=$(bazel cquery --config=mactools --output=files //src/main/objc/net/eagle0/sparkle:SparklePlugin 2>/dev/null)
+ZIP_PATH=$(bazel cquery --output=files //:SparklePlugin 2>/dev/null)
 
 echo "=== Extracting SparklePlugin.bundle ==="
 mkdir -p "$OUTPUT_DIR"

scripts/check_build_deps.sh

@@ -22,11 +22,31 @@ NC='\033[0m' # No Color
 MODE="${1:-check}"
 EXIT_CODE=0
 
+# Cache for expensive bazel query results
+LIBRARY_DEPS_CACHE=""
+MAIN_DEPS_CACHE=""
+
+# Get deps of library/ (cached)
+get_library_deps() {
+    if [ -z "$LIBRARY_DEPS_CACHE" ]; then
+        LIBRARY_DEPS_CACHE=$(bazel query 'deps(//src/main/scala/net/eagle0/eagle/library/...)' 2>/dev/null || true)
+    fi
+    echo "$LIBRARY_DEPS_CACHE"
+}
+
+# Get deps of src/main (cached)
+get_main_deps() {
+    if [ -z "$MAIN_DEPS_CACHE" ]; then
+        MAIN_DEPS_CACHE=$(bazel query 'deps(//src/main/...)' 2>/dev/null || true)
+    fi
+    echo "$MAIN_DEPS_CACHE"
+}
+
 # Rule 1: src/main should not depend on src/test
 check_main_depends_on_test() {
     echo -e "${YELLOW}Checking: src/main should not depend on src/test...${NC}"
 
-    violations=$(bazel query 'deps(//src/main/...) intersect //src/test/...' 2>/dev/null || true)
+    violations=$(get_main_deps | grep "^//src/test/" || true)
 
     if [ -n "$violations" ]; then
         echo -e "${RED}VIOLATION: src/main depends on src/test:${NC}"
@@ -43,7 +63,7 @@ check_main_depends_on_test() {
 check_library_depends_on_scala_proto() {
     echo -e "${YELLOW}Checking: library/ should not depend on Scala proto types...${NC}"
 
-    violations=$(bazel query 'deps(//src/main/scala/net/eagle0/eagle/library/...) intersect //src/main/protobuf/...' 2>/dev/null | grep "_scala_proto" || true)
+    violations=$(get_library_deps | grep "^//src/main/protobuf/.*_scala_proto$" || true)
     if [ -z "$violations" ]; then
         count=0
     else
@@ -65,7 +85,7 @@ check_library_depends_on_scala_proto() {
 check_library_depends_on_proto_converters() {
     echo -e "${YELLOW}Checking: library/ should not depend on proto_converters...${NC}"
 
-    violations=$(bazel query 'deps(//src/main/scala/net/eagle0/eagle/library/...) intersect //src/main/scala/net/eagle0/eagle/model/proto_converters/...' 2>/dev/null | grep "^//" || true)
+    violations=$(get_library_deps | grep "^//src/main/scala/net/eagle0/eagle/model/proto_converters/" || true)
 
     if [ -n "$violations" ]; then
         count=$(echo "$violations" | wc -l | tr -d ' ')
@@ -85,7 +105,8 @@ check_library_depends_on_proto_converters() {
 count_proto_deps() {
     echo -e "${YELLOW}=== Proto dependency counts ===${NC}"
 
-    scala_proto_results=$(bazel query 'deps(//src/main/scala/net/eagle0/eagle/library/...) intersect //src/main/protobuf/...' 2>/dev/null | grep "_scala_proto" || true)
+    library_deps=$(get_library_deps)
+    scala_proto_results=$(echo "$library_deps" | grep "^//src/main/protobuf/.*_scala_proto$" || true)
     if [ -z "$scala_proto_results" ]; then
         scala_proto_count=0
     else
@@ -94,7 +115,7 @@ count_proto_deps() {
     echo "library/ Scala proto deps: $scala_proto_count"
 
     # C++/Go proto deps are expected (map generation tools)
-    all_proto_count=$(bazel query 'deps(//src/main/scala/net/eagle0/eagle/library/...) intersect //src/main/protobuf/...' 2>/dev/null | wc -l | tr -d ' ')
+    all_proto_count=$(echo "$library_deps" | grep -c "^//src/main/protobuf/" || echo "0")
     echo "library/ all proto deps (includes C++/Go build tools): $all_proto_count"
 }
 

scripts/codesign_mac_app.sh

@@ -5,24 +5,58 @@
 #
 # Environment variables:
 #   SIGNING_IDENTITY - The signing identity (default: "Developer ID Application")
-#   KEYCHAIN_PASSWORD - Password to unlock the build keychain (optional)
+#   KEYCHAIN_PASSWORD - Password to unlock the keychain (optional, CI only)
+#   KEYCHAIN_NAME - Name of the keychain containing the signing certificate (optional, CI only)
+#                   When set, looks for certificate in this specific keychain.
+#                   When not set, searches all keychains (local dev mode).
 
 set -euxo pipefail
 
 APP_PATH="$1"
 ENTITLEMENTS_PATH="${2:-}"
 SIGNING_IDENTITY="${SIGNING_IDENTITY:-Developer ID Application}"
+# KEYCHAIN_NAME is set by CI workflow - don't set a default here so we can detect if we're in CI
 
 if [ ! -d "$APP_PATH" ]; then
     echo "ERROR: App not found at $APP_PATH"
     exit 1
 fi
 
-# Unlock keychain if password provided
-if [ -n "${KEYCHAIN_PASSWORD:-}" ]; then
-    security unlock-keychain -p "$KEYCHAIN_PASSWORD" build.keychain || true
+# Unlock keychain if password and keychain name are provided (CI environment)
+if [ -n "${KEYCHAIN_PASSWORD:-}" ] && [ -n "${KEYCHAIN_NAME:-}" ]; then
+    security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_NAME" || true
 fi
 
+# Get the SHA-1 hash of the signing certificate
+# Using the hash avoids "ambiguous" errors when the same identity exists in multiple keychains
+# We look in the build keychain specifically if KEYCHAIN_NAME is set (CI environment)
+# Otherwise fall back to searching all keychains (local dev)
+
+if [ -n "${KEYCHAIN_NAME:-}" ]; then
+    # CI environment: look for certificate in the build keychain specifically
+    KEYCHAIN_PATH="$HOME/Library/Keychains/${KEYCHAIN_NAME}-db"
+    echo "Looking for signing identity in build keychain: $KEYCHAIN_PATH"
+    echo "Available identities in build keychain:"
+    security find-identity -v -p codesigning "$KEYCHAIN_PATH"
+
+    CERT_HASH=$(security find-identity -v -p codesigning "$KEYCHAIN_PATH" | grep -E '^\s+[0-9]+\)' | head -1 | awk '{print $2}')
+else
+    # Local dev: search all keychains
+    echo "Available codesigning identities:"
+    security find-identity -v -p codesigning
+
+    CERT_HASH=$(security find-identity -v -p codesigning | grep -E '^\s+[0-9]+\)' | head -1 | awk '{print $2}')
+fi
+
+if [ -z "$CERT_HASH" ]; then
+    echo "ERROR: No valid signing identity found"
+    exit 1
+fi
+echo "Using certificate hash: $CERT_HASH"
+
+# Use the hash as the signing identity to avoid ambiguity
+SIGNING_IDENTITY="$CERT_HASH"
+
 echo "=== Signing nested components first ==="
 
 # Sign all dylibs

scripts/deploy-blue-green.sh

@@ -317,11 +317,23 @@ main() {
         echo "JFR_SIDECAR_ADDR=jfr-sidecar:8081" >> "${env_file}"
     fi
 
-    # Restart admin to pick up new .env
+    # Restart admin to pick up new .env and ensure latest image
     # Use --no-deps to prevent cascading to auth (which has secrets not available here)
     log_info "Restarting admin service..."
     docker compose -f "${COMPOSE_FILE}" up -d --force-recreate --no-deps admin
 
+    # Verify admin container is running
+    sleep 3
+    if ! docker inspect admin-server --format '{{.State.Running}}' 2>/dev/null | grep -q "true"; then
+        log_error "Admin container failed to start!"
+        log_error "Container logs:"
+        docker logs admin-server --tail 20 2>&1 || true
+        log_error "Container inspect:"
+        docker inspect admin-server 2>&1 | head -50 || true
+        exit 1
+    fi
+    log_info "Admin service restarted successfully"
+
     # Clean up old instance
     log_info "Cleaning up old eagle-${active}..."
     docker compose -f "${COMPOSE_FILE}" rm -f "eagle-${active}" 2>/dev/null || true

scripts/downloadTsvs.sh

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

scripts/eagle-restart.sh

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

scripts/generate_changelog.sh

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

sparkle_workspace/.bazelversion

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

sparkle_workspace/.gitignore

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

sparkle_workspace/MODULE.bazel

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

sparkle_workspace/MODULE.bazel.lock

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

sparkle_workspace/WORKSPACE.bazel

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

src/main/cpp/net/eagle0/common/UnitConversions.cpp

@@ -95,9 +95,16 @@ auto ConvertUnit(
     shardokUnit.mutate_stun_rounds_remaining(0);
 
     for (const PlayerId pid : allPlayerIds) {
+        int8_t initialKnowledge = 0;
+        for (const auto visibleToPid : unit.visible_to_player_ids()) {
+            if (visibleToPid == pid) {
+                initialKnowledge = 100;
+                break;
+            }
+        }
         shardokUnit.mutable_opponent_knowledge()->Mutate(
                 static_cast<flatbuffers::uoffset_t>(pid),
-                0);
+                initialKnowledge);
     }
 
     shardokUnit.mutate_has_moved_in_zoc(false);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -90,6 +90,7 @@ cc_library(
         "//src/main/cpp/net/eagle0/shardok/library/actions:end_player_setup_command",
         "//src/main/cpp/net/eagle0/shardok/library/actions:place_hidden_unit_command",
         "//src/main/cpp/net/eagle0/shardok/library/actions:place_unit_command",
+        "//src/main/cpp/net/eagle0/shardok/library/map:coordinates",
         "//src/main/cpp/net/eagle0/shardok/library/settings:game_settings",
         "//src/main/cpp/net/eagle0/shardok/library/util:hex_map_utils",
         "//src/main/cpp/net/eagle0/shardok/library/util:player_utils",

src/main/cpp/net/eagle0/shardok/library/action_factories/PlayerSetupCommandFactory.cpp

@@ -66,11 +66,30 @@ auto PlayerSetupCommandFactory::AddAvailablePlaceAndHideUnitCommandsForOneUnit(
 auto PlayerSetupCommandFactory::AddAvailablePlayerSetupCommands(
         CommandList &existingCommands,
         PlayerId playerId,
-        const GameStateW &gameState) const -> void {
+        const GameStateW &gameState,
+        const std::optional<std::vector<Coords>> &reinforcementPositions) const -> void {
     if (playerId < 0) return;
-    if (gameState->status()->state() !=
-        net::eagle0::shardok::storage::fb::GameStatus_::State_SET_UP)
+
+    const auto state = gameState->status()->state();
+
+    // Handle reinforcement placement phase
+    if (state == net::eagle0::shardok::storage::fb::GameStatus_::State_REINFORCEMENT_PLACEMENT) {
+        if (!reinforcementPositions.has_value()) return;
+
+        const auto unplacedUnits = ReserveUnitsForPlayer(gameState->units(), playerId);
+        if (unplacedUnits.empty()) return;
+
+        for (const auto &[unitId, unit] : unplacedUnits) {
+            for (const Coords &position : *reinforcementPositions) {
+                if (!gameState.GetOccupant(position)) {
+                    existingCommands.push_back(std::make_shared<PlaceUnitCommand>(unit, position));
+                }
+            }
+        }
         return;
+    }
+
+    if (state != net::eagle0::shardok::storage::fb::GameStatus_::State_SET_UP) return;
 
     const bool isDefender = PlayerIsDefender(gameState, playerId);
 

src/main/cpp/net/eagle0/shardok/library/action_factories/PlayerSetupCommandFactory.hpp

@@ -5,8 +5,12 @@
 #ifndef EAGLE0_PLAYERSETUPCOMMANDFACTORY_HPP
 #define EAGLE0_PLAYERSETUPCOMMANDFACTORY_HPP
 
+#include <optional>
+#include <vector>
+
 #include "src/main/cpp/net/eagle0/shardok/library/GameStateW.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/ShardokCommand.hpp"
+#include "src/main/cpp/net/eagle0/shardok/library/map/Coordinates.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/settings/GameSettings.hpp"
 
 namespace shardok {
@@ -29,7 +33,9 @@ public:
     auto AddAvailablePlayerSetupCommands(
             CommandList& existingCommands,
             PlayerId playerId,
-            const GameStateW& gameState) const -> void;
+            const GameStateW& gameState,
+            const std::optional<std::vector<Coords>>& reinforcementPositions = std::nullopt) const
+            -> void;
 };
 
 }  // namespace shardok

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

@@ -1,4 +1,3 @@
-load("@build_bazel_rules_apple//apple:macos.bzl", "macos_command_line_application")
 load("//tools:copts.bzl", "COPTS")
 
 cc_library(
@@ -82,11 +81,3 @@ cc_binary(
         ":fixed_action_point_distances_timer",
     ],
 )
-
-macos_command_line_application(
-    name = "fixed_action_point_distances_timer_macos_app",
-    minimum_os_version = "10.15",
-    deps = [
-        ":fixed_action_point_distances_timer",
-    ],
-)

src/main/cpp/net/eagle0/shardok/library/action_result_applier/ActionResultApplier.cpp

@@ -331,7 +331,7 @@ void MutatingApplyResult(
                                                           .size()
                                                 : changedUnit->battalion().size();
 
-        auto status = net::eagle0::shardok::storage::fb::UnitStatus_NORMAL_UNIT;
+        auto status = changedUnit->status();
         if (IsDestroyed(*changedUnit)) {
             status =
                     changedUnit->has_attached_hero()

src/main/cpp/net/eagle0/shardok/library/actions/MeteorCastAction.cpp

@@ -34,6 +34,7 @@ auto IsResolved(const net::eagle0::shardok::storage::fb::UnitStatus status) -> b
         case net::eagle0::shardok::storage::fb::UnitStatus_RESERVE_UNIT:
         case net::eagle0::shardok::storage::fb::UnitStatus_NEVER_ENTERED_UNIT:
         case net::eagle0::shardok::storage::fb::UnitStatus_RESERVED_SLOT:
+        case net::eagle0::shardok::storage::fb::UnitStatus_PENDING_REINFORCEMENT:
         case net::eagle0::shardok::storage::fb::UnitStatus_UNKNOWN_UNIT: return false;
     }
 

src/main/cpp/net/eagle0/shardok/library/actions/PlaceHiddenUnitCommand.cpp

@@ -18,6 +18,7 @@ using net::eagle0::shardok::common::GameStatus;
     auto actorAfter = *currentState->units()->Get(actorId);
     actorAfter.mutable_location() = target;
     actorAfter.mutate_hidden(true);
+    actorAfter.mutate_status(net::eagle0::shardok::storage::fb::UnitStatus_NORMAL_UNIT);
     MutatingBumpAllKnowledgeToMinimum(&actorAfter, minimumKnowledge);
 
     ActionResult placeResult{};

src/main/cpp/net/eagle0/shardok/library/actions/PlaceUnitCommand.cpp

@@ -16,6 +16,7 @@ auto PlaceUnitCommand::InternalExecute(
         const std::shared_ptr<RandomGenerator>& /*generator*/) const -> vector<ActionResult> {
     auto actorAfter = *actor;
     actorAfter.mutable_location() = target;
+    actorAfter.mutate_status(net::eagle0::shardok::storage::fb::UnitStatus_NORMAL_UNIT);
 
     ActionResult placeResult{};
     placeResult.set_type(ActionType::PLACE_UNIT);

src/main/cpp/net/eagle0/shardok/library/actions/UpdateGameStatusAction.cpp

@@ -89,7 +89,9 @@ auto UpdateGameStatusAction::InternalExecute(
     // If the game has already ended, just return that state
     if (GameIsOver(gameState->status())) { return results; }
     if (gameState->status()->state() ==
-        net::eagle0::shardok::storage::fb::GameStatus_::State_SET_UP) {
+                net::eagle0::shardok::storage::fb::GameStatus_::State_SET_UP ||
+        gameState->status()->state() ==
+                net::eagle0::shardok::storage::fb::GameStatus_::State_REINFORCEMENT_PLACEMENT) {
         return results;
     }
 

src/main/cpp/net/eagle0/shardok/library/commands/ReinforceCommand.cpp

@@ -25,6 +25,7 @@ auto ReinforceCommand::InternalExecute(
     const Unit* joiningUnit = currentState->units()->Get(joiningUnitId);
     auto joinerAfter = *joiningUnit;
     joinerAfter.mutable_location() = location;
+    joinerAfter.mutate_status(net::eagle0::shardok::storage::fb::UnitStatus_NORMAL_UNIT);
 
     ActionResult placeResult{};
     placeResult.set_type(ActionType::REINFORCED);

src/main/cpp/net/eagle0/shardok/library/fb_helpers/GameStateHelpers.cpp

@@ -176,7 +176,10 @@ auto SetupInitialGameState(
         modifiedUnit.mutable_battalion().mutate_base_morale(baseMorale);
         modifiedUnit.mutable_battalion().mutate_morale(baseMorale);
 
-        modifiedUnit.mutate_status(net::eagle0::shardok::storage::fb::UnitStatus_RESERVE_UNIT);
+        if (modifiedUnit.status() !=
+            net::eagle0::shardok::storage::fb::UnitStatus_PENDING_REINFORCEMENT) {
+            modifiedUnit.mutate_status(net::eagle0::shardok::storage::fb::UnitStatus_RESERVE_UNIT);
+        }
 
         unitsVec.push_back(modifiedUnit);
     }

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

@@ -0,0 +1,19 @@
+load("//tools:copts.bzl", "COPTS")
+
+cc_library(
+    name = "tutorial_battle_controller",
+    srcs = ["TutorialBattleController.cpp"],
+    hdrs = ["TutorialBattleController.hpp"],
+    copts = COPTS,
+    visibility = ["//visibility:public"],
+    deps = [
+        "//src/main/cpp/net/eagle0/common:random_generator",
+        "//src/main/cpp/net/eagle0/shardok/library:game_state_w",
+        "//src/main/cpp/net/eagle0/shardok/library/map:coordinates",
+        "//src/main/cpp/net/eagle0/shardok/library/settings:game_settings",
+        "//src/main/cpp/net/eagle0/shardok/library/util:action_result_flatbuffer_helpers",
+        "//src/main/protobuf/net/eagle0/common:tutorial_battle_config_cc_proto",
+        "//src/main/protobuf/net/eagle0/shardok/common:action_type_cc_proto",
+        "//src/main/protobuf/net/eagle0/shardok/storage:action_result_cc_proto",
+    ],
+)

src/main/cpp/net/eagle0/shardok/library/tutorial/TutorialBattleController.cpp

@@ -0,0 +1,283 @@
+//
+//  TutorialBattleController.cpp
+//  eagle0
+//
+//  Created for tutorial battle system.
+//  Copyright 2025 none. All rights reserved.
+//
+
+#include "TutorialBattleController.hpp"
+
+#include <ranges>
+#include <vector>
+
+#include "src/main/cpp/net/eagle0/shardok/library/util/ActionResultFlatbufferHelpers.hpp"
+
+namespace shardok {
+
+using UnitStatusFB = net::eagle0::shardok::storage::fb::UnitStatus;
+using ActionType = net::eagle0::shardok::common::ActionType;
+using FleeActionProto = net::eagle0::common::FleeAction;
+using ReinforcementsActionProto = net::eagle0::common::ReinforcementsAction;
+using UnitKilledTriggerProto = net::eagle0::common::UnitKilledTrigger;
+
+TutorialBattleController::TutorialBattleController()
+    : enabled_(false),
+      config_(),
+      firedEventIds_() {}
+
+TutorialBattleController::TutorialBattleController(const TutorialBattleConfigProto& protoConfig)
+    : enabled_(protoConfig.enabled()),
+      config_(protoConfig),
+      firedEventIds_() {}
+
+auto TutorialBattleController::CheckAndExecuteEvents(
+        const GameStateW& state,
+        const SettingsGetter& settings,
+        const std::shared_ptr<RandomGenerator>& randomGenerator) -> TutorialEventResults {
+    if (!enabled_) { return {}; }
+
+    TutorialEventResults combined;
+
+    // Check events in config order
+    for (const auto& event : config_.events()) {
+        // Skip already-fired events
+        if (firedEventIds_.contains(event.event_id())) { continue; }
+
+        // Check if trigger condition is met
+        if (EvaluateTrigger(event.trigger(), state)) {
+            // Mark as fired before executing (to prevent re-triggering)
+            firedEventIds_.insert(event.event_id());
+
+            // Execute the action
+            auto eventResults = ExecuteAction(event.action(), state, settings, randomGenerator);
+            combined.actionResults.insert(
+                    combined.actionResults.end(),
+                    eventResults.actionResults.begin(),
+                    eventResults.actionResults.end());
+
+            // Only one reinforcement placement can be pending at a time
+            if (eventResults.reinforcementPlacement.has_value()) {
+                combined.reinforcementPlacement = eventResults.reinforcementPlacement;
+            }
+        }
+    }
+
+    return combined;
+}
+
+auto TutorialBattleController::EvaluateTrigger(
+        const TutorialTriggerProto& trigger,
+        const GameStateW& state) const -> bool {
+    switch (trigger.trigger_type_case()) {
+        case TutorialTriggerProto::kAfterRound: {
+            const int currentRound = state->current_round();
+            return currentRound >= trigger.after_round().round_number();
+        }
+
+        case TutorialTriggerProto::kUnitsLost: {
+            const auto& unitsLost = trigger.units_lost();
+            const int lostCount = CountLostUnits(state, unitsLost.player_id());
+            return lostCount >= unitsLost.threshold();
+        }
+
+        case TutorialTriggerProto::kDamageTaken: {
+            const auto& damageTaken = trigger.damage_taken();
+            const int totalDamage = GetTotalDamageTaken(state, damageTaken.player_id());
+            return totalDamage >= damageTaken.threshold();
+        }
+
+        case TutorialTriggerProto::kUnitKilled: {
+            return IsUnitKilled(state, trigger.unit_killed());
+        }
+
+        case TutorialTriggerProto::TRIGGER_TYPE_NOT_SET:
+        default: return false;
+    }
+}
+
+auto TutorialBattleController::ExecuteAction(
+        const TutorialActionProto& action,
+        const GameStateW& state,
+        [[maybe_unused]] const SettingsGetter& settings,
+        [[maybe_unused]] const std::shared_ptr<RandomGenerator>& randomGenerator) const
+        -> TutorialEventResults {
+    switch (action.action_type_case()) {
+        case TutorialActionProto::kFlee:
+            return {.actionResults = ExecuteFleeAction(action.flee(), state),
+                    .reinforcementPlacement = std::nullopt};
+
+        case TutorialActionProto::kReinforcements:
+            return ExecuteReinforcementsAction(action.reinforcements(), state);
+
+        case TutorialActionProto::ACTION_TYPE_NOT_SET:
+        default: return {};
+    }
+}
+
+auto TutorialBattleController::CountLostUnits(const GameStateW& state, const PlayerId playerId)
+        const -> int {
+    int count = 0;
+    for (const auto* unit : *state->units()) {
+        if (unit->player_id() != playerId) { continue; }
+
+        // Count units that are no longer in battle (destroyed, captured, fled, retreated)
+        const auto status = unit->status();
+        if (status != UnitStatusFB::UnitStatus_NORMAL_UNIT &&
+            status != UnitStatusFB::UnitStatus_RESERVE_UNIT &&
+            status != UnitStatusFB::UnitStatus_NEVER_ENTERED_UNIT &&
+            status != UnitStatusFB::UnitStatus_RESERVED_SLOT &&
+            status != UnitStatusFB::UnitStatus_PENDING_REINFORCEMENT) {
+            count++;
+        }
+    }
+    return count;
+}
+
+auto TutorialBattleController::GetTotalDamageTaken(const GameStateW& state, const PlayerId playerId)
+        const -> int {
+    int totalDamage = 0;
+    for (const auto* unit : *state->units()) {
+        if (unit->player_id() != playerId) { continue; }
+
+        // Calculate damage as difference between initial and current size
+        // Initial sizes are stored in config since flatbuffers don't track starting sizes
+        int initialSize = 0;
+        for (const auto& initial : config_.initial_sizes()) {
+            if (initial.unit_id() == unit->unit_id()) {
+                initialSize = initial.size();
+                break;
+            }
+        }
+        if (initialSize == 0) { continue; }
+
+        const int currentSize = unit->battalion().size();
+        if (initialSize > currentSize) { totalDamage += (initialSize - currentSize); }
+    }
+    return totalDamage;
+}
+
+auto TutorialBattleController::IsUnitKilled(
+        const GameStateW& state,
+        const UnitKilledTriggerProto& trigger) const -> bool {
+    for (const auto* unit : *state->units()) {
+        // Check if this unit matches the identifier
+        bool matches = false;
+
+        switch (trigger.unit_identifier_case()) {
+            case UnitKilledTriggerProto::kUnitId:
+                matches = (unit->unit_id() == trigger.unit_id());
+                break;
+
+            case UnitKilledTriggerProto::kEagleHeroId:
+                if (unit->has_attached_hero()) {
+                    matches = (unit->attached_hero().eagle_hero_id() == trigger.eagle_hero_id());
+                }
+                break;
+
+            case UnitKilledTriggerProto::UNIT_IDENTIFIER_NOT_SET:
+            default: continue;
+        }
+
+        if (!matches) { continue; }
+
+        // Check if the unit is "killed" (destroyed/captured status)
+        const auto status = unit->status();
+        if (status == UnitStatusFB::UnitStatus_DESTROYED_SUMMONED_UNIT ||
+            status == UnitStatusFB::UnitStatus_CAPTURED_UNIT) {
+            return true;
+        }
+    }
+    return false;
+}
+
+auto TutorialBattleController::ExecuteFleeAction(
+        const FleeActionProto& fleeAction,
+        const GameStateW& state) const -> std::vector<ActionResult> {
+    std::vector<ActionResult> results;
+    const PlayerId fleeingPlayerId = fleeAction.player_id();
+
+    // First, create a "tutorial enemy fled" notification
+    ActionResult fleeNotification{};
+    fleeNotification.set_type(ActionType::TUTORIAL_ENEMY_FLED);
+    results.push_back(fleeNotification);
+
+    // Determine which units should flee
+    std::set<int32_t> specificUnitIds(fleeAction.unit_ids().begin(), fleeAction.unit_ids().end());
+    std::set<int32_t> specificHeroIds(
+            fleeAction.eagle_hero_ids().begin(),
+            fleeAction.eagle_hero_ids().end());
+    const bool fleeAllUnits = specificUnitIds.empty() && specificHeroIds.empty();
+
+    // Find all matching units that are still active and make them flee
+    for (const auto* unit : *state->units()) {
+        if (unit->player_id() != fleeingPlayerId) { continue; }
+        if (unit->status() != UnitStatusFB::UnitStatus_NORMAL_UNIT) { continue; }
+
+        // Check if this unit should flee
+        if (!fleeAllUnits) {
+            const bool matchesUnitId = specificUnitIds.contains(unit->unit_id());
+            const bool matchesHeroId =
+                    unit->has_attached_hero() &&
+                    specificHeroIds.contains(unit->attached_hero().eagle_hero_id());
+            if (!matchesUnitId && !matchesHeroId) { continue; }
+        }
+
+        // Create flee result for this unit (100% success - guaranteed flee)
+        ActionResult fleeResult{};
+        fleeResult.set_type(ActionType::FLED);
+        fleeResult.mutable_player()->set_value(fleeingPlayerId);
+        fleeResult.mutable_actor()->set_value(unit->unit_id());
+
+        auto* resolvedUnit = fleeResult.add_resolved_units();
+        AddUnitToResolved(*resolvedUnit, *unit);
+        resolvedUnit->set_status(net::eagle0::shardok::storage::ResolvedUnit_UnitStatus_FLED_UNIT);
+
+        results.push_back(fleeResult);
+    }
+
+    return results;
+}
+
+auto TutorialBattleController::ExecuteReinforcementsAction(
+        const ReinforcementsActionProto& reinforcementsAction,
+        const GameStateW& state) const -> TutorialEventResults {
+    TutorialEventResults eventResults;
+
+    if (reinforcementsAction.units().empty()) { return eventResults; }
+
+    const PlayerId playerId = reinforcementsAction.player_id();
+
+    // Look up starting positions from the hex map's attacker starting positions
+    using Coords = net::eagle0::shardok::storage::fb::Coords;
+    std::vector<Coords> availablePositions;
+    const int startingPosGroupIndex = reinforcementsAction.attacker_starting_position_index();
+    const auto* attackerPositions = state->hex_map()->attacker_starting_positions();
+    if (startingPosGroupIndex >= 0 &&
+        startingPosGroupIndex < static_cast<int>(attackerPositions->size())) {
+        for (const auto* pos : *attackerPositions->Get(startingPosGroupIndex)->positions()) {
+            if (!state.GetOccupant(*pos)) { availablePositions.push_back(*pos); }
+        }
+    }
+
+    // Place PENDING_REINFORCEMENT units directly at available positions as NORMAL_UNIT
+    ActionResult reinforcementsResult{};
+    reinforcementsResult.set_type(ActionType::TUTORIAL_REINFORCEMENTS_ARRIVED);
+    reinforcementsResult.mutable_player()->set_value(playerId);
+
+    size_t posIndex = 0;
+    for (const auto* unit : *state->units()) {
+        if (unit->status() != UnitStatusFB::UnitStatus_PENDING_REINFORCEMENT) { continue; }
+        if (posIndex >= availablePositions.size()) { break; }
+
+        net::eagle0::shardok::storage::fb::Unit changedUnit = *unit;
+        changedUnit.mutate_status(UnitStatusFB::UnitStatus_NORMAL_UNIT);
+        changedUnit.mutable_location() = availablePositions[posIndex++];
+        AddChangedUnit(reinforcementsResult, changedUnit);
+    }
+
+    eventResults.actionResults.push_back(reinforcementsResult);
+    return eventResults;
+}
+
+}  // namespace shardok

src/main/cpp/net/eagle0/shardok/library/tutorial/TutorialBattleController.hpp

@@ -0,0 +1,116 @@
+//
+//  TutorialBattleController.hpp
+//  eagle0
+//
+//  Created for tutorial battle system.
+//  Copyright 2025 none. All rights reserved.
+//
+
+#ifndef TutorialBattleController_hpp
+#define TutorialBattleController_hpp
+
+#include <optional>
+#include <set>
+#include <string>
+#include <vector>
+
+#include "src/main/cpp/net/eagle0/common/RandomGenerator.hpp"
+#include "src/main/cpp/net/eagle0/shardok/library/GameStateW.hpp"
+#include "src/main/cpp/net/eagle0/shardok/library/map/Coordinates.hpp"
+#include "src/main/cpp/net/eagle0/shardok/library/settings/GameSettings.hpp"
+#include "src/main/protobuf/net/eagle0/common/tutorial_battle_config.pb.h"
+#include "src/main/protobuf/net/eagle0/shardok/storage/action_result.pb.h"
+
+namespace shardok {
+
+using ActionResult = net::eagle0::shardok::storage::ActionResult;
+using TutorialBattleConfigProto = net::eagle0::common::TutorialBattleConfig;
+using TutorialEventProto = net::eagle0::common::TutorialEvent;
+using TutorialTriggerProto = net::eagle0::common::TutorialTrigger;
+using TutorialActionProto = net::eagle0::common::TutorialAction;
+
+/// Info about a pending reinforcement placement phase.
+struct ReinforcementPlacementInfo {
+    PlayerId playerId;
+    std::vector<Coords> startingPositions;
+};
+
+/// Results from tutorial event processing, including action results and any pending
+/// reinforcement placement.
+struct TutorialEventResults {
+    std::vector<ActionResult> actionResults;
+    std::optional<ReinforcementPlacementInfo> reinforcementPlacement;
+};
+
+/// Controller for scripted tutorial battles with event-driven triggers and actions.
+/// Events are checked at the end of each round and fire in config order.
+/// Each event fires at most once (tracked by event_id).
+class TutorialBattleController {
+public:
+    /// Creates a disabled controller.
+    TutorialBattleController();
+
+    /// Creates a controller from proto configuration.
+    explicit TutorialBattleController(const TutorialBattleConfigProto& protoConfig);
+
+    /// Returns true if the controller is enabled for this battle.
+    [[nodiscard]] auto IsEnabled() const -> bool { return enabled_; }
+
+    /// Check all events at end of round, return actions for triggered events.
+    /// Events fire in config order - first triggered event executes, then next.
+    /// Each event fires at most once.
+    [[nodiscard]] auto CheckAndExecuteEvents(
+            const GameStateW& state,
+            const SettingsGetter& settings,
+            const std::shared_ptr<RandomGenerator>& randomGenerator) -> TutorialEventResults;
+
+    /// Gets the set of fired event IDs (for testing/debugging).
+    [[nodiscard]] auto GetFiredEventIds() const -> const std::set<std::string>& {
+        return firedEventIds_;
+    }
+
+private:
+    bool enabled_ = false;
+    TutorialBattleConfigProto config_;
+    std::set<std::string> firedEventIds_;  // Track which events have fired
+
+    /// Evaluates whether a trigger condition is met.
+    [[nodiscard]] auto EvaluateTrigger(const TutorialTriggerProto& trigger, const GameStateW& state)
+            const -> bool;
+
+    /// Executes an action and returns the resulting action results.
+    [[nodiscard]] auto ExecuteAction(
+            const TutorialActionProto& action,
+            const GameStateW& state,
+            const SettingsGetter& settings,
+            const std::shared_ptr<RandomGenerator>& randomGenerator) const -> TutorialEventResults;
+
+    // Helper methods for trigger evaluation
+
+    /// Counts units lost (destroyed, captured, fled, retreated) for a player.
+    [[nodiscard]] auto CountLostUnits(const GameStateW& state, PlayerId playerId) const -> int;
+
+    /// Gets total damage taken (cumulative size reduction) for a player.
+    [[nodiscard]] auto GetTotalDamageTaken(const GameStateW& state, PlayerId playerId) const -> int;
+
+    /// Checks if a specific unit has been killed.
+    [[nodiscard]] auto IsUnitKilled(
+            const GameStateW& state,
+            const net::eagle0::common::UnitKilledTrigger& trigger) const -> bool;
+
+    // Helper methods for action execution
+
+    /// Executes a flee action for specified units.
+    [[nodiscard]] auto ExecuteFleeAction(
+            const net::eagle0::common::FleeAction& fleeAction,
+            const GameStateW& state) const -> std::vector<ActionResult>;
+
+    /// Executes a reinforcements action, placing units directly at available starting positions.
+    [[nodiscard]] auto ExecuteReinforcementsAction(
+            const net::eagle0::common::ReinforcementsAction& reinforcementsAction,
+            const GameStateW& state) const -> TutorialEventResults;
+};
+
+}  // namespace shardok
+
+#endif /* TutorialBattleController_hpp */

src/main/cpp/net/eagle0/shardok/library/unit/Unit.cpp

@@ -331,7 +331,8 @@ auto PlacedUnitsForPlayer(const Units *units, const PlayerId pid)
     std::map<UnitId, const Unit *> placedUnits{};
     for (const Unit *unit : *units) {
         if (unit->player_id() == pid &&
-            unit->status() != net::eagle0::shardok::storage::fb::UnitStatus_RESERVE_UNIT)
+            unit->status() != net::eagle0::shardok::storage::fb::UnitStatus_RESERVE_UNIT &&
+            unit->status() != net::eagle0::shardok::storage::fb::UnitStatus_PENDING_REINFORCEMENT)
             placedUnits[unit->unit_id()] = unit;
     }
 

src/main/cpp/net/eagle0/shardok/library/util/GameStateDumper.cpp

@@ -73,6 +73,9 @@ void DumpGameStateToFile(const GameStateW& gameState, const std::string& gameId)
                 case net::eagle0::shardok::storage::fb::UnitStatus_RETREATED_UNIT:
                     out << "RETREATED_UNIT\n";
                     break;
+                case net::eagle0::shardok::storage::fb::UnitStatus_PENDING_REINFORCEMENT:
+                    out << "PENDING_REINFORCEMENT\n";
+                    break;
                 default: out << "OTHER (" << (int)unit->status() << ")\n";
             }
             out << "  Remaining Action Points: " << (int)unit->remaining_action_points() << "\n";

src/main/cpp/net/eagle0/shardok/library/view_filters/GameStateFilter.cpp

@@ -49,7 +49,8 @@ auto GameStateFilteredForPlayer(
             case net::eagle0::shardok::storage::fb::UnitStatus_FLED_UNIT:
             case net::eagle0::shardok::storage::fb::UnitStatus_RETREATED_UNIT:
             case net::eagle0::shardok::storage::fb::UnitStatus_OUTLAWED_UNIT:
-            case net::eagle0::shardok::storage::fb::UnitStatus_RESERVED_SLOT: break;
+            case net::eagle0::shardok::storage::fb::UnitStatus_RESERVED_SLOT:
+            case net::eagle0::shardok::storage::fb::UnitStatus_PENDING_REINFORCEMENT: break;
 
             case net::eagle0::shardok::storage::fb::UnitStatus_UNKNOWN_UNIT:
                 throw ShardokInternalErrorException("Unknown unit status");
@@ -100,6 +101,7 @@ auto GameStateFilteredForPlayer(
                 case net::eagle0::shardok::storage::fb::UnitStatus_RETREATED_UNIT:
                 case net::eagle0::shardok::storage::fb::UnitStatus_OUTLAWED_UNIT:
                 case net::eagle0::shardok::storage::fb::UnitStatus_RESERVED_SLOT:
+                case net::eagle0::shardok::storage::fb::UnitStatus_PENDING_REINFORCEMENT:
                 case net::eagle0::shardok::storage::fb::UnitStatus_UNKNOWN_UNIT: break;
             }
         }

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

@@ -12,6 +12,7 @@ cc_library(
     deps = [
         ":server_configuration",
         "//src/main/cpp/net/eagle0/common:tsv_parser",
+        "//src/main/cpp/net/eagle0/common:unit_conversions",
         "//src/main/cpp/net/eagle0/shardok/ai:shardok_ai_client",
         "//src/main/cpp/net/eagle0/shardok/controller",
         "//src/main/cpp/net/eagle0/shardok/library:engine",
@@ -19,6 +20,7 @@ cc_library(
         "//src/main/cpp/net/eagle0/shardok/library/settings_loader",
         "//src/main/cpp/net/eagle0/shardok/util:battalion_type_registrar",
         "//src/main/cpp/net/eagle0/shardok/util:map_loader",
+        "//src/main/protobuf/net/eagle0/common:tutorial_battle_config_cc_proto",
         "//src/main/protobuf/net/eagle0/common:victory_condition_cc_proto",
     ],
 )

src/main/cpp/net/eagle0/shardok/server/EagleInterfaceGrpcServer.cpp

@@ -193,6 +193,7 @@ void EagleInterfaceImpl::StartGame(const NewGameRequest &request) {
             mapName,
             customMapBytes,
             month,
+            request.tutorial_battle_config(),
             request.SerializeAsString());
 }
 
@@ -221,20 +222,14 @@ auto EagleInterfaceImpl::PostCommand(
                 request->game_setup_info().known_result_count(),
                 response);
     } catch (ShardokClientErrorException &e) {
-        std::cerr << "Bad request from client!" << std::endl;
-        std::cerr << "Exception: " << e.what();
-
-        throw e;
+        std::cerr << "Bad request from client: " << e.what() << std::endl;
+        return Status(StatusCode::INVALID_ARGUMENT, e.what());
     } catch (ShardokInternalErrorException &e) {
-        std::cerr << "ShardokInternalErrorException thrown!" << std::endl;
-        std::cerr << "Exception: " << e.what();
-
-        throw e;
+        std::cerr << "Internal error: " << e.what() << std::endl;
+        return Status(StatusCode::INTERNAL, e.what());
     } catch (std::exception &e) {
-        std::cerr << "Unknown exception in client->PostCommand" << std::endl;
-        std::cerr << "Exception: " << e.what();
-
-        throw e;
+        std::cerr << "Unknown exception: " << e.what() << std::endl;
+        return Status(StatusCode::INTERNAL, e.what());
     }
 
     return Status::OK;
@@ -273,20 +268,14 @@ auto EagleInterfaceImpl::PostPlacementCommands(
                 request->game_setup_info().known_result_count(),
                 response);
     } catch (ShardokClientErrorException &e) {
-        std::cerr << "Bad request from client!" << std::endl;
-        std::cerr << "Exception: " << e.what();
-
-        throw e;
+        std::cerr << "Bad request from client: " << e.what() << std::endl;
+        return Status(StatusCode::INVALID_ARGUMENT, e.what());
     } catch (ShardokInternalErrorException &e) {
-        std::cerr << "ShardokInternalErrorException thrown!" << std::endl;
-        std::cerr << "Exception: " << e.what();
-
-        throw e;
+        std::cerr << "Internal error: " << e.what() << std::endl;
+        return Status(StatusCode::INTERNAL, e.what());
     } catch (std::exception &e) {
-        std::cerr << "Unknown exception in client->PostCommand" << std::endl;
-        std::cerr << "Exception: " << e.what();
-
-        throw e;
+        std::cerr << "Unknown exception: " << e.what() << std::endl;
+        return Status(StatusCode::INTERNAL, e.what());
     }
 
     return Status::OK;