Merge pull request 'Promote development → master: Erudit blank star + dictionary v1.3.0 pin' (#111 ) from development into master

Merge pull request 'chore(deploy): pin dictionary seed to v1.3.0' (#110 ) from feature/pin-dict-v130 into development
refactor(deploy): make DICT_VERSION a required build arg (single-sourced)
2026-06-22 13:12:01 +00:00 · 2026-06-22 13:06:26 +00:00 · 2026-06-22 15:03:07 +02:00 · 2026-06-22 14:45:52 +02:00 · 2026-06-22 11:06:22 +00:00 · 2026-06-22 12:55:06 +02:00
72 changed files with 1925 additions and 2480 deletions
@@ -31,7 +31,7 @@ on:
 # unit/integration jobs inherit it. The deploy job overrides it per contour with
 # vars.TEST_DICT_VERSION (the seed for a fresh volume), see deploy/README.md.
 env:
-  DICT_VERSION: v1.2.1
+  DICT_VERSION: v1.3.0
 jobs:
  # changes detects which areas a PR/push touched, so the test jobs can skip when
@@ -301,8 +301,11 @@ jobs:
          # App version for the About screen: the git tag if present, else the short SHA
          # (the test checkout is shallow/untagged, so this is the SHA here — fine).
          export APP_VERSION="$(git -C "$GITHUB_WORKSPACE" describe --tags --always 2>/dev/null || echo dev)"
-          docker compose --ansi never build --progress plain
+          # The telegram-local profile brings the bot + its VPN sidecar; prod runs the
-          docker compose --ansi never up -d --remove-orphans
+          # bot on its own host instead (deploy/docker-compose.bot.yml), and the prod
          # main host omits both. Without the profile they would not start here.
          docker compose --ansi never --profile telegram-local build --progress plain
          docker compose --ansi never --profile telegram-local up -d --remove-orphans
          # The config-only services bind-mount the reseeded config dir. A plain `up -d`
          # leaves them on the previous bind mount (the dir was rm'd + recreated), so a
          # changed Caddyfile or Grafana dashboard is ignored — force-recreate them to
@@ -0,0 +1,266 @@
 # Manual production rollout. Runs ONLY from master, ONLY on workflow_dispatch with
 # confirm=deploy (development->master is merged + green first; this is the separate,
 # deliberate prod step). Visible sequential jobs from most to least significant:
 #   build -> deploy-main -> deploy-bot -> verify
 # The per-service rolling (postgres->backend->gateway->landing->validator->caddy),
 # health-gating and auto-rollback live in deploy/prod-deploy.sh on the main host and
 # show in the deploy-main log. Manual post-deploy rollback is prod-rollback.yaml.
 # See deploy/README.md (prod runbook).
 name: prod-deploy
 run-name: "prod deploy ${{ github.sha }}"
 on:
  workflow_dispatch:
    inputs:
      confirm:
        description: 'Type "deploy" to confirm a production rollout from master.'
        required: true
        default: ""
 permissions:
  contents: read
 env:
  NO_COLOR: "1"
  DOCKER_CLI_HINTS: "false"
  REGISTRY: docker.iliadenisov.ru/developer
 jobs:
  build:
    if: ${{ github.ref == 'refs/heads/master' && inputs.confirm == 'deploy' }}
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
    outputs:
      tag: ${{ steps.ver.outputs.tag }}
    env:
      PROD_REGISTRY_USER: ${{ vars.PROD_REGISTRY_USER }}
      PROD_REGISTRY_PASSWORD: ${{ secrets.PROD_REGISTRY_PASSWORD }}
      VITE_TELEGRAM_BOT_ID: ${{ vars.PROD_VITE_TELEGRAM_BOT_ID }}
      VITE_TELEGRAM_LINK: ${{ vars.PROD_VITE_TELEGRAM_LINK }}
      VITE_TELEGRAM_GAME_CHANNEL_NAME: ${{ vars.PROD_VITE_TELEGRAM_GAME_CHANNEL_NAME }}
      VITE_GATEWAY_URL: ${{ vars.PROD_VITE_GATEWAY_URL }}
      POSTGRES_PASSWORD: ${{ secrets.PROD_POSTGRES_PASSWORD }}
      GM_BASICAUTH_HASH: ${{ secrets.PROD_GM_BASICAUTH_HASH }}
      TELEGRAM_MINIAPP_URL: ${{ vars.PROD_TELEGRAM_MINIAPP_URL }}
      DICT_VERSION: ${{ vars.PROD_DICT_VERSION }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Compute version tag
        id: ver
        run: echo "tag=$(git describe --tags --always)" >> "$GITHUB_OUTPUT"
      - name: Registry login
        run: echo "$PROD_REGISTRY_PASSWORD" | docker login "${REGISTRY%%/*}" -u "$PROD_REGISTRY_USER" --password-stdin
      - name: Build and push images
        working-directory: deploy
        run: |
          export TAG="${{ steps.ver.outputs.tag }}" APP_VERSION="${{ steps.ver.outputs.tag }}" SCRABBLE_CONFIG_DIR=.
          # The four main-stack images via compose (reuses the build args, incl. VERSION);
          # the bot separately, since it is profiled out of the prod compose.
          docker compose -f docker-compose.yml -f docker-compose.prod.yml build
          docker compose -f docker-compose.yml -f docker-compose.prod.yml push backend gateway landing validator
          docker build -f ../platform/telegram/Dockerfile --target bot --build-arg VERSION="$TAG" -t "$REGISTRY/scrabble-telegram-bot:$TAG" ..
          docker push "$REGISTRY/scrabble-telegram-bot:$TAG"
  deploy-main:
    needs: build
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
    env:
      TAG: ${{ needs.build.outputs.tag }}
      PROD_REGISTRY_USER: ${{ vars.PROD_REGISTRY_USER }}
      PROD_REGISTRY_PASSWORD: ${{ secrets.PROD_REGISTRY_PASSWORD }}
      PROD_SSH_KEY: ${{ secrets.PROD_SSH_KEY }}
      PROD_SSH_KNOWN_HOSTS: ${{ secrets.PROD_SSH_KNOWN_HOSTS }}
      MAIN_HOST: ${{ vars.PROD_MAIN_HOST }}
      POSTGRES_PASSWORD: ${{ secrets.PROD_POSTGRES_PASSWORD }}
      GM_BASICAUTH_HASH: ${{ secrets.PROD_GM_BASICAUTH_HASH }}
      GRAFANA_ADMIN_PASSWORD: ${{ secrets.PROD_GRAFANA_ADMIN_PASSWORD }}
      TELEGRAM_BOT_TOKEN: ${{ secrets.PROD_TELEGRAM_BOT_TOKEN }}
      PROD_BOTLINK_CA: ${{ secrets.PROD_BOTLINK_CA }}
      PROD_BOTLINK_GATEWAY_CERT: ${{ secrets.PROD_BOTLINK_GATEWAY_CERT }}
      PROD_BOTLINK_GATEWAY_KEY: ${{ secrets.PROD_BOTLINK_GATEWAY_KEY }}
      GM_BASICAUTH_USER: ${{ vars.PROD_GM_BASICAUTH_USER }}
      GRAFANA_ROOT_URL: ${{ vars.PROD_GRAFANA_ROOT_URL }}
      CADDY_SITE_ADDRESS: ${{ vars.PROD_CADDY_SITE_ADDRESS }}
      LOG_LEVEL: ${{ vars.PROD_LOG_LEVEL }}
      DICT_VERSION: ${{ vars.PROD_DICT_VERSION }}
      POSTGRES_DB: ${{ vars.PROD_POSTGRES_DB }}
      POSTGRES_USER: ${{ vars.PROD_POSTGRES_USER }}
      TELEGRAM_MINIAPP_URL: ${{ vars.PROD_TELEGRAM_MINIAPP_URL }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Set up SSH
        run: |
          mkdir -p ~/.ssh && chmod 700 ~/.ssh
          printf '%s\n' "$PROD_SSH_KEY" > ~/.ssh/id_deploy && chmod 600 ~/.ssh/id_deploy
          printf '%s\n' "$PROD_SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
      - name: Determine previous tag and migration
        run: |
          ssh_main() { ssh -i ~/.ssh/id_deploy -o BatchMode=yes "deploy@$MAIN_HOST" "$@"; }
          PREV_TAG="$(ssh_main 'cat /opt/scrabble/DEPLOYED_TAG 2>/dev/null || echo none')"
          MIGRATION=0
          if [ "$PREV_TAG" != none ]; then
            if ! git cat-file -e "$PREV_TAG^{commit}" 2>/dev/null; then
              MIGRATION=1
            elif git diff --name-only "$PREV_TAG..$TAG" -- backend/internal/postgres/migrations/ | grep -q .; then
              MIGRATION=1
            fi
          fi
          { echo "PREV_TAG=$PREV_TAG"; echo "MIGRATION=$MIGRATION"; } >> "$GITHUB_ENV"
          echo "prev=$PREV_TAG migration=$MIGRATION"
      - name: Render main env + certs
        run: |
          umask 077
          mkdir -p stage/certs-main
          cat > stage/env.sh <<EOF
          export REGISTRY='$REGISTRY'
          export SCRABBLE_CONFIG_DIR='/opt/scrabble'
          export POSTGRES_DB='${POSTGRES_DB:-scrabble}'
          export POSTGRES_USER='${POSTGRES_USER:-scrabble}'
          export POSTGRES_PASSWORD='$POSTGRES_PASSWORD'
          export GM_BASICAUTH_USER='${GM_BASICAUTH_USER:-gm}'
          export GM_BASICAUTH_HASH='$GM_BASICAUTH_HASH'
          export GRAFANA_ADMIN_PASSWORD='$GRAFANA_ADMIN_PASSWORD'
          export GRAFANA_ROOT_URL='$GRAFANA_ROOT_URL'
          export CADDY_SITE_ADDRESS='$CADDY_SITE_ADDRESS'
          export LOG_LEVEL='${LOG_LEVEL:-info}'
          export DICT_VERSION='$DICT_VERSION'
          export APP_VERSION='$TAG'
          export TELEGRAM_BOT_TOKEN='$TELEGRAM_BOT_TOKEN'
          export TELEGRAM_MINIAPP_URL='$TELEGRAM_MINIAPP_URL'
          export GATEWAY_ABUSE_BAN_ENABLED='true'
          EOF
          printf '%s\n' "$PROD_BOTLINK_CA"           > stage/certs-main/ca.crt
          printf '%s\n' "$PROD_BOTLINK_GATEWAY_CERT" > stage/certs-main/gateway.crt
          printf '%s\n' "$PROD_BOTLINK_GATEWAY_KEY"  > stage/certs-main/gateway.key
          chmod 644 stage/certs-main/*
      - name: Deploy the main host
        run: |
          ssh_main() { ssh -i ~/.ssh/id_deploy -o BatchMode=yes "deploy@$MAIN_HOST" "$@"; }
          ssh_main 'mkdir -p /opt/scrabble/compose'
          tar -C deploy -czf - docker-compose.yml docker-compose.prod.yml prod-deploy.sh \
            | ssh_main 'tar -C /opt/scrabble/compose -xzf -'
          tar -C deploy -czf - caddy otelcol prometheus tempo grafana \
            | ssh_main 'tar -C /opt/scrabble -xzf -'
          tar -C stage -czf - certs-main \
            | ssh_main 'rm -rf /opt/scrabble/certs && mkdir -p /opt/scrabble/certs && tar -C /opt/scrabble/certs --strip-components=1 -xzf -'
          scp -i ~/.ssh/id_deploy -o BatchMode=yes stage/env.sh "deploy@$MAIN_HOST:/opt/scrabble/env.sh"
          echo "$PROD_REGISTRY_PASSWORD" | ssh_main "docker login ${REGISTRY%%/*} -u $PROD_REGISTRY_USER --password-stdin"
          ssh_main "TAG='$TAG' PREV_TAG='$PREV_TAG' MIGRATION='$MIGRATION' bash /opt/scrabble/compose/prod-deploy.sh"
  deploy-bot:
    needs: [build, deploy-main]
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
    env:
      TAG: ${{ needs.build.outputs.tag }}
      PROD_REGISTRY_USER: ${{ vars.PROD_REGISTRY_USER }}
      PROD_REGISTRY_PASSWORD: ${{ secrets.PROD_REGISTRY_PASSWORD }}
      PROD_SSH_KEY: ${{ secrets.PROD_SSH_KEY }}
      PROD_SSH_KNOWN_HOSTS: ${{ secrets.PROD_SSH_KNOWN_HOSTS }}
      TG_HOST: ${{ vars.PROD_TG_HOST }}
      MAIN_HOST: ${{ vars.PROD_MAIN_HOST }}
      TELEGRAM_BOT_TOKEN: ${{ secrets.PROD_TELEGRAM_BOT_TOKEN }}
      TELEGRAM_PROMO_BOT_TOKEN: ${{ secrets.PROD_TELEGRAM_PROMO_BOT_TOKEN }}
      PROD_BOTLINK_CA: ${{ secrets.PROD_BOTLINK_CA }}
      PROD_BOTLINK_BOT_CERT: ${{ secrets.PROD_BOTLINK_BOT_CERT }}
      PROD_BOTLINK_BOT_KEY: ${{ secrets.PROD_BOTLINK_BOT_KEY }}
      LOG_LEVEL: ${{ vars.PROD_LOG_LEVEL }}
      TELEGRAM_MINIAPP_URL: ${{ vars.PROD_TELEGRAM_MINIAPP_URL }}
      TELEGRAM_GAME_CHANNEL_ID: ${{ vars.PROD_TELEGRAM_GAME_CHANNEL_ID }}
      TELEGRAM_CHAT_ID: ${{ vars.PROD_TELEGRAM_CHAT_ID }}
      TELEGRAM_BOT_USERNAME: ${{ vars.PROD_TELEGRAM_BOT_USERNAME }}
      TELEGRAM_BOT_LINK: ${{ vars.PROD_VITE_TELEGRAM_LINK }}
    steps:
      - uses: actions/checkout@v4
      - name: Set up SSH
        run: |
          mkdir -p ~/.ssh && chmod 700 ~/.ssh
          printf '%s\n' "$PROD_SSH_KEY" > ~/.ssh/id_deploy && chmod 600 ~/.ssh/id_deploy
          printf '%s\n' "$PROD_SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
      - name: Render bot env + certs
        run: |
          umask 077
          mkdir -p stage/certs-bot
          cat > stage/env.bot.sh <<EOF
          export SCRABBLE_CONFIG_DIR='/opt/scrabble'
          export BOT_IMAGE='$REGISTRY/scrabble-telegram-bot:$TAG'
          export BOTLINK_GATEWAY_ADDR='$MAIN_HOST:9443'
          export TELEGRAM_BOT_TOKEN='$TELEGRAM_BOT_TOKEN'
          export TELEGRAM_MINIAPP_URL='$TELEGRAM_MINIAPP_URL'
          export TELEGRAM_GAME_CHANNEL_ID='$TELEGRAM_GAME_CHANNEL_ID'
          export TELEGRAM_CHAT_ID='$TELEGRAM_CHAT_ID'
          export TELEGRAM_PROMO_BOT_TOKEN='$TELEGRAM_PROMO_BOT_TOKEN'
          export TELEGRAM_BOT_USERNAME='$TELEGRAM_BOT_USERNAME'
          export TELEGRAM_BOT_LINK='$TELEGRAM_BOT_LINK'
          export LOG_LEVEL='${LOG_LEVEL:-info}'
          EOF
          printf '%s\n' "$PROD_BOTLINK_CA"       > stage/certs-bot/ca.crt
          printf '%s\n' "$PROD_BOTLINK_BOT_CERT" > stage/certs-bot/bot.crt
          printf '%s\n' "$PROD_BOTLINK_BOT_KEY"  > stage/certs-bot/bot.key
          chmod 644 stage/certs-bot/*
      - name: Deploy the bot host
        run: |
          ssh_tg() { ssh -i ~/.ssh/id_deploy -o BatchMode=yes "deploy@$TG_HOST" "$@"; }
          ssh_tg 'mkdir -p /opt/scrabble/compose'
          tar -C deploy -czf - docker-compose.bot.yml | ssh_tg 'tar -C /opt/scrabble/compose -xzf -'
          tar -C stage -czf - certs-bot \
            | ssh_tg 'rm -rf /opt/scrabble/certs && mkdir -p /opt/scrabble/certs && tar -C /opt/scrabble/certs --strip-components=1 -xzf -'
          scp -i ~/.ssh/id_deploy -o BatchMode=yes stage/env.bot.sh "deploy@$TG_HOST:/opt/scrabble/env.bot.sh"
          echo "$PROD_REGISTRY_PASSWORD" | ssh_tg "docker login ${REGISTRY%%/*} -u $PROD_REGISTRY_USER --password-stdin"
          ssh_tg 'set -a; . /opt/scrabble/env.bot.sh; set +a; cd /opt/scrabble/compose;
            docker compose -f docker-compose.bot.yml pull;
            docker compose -f docker-compose.bot.yml up -d'
          ssh_tg 'for i in $(seq 1 20); do
              s=$(docker inspect -f "{{.State.Status}}" scrabble-telegram-bot 2>/dev/null || echo missing)
              r=$(docker inspect -f "{{.State.Restarting}}" scrabble-telegram-bot 2>/dev/null || echo true)
              if [ "$s" = running ] && [ "$r" = false ]; then
                c1=$(docker inspect -f "{{.RestartCount}}" scrabble-telegram-bot); sleep 5
                c2=$(docker inspect -f "{{.RestartCount}}" scrabble-telegram-bot)
                [ "$c1" = "$c2" ] && { echo "bot healthy"; exit 0; }
              fi
              sleep 3
            done
            echo "bot not healthy:"; docker logs --tail 80 scrabble-telegram-bot; exit 1'
  verify:
    needs: [deploy-main, deploy-bot]
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
    env:
      PROD_SSH_KEY: ${{ secrets.PROD_SSH_KEY }}
      PROD_SSH_KNOWN_HOSTS: ${{ secrets.PROD_SSH_KNOWN_HOSTS }}
      MAIN_HOST: ${{ vars.PROD_MAIN_HOST }}
      CADDY_SITE_ADDRESS: ${{ vars.PROD_CADDY_SITE_ADDRESS }}
    steps:
      - name: Set up SSH
        run: |
          mkdir -p ~/.ssh && chmod 700 ~/.ssh
          printf '%s\n' "$PROD_SSH_KEY" > ~/.ssh/id_deploy && chmod 600 ~/.ssh/id_deploy
          printf '%s\n' "$PROD_SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
      - name: Verify the public site
        run: |
          domain="${CADDY_SITE_ADDRESS%% *}"
          ssh -i ~/.ssh/id_deploy -o BatchMode=yes "deploy@$MAIN_HOST" "for i in \$(seq 1 20); do
              if curl -fsS -k --resolve $domain:443:127.0.0.1 https://$domain/ -o /dev/null &&
                 curl -fsS -k --resolve $domain:443:127.0.0.1 https://$domain/app/ -o /dev/null &&
                 docker run --rm --network scrabble-internal alpine:3.20 wget -q -T 5 -O /dev/null http://backend:8080/readyz; then
                echo 'public site + /app/ + backend healthy'; exit 0
              fi
              sleep 5
            done
            echo 'public verify failed; recent caddy + gateway + backend logs:'
            docker logs --tail 40 scrabble-caddy; docker logs --tail 40 scrabble-gateway; docker logs --tail 40 scrabble-backend
            exit 1"
@@ -0,0 +1,223 @@
 # Manual production rollback. Runs ONLY from master, ONLY on workflow_dispatch with
 # confirm=rollback. Re-deploys an already-published image tag (no build): leave
 # target_version blank to roll back to the previously deployed version (read from the
 # main host), or set it to a specific release tag from the Releases page. The
 # re-deploy is the same rolling, health-gated path as prod-deploy (TAG=target,
 # MIGRATION=0 — rollback is image-only and never migrates the DB; image rollback is
 # DB-safe under the expand-contract rule). See deploy/README.md (prod runbook).
 name: prod-rollback
 run-name: "prod rollback ${{ inputs.target_version || 'previous' }}"
 on:
  workflow_dispatch:
    inputs:
      confirm:
        description: 'Type "rollback" to confirm a production rollback.'
        required: true
        default: ""
      target_version:
        description: "Release tag to roll back to (blank = the previous deployed version)."
        required: false
        default: ""
 permissions:
  contents: read
 env:
  NO_COLOR: "1"
  DOCKER_CLI_HINTS: "false"
  REGISTRY: docker.iliadenisov.ru/developer
 jobs:
  rollback-main:
    if: ${{ github.ref == 'refs/heads/master' && inputs.confirm == 'rollback' }}
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
    outputs:
      target: ${{ steps.resolve.outputs.target }}
    env:
      PROD_REGISTRY_USER: ${{ vars.PROD_REGISTRY_USER }}
      PROD_REGISTRY_PASSWORD: ${{ secrets.PROD_REGISTRY_PASSWORD }}
      PROD_SSH_KEY: ${{ secrets.PROD_SSH_KEY }}
      PROD_SSH_KNOWN_HOSTS: ${{ secrets.PROD_SSH_KNOWN_HOSTS }}
      MAIN_HOST: ${{ vars.PROD_MAIN_HOST }}
      POSTGRES_PASSWORD: ${{ secrets.PROD_POSTGRES_PASSWORD }}
      GM_BASICAUTH_HASH: ${{ secrets.PROD_GM_BASICAUTH_HASH }}
      GRAFANA_ADMIN_PASSWORD: ${{ secrets.PROD_GRAFANA_ADMIN_PASSWORD }}
      TELEGRAM_BOT_TOKEN: ${{ secrets.PROD_TELEGRAM_BOT_TOKEN }}
      PROD_BOTLINK_CA: ${{ secrets.PROD_BOTLINK_CA }}
      PROD_BOTLINK_GATEWAY_CERT: ${{ secrets.PROD_BOTLINK_GATEWAY_CERT }}
      PROD_BOTLINK_GATEWAY_KEY: ${{ secrets.PROD_BOTLINK_GATEWAY_KEY }}
      GM_BASICAUTH_USER: ${{ vars.PROD_GM_BASICAUTH_USER }}
      GRAFANA_ROOT_URL: ${{ vars.PROD_GRAFANA_ROOT_URL }}
      CADDY_SITE_ADDRESS: ${{ vars.PROD_CADDY_SITE_ADDRESS }}
      LOG_LEVEL: ${{ vars.PROD_LOG_LEVEL }}
      DICT_VERSION: ${{ vars.PROD_DICT_VERSION }}
      POSTGRES_DB: ${{ vars.PROD_POSTGRES_DB }}
      POSTGRES_USER: ${{ vars.PROD_POSTGRES_USER }}
      TELEGRAM_MINIAPP_URL: ${{ vars.PROD_TELEGRAM_MINIAPP_URL }}
      INPUT_TARGET: ${{ inputs.target_version }}
    steps:
      - uses: actions/checkout@v4
      - name: Set up SSH
        run: |
          mkdir -p ~/.ssh && chmod 700 ~/.ssh
          printf '%s\n' "$PROD_SSH_KEY" > ~/.ssh/id_deploy && chmod 600 ~/.ssh/id_deploy
          printf '%s\n' "$PROD_SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
      - name: Resolve rollback target
        id: resolve
        run: |
          ssh_main() { ssh -i ~/.ssh/id_deploy -o BatchMode=yes "deploy@$MAIN_HOST" "$@"; }
          CURRENT="$(ssh_main 'cat /opt/scrabble/DEPLOYED_TAG 2>/dev/null || echo none')"
          if [ -n "$INPUT_TARGET" ]; then
            TARGET="$INPUT_TARGET"
          else
            TARGET="$(ssh_main 'cat /opt/scrabble/PREVIOUS_TAG 2>/dev/null || echo none')"
          fi
          if [ -z "$TARGET" ] || [ "$TARGET" = none ]; then
            echo "no rollback target (no PREVIOUS_TAG on the host and no target_version input)"; exit 1
          fi
          if [ "$TARGET" = "$CURRENT" ]; then
            echo "target $TARGET is already the deployed version; nothing to do"; exit 1
          fi
          echo "rolling back: current=$CURRENT -> target=$TARGET"
          echo "target=$TARGET" >> "$GITHUB_OUTPUT"
          { echo "TARGET=$TARGET"; echo "CURRENT=$CURRENT"; } >> "$GITHUB_ENV"
      - name: Render main env + certs
        run: |
          umask 077
          mkdir -p stage/certs-main
          cat > stage/env.sh <<EOF
          export REGISTRY='$REGISTRY'
          export SCRABBLE_CONFIG_DIR='/opt/scrabble'
          export POSTGRES_DB='${POSTGRES_DB:-scrabble}'
          export POSTGRES_USER='${POSTGRES_USER:-scrabble}'
          export POSTGRES_PASSWORD='$POSTGRES_PASSWORD'
          export GM_BASICAUTH_USER='${GM_BASICAUTH_USER:-gm}'
          export GM_BASICAUTH_HASH='$GM_BASICAUTH_HASH'
          export GRAFANA_ADMIN_PASSWORD='$GRAFANA_ADMIN_PASSWORD'
          export GRAFANA_ROOT_URL='$GRAFANA_ROOT_URL'
          export CADDY_SITE_ADDRESS='$CADDY_SITE_ADDRESS'
          export LOG_LEVEL='${LOG_LEVEL:-info}'
          export DICT_VERSION='$DICT_VERSION'
          export APP_VERSION='$TARGET'
          export TELEGRAM_BOT_TOKEN='$TELEGRAM_BOT_TOKEN'
          export TELEGRAM_MINIAPP_URL='$TELEGRAM_MINIAPP_URL'
          export GATEWAY_ABUSE_BAN_ENABLED='true'
          EOF
          printf '%s\n' "$PROD_BOTLINK_CA"           > stage/certs-main/ca.crt
          printf '%s\n' "$PROD_BOTLINK_GATEWAY_CERT" > stage/certs-main/gateway.crt
          printf '%s\n' "$PROD_BOTLINK_GATEWAY_KEY"  > stage/certs-main/gateway.key
          chmod 644 stage/certs-main/*
      - name: Roll the main host back
        run: |
          ssh_main() { ssh -i ~/.ssh/id_deploy -o BatchMode=yes "deploy@$MAIN_HOST" "$@"; }
          ssh_main 'mkdir -p /opt/scrabble/compose'
          tar -C deploy -czf - docker-compose.yml docker-compose.prod.yml prod-deploy.sh \
            | ssh_main 'tar -C /opt/scrabble/compose -xzf -'
          tar -C deploy -czf - caddy otelcol prometheus tempo grafana \
            | ssh_main 'tar -C /opt/scrabble -xzf -'
          tar -C stage -czf - certs-main \
            | ssh_main 'rm -rf /opt/scrabble/certs && mkdir -p /opt/scrabble/certs && tar -C /opt/scrabble/certs --strip-components=1 -xzf -'
          scp -i ~/.ssh/id_deploy -o BatchMode=yes stage/env.sh "deploy@$MAIN_HOST:/opt/scrabble/env.sh"
          echo "$PROD_REGISTRY_PASSWORD" | ssh_main "docker login ${REGISTRY%%/*} -u $PROD_REGISTRY_USER --password-stdin"
          # Image-only rollback: no migration window (TAG=target, MIGRATION=0). A failed
          # rollback's auto-revert returns to the current version (PREV_TAG=$CURRENT).
          ssh_main "TAG='$TARGET' PREV_TAG='$CURRENT' MIGRATION=0 bash /opt/scrabble/compose/prod-deploy.sh"
  rollback-bot:
    needs: rollback-main
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
    env:
      TARGET: ${{ needs.rollback-main.outputs.target }}
      PROD_REGISTRY_USER: ${{ vars.PROD_REGISTRY_USER }}
      PROD_REGISTRY_PASSWORD: ${{ secrets.PROD_REGISTRY_PASSWORD }}
      PROD_SSH_KEY: ${{ secrets.PROD_SSH_KEY }}
      PROD_SSH_KNOWN_HOSTS: ${{ secrets.PROD_SSH_KNOWN_HOSTS }}
      TG_HOST: ${{ vars.PROD_TG_HOST }}
      MAIN_HOST: ${{ vars.PROD_MAIN_HOST }}
      TELEGRAM_BOT_TOKEN: ${{ secrets.PROD_TELEGRAM_BOT_TOKEN }}
      TELEGRAM_PROMO_BOT_TOKEN: ${{ secrets.PROD_TELEGRAM_PROMO_BOT_TOKEN }}
      PROD_BOTLINK_CA: ${{ secrets.PROD_BOTLINK_CA }}
      PROD_BOTLINK_BOT_CERT: ${{ secrets.PROD_BOTLINK_BOT_CERT }}
      PROD_BOTLINK_BOT_KEY: ${{ secrets.PROD_BOTLINK_BOT_KEY }}
      LOG_LEVEL: ${{ vars.PROD_LOG_LEVEL }}
      TELEGRAM_MINIAPP_URL: ${{ vars.PROD_TELEGRAM_MINIAPP_URL }}
      TELEGRAM_GAME_CHANNEL_ID: ${{ vars.PROD_TELEGRAM_GAME_CHANNEL_ID }}
      TELEGRAM_CHAT_ID: ${{ vars.PROD_TELEGRAM_CHAT_ID }}
      TELEGRAM_BOT_USERNAME: ${{ vars.PROD_TELEGRAM_BOT_USERNAME }}
      TELEGRAM_BOT_LINK: ${{ vars.PROD_VITE_TELEGRAM_LINK }}
    steps:
      - uses: actions/checkout@v4
      - name: Set up SSH
        run: |
          mkdir -p ~/.ssh && chmod 700 ~/.ssh
          printf '%s\n' "$PROD_SSH_KEY" > ~/.ssh/id_deploy && chmod 600 ~/.ssh/id_deploy
          printf '%s\n' "$PROD_SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
      - name: Render bot env + certs
        run: |
          umask 077
          mkdir -p stage/certs-bot
          cat > stage/env.bot.sh <<EOF
          export SCRABBLE_CONFIG_DIR='/opt/scrabble'
          export BOT_IMAGE='$REGISTRY/scrabble-telegram-bot:$TARGET'
          export BOTLINK_GATEWAY_ADDR='$MAIN_HOST:9443'
          export TELEGRAM_BOT_TOKEN='$TELEGRAM_BOT_TOKEN'
          export TELEGRAM_MINIAPP_URL='$TELEGRAM_MINIAPP_URL'
          export TELEGRAM_GAME_CHANNEL_ID='$TELEGRAM_GAME_CHANNEL_ID'
          export TELEGRAM_CHAT_ID='$TELEGRAM_CHAT_ID'
          export TELEGRAM_PROMO_BOT_TOKEN='$TELEGRAM_PROMO_BOT_TOKEN'
          export TELEGRAM_BOT_USERNAME='$TELEGRAM_BOT_USERNAME'
          export TELEGRAM_BOT_LINK='$TELEGRAM_BOT_LINK'
          export LOG_LEVEL='${LOG_LEVEL:-info}'
          EOF
          printf '%s\n' "$PROD_BOTLINK_CA"       > stage/certs-bot/ca.crt
          printf '%s\n' "$PROD_BOTLINK_BOT_CERT" > stage/certs-bot/bot.crt
          printf '%s\n' "$PROD_BOTLINK_BOT_KEY"  > stage/certs-bot/bot.key
          chmod 644 stage/certs-bot/*
      - name: Roll the bot host back
        run: |
          ssh_tg() { ssh -i ~/.ssh/id_deploy -o BatchMode=yes "deploy@$TG_HOST" "$@"; }
          ssh_tg 'mkdir -p /opt/scrabble/compose'
          tar -C deploy -czf - docker-compose.bot.yml | ssh_tg 'tar -C /opt/scrabble/compose -xzf -'
          tar -C stage -czf - certs-bot \
            | ssh_tg 'rm -rf /opt/scrabble/certs && mkdir -p /opt/scrabble/certs && tar -C /opt/scrabble/certs --strip-components=1 -xzf -'
          scp -i ~/.ssh/id_deploy -o BatchMode=yes stage/env.bot.sh "deploy@$TG_HOST:/opt/scrabble/env.bot.sh"
          echo "$PROD_REGISTRY_PASSWORD" | ssh_tg "docker login ${REGISTRY%%/*} -u $PROD_REGISTRY_USER --password-stdin"
          ssh_tg 'set -a; . /opt/scrabble/env.bot.sh; set +a; cd /opt/scrabble/compose;
            docker compose -f docker-compose.bot.yml pull;
            docker compose -f docker-compose.bot.yml up -d'
  verify:
    needs: [rollback-main, rollback-bot]
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
    env:
      PROD_SSH_KEY: ${{ secrets.PROD_SSH_KEY }}
      PROD_SSH_KNOWN_HOSTS: ${{ secrets.PROD_SSH_KNOWN_HOSTS }}
      MAIN_HOST: ${{ vars.PROD_MAIN_HOST }}
      CADDY_SITE_ADDRESS: ${{ vars.PROD_CADDY_SITE_ADDRESS }}
    steps:
      - name: Set up SSH
        run: |
          mkdir -p ~/.ssh && chmod 700 ~/.ssh
          printf '%s\n' "$PROD_SSH_KEY" > ~/.ssh/id_deploy && chmod 600 ~/.ssh/id_deploy
          printf '%s\n' "$PROD_SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
      - name: Verify the public site
        run: |
          domain="${CADDY_SITE_ADDRESS%% *}"
          ssh -i ~/.ssh/id_deploy -o BatchMode=yes "deploy@$MAIN_HOST" "for i in \$(seq 1 20); do
              if curl -fsS -k --resolve $domain:443:127.0.0.1 https://$domain/ -o /dev/null &&
                 docker run --rm --network scrabble-internal alpine:3.20 wget -q -T 5 -O /dev/null http://backend:8080/readyz; then
                echo 'rolled-back site healthy'; exit 0
              fi
              sleep 5
            done
            echo 'verify failed'; docker logs --tail 40 scrabble-caddy; docker logs --tail 40 scrabble-backend; exit 1"
@@ -1,96 +1,97 @@
 # scrabble-game — project guide
-Multiplatform Scrabble game. Read this first every session. The owner drives the
+Multiplatform Scrabble game, **in production** at `https://erudit-game.ru`. Read this
-project **one stage per session** (tariff constraint), so the repository — not
+first every session. The repository — not conversation memory — is the source of
-conversation memory — is the source of continuity. Keep it that way.
+continuity; keep it that way.
 ## Sources of truth (read before changing behaviour)
- [`PLAN.md`](PLAN.md) — staged plan + **stage tracker** + per-stage *open
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — architecture, transport, security,
-  details to interview*.
+  the decision record. Always describes the current state.
- [`PRERELEASE.md`](PRERELEASE.md) — pre-release hardening tracker (phases R1–R7
+- [`docs/FUNCTIONAL.md`](docs/FUNCTIONAL.md) (+ [`_ru`](docs/FUNCTIONAL_ru.md) mirror)
-  before Stage 18); same per-phase *interview + bake-back* discipline as `PLAN.md`.
+  — per-domain user stories. English authoritative.
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — architecture, transport,
+- [`docs/TESTING.md`](docs/TESTING.md) — test layers + the CI gate.
  security, the decision record. Always describes current state.
 - [`docs/FUNCTIONAL.md`](docs/FUNCTIONAL.md) (+ [`_ru`](docs/FUNCTIONAL_ru.md)
  mirror) — per-domain user stories. English authoritative.
 - [`docs/TESTING.md`](docs/TESTING.md) — test layers + the per-stage CI gate.
 - [`docs/UI_DESIGN.md`](docs/UI_DESIGN.md) — the `ui` visual/interaction design system.
 - [`deploy/README.md`](deploy/README.md) — the deploy contour + the production
  rollout / rollback runbook.
-## Mandatory per-stage workflow
+## How we work
-**Start of a stage**
+- Inspect the relevant code path and the docs above before changing behaviour.
-1. Read `PLAN.md` (the stage's scope + *open details*) and the relevant `docs/`.
+- **Interview the owner on every fork** — do not silently pick borderline decisions;
-2. Analyse what the stage actually requires against the current code.
+  offer options with brief pros/cons.
-3. **Interview the owner** on every open detail and any fork not already fixed
+- Smallest correct diff. Prefer compact code; reuse before adding; do not add deps,
-   in the plan — do not silently pick borderline decisions. Offer options with
+  seams or knobs until they are needed.
-   brief pros/cons.
+- **Update or add tests for every functional change**, at the layers
-4. Only then implement, strictly within the stage's scope.
+  `docs/TESTING.md` calls out.
-
+- **Bake docs in the same PR**: update `docs/ARCHITECTURE.md`, `docs/FUNCTIONAL.md`
-**End of a stage**
+  (+`_ru`), the affected service `README` and Go Doc comments alongside the change.
-1. Bake every new agreement back into `PLAN.md`, `docs/ARCHITECTURE.md`,
+- Document added packages, types, funcs, consts and vars with Go Doc comments.
   `docs/FUNCTIONAL.md` (+ `_ru`), the affected service `README`, and Go Doc
   comments — in the **same** PR. Correct earlier stages' docs/code if a new
   decision changes them.
 2. Update the stage tracker; add a line under *Refinements logged during
   implementation* for any plan deviation.
 3. Get CI green, then mark the stage done.
 (The `stage-implementation` skill encodes this same loop and can be invoked.)
 ## Conventions
 - All code, comments, identifiers, commits, docs, filenames in **English**.
- Chat with the owner follows the user-level `~/.claude/CLAUDE.md` (Russian,
+- Chat with the owner follows the user-level `~/.claude/CLAUDE.md` (Russian, the
-  the agreed persona and translation rules).
+  agreed persona and translation rules).
- Mirror every point edit of `docs/FUNCTIONAL.md` into `docs/FUNCTIONAL_ru.md`
+- Mirror every point edit of `docs/FUNCTIONAL.md` into `docs/FUNCTIONAL_ru.md` in the
-  in the same patch (translate only the touched paragraphs).
+  same patch (translate only the touched paragraphs).
 - Prefer compact code; do not add deps, seams or knobs until a stage needs them.
  Reuse before adding. Document added packages/types/funcs with Go Doc comments.
 - Update or add tests for every functional change.
-## Branching & CI
+## Branching, CI & production
- **Two long-lived branches** (Stage 16 onward): **`development`** is the
+- **Two long-lived branches**: **`development`** is the integration branch; **`master`**
-  integration branch; **`master`** is the production trunk. Cut `feature/*`
+  is the production trunk. Cut `feature/*` from `development` and PR back into it;
-  branches **from `development`** and PR them back into it. (Stages 0–15 used
+  promote `development → master` via PR when ready to release. Both branches require
-  `master` as the trunk with `feature/* → master`; the genesis Stage 0 commit is
+  one approval + the `CI / gate` check.
-  on `master` by necessity.)
+- A commit to a `feature/*` branch triggers nothing. The single workflow
- A commit to a `feature/*` branch triggers **nothing**. The single workflow
+  `.gitea/workflows/ci.yaml` runs the full suite (`unit` + `integration` + `ui`) on a
-  `.gitea/workflows/ci.yaml` runs the full suite (`unit` + `integration` + `ui`)
+  PR into `development` or `master`, and the gated **`deploy`** job auto-rolls the
-  on a PR into `development` or `master`, and the gated **`deploy`** job auto-rolls
+  **test contour** on a PR into — or a push to — `development`
-  the **test contour** on a PR into — or a push to — `development`
+  (`docker compose up -d --build` on the runner host + landing/SPA/backend probes). A
-  (`docker compose up -d --build` on the runner host + a `GET /` probe). A PR into
+  PR into `master` is test-only.
-  `master` is test-only.
+- **Production is live on two hosts** (main + the Telegram bot host) and deploys
- Merge `development → master` only when CI is green; the **prod** deploy is then a
+  **only manually** (`workflow_dispatch`), never automatically:
-  **manual** workflow (Stage 18), never automatic. Secrets/variables are prefixed
+  - **`.gitea/workflows/prod-deploy.yaml`** (`confirm=deploy`, from `master`) builds +
-  `TEST_` / `PROD_` per contour (Gitea 1.26 has no deployment environments).
+    pushes the images to the registry, then SSH-deploys both hosts — rolling per
- After any push, watch the run to green before declaring a stage done — use the
+    service in dependency order, health-gated, **auto-rollback to the previous tag**;
-  ready-made watcher, never an inline poll loop:
+    a schema migration adds a maintenance window + a consistent `pg_dump`. Four visible
-  `python3 ~/.claude/bin/gitea-ci-watch.py` (background). It reads `$GITEA_URL`
+    jobs: build → deploy-main → deploy-bot → verify.
-  / `$GITEA_TOKEN`; `gitea.iliadenisov.ru` is allow-listed in
+  - **`.gitea/workflows/prod-rollback.yaml`** (`confirm=rollback`) re-deploys a prior
-  `.claude/settings.json`. Remote: `origin git@gitea.iliadenisov.ru:developer/scrabble-game.git`.
+    release (blank `target_version` = the previous deployed version) — image-only,
    rolling, health-gated.
  - **Releases are git tags `vX.Y.Z` on `master`**; the deploy stamps `git describe
    --tags` into the image tag, every binary (`pkg/version` via `-ldflags` → the
    `service.version` telemetry attribute) and the SPA About screen. Tag the release
    before deploying.
  - Hosts are provisioned idempotently by **`deploy/ansible/`**. Per-contour
    secrets/variables use the `TEST_` / `PROD_` prefix (Gitea 1.26 has no deployment
    environments). Migrations must be **expand-contract** (backward-compatible) so
    image rollback stays DB-safe. Full runbook + variable list in `deploy/README.md`.
 - After any push, merge or deploy, **watch the run to green** before declaring done —
  use the ready-made watcher (run it in the background), never an inline poll loop:
  `python3 ~/.claude/bin/gitea-ci-watch.py`. It reads `$GITEA_URL` / `$GITEA_TOKEN`;
  `gitea.iliadenisov.ru` is allow-listed in `.claude/settings.json`. Remote:
  `origin git@gitea.iliadenisov.ru:developer/scrabble-game.git`.
 ## Stack
-Go 1.26.3, `go.work` monorepo, module paths `scrabble/<name>`. Dependencies are
+Go 1.26.3, `go.work` monorepo, module paths `scrabble/<name>`. Backend uses `gin` +
-added **when first used** (incremental): backend uses `gin` + `zap` +
+`zap` + `pgx`/`go-jet`/`goose`/OTel. Client↔gateway is Connect-RPC + FlatBuffers
-`pgx`/`go-jet`/`goose`/OTel (added in Stage 1). Client↔gateway is Connect-RPC +
+(h2c); gateway↔backend is REST/JSON + `X-User-ID` plus a gRPC server-stream for live
-FlatBuffers (h2c); gateway↔backend is REST/JSON + `X-User-ID` plus a gRPC
+events. UI is pure HTML5/CSS on plain Svelte + Vite, packaged to native with
-server-stream for live events. UI is pure HTML5/CSS on plain Svelte + Vite,
+Capacitor. No Redis.
 packaged to native with Capacitor. Likely no Redis.
 ## Reused engine: `../scrabble-solver` (module `scrabble-solver`, Go 1.26.3)
-Embedded **in-process as a library** — there is no per-game container. Public
+Embedded **in-process as a library** (`replace scrabble-solver => ../scrabble-solver`
-API to reuse (do not reimplement):
+in `go.work`; CI checks out the sibling from
 `https://gitea.iliadenisov.ru/.../scrabble-solver.git`). There is no per-game
 container. Public API to reuse (do not reimplement):
- `scrabble.NewSolver(rs, finder)` → `GenerateMoves(b, r, mode)` (ranked,
+- `scrabble.NewSolver(rs, finder)` → `GenerateMoves(b, r, mode)` (ranked, highest
-  highest score first), `ValidatePlay(b, dir, tiles)`, `ScorePlay(...)`;
+  score first), `ValidatePlay(b, dir, tiles)`, `ScorePlay(...)`; `scrabble.Apply(b, m)`;
-  `scrabble.Apply(b, m)`; types `Move/Word/Placement/Direction/Mode`
+  types `Move/Word/Placement/Direction/Mode`
  (`scrabble-solver/scrabble/{solver,move,apply}.go`).
- `rules.English() / RussianScrabble() / Erudit()`
+- `rules.English() / RussianScrabble() / Erudit()` (`scrabble-solver/rules/rules.go`).
  (`scrabble-solver/rules/rules.go`).
 - `board.New / Parse / Clone / Transpose`; `rack.New / Add / Remove / Clone`;
  `selfplay.NewBag / Draw / Len` (bag pattern).
 - Load committed dictionaries with `dawg.Load(path)` from
@@ -99,20 +100,17 @@ API to reuse (do not reimplement):
 Constraints:
 - Words/tiles are **alphabet-index bytes**, meaningful only with the matching
-  `rules.Ruleset` (`Alphabet.Decode`); blank flag carried separately. **Decode
+  `rules.Ruleset` (`Alphabet.Decode`); the blank flag is carried separately. **Decode
  to real characters before persisting history** (history must be
  dictionary-independent — see `docs/ARCHITECTURE.md` §9.1).
 - The solver's `internal/*` is NOT importable from this sibling module.
 - **GCG is test-only** in the solver (no public writer) — we ship our own.
- Wiring: add `replace scrabble-solver => ../scrabble-solver` to `go.work` in
+- The solver uses published `github.com/iliadenisov/{alphabet,dafsa}` (no local replace).
  **Stage 2** (when `internal/engine` first imports it), and make CI check out
  the solver sibling (`https://gitea.iliadenisov.ru/.../scrabble-solver.git`).
  It uses published `github.com/iliadenisov/{alphabet,dafsa}` (no local replace).
 ## Repository layout
 ```
-go.work                      # use the existing modules; grows per stage
+go.work                      # the go.work monorepo
 backend/                     # module scrabble/backend
  cmd/backend/               # main: telemetry -> db+migrate -> cache -> server
  cmd/jetgen/                # dev tool: regenerate go-jet code (throwaway container)
@@ -123,12 +121,14 @@ backend/                     # module scrabble/backend
  internal/session/          # opaque tokens, sessions store, cache, service
  internal/server/           # gin engine, /api/v1 groups, X-User-ID, probes
  internal/inttest/          # //go:build integration Postgres-backed tests
-docs/  .gitea/workflows/  PLAN.md  CLAUDE.md  README.md
+gateway/                     # module scrabble/gateway: Connect-RPC edge, embeds the SPA
-gateway/  ui/  pkg/              # added by their stages
+ui/                          # Svelte + Vite SPA + landing (Node project, not in go.work)
-platform/telegram/               # Telegram side-service, two binaries (Stage 9; split in phase TX): cmd/validator (HMAC, no VPN) + cmd/bot (Bot API; dials gateway over reverse mTLS bot-link)
+pkg/                         # shared: telemetry, version, wire/FlatBuffers, proto, mtls
-loadtest/                        # module scrabble/loadtest: the pre-release stress harness (R2)
+platform/telegram/           # Telegram side-service: cmd/validator (HMAC, no VPN) + cmd/bot (Bot API; dials gateway over reverse mTLS bot-link)
-backend/Dockerfile gateway/Dockerfile platform/telegram/Dockerfile loadtest/Dockerfile  # multi-stage distroless (Stage 16; loadtest R2); gateway/Dockerfile has the `landing` target (R3), platform/telegram/Dockerfile has `validator`+`bot` targets (TX)
+loadtest/                    # module scrabble/loadtest: the load/stress harness
-deploy/                          # docker-compose (per-service limits, R7) + caddy + landing + otelcol (OTLP + docker_stats per-container metrics) + prometheus/tempo/grafana + postgres_exporter
+docs/  .gitea/workflows/  CLAUDE.md  README.md
 backend/Dockerfile gateway/Dockerfile platform/telegram/Dockerfile loadtest/Dockerfile  # multi-stage distroless; gateway/Dockerfile has the `landing` target, platform/telegram/Dockerfile has `validator`+`bot` targets
 deploy/                      # docker-compose (+ prod overlay + bot host) + ansible provisioning + caddy + landing + otelcol (OTLP + docker_stats) + prometheus/tempo/grafana + node_exporter + postgres_exporter; prod-deploy.sh
 ```
 ## Build & test
@@ -138,20 +138,19 @@ go build ./backend/...          # per module ('./...' from the root won't span t
 go vet ./backend/...
 gofmt -l .                      # must print nothing
 go test -count=1 ./backend/...
-go build ./platform/telegram/... && go test ./platform/telegram/...  # Telegram validator + bot (Stage 9; split in TX)
+go build ./platform/telegram/... && go test ./platform/telegram/...  # Telegram validator + bot
 go run ./backend/cmd/backend    # /healthz, /readyz on :8080
-cd ui && pnpm install && pnpm check && pnpm test:unit && pnpm build  # the UI (Stage 7+)
+cd ui && pnpm install && pnpm check && pnpm test:unit && pnpm build  # the UI
 pnpm start                      # UI mock mode: lobby -> game, no backend
-docker build -f backend/Dockerfile -t scrabble-backend .   # images (Stage 16); gateway embeds the SPA
+docker build --build-arg DICT_VERSION=v1.3.0 -f backend/Dockerfile -t scrabble-backend .  # DICT_VERSION required (no default); gateway embeds the SPA
 docker build -f gateway/Dockerfile --target gateway -t scrabble-gateway .
-docker build -f gateway/Dockerfile --target landing -t scrabble-landing .  # static landing (R3)
+docker build -f gateway/Dockerfile --target landing -t scrabble-landing .  # static landing
 docker compose -f deploy/docker-compose.yml config         # validate the full contour
 ```
-The `ui` module is a Node project (pnpm), **not** in `go.work`; it is the `ui` job
+The `ui` module is a Node project (pnpm), **not** in `go.work`; it is the `ui` job of
-of the single `.gitea/workflows/ci.yaml` (Stage 16 folded the former go-unit /
+the single `.gitea/workflows/ci.yaml`. Committed edge codegen under `ui/src/gen/`
 integration / ui-test workflows into it). Committed edge codegen under `ui/src/gen/`
 (regenerate with `pnpm codegen`); pnpm build-script approval lives in
 `ui/pnpm-workspace.yaml` (`allowBuilds: esbuild: true`).
@@ -1,632 +0,0 @@
 # Pre-release plan — hardening before Stage 18
 Living tracker for the pre-release hardening pass that runs **before Stage 18** (the
 prod cutover). Same discipline as [`PLAN.md`](PLAN.md): one phase per session,
 **interview the owner on the open details** at the start of each phase, bake every
 decision back into `PLAN.md` / `docs/` / the affected `README`s / Go Doc comments in
 the **same** PR, get CI green, then mark the phase done. Phases run as
 `feature/* → development` PRs (the Stage 16 branch model); the owner approves+merges.
 **Why now:** the system is feature-complete through Stage 17 and the test contour is
 green, but there is **no prod data yet** — schema, wire labels and the dictionary
 layout can still change for free. These phases spend that one-time freedom and harden
 the edge before prod. Each phase maps back to the owner's raw pre-release TODO list
 (numbers in the tracker).
 ## Phase tracker
 | # | Phase | Raw TODOs | Status |
 |---|-------|-----------|--------|
 | R1 | Schema & naming reset | 1 + 10 | **done** |
 | R2 | Stress harness + contour observability + early run | 9a | **done** |
 | R3 | Edge hardening | 2 + 8 + 3 | **done** |
 | R4 | Push enrichment + kill the last poll | 4 + 5 | **done** |
 | R5 | Bundle slimming | 6 | **done** |
 | R6 | Refactor + docs reconciliation + de-staging | 7 | **done** |
 | R7 | Final stress run + tuning | 9b | **done** |
 | UI | Tab-bar navigation redesign (drop the hamburger) | owner ad-hoc | **done** |
 | MW | "Multiple words per turn" rule for Russian games (engine v1.1.0) | owner ad-hoc | **done** |
 | MW2 | Single-word rule connectivity fix: the word must run along its own line through an existing tile (perpendicular-only contact no longer connects); single-tile direction picks the best legal word (engine v1.1.1) | owner ad-hoc | **done** |
 | MW3 | Graceful replay degradation: a game whose journalled move became illegal under MW2 is closed as a draw (`end_reason='aborted'`) on open instead of erroring, with an impersonal organizer note in the history + GCG (migration `00002`) | owner ad-hoc | **done** |
 | OW | Open auto-match: enter the game at once and wait inside it (robot after 90–180 s) | owner ad-hoc | **done** |
 | DA | Dictionary admin: online release-archive upload → word-diff preview → install/activate; versioned dict volume; active version persisted in DB; resident label = release tag | owner ad-hoc | **done** |
 | AB | Manual account block (admin suspension): permanent/temporary with an editable en+ru reason picklist; a block forfeits the player's active games + cancels their open ones; a backend gate refuses a blocked account with **403 `account_blocked`**; the UI shows a terminal blocked screen and stops all push/poll; manual unblock; temporary blocks self-expire (migration `00003`) | owner ad-hoc | **done** |
 | AI | Honest AI opponent in quick game: an explicit 🤖 AI / 👤 random selector (AI default); the robot is seated and moves at once; 7-day inactivity loss (the per-turn timeout reused); chat/nudge disabled, no statistics; the opponent is shown as 🤖 everywhere | owner ad-hoc | **done** |
 | AD | Advertising banner ("ad network"): server-driven weighted campaigns (percent weight + validity window; the perpetual default fills the remainder up to 100%), bilingual messages shown by bot (`service_language`); eligibility = free account + empty hint wallet + no `no_banner` role (guests included); the resolved feed rides `profile.get` with a `notify` `banner` re-poll on eligibility change; `/_gm/banners` admin + global display timings; client smooth-weighted-round-robin rotation + fade-out/gap/fade-in UX. A single `app.load` bootstrap aggregator was considered and **deferred** (see ARCHITECTURE §10). | owner ad-hoc | **done** (PR1 backend+admin, PR2 UI rotation) |
 | GL | Simultaneous quick-game cap (10): grey "New Game" + a lobby notice at the cap; backend gate on quick enqueue + invitation creation (409 `game_limit_reached`), accepting invitations exempt; `at_game_limit` rides `games.list` | owner ad-hoc | **done** |
 | CR | In-game chat read receipts: per-message `unread_seats` bitmask (migration `00008`); a per-viewer unread **dot** in the lobby + game header (a nudge counts and clears when its recipient moves); reading = opening the move history (the 💬 fade-blinks twice) or the chat, acked (`chat.read`) only when unread; `chat_read_duration` + `chat_unread_messages` metrics + tracing + the **Scrabble — Messages** Grafana dashboard (follow-up PR); a message to a disguised robot opponent is born read; admin unread-only filter / read column / per-seat read card | owner ad-hoc | **done** |
 | BX | Asymmetric per-user block + in-game controls: a block now silently suppresses everything **from** the blocked user (chat, nudge, friend requests, invitations are kept but never delivered/surfaced, born-read) while they notice nothing, **without** deleting the friendship (unblock restores it); auto-match excludes a block-related pair (either direction); in-game opponent card gains a ✖️ **block** control (mirroring 🤝, red "Block?" confirm, mutual-hide, struck name + hidden chat composer when blocked); optimistic apply + `user_blocked`/`user_unblocked` event confirm + rollback; admin user card gains **blocks / blocked-by / friends** cross-linked lists. Blocking a disguised-robot opponent is recorded per-game in a separate **`robot_blocks`** table (migration `00011`), keyed on game+seat with the seen name — never the shared robot account — so the matchmaker keeps giving robots; it shows in the blocked list and re-marks the in-game card | owner ad-hoc | **done** |
 | FM | First-move tile draw (official rules): each seated player draws a tile, the one closest to "A" leads (a blank beats every letter), ties re-drawing until a single leader; **honest per-draw `crypto/rand` entropy**, not the bag seed, so the **record** (`game_setup_draws`, migration `00013`) — not a seed — is the only account of the outcome, kept for future **tournaments** (designed as a discrete per-tile "player N draws" step). Friend/AI draws at create; **auto-match draws at *open*** against a synthetic `uuid.Nil` opponent whose draw rows are back-filled on join, so the opener's seat is fixed up front and the existing open-game pre-move is preserved (no reseating, no play-gating). Admin `/_gm/games/:id` gains the recorded draw list + a simple **step-by-step board replay** (`ReplayTimeline`). | owner ad-hoc | **done** |
 | SB | Single Telegram bot + per-user variant preferences: the two per-language bots collapse into **one** (drop `accounts.service_language`, `supported_languages`, the `*_EN`/`*_RU` env vars and game-language push routing — the single bot renders in the recipient's `preferred_language`); New Game variant gating moves to a profile **`variant_preferences`** set (default Erudit only, Erudit-first, server-enforced on the caller's auto-match/vs-AI/invitation-create paths, an invited friend may accept any variant); env vars collapse to unsuffixed `TELEGRAM_BOT_TOKEN`/`TELEGRAM_GAME_CHANNEL_ID`/`VITE_TELEGRAM_LINK`/`VITE_TELEGRAM_GAME_CHANNEL_NAME` and `GATEWAY_DEFAULT_SUPPORTED_LANGUAGES` is removed; wire drops `service_language`/`supported_languages` (Session, ValidateInitDataResponse) + the push `language` routing field and adds `variant_preferences` to Profile/UpdateProfile. | owner ad-hoc | **done** |
 | DV | Dictionary version hygiene: CI + image/compose seed track the current release (`v1.2.1`); a **seed-drift guard** records the flat dir's seed in an authoritative `.seed_version` marker so a bumped build seed on a live volume is ignored (it can't relabel live bytes — which would mis-serve the dictionary + void games pinned to the prior label); `DICT_VERSION` is the fresh-volume seed only, a live contour migrates through the admin console | owner ad-hoc | **done** |
 | TX | Telegram egress off the main host: split the connector into a home **validator** (Mini App / Login-Widget HMAC, no VPN, no Bot API — so game login no longer depends on Telegram being reachable) and a remote **bot** (Bot API long-poll + `sendMessage`) that holds **no inbound port** and dials the gateway over a reverse **mTLS bot-link** (`pkg/proto/botlink/v1`); the gateway funnels out-of-app push (fire-and-forget, at-most-once) and the backend admin broadcasts (a relay that awaits the bot's ack) down the link. The bot is Telegram-rate-limited; **one bot now**, with seams (a bot registry + `owns_updates` + command ids) for N later; **no webhook** (rejected: one URL per token, adds inbound + a static address). The **unified test contour** runs the split (the bot keeps its VPN sidecar and dials the gateway by its internal name; certs from `deploy/gen-certs.sh`). The **prod** wiring — the bot on a separate host (no VPN), the gateway bot-link port published, `PROD_` certs with scheduled rotation, an SSH deploy of both hosts together — is the **deferred final stage** (Stage 18). | owner ad-hoc | **done** (code + test contour; prod wiring → Stage 18) |
 | AG | Anti-abuse IP ban + honeypot/honeytoken (prod-only): a fail2ban-style in-memory `ratelimit.Banlist` keyed by client IP, fed by sustained rate-limiter rejections (the IP-keyed public/email/admin classes — the user class stays the soft-flag's concern), a **honeypot** decoy path (the contour caddy tags `/.env`, `/.git`, `/wp-*`, … with `X-Scrabble-Honeypot` and routes them to the gateway), and a **honeytoken** (`GATEWAY_HONEYTOKEN`, a planted bearer). The `abuseGuard` edge middleware refuses a banned IP with **429** before any work — closing the R3 gap that the static SPA/landing was outside the token bucket. Off by default — it keys by the real client IP the shared-NAT test contour does not expose (detection still logs there); enabled in prod via `GATEWAY_ABUSE_BAN_ENABLED`. Operators see + lift bans on the console **Throttled** page; the gateway syncs its active set to the backend (`/api/v1/internal/bans/sync`, `internal/banview`) every 30 s and applies operator unbans. | owner ad-hoc | **done** (code + test contour; ban enabled in prod → Stage 18) |
 | CM | Channel-chat moderation + promo bot: a second standalone bot in the bot container answers `/start` with a localized message + a **URL** button into the **main** bot's Mini App (`?startapp`; a `web_app` button would sign initData with the promo token, which the main validator rejects). The **main** bot gates write access in a channel's linked discussion chat. The chat **allows sending by default** and the bot only restricts (Telegram intersects the chat default with the per-user permission, so a per-user grant cannot exceed a deny-by-default group): it **mutes** a member who is not registered or is admin-suspended or holding a new **`chat_muted`** role, and **un-mutes** an eligible one it had muted, for a member currently in the chat (a `getChatMember` guard, since bots cannot list members). Eligibility = `registered AND NOT suspended AND NOT chat_muted` (the game suspension dominates), resolved once in the backend and reached two ways: the bot's `ResolveChatEligibility` on a `chat_member` event over the existing mTLS bot-link, and a backend `chat_access_changed` event → gateway → `ChatGate` command (emitted on block/unblock, a `chat_muted` change, a first registration, or a temporary-block expiry via a sweeper; idempotent). No schema change — `chat_muted` reuses `account_roles`. | owner ad-hoc | **done** |
 | → | Stage 18 — prod contour deploy | — | see [`PLAN.md`](PLAN.md) |
 ## Key findings (these reshaped the raw list — read before starting a phase)
 - **R1 (TODO 1 + 10) is one cheap moment, now.** Squashing the 12 goose migrations is
  safe precisely because there is no prod data and the contour DB is wiped. Folding the
  new variant labels (`scrabble_ru`/`scrabble_en`/`erudit_ru`) into that single baseline
  makes the rename need **no data migration and no back-compat mapping**. Today's labels
  (`english`/`russian_scrabble`/`erudit`) are persisted in `games.variant`,
  `game_invitations.variant`, in `pkg/fbs` and the UI — ~100 files, but a mechanical sweep
  on a clean DB.
 - **R4 (TODO 4 + 5): the app is already push-first.** Game state refreshes on
  `your_turn`/`opponent_moved`, the lobby on `notify`, chat on `chat_message`. The **only**
  genuine periodic server poll is `lobby.poll` (matchmaking, 2.5 s,
  `ui/src/screens/NewGame.svelte`). What remains is killing that one poll **and** enriching
  push events to carry payloads so the UI stops re-fetching after each signal.
 - **R3 (TODO 2): identity forgery is already mitigated.** Identity is always derived from
  the session (`Authorization: Bearer` → `X-User-ID`); the client cannot inject identity,
  the backend re-validates resource ownership, Telegram initData is HMAC-checked. The real
  gaps are a missing **request-body size limit** (cheap DoS) and **invisible rate-limit
  rejections** (no log/metric/admin view — that is TODO 8). Static landing serving is **not**
  covered by the gateway token bucket (it only guards `Execute`).
 - **R6 (TODO 7) scale:** ~431 `Stage N` references across ~104 files (incl. the file name
  `backend/internal/inttest/stage6_test.go`). Code is the source of truth; `docs/` describe
  current state; `PLAN.md` keeps the decision history.
 ## Locked decisions (owner interview)
 - **Stress test (TODO 9):** **early + final** runs. Driver = **edge protocol** (Connect/FB
  through the gateway, moves generated by the solver) **plus a separate gateway-hammer**
  saturation test. Pacing = **realistic (under limits) + saturation (ramp to the knee)**.
  Resource metrics = **add cAdvisor + postgres_exporter to the contour** (today only
  Go-runtime metrics exist). The harness stays in the repo for repeats.
 - **Push (TODO 4 + 5):** **both** — kill `lobby.poll` (use the existing `match_found`, keep
  poll as the ws-down fallback) **and** enrich push events with payloads.
 - **Refactor (TODO 7):** **hygiene + structural changes by a reviewed list** —
  behaviour-preserving, test-gated, contentious items surfaced to the owner before applying.
 - **Landing (TODO 3):** **separate static container** behind the project caddy
  (`/` → landing, `/app/` + `/telegram/` → gateway); drop `landing.html` from the gateway
  `go:embed`.
 - **Rate-abuse (TODO 8):** metric + Grafana + admin view **plus a conservative auto-flag** —
  a *soft, reversible* "suspected high-rate" marker for operator review, tunable threshold,
  **no auto-ban**.
 - **Anti-abuse IP ban (AG, owner ad-hoc):** a honeypot was considered and rejected as a *DDoS*
  defence — it detects/deceives but does not shed volumetric load, cannot cover the real
  endpoints, and a tarpit backfires under flood; volumetric L3/L4 is an upstream/CDN concern,
  out of scope. The effective layer is a **temporary IP ban** (fail2ban-style) that the honeypot
  and honeytoken merely *feed*. This does **not** reverse the TODO-8 "no auto-ban": that decision
  governs the **account** soft-flag (still never a gate); the IP ban is a separate, IP-keyed,
  **prod-only** layer with an **operator unban** in the console. Decisions: banlist lives in the
  existing `ratelimit` package (smallest surface); the decoy path list is a **single source of
  truth in the caddy** (it tags requests with a header — the gateway keeps no second list);
  bans are in-memory + single-instance (like `ratewatch`), auto-expiring, **plus** an admin
  console view + manual unban over a bidirectional 30 s sync (operator control = owner's choice).
  An active-bans Grafana **gauge** was trimmed (the console view + the `gateway_abuse_banned_total`
  counter cover it) to keep the diff focused.
 - **Open auto-match (owner ad-hoc):** a quick game **enters a real game at once and waits inside
  it** (status `open`, the opponent seat empty); a second human searching the same variant+rule
  joins it, or a robot fills it after a **90 s + random 0–90 s** wait, pushing the in-app
  **opponent_joined** event. While open, the starter may move on their turn but resign, chat and
  nudge are disabled, and the lobby + opponent card read "searching for opponent". Matchmaking is
  now **DB-backed open games** — the in-memory pool, `lobby.poll` and `lobby.cancel` are gone. The
  schema is edited in the baseline (no prod data); `game_players.account_id` is nullable for the
  empty seat.
 - **Telegram egress off-host (TX, owner ad-hoc):** the driver is **removing VPN/Telegram
  traffic from the main host** (OPSEC / one fewer analysis vector), not only notification
  resilience. Login is local HMAC, so it stays up regardless of the bot — confirmed in the
  code and made structural by the split. **Unified topology in code** (validator + bot, the
  bot dialing the gateway) in **both** contours, differing only in deployment; the test bot
  keeps its VPN sidecar. Transport = a **reverse gRPC bidi stream, mTLS, bot-dials-gateway**
  (no inbound/static IP on the bot), reusing the push-stream pattern; **webhook rejected**
  (one URL per token, adds inbound + a static address). Delivery **at-most-once** (a dropped
  nudge beats a duplicate). **One bot now**, seams (registry + `owns_updates` + command ids)
  for N later. **Cert rotation** by a scheduled CI job from a long-lived CA. **Prod deploy by
  SSH** (pull excluded), the bot rolled **together** with the main app (the bot-link protocol
  kept back-compatible by one version as the non-atomic-two-host-deploy safety net). The bot
  is monitored **from the gateway** (connection + ack metrics). The bot-host token-at-rest is
  **accepted**.
 ## Phases
 Each phase: read this tracker + the relevant `docs/`, **interview the owner on the open
 details below**, implement within scope, then update the tracker + docs/code and get CI
 green before marking it done.
 ### R1 — Schema & naming reset *(TODO 1 + 10)* — first
 Squash `backend/internal/postgres/migrations/00001..00012` into one `00001_baseline.sql`
 (method: `pg_dump --schema-only` from a fully-migrated DB → wrap as the goose baseline →
 prove a fresh migrate yields a schema identical to the 12-migration chain via the
 integration suite → delete the old files; keep goose). Bake the new variant labels into the
 baseline. Propagate `scrabble_ru`/`scrabble_en`/`erudit_ru` through the backend
 (`engine.Variant`/`ParseVariant`, `registry.dictFiles`, the CHECK values), the wire
 (`pkg/fbs` `variant:string`, regenerate FB) and the UI (`lib/model.ts` union, `variants.ts`,
 fixtures, premium/alphabet keys, tests); i18n display keys stay display-only. Tidy
 `../scrabble-dictionary` to a single source→dawg build point and align the dawg artifact
 names to the new labels (crosses into `../scrabble-solver`'s committed fixtures — keep them
 byte-identical). After merge, **wipe the contour DB** (drop the volume) so it re-provisions
 on the next deploy.
 - Critical files: `backend/internal/postgres/migrations/`,
  `backend/internal/engine/{engine,registry}.go`, `pkg/fbs/scrabble.fbs`,
  `ui/src/lib/{model,variants}.ts`, `../scrabble-dictionary/{Makefile,cmd/builddict,…}`.
 - Open details to interview: the exact dawg filename scheme; whether the dict-repo tidy is
  one PR or split; how to script the contour DB wipe in the deploy.
 ### R2 — Stress harness + contour observability + early run *(TODO 9, part 1)*
 Build the reusable load harness as a new `loadtest` module in `go.work` (reuses `pkg/fbs`,
 `connect-go`, and `scrabble-solver` for legal-move generation): a seeder that inserts
 **1000 guest + 10000 durable** accounts with pre-created sessions (token hashes) directly in
 the DB and hands the plaintext tokens to the client; a driver that runs N virtual users,
 each in 3–5 concurrent 2–4-player games, exercising submit-play / pass / exchange / nudge /
 chat / check-word / draft-move / profile-save through the **edge protocol**, in
 **realistic** (under rate limits) and **saturation** (ramp) modes; plus a separate
 **gateway-hammer** that deliberately exceeds limits to verify the limiter holds and measure
 its cost. Add **cAdvisor + postgres_exporter** to `deploy/docker-compose.yml` and a Grafana
 resource dashboard. Run the **early pass** against the freshly-wiped contour; produce a
 **trip report** (logic/concurrency bugs + a resource baseline) that feeds R3 and R6.
 - Critical files: new `loadtest/`, `deploy/docker-compose.yml`, `deploy/observability/*`,
  `docs/TESTING.md`.
 - Open details: the scale ramp steps; the move-selection policy (a mid-ranked solver move
  for realistic game progress); run duration; the pass/fail bar.
 ### R3 — Edge hardening *(TODO 2 + 8 + 3)*
 Add a **request-body size cap** at the gateway h2c mux / `Execute` (e.g. ~1 MB). Add
 **rate-limit observability**: a `gateway_rate_limited_total{class}` counter + a structured
 log per rejection; an **aggregate** Grafana panel (request rate + rejection rate — spikes
 visible without per-user label cardinality, honouring the Stage 12/17 discipline); an
 **admin-console view** of recently throttled users/IPs (in-memory ring buffer, single-
 instance, reset-on-restart, like the `active_users` gauge). Add the **conservative
 auto-flag**: when a user is *sustained*-throttled past a tunable threshold, set a soft,
 reversible `account.flagged_high_rate_at` marker (baked into the R1 baseline) surfaced in the
 admin user list/detail — **no auto-ban**; the operator clears it. Split the **landing** into
 its own static container (`deploy/` + a Caddyfile route `/` → landing) and drop
 `landing.html` from the gateway `go:embed`.
 - Critical files: `gateway/internal/connectsrv/server.go`, `gateway/internal/ratelimit/`,
  `gateway/internal/connectsrv/metrics.go`, `backend/internal/adminconsole/`,
  `deploy/caddy/Caddyfile`, `deploy/docker-compose.yml`, `gateway/internal/webui/`.
 - Open details: the auto-flag threshold/window + whether the marker is persisted vs
  in-memory; the landing image base (caddy vs nginx).
 ### R4 — Push enrichment + kill the last poll *(TODO 4 + 5)*
 Replace `lobby.poll` with the existing `match_found` push (keep the poll as a ws-down
 fallback). Enrich `your_turn`/`opponent_moved`/`notify` to carry the state payload so the UI
 renders from the event without a follow-up `game.state` (removes the lobby↔game nav latency
 the owner noticed). Wire-contract change: `pkg/fbs` event payloads → backend `notify` emit →
 UI stream consumers (`ui/src/lib/app.svelte.ts`), with the per-game cache as the landing
 spot; regenerate FB.
 - Critical files: `pkg/fbs/scrabble.fbs`, `backend/internal/notify/events.go`,
  `ui/src/lib/{app.svelte,transport}.ts`, `ui/src/screens/NewGame.svelte`.
 - Open details: which events carry full vs delta payloads; the fallback-poll cadence when the
  stream is down.
 ### R5 — Bundle slimming *(TODO 6)* — done
 Analysed the bundle against the 100 KB-gzip budget; **no code slimming was warranted**, and the
 budget metric was retargeted to measure the app correctly. The build already minifies +
 tree-shakes; the dominant cost is the Connect/FlatBuffers transport runtime + generated bindings
 + the Svelte runtime (≈⅔ of `main`'s source is third-party/generated) — irreducible within scope.
 **Lazy-loading was rejected**: `bundle-size.mjs` sums every emitted chunk, so code-splitting yields
 no total-size win and adds request latency (+N gateway fetches on first navigation to a split
 screen). i18n lazy-load was skipped (the catalogs are a sliver of a Svelte-runtime-dominated shared
 chunk, and `en` must stay bundled as the `MessageKey` type source + fallback). Instead,
 `bundle-size.mjs` now measures **per HTML entry**, with three independent gates on the natural chunk
 boundaries — **app entry ≤ 100 KB, the Svelte+i18n shared chunk ≤ 30 KB, the landing's own chunk
 ≤ 5 KB** — since the app's real payload is its entry chunk plus the shared chunk (≈97 KB), while the
 landing (≈24 KB) is reported separately and kept minimal. Same CLI + exit-code contract, so the CI
 step is unchanged.
 - Critical files: `ui/scripts/bundle-size.mjs`; no app code changed.
 ### R6 — Refactor + docs reconciliation + de-staging *(TODO 7)* — done
 Behaviour-preserving only. Three separable, separately-committed passes: (a) mechanical
 **de-staging** — remove `Stage N`/`TODO-N` references from code, comments and service
 READMEs (rename `stage6_test.go`); (b) **docs↔code reconciliation** — reconcile
 `docs/ARCHITECTURE.md` / `docs/FUNCTIONAL.md`(+`_ru`) against the code-as-truth, fixing drift
 and Go Doc comments; (c) **structural changes by a reviewed list** — surface a list of
 proposed optimizations / test-suite consolidations to the owner, apply only the approved,
 behaviour-preserving, test-gated ones. The full suite + the final stress run (R7) are the
 regression gate. Incorporates the early-run (R2) bug fixes not already shipped.
 - Open details: the structural-changes list itself (owner-approved before applying); the test
  consolidation targets.
 ### R7 — Final stress run + tuning *(TODO 9, part 2)* — done
 Re-run the R2 harness against the final, refactored system on a clean contour; analyse
 resource consumption across **all** components (gateway, backend, Postgres, the
 metrics/observability stack, docker log volume) and agree the tuning (pool sizes, rate
 limits, cache TTLs, container limits, GOMAXPROCS, log levels). Apply the agreed tuning; record
 the methodology + results in the repo.
 → **Stage 18** (prod contour) then proceeds per [`PLAN.md`](PLAN.md).
 ## Sequencing rationale
 `R1` first (cheapest now; everything builds on the final schema/naming and the stress test
 must run against it). `R2` builds the harness and runs the **early** pass to surface bugs and
 a resource baseline that feed `R3` and `R6`. `R3`/`R4`/`R5` harden and improve the system.
 `R6` (de-stage + reconcile + structural) runs near the end so it sweeps settled code once and
 benefits from all accumulated bug knowledge. `R7` validates the final system and tunes it.
 Then Stage 18.
 ## Regression-safety discipline (cross-cutting)
 - Every phase is a `feature/* → development` PR; CI (`unit` + `integration` + `ui` behind the
  `CI / gate` check) must be green before the owner merges; watch the post-merge contour
  deploy with `gitea-ci-watch.py`.
 - `R6` structural changes are behaviour-preserving, test-gated, and split from the mechanical
  sweeps; contentious items are owner-approved first.
 - The two stress runs (`R2` early, `R7` final) are the system-level regression gate.
 ## Verification (per phase)
 - `go build ./<module>/...`, `go vet`, `gofmt -l .` clean, `go test -count=1 ./<module>/...`;
  UI: `pnpm check && pnpm test:unit && pnpm build`; the integration suite
  (`-tags integration`) for DB/schema changes; `docker compose config` for deploy changes;
  green CI on the PR + a healthy contour deploy.
 - `R1`: prove the squashed baseline yields a schema identical to the 12-migration chain
  (integration suite on a fresh DB) **before** deleting the old files.
 - `R2`/`R7`: the harness runs end-to-end against the contour; the trip report lists concrete
  defects + a resource profile from the Grafana cAdvisor/postgres_exporter panels.
 ## Refinements logged during implementation
 - **R1** (interview + implementation):
  - **Variant labels** `english`/`russian_scrabble`/`erudit` → **`scrabble_en`/`scrabble_ru`/`erudit_ru`**
    across the backend (`engine.Variant.String`/`ParseVariant`; the `games`/`game_invitations` `variant`
    CHECK in the baseline; GCG `#lexicon` and the `variant` metric attribute both flow from `String`),
    the wire (`pkg/fbs` `variant` is a `string` field — values change with **no FlatBuffers regen**) and
    the UI (`model.ts` union, `variants.ts` records, `codec`/`premiums`/mocks/tests, the admin
    `dictionary.gohtml`). **Kept:** the Go enum identifiers (`VariantEnglish`…, internal) and the i18n
    display keys (`new.english`/`new.russian`/`new.erudit`, display-only). `complaints.variant` stays
    free-text (no CHECK, as before).
  - **dawg filenames kept descriptive** (`en_sowpods`/`ru_scrabble`/`ru_erudit`) — only the registry's
    `Variant` key carries the rename, so `registry.go`, the published `scrabble-solver` fixtures and the
    dictionary release artifact are untouched (decouples the three repos).
  - **Migrations squashed** 12 → one hand-written `00001_baseline.sql`. Verified by a
    `pg_dump --schema-only` diff (the chain vs the baseline are **identical** but for the two intended
    variant-CHECK values) plus the green integration suite. **No data migration** (no production data).
  - **Done (cross-repo + contour):** the **`scrabble-dictionary` tidy** merged (PR #2) and was re-cut as
    the **byte-identical `v1.0.1`** release for clean provenance (the backend stays on `v1.0.0` — same
    bytes, no rewire; the backend pulls a version-pinned release artifact, not master). Post-merge the
    contour `backend` schema was wiped (`DROP SCHEMA backend CASCADE` + restart, not a volume drop) and
    re-migrated to the baseline — verified the new variant CHECK (`scrabble_en/scrabble_ru/erudit_ru`),
    `games`=0 and a clean boot.
 - **R2** (interview + implementation):
  - **Locked decisions:** game assembly via **invitations** (real path, no robots; not direct game-row
    inserts); **moderate** ramp **50 → 200 → 500** at 10 min/step; **diagnostic** pass bar (no SLO gate);
    run as a **one-shot container on `scrabble-internal`** in this PR.
  - **Harness** = new `scrabble/loadtest` module (`use ./loadtest` + a `replace scrabble/gateway` for the
    dot-free edge-proto import). It seeds 1000 guest + 10000 durable accounts + sessions **directly in
    Postgres** (token hash mirrors `backend/internal/session`), drives players over the **edge protocol**,
    generates **mid-ranked legal moves locally** with the embedded `scrabble-solver` by replaying
    `game.history` (the edge carries no board — mirrors `engine.ReplayBoard` via the public API), and a
    **gateway-hammer**. Compact CLI (`run` / `cleanup`), distroless Dockerfile (DAWGs baked), Go unit tests.
  - **Adding the module broke the other images' builds** — backend/gateway/telegram Dockerfiles reduce the
    workspace but still referenced `./loadtest` (not in their context); each now also
    `-dropuse=./loadtest` (backend/telegram additionally `-dropreplace` the gateway replace). Caught by the
    first deploy run; verified by building all four images.
  - **Harness payload fixes found by the smoke pass:** the draft DTO's `rack_order` is a string (was sent
    as `[]` → `bad_request`); the display-name validator forbids digits/colons, so the cleanup marker
    became a letters-only `Zzloadtest` so `profile.update` resends the seeded name. `chat_not_your_turn` /
    `nudge_own_turn` are **by-design** turn gates, correctly exercised.
  - **Observability:** added **cAdvisor + postgres_exporter** + the **Scrabble — Resources** dashboard +
    two Prometheus jobs. **Finding:** cAdvisor yields only the root cgroup on the contour host (separate
    XFS `/var/lib/docker` breaks its layer-ID resolution — the existing galaxy deploy has the same limit),
    so per-container CPU/RSS for the early pass was captured via `docker stats`. **R7:** adopt the otelcol
    `docker_stats` receiver (already the contrib image) for per-container metrics in Grafana.
  - **Early run (2026-06-09):** ramped clean to 500 players, no crash/deadlock, cleanup removed all 11000
    accounts. 1.2 M edge calls, 48 870 plays, 2 798 games finished; the per-user limiter held under the
    hammer (99.97 % rejected, p99 2 ms). **Top finding:** ~14 % `transport_error` on `game.state` at 500
    players, under CPU saturation (backend/gateway/Postgres each ~1 core) and amplified by the harness's
    single shared `http2.Transport`; the harness itself peaked at 86 % of a core on the same host, so the
    figures are pessimistic. Full trip report in [`../loadtest/REPORT.md`](../loadtest/REPORT.md);
    it feeds R3 (h2c `MaxConcurrentStreams`/timeouts, body-size cap), R6 and R7 (per-player transports,
    separate hardware, pool/limit sizing).
  - **CI:** `./loadtest/...` added to the path filter + vet/build/test; `go.work.sum` carries the new deps.
 - **R3** (interview + implementation):
  - **Locked decisions:** the flag column lands by **editing the R1 baseline** (+ a contour schema
    wipe after merge — no migration chain accrues before prod); auto-flag defaults **1000 rejected /
    10 min** (`BACKEND_HIGHRATE_FLAG_THRESHOLD`/`_WINDOW`, rolling window, set-once, operator clears,
    no auto-ban); landing image = **caddy:2-alpine**; throttle data flows **gateway → backend** (a
    30 s per-key summary POST to the new `/api/v1/internal/ratelimit/report`, the existing trusted
    direction) with the episode window + flag rule in the backend (`internal/ratewatch`); rejection
    logging = **Warn summary per key per window + Debug per rejection** — a deliberate deviation from
    the phase's "structured log per rejection" (the R2 hammer would have logged ~522k lines in
    minutes); all three R2-report tails included (explicit h2c sizing, the session-resolve failure
    cause at Warn, reviving the admin limiter).
  - **Body cap:** `GATEWAY_MAX_BODY_BYTES` (default 1 MiB) as both the Connect per-message read limit
    and an `http.MaxBytesReader` wrap of the public mux; an oversized Execute is `resource_exhausted`.
  - **Dead config found:** `AdminPerMinute`/`AdminBurst` were never wired — the gateway `/_gm` mount is
    now 429-guarded per IP ahead of its Basic-Auth. The caddy-fronted contour path stays unlimited
    (stock caddy has no limiter) — an accepted gap, recorded in `docs/ARCHITECTURE.md` §12.
  - **Landing split:** a `landing` target in `gateway/Dockerfile` (the UI build stage is shared;
    identical compose build args keep it one cached build); the gateway drops `landing.html` from the
    embed and 308-redirects `/` → `/app/`; the contour caddy routes `/app/`, `/telegram/` and the
    Connect path to the gateway and the catch-all to the landing container; the CI deploy probe now
    checks both `/` (landing) and `/app/` (gateway).
  - **Observability:** `gateway_rate_limited_total{class}` (user/public/email/admin, aggregate-only)
    + a rate-vs-rejections panel on the Edge/UX dashboard; the admin console gains the **Throttled**
    page (the in-memory episode window, reset-on-restart like `active_users`, plus the flagged-account
    queue) and the flag badge / clear action on the user list / card.
  - The jet regen also restored the previously missing `game_drafts`/`game_hidden` generated models
    (their tables were added after the last jetgen run; no behaviour change).
 - **R4** (interview + implementation):
  - **Locked decisions:** **delta-first**, not full snapshots — an event carries only the new move and
    the UI applies it to its per-game cache, keyed on `move_count` (idempotent + gap-safe: a gap or the
    actor's own move falls back to a `game.state` + `game.history` refetch). `match_found` /
    `game_started` carry the recipient's **initial `StateView`** (instant lobby→game); the fallback
    refetch stays the existing two calls (no merged endpoint); the matchmaking poll runs **only while
    the stream is down** (2.5 s); **all** UI-state-changing events carry their payload (incl. lobby `notify`).
  - **Enriched events** (`pkg/fbs` trailing fields — backward-compatible, no FB regen of *values*, only
    the schema): `opponent_moved` (+`move`/`game`/`bag_len`), `your_turn` (+`move_count`), `match_found`
    (+`state`), `game_over` (+`game`), `notify` (+`account`/`invitation`/`state`). The pre-R4
    `opponent_moved` scalars (`seat`/`action`/`score`/`total`) stay for wire back-compat, now redundant
    with `move`/`game` — slated for the R6 de-stage.
  - **Encoding placement:** the `notify` package keeps ownership of the FlatBuffers encoding (a new
    `encode.go` mirrors the gateway transcode but reads wire-agnostic `notify.*` input structs +
    `engine.MoveRecord`); the game/lobby/social services map their domain types to those structs, so the
    wire schema stays out of the domain. **Flagged for R6:** this partly duplicates the gateway encoders
    (different source types) — a candidate consolidation.
  - **Actor self-fetch killed too** (beyond literal "push"): the `submit_play`/`pass`/`exchange`/`resign`
    **response** (`MoveResult`) now returns the actor's refilled rack + bag size, so the mover renders the
    next turn from the response — `Game.svelte`'s `commit`/`pass`/`exchange`/`resign` drop their `await load()`.
  - **`match_found` enrichment** needs a per-seat initial state: `lobby.GameCreator` gained `InitialState`,
    and `game.Service.InitialState` builds the `notify.PlayerState` (rack re-encoded to wire indices, the
    variant alphabet embedded for a first-seen variant).
  - **UI:** a pure `lib/gamedelta.ts` reducer (`applyMoveDelta` / `applyGameOver` / `seedInitialState`,
    unit-tested) advances the cache; `app.svelte` seeds it on `match_found` / `game_started`; `Game.svelte`
    applies the delta (falling back to `load()` while composing, on a gap, or on its own move's new rack);
    `NewGame.svelte` polls only when `app.streamAlive` is false and guards its teardown so a push-delivered
    match is not cancelled.
  - **notify (friends/invitations) scope:** the backend carries the full account / invitation payload on the
    wire (per "all events → push"); the UI seeds the game cache from `game_started` but keeps its lightweight
    **authoritative** badge refresh (`refreshNotifications`, on the rare `notify` event + on foreground) rather
    than adding client-side friend/invitation caches — the per-move hot path is fully de-fetched, which was the
    goal. Deeper lobby-cache consumption is an easy follow-up.
  - **No schema change** (no migration); the contour needs no DB wipe. Tests: `notify` FB round-trips +
    `emitMove` delta + the `gamedelta` reducer; the e2e mock now emits the enriched delta.
 - **R5** (interview + implementation):
  - **No code slimming — by analysis.** A gzip measure + sourcemap attribution of the real `dist` showed
    the app bundle is already minified + tree-shaken and dominated by the Connect/FlatBuffers transport
    runtime + generated FB/PB bindings (≈⅔ of `main`'s source) and the Svelte runtime — all
    third-party/generated, irreducible within R5's scope. App-authored code carries no hand-trimmable fat.
  - **Lazy-load rejected** (screens *and* i18n): `bundle-size.mjs` sums every emitted chunk, so
    code-splitting moves bytes between chunks for **zero total-size win** while adding request latency (+N
    gateway fetches on first navigation to a split screen). i18n lazy-load additionally buys ≤3 KB (en-only
    users) at the cost of an async `t()`, and `en` must stay bundled (it is the `MessageKey` type source +
    fallback). **Chunk-collapsing rejected** too — keeping the near-static Svelte runtime in its own
    cacheable chunk is the recommended practice (an app deploy then re-busts only `main`, not the runtime),
    and HTTP/2 makes the extra preload request negligible.
  - **Metric retargeted to the app.** The two-entry build (`index.html` app + `landing.html`) makes Rollup
    hoist the code shared by both (Svelte runtime + i18n + `aboutContent`) into one preloaded chunk, so the
    app actually loads its entry chunk **+ the shared chunk** (≈74 + ≈23 = **≈97 KB**), never `landing.js`
    (≈1.6 KB). The old script summed all three chunks (98.8 KB), over-counting the app by `landing.js`.
    `bundle-size.mjs` now parses each built HTML for the JS it eagerly loads and gates three parts
    independently — **app entry ≤ 100 KB, shared (Svelte+i18n) ≤ 30 KB, landing-own ≤ 5 KB** — reporting the
    app total (≈97) and landing total (≈24.5). Same CLI + exit-code contract, so the CI step is unchanged.
  - **No app/source/build change** (`App.svelte`, `lib/i18n/`, `vite.config.ts` untouched); no schema
    change, no contour wipe. The stale "~82 KB" figure was corrected in `bundle-size.mjs` and `ui/README.md`.
 - **R6** (interview + implementation):
  - **Locked decisions:** apply **both** wire/code structural changes (**B** + **A**) and **only C1+C2** of
    the test consolidation (not C3/C5); strip the `*(Stage N)*` tags from **all current-state docs**
    (ARCHITECTURE / FUNCTIONAL+`_ru` / TESTING / UI_DESIGN), keeping PLAN.md / PRERELEASE.md / CLAUDE.md as
    history; **split `stage6_test.go`** by domain. The `h2cMaxConcurrentStreams` sizing stays an **R7**
    concern (tuning, not behaviour-preserving); the R2 early run forced no code fix, so nothing was carried in.
  - **(a) De-staging:** removed the `Stage N` / `TODO-N` / `(RN)` references across code, comments, service
    READMEs and the current-state docs, rewording narratives to present tense (no technical content lost).
    Renamed the only stage-named identifiers (`registerStage8`→`registerSocialOps`,
    `registerStage11`→`registerLinkOps`) and split `stage6_test.go` (`TestEmailLoginFlow`→`email_test.go`;
    `TestGuestAutoMatchLeavesNoStats`+`provisionGuest`→`account_test.go`). De-staged the `.fbs`/`.proto`
    comments and regenerated: only the `.proto`-derived Go docstrings (`*_grpc.pb.go`, `push.pb.go`) changed —
    flatc strips schema comments, so the FB Go/TS bindings were untouched.
  - **(b) Reconciliation:** the docs were accurate (each R-phase baked its own); the one drift was a stale
    "guest-reaping deferred (TODO-3)" note in `ARCHITECTURE.md` §3 — guest reaping is implemented, so the
    note was replaced with the current behaviour (FUNCTIONAL/TESTING already described it).
  - **(c) B — dead `opponent_moved` scalars:** removed `seat/action/score/total` from `OpponentMovedEvent`
    (`pkg/fbs/scrabble.fbs` + the `notify` emit + the round-trip test); regenerated FB Go + TS. No reader
    used them (the UI codec/mock take `move`/`game`/`bag_len`; the gateway forwards the payload verbatim).
    A pre-release wire-slot renumber — free with no prod data, no DB change.
  - **(c) A — shared FB builders:** new `scrabble/pkg/wire` holds the single definition of the nested wire
    tables (GameView / MoveRecord / StateView / AccountRef / Invitation) shared by the backend `notify`
    encoder and the gateway `transcode`; both map their own source types to neutral `wire.*` structs and
    delegate. **Honest tradeoff:** the verbose `Start/Add/End` + reverse-prepend boilerplate is now written
    once, but the field *set* is still mapped per side, and the new package makes the change net **+~145 LOC**
    — a single-source / anti-drift win for the fiddly mechanics rather than a line-count cut. Behaviour-
    preserving: the two sides' field sets were verified identical and the round-trip tests pass unchanged.
  - **(c) C1+C2 — inttest fixtures:** moved the cross-file service/game fixtures (`newGameService` was used by
    10 files) into `backend/internal/inttest/helpers.go`; single-file helpers stay local. Pure relocation.
  - **No schema change → no contour DB wipe.** Regression gate: the full unit + integration + UI suites plus
    the R7 stress run.
 - **R7** (interview + implementation):
  - **Locked decisions:** run the harness **same-host** (one-shot container on `scrabble-internal`, capped
    `--cpus=3` so the contour keeps spare cores); **apply container limits + `GOMAXPROCS` now** (not just a
    prod recommendation); **replace cAdvisor with the otelcol `docker_stats` receiver** (it resolved only the
    root cgroup on this host); keep rate-limit / h2c knobs **compiled-in** (change values only if the data
    demands — it did not).
  - **Harness refinements (pre-run):** each virtual player builds its **own `edge.Client`** (its own h2c
    connection for its Subscribe stream + Execute calls) instead of all players sharing one `http2.Transport` —
    the R2 `transport_error` artifact; and `playTurn` now reports a **finished** game so the player drops it
    from rotation. Effect, measured: `game.state` `transport_error` 14 % (R2) → **2.49 %**; `game_finished` on
    chat ≈ 3 900 → **35**.
  - **Observability:** added the `docker_stats` receiver to `otelcol` (`api_version: "1.44"` — the daemon's
    minimum is 1.40; the receiver defaults to 1.25 and crash-looped until pinned), mounted the docker socket
    read-only with `group_add` (the contrib image runs as UID 10001), dropped the cAdvisor service + its
    Prometheus job, and retargeted the **Scrabble — Resources** dashboard to the docker_stats metric names
    (`container_cpu_utilization`/100 == cores). Cross-checked against `docker stats` within sampling error.
  - **Profile (final run, 500 players, limits in force):** the **gateway is the binding constraint** — with
    one connection per player it bursts into its 2-core cap (the residual 2.49 % `transport_error`); backend
    ~0.85 core and postgres ~1.4 cores had headroom; **tempo reached its 1 GiB cap**; the backend pool sat at
    its `MaxOpenConns=25` cap (28 backends); docker logs were unbounded (~14 MiB / 30 min on the backend at
    info). Full write-up in [`../loadtest/REPORT.md`](../loadtest/REPORT.md). *(Superseded in part: a
    later pass modelling the `game.evaluate` hot path traced the gateway's CPU appetite to
    **gateway→backend connection churn** — the default 2-idle-connection HTTP transport — not proxying
    work. Pooling the connections cut peak gateway CPU ~7× (~1.75 → ~0.26 cores at 500 players) and
    removed the ephemeral-port-exhaustion cliff behind the residual `transport_error`, so the gateway is
    no longer the binding constraint — postgres is. The 3-core gateway cap below is now generous headroom.)*
  - **Round-2 tuning (owner-agreed, all in `deploy/docker-compose.yml`, no code change):** gateway **2 → 3
    cores + `GOMAXPROCS=3`**; tempo memory **1 → 2 GiB**; backend `MAX_OPEN_CONNS` **25 → 40**; a json-file
    **log-rotation** default (10m × 3) applied contour-wide via a YAML anchor (level stays info).
    backend/postgres kept at 2 cores / 512 MiB (headroom is cheap on the shared host).
  - **Validation:** the same gradual ramp on the tuned contour cut `game.state` `transport_error` to **0.72 %**
    (gateway ~2 cores, now under the 3-core cap, no throttle; tempo ~1.27 GiB, under 2 GiB). A separate
    **burst** run (a single 100 → 500 jump) pegged the gateway at 3 cores (≈296 % sustained, 9.27 % error),
    confirming it is **connection-CPU-bound** — a true arrival spike is a **horizontal-scaling** lever, not
    more cores per node (recorded in the prod-sizing recommendation).
  - **No schema change → no contour DB wipe.** Bake-back: `loadtest/REPORT.md`, `loadtest/README.md`,
    `docs/TESTING.md`, the telemetry/observability section of `docs/ARCHITECTURE.md`, the repo-layout line in `CLAUDE.md`.
 - **UI — Tab-bar navigation redesign** (owner ad-hoc, not on the raw TODO list): drop the hamburger
  `Menu.svelte` everywhere (it fought the Telegram-fullscreen layout, where it had to be re-centred).
  - **Locked decisions (interview):** the in-Settings sub-nav is a **bottom TabBar with the active tab
    highlighted** (icon-only); **Export GCG** moves to the left slot of the move-history header (free in a
    finished game, where 🏁 *leave* does not apply); the lobby **⚙️ badge counts incoming friend requests
    only** (invitations keep their own lobby section); unread chat is badged on **the score bar and the 💬**.
  - **What shipped:** a ⚙️ **Settings hub** (`screens/SettingsHub.svelte`) over the existing
    Settings/Profile/Friends/About bodies and an in-game **comms hub** (`game/CommsHub.svelte`) over
    chat + dictionary, both with in-place tabs and a fixed back target; the game's menu items relocate into
    the open move history (🏁 leave / 📤 export + 💬 comms header) and the player cards (🤝 add-friend); a
    shared **TapConfirm** (`components/TapConfirm.svelte`, `lib/tapconfirm.ts`) — tap → fading ✅ → tap —
    replaces the Skip/Hint press-and-hold popovers and drives the add-friend confirm. Fixed the move-history
    "jump" bug (the slid board is now inert and the stage can't scroll, so a swipe up genuinely closes it).
    `Menu.svelte` + `HoldConfirm.svelte` removed.
  - **No schema/wire change → no contour DB wipe.** Bake-back: `docs/UI_DESIGN.md`, `docs/FUNCTIONAL.md`
    (+`_ru`). Regression gate: UI `check` + unit (`tapconfirm`) + build + bundle budget + e2e (Chromium &
    WebKit), all green.
 - **UI — Merge Exchange/Pass; drop the dead Tournaments tab** (owner ad-hoc, not on the raw TODO
  list): the lobby's 🏆 *Tournaments* tab was an inert `lobby.soon` toast — removed (the lobby is back
  to three tabs, matching `docs/FUNCTIONAL.md`). In-game the separate 🥺 *Skip* (pass) tab folds into
  the 🔄 tab, now **Exchange/Pass**, whose dialog passes when no tile is selected and exchanges when
  tiles are.
  - **Decision — a pass is NOT an exchange of zero (verified against the rules + GCG):** the merge is
    **UI-only**. Pass and exchange stay distinct game actions end-to-end — wire (`GameActionRequest` vs
    `ExchangeRequest`), engine (`ActionPass` vs `ActionExchange`), and the GCG Poslfit dialect (a pass is
    a bare `-`, an exchange is `-TILES`). The engine forbids a zero-tile exchange (`ErrNothingToExchange`)
    and allows an exchange only with a full rack left in the bag (`ErrNotEnoughTilesToExchange`), while a
    pass is always legal — collapsing them would lose a real distinction. The dialog dispatches the
    existing `gateway.pass` / `gateway.exchange`.
  - **What shipped:** `Lobby.svelte` (tab removed); `Game.svelte` (one 🔄 Exchange/Pass tab no longer
    gated on an empty bag; the dialog disables tile selection while the bag is below a full rack
    (`bagLen >= RACK_SIZE`), its confirm button reading **Pass without exchanging** / **Exchange N**);
    i18n (`game.draw` → Exchange/Pass, new `game.passNoExchange`, dropped `game.skip` /
    `lobby.tournaments` / `lobby.soon`). No backend/wire/history/GCG change.
  - **No schema/wire change → no contour DB wipe.** Bake-back: `docs/UI_DESIGN.md`, `docs/FUNCTIONAL.md`
    (+`_ru`). Regression gate: UI `check` + unit + build + bundle budget + e2e (Chromium & WebKit).
 - **AI — Honest AI opponent in quick game** (owner ad-hoc, not on the raw TODO list): a second quick-game
  opponent the player *knowingly* chooses, distinct from the disguised robot of the random/open path
  (which is kept as-is). New Game's quick-game mode replaces the "auto-match" subtitle with a two-button
  selector **🤖 AI / 👤 Random player** (the `.seg`/`.opt` segmented style, AI the default); for AI the
  move-clock line reads "Loss after 7 days of inactivity" and the "searching" hint is hidden.
  - **Locked decisions (interview):** AI move is **event-driven** (the robot replies the instant the
    player's move commits; the 30 s driver is the fallback); AI games **do not touch `account_stats`**
    (practice, like guests); the **Stage 5 strength logic is reused unchanged** (`playToWin` 40 % from the
    seed + margin band); **no per-move timeout — a 7-day inactivity loss** instead; the 7-day line lives on
    the New Game screen (the in-game screen has no move-clock line); chat + nudge **disabled**, word-check
    kept, add-friend never drawn, opponent shown as **🤖** everywhere.
  - **The 7-day rule reuses the existing per-turn timeout:** an AI game is created with
    `turn_timeout_secs = AIInactivityTimeout` (7 days) and the existing timeout sweeper resigns the overdue
    seat — since the robot moves at once, only the human is ever on the clock, so the per-turn timeout *is*
    the abandon rule (no new column, no new sweeper).
  - **One game flag drives everything:** `games.vs_ai` (edited into the R1 baseline — pre-release, so a
    contour DB wipe after merge). It is set **only** on AI-started games, so a robot-filled random game keeps
    `vs_ai=false` and the disguised opponent is never revealed; the UI derives 🤖 / the gates **from the flag,
    never from the opponent account**. New backend path `Matchmaker.StartVsAI` (picks a pooled robot via the
    existing `Pick`, creates an **active** seated game via `game.Service.Create`, random seat order) — the AI
    request never enters the open pool, so the open-game reaper never touches it. The robot driver gains a
    `vs_ai` branch (no sleep, no proactive nudge, zero delay) and a focused `DriveGame`/`TriggerMove` fast
    path wired from the game service's after-create/after-commit hook (`SetAITrigger`, a func value so the
    game package never imports the robot package). Chat/nudge gated by a new `social` `VsAI` check
    (`ErrGameVsAI` → 409 `ai_game`); statistics skipped in `commit` when `vs_ai`.
  - **Wire:** `EnqueueRequest` += `vs_ai`, `GameView` += `vs_ai` (trailing FB fields, regenerated Go + TS),
    threaded through the backend DTO, the gateway transcode and the `pkg/wire` + `notify` builders.
  - **Tests:** `lobby` unit (StartVsAI seats a robot + flags the game; empty pool leaves no game); backend
    integration (`ai_game_test.go`: active+seated+vs_ai+7-day clock, robot moves immediately, stats skipped,
    7-day timeout resigns the human, chat/nudge rejected); UI codec round-trip (`vs_ai` on enqueue + game
    view); e2e (an AI game shows 🤖, no "searching", chat disabled, the dictionary still works) + the
    existing quick-match e2e updated to pick **Random player** (the default is now AI).
  - **Schema/wire change → a contour DB wipe** after merge (`DROP SCHEMA backend CASCADE` + restart, the
    R1/R3 pattern). Bake-back: `docs/ARCHITECTURE.md`, `docs/FUNCTIONAL.md` (+`_ru`), `docs/UI_DESIGN.md`,
    `backend/README.md`, Go Doc comments.
  - **Post-review refinements (owner, same PR):** (1) the **GCG export labels the robot seat "AI"** rather
    than its human-like pool name (`ExportGCG` overrides the name via `accounts.IsRobot`; the in-app 🤖 is
    unchanged); (2) honest-AI games **emit no `your_turn`** — the robot replies instantly, so the signal
    would arrive with the move and be pointless; `opponent_moved` still advances the UI; (3) the **admin
    console surfaces the AI flag** — a **🤖 column** in `/games` and an "AI game" line on the game card
    (`GameRow`/`GameDetailView` gain `VsAI`); (4) `games_started_total` / `games_abandoned_total` gain a
    **`vs_ai`** attribute and the Grafana *Game domain* dashboard splits started/abandoned into **human**
    and **AI** panels.
  - **Follow-up (separate PR — strategy deviation):** the robot now plays **≈20%** of opening/midgame moves
    *against* its per-game `playToWin` intent (toward the opposite margin band — a winning robot eases off, a
    losing one surges ahead), tapering linearly to **0 over the last 14 bag tiles** and **0 once the bag is
    empty**, so the endgame follows the chosen strategy strictly while earlier outcomes can swing the human's
    way. Deterministic from the seed (`mix(seed,"deviate",moveCount)`), applied to **both** robot paths via
    the shared `selectMove`; the per-game intent (and the admin card) is unchanged. Tests: `robot` unit
    (taper bounds + monotonicity, never-in-endgame, determinism, ~20% distribution). Bake-back:
    `docs/ARCHITECTURE.md` §7, `docs/FUNCTIONAL.md` (+`_ru`), `backend/README.md`, `PLAN.md` Stage 5.
 - **GL — Simultaneous quick-game cap** (owner ad-hoc, not on the raw TODO list): a player may hold at
  most **10** active quick games; at the cap the lobby greys **New Game** and shows a plain notice
  "Вы достигли лимита одновременных партий", both clearing automatically when an active game finishes.
  - **Locked decisions (interview):** what counts = active **+** open (searching) quick games, **including
    AI** (`vs_ai`); friend games (invitation-linked) **never** count. The backend gate refuses **all** new-game
    creation at the cap — `lobby/enqueue` **and** `invitations` — with **409 `game_limit_reached`**; **accepting**
    an invitation is never gated, so friend games are capped "from the other end". Delivery = a boolean
    **`at_game_limit`** on the existing `games.list` (no per-event payload: a turn change does not move the count,
    and the lobby already re-fetches `games.list` on entry + every game event); the first uncached lobby frame
    defaults the button **enabled** (the backend gate is the authority).
  - **What shipped:** `game.MaxActiveQuickGames` + `Store/Service.CountActiveQuickGames` (active/open seats, no
    `game_invitations` row; hidden games still count → a dedicated count, not a filter over the lobby list);
    `Server.atGameLimit`/`ensureUnderGameLimit` gating `handleEnqueue` + `handleCreateInvitation`;
    `gameListDTO.at_game_limit`; the FB `GameList` trailing `at_game_limit` (regenerated Go + TS) threaded through
    the gateway transcode + UI codec; `lib/model` + `lobbycache` snapshot + `Lobby.svelte` (disabled tab + a muted
    `.limit` notice); i18n `lobby.limitReached` (en authoritative + ru).
  - **Caveat (logged):** the gate is a pre-check, not transaction-atomic — concurrent creates from one account could
    momentarily exceed by 1–2 (harmless soft cap; the UI disables the button regardless). Strict atomicity was judged
    a disproportionate diff across the two create paths.
  - **No schema change → no contour DB wipe** (only a trailing FB field, no migration). Tests: backend integration
    (`game_limit_test.go`: count rule + HTTP gate 409 + accept bypass), server unit (error mapping), gateway
    transcode round-trip, UI codec + lobbycache unit, e2e (`gamelimit.spec.ts`). Bake-back: `docs/FUNCTIONAL.md`
    (+`_ru`), `docs/ARCHITECTURE.md` §8, `docs/UI_DESIGN.md`, `backend/README.md`.
 - **CM — Channel-chat moderation + promo bot** (owner ad-hoc, not on the raw TODO list):
  - **Locked decisions (interview):** the promo bot is a **goroutine in `cmd/bot`** (its own token, no
    bot-link); the moderated chat's default-no-send is configured by a **human** in the group settings (the
    bot only grants, never `setChatPermissions`); a non-eligible joiner is **left muted silently**; a
    temporary-suspension expiry is handled by a **backend sweeper** that emits the re-evaluate event; and a new
    **`chat_muted` role** is a chat-only mute with the **game suspension dominating**
    (`eligible = registered AND NOT suspended AND NOT chat_muted`).
  - **Bot API reality (verified against the docs):** a cross-bot Mini App launch must be a **URL button** to the
    main bot's `t.me/<bot>?startapp` link — a `web_app` button signs initData with the *sending* bot's token,
    which the main validator rejects — so the promo button reuses the UI's `VITE_TELEGRAM_LINK`. `chat_member`
    updates arrive **only** when the bot is a chat **admin** with the "Ban users" right (the client label for the
    Bot API `can_restrict_members`) and `chat_member` is in `allowed_updates`; bots cannot list members but can
    `getChatMember` a single user, which is the membership guard on the block/unblock path.
  - **Wire:** `pkg/proto/botlink/v1` gains a `ChatGateCommand` in the `Command` oneof and a unary
    `ResolveChatEligibility`; the backend gains `notify.KindChatAccessChanged` (no payload, infra-only — never an
    out-of-app message) and an internal `POST /api/v1/internal/chat-access` resolver; the gateway resolves the
    join (by external_id) and the event (by user_id) through it and pushes the chat-gate command fire-and-forget
    (at-most-once, recovered by the next moderation action or a re-join).
  - **No schema change → no contour DB wipe:** `chat_muted` is a new `account.KnownRoles` entry (the
    `account_roles` table is data-driven). The suspension-expiry sweeper is a new `account.SuspensionSweeper`
    (a 1-minute window, idempotent) started in `cmd/backend`, alongside the guest reaper.
  - **Deploy:** new `TEST_`/`PROD_` `TELEGRAM_PROMO_BOT_TOKEN` (secret), `TELEGRAM_BOT_USERNAME` and
    `TELEGRAM_CHAT_ID` (variables); the promo link reuses the existing `*_VITE_TELEGRAM_LINK` variable as
    `TELEGRAM_BOT_LINK`. The bot must be promoted to admin in the real discussion group, and the group default
    set to no-send, as part of the Stage 18 prod cutover (the test contour exercises the code path).
  - **Bake-back:** `docs/ARCHITECTURE.md`, `docs/FUNCTIONAL.md` (+`_ru`), `platform/telegram/README.md`,
    `backend/README.md`, Go Doc comments. Tests: backend resolver truth table + publish on block/unblock/role +
    the sweeper window (unit + integration); gateway hub `ResolveChatEligibility` + the chat-gate command; bot
    `chat_member` grant + `ApplyChatGate` getChatMember-guard; promo `/start` localization + URL button; config
    parsing.
  - **Post-contour-test fixes (same PR):** a live test drove three corrections. (1) **Strategy
    inversion (the key one)** — the original "group default no-send, bot grants the eligible" cannot
    work: Telegram intersects the chat default with each user's permission, so a per-user grant never
    exceeds a deny-by-default group (the bot set `can_send=true` yet the user still could not write).
    The group now **allows sending by default** and the bot only **restricts** — it mutes an ineligible
    member (unregistered / admin-suspended / `chat_muted`) and un-mutes an eligible one it had muted,
    acting only when the current state differs (idempotent; the bot's own change is skipped by matching
    the actor id to the bot). A present member in a default-allow group can appear as `restricted` with
    `is_member`, so the gate reads both. (2) **Join-before-register** — a user who joins before
    registering is covered by no `chat_member` event, so `ProvisionTelegram` now reports first contact
    and the Telegram auth handler emits `chat_access_changed` on it. (3) **Observability** — a startup
    self-check logs whether the bot is an admin-with-restrict in the chat (it caught a misconfigured
    `TELEGRAM_CHAT_ID` set to a channel id, not the discussion-group id); the per-event trace is at
    Debug, the actual mute/unmute and warnings at Info.
@@ -22,9 +22,8 @@ supports English Scrabble, Russian Scrabble and Эрудит.
  security, cross-service contracts.
 - [`docs/FUNCTIONAL.md`](docs/FUNCTIONAL.md) (+ [`_ru`](docs/FUNCTIONAL_ru.md)) —
  per-domain user stories.
- [`docs/TESTING.md`](docs/TESTING.md) — test layers and the per-stage CI gate.
+- [`docs/TESTING.md`](docs/TESTING.md) — test layers and the CI gate.
- [`PLAN.md`](PLAN.md) — the staged implementation plan and stage tracker.
+- [`CLAUDE.md`](CLAUDE.md) — project guide and development workflow.
 - [`CLAUDE.md`](CLAUDE.md) — project guide and the mandatory per-stage workflow.
 ## Build & test
@@ -90,7 +89,7 @@ observability stack (OTel Collector → Prometheus + Tempo → Grafana) + a fron
 services build from multi-stage distroless `*/Dockerfile`.
 ```sh
-docker build -f backend/Dockerfile -t scrabble-backend .   # pulls the DAWG release artifact
+docker build --build-arg DICT_VERSION=v1.3.0 -f backend/Dockerfile -t scrabble-backend .  # DICT_VERSION required; pulls that DAWG release artifact
 docker build -f gateway/Dockerfile -t scrabble-gateway .   # node stage builds + embeds the UI
 docker compose -f deploy/docker-compose.yml config         # validate (needs the TEST_/PROD_ env)
 ```
@@ -7,12 +7,14 @@
 # (GOPRIVATE), so the build stage needs git and network.
 #
 # Build from the repository root so go.work, go.work.sum, pkg/ and backend/ are all
-# in the Docker context:
+# in the Docker context. DICT_VERSION has no default — the caller supplies the
-#   docker build -f backend/Dockerfile -t scrabble-backend .
+# scrabble-dictionary release tag (compose/CI pass it; see deploy/README.md
 # "Bumping the dictionary version"):
 #   docker build --build-arg DICT_VERSION=v1.3.0 -f backend/Dockerfile -t scrabble-backend .
 # --- dictionary artifact -----------------------------------------------------
 FROM alpine:3.20 AS dawg
-ARG DICT_VERSION=v1.2.1
+ARG DICT_VERSION
 RUN apk add --no-cache curl tar
 RUN mkdir -p /dawg \
 && curl -fsSL -o /tmp/dawg.tar.gz \
@@ -33,14 +35,16 @@ COPY backend ./backend
 # Reduce the workspace to what the backend needs: backend + pkg. loadtest and the
 # gateway replace it requires are not in this context, so drop both.
 RUN go work edit -dropuse=./gateway -dropuse=./platform/telegram -dropuse=./loadtest -dropreplace=scrabble/gateway@v0.0.0
-RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -o /out/backend ./backend/cmd/backend
+# VERSION (the deploy passes the git tag) is stamped into the binary via the linker.
 ARG VERSION=dev
 RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "-X scrabble/pkg/version.Version=${VERSION}" -o /out/backend ./backend/cmd/backend
 # --- runtime -----------------------------------------------------------------
 FROM gcr.io/distroless/static-debian12:nonroot
 # Re-declare the build arg in this stage so it labels the seed dictionary. One
 # DICT_VERSION drives both the artifact the dawg stage downloads and the version
 # label the binary pins, so the resident version equals the release tag.
-ARG DICT_VERSION=v1.2.1
+ARG DICT_VERSION
 COPY --from=build /out/backend /usr/local/bin/backend
 # Own the seed dictionary as the nonroot runtime user (UID 65532): a named volume
 # mounted at /opt/dawg inherits this ownership on first use, so the admin console
@@ -228,7 +228,7 @@ internal/banview/    # gateway active-ban mirror: the console's Active IP bans p
 ```sh
 docker run -d --name scrabble-pg -e POSTGRES_PASSWORD=dev -p 5432:5432 postgres:17-alpine
 # DAWGs: extract the dictionary release artifact (or point at a local scrabble-solver/dawg):
-mkdir -p /tmp/dawg && curl -fsSL https://gitea.iliadenisov.ru/developer/scrabble-dictionary/releases/download/v1.2.1/scrabble-dawg-v1.2.1.tar.gz | tar xz -C /tmp/dawg
+mkdir -p /tmp/dawg && curl -fsSL https://gitea.iliadenisov.ru/developer/scrabble-dictionary/releases/download/v1.3.0/scrabble-dawg-v1.3.0.tar.gz | tar xz -C /tmp/dawg
 BACKEND_POSTGRES_DSN='postgres://postgres:dev@localhost:5432/postgres?search_path=backend&sslmode=disable' \
  BACKEND_DICT_DIR=/tmp/dawg \
  GOPRIVATE='gitea.iliadenisov.ru/*' \
@@ -3,8 +3,8 @@
 // loads the dictionaries into the engine registry, warms the session cache,
 // constructs the game domain and starts its turn-timeout sweeper, constructs the
 // lobby and social domains, then serves the HTTP listener with the infrastructure
-// probes and the /api/v1 route-group skeleton. Domain HTTP endpoints are added
+// probes and the /api/v1 route group, behind which the domains expose their HTTP
-// with the gateway in a later stage described in PLAN.md.
+// endpoints to the gateway.
 package main
 import (
@@ -207,10 +207,11 @@ type provisionSeed struct {
 // telegramSeed derives the create-time seed from Telegram launch fields: a
 // supported preferred language from languageCode (an ISO-639 code, possibly
-// region-tagged like "ru-RU"), and a display name sanitized from firstName or,
+// region-tagged like "ru-RU"), and a display name. The name precedence is the real
-// failing that, username (sanitizeDisplayName strips disallowed characters to the
+// name (firstName, sanitized to the editable format) → the @username taken verbatim
-// editable format). When neither yields any letters, it falls back to a generated
+// (already a valid handle, only trimmed and length-capped, never character-stripped)
-// placeholder in the seeded language (placeholderDisplayName).
+// → a generated placeholder in the seeded language (placeholderDisplayName), reached
 // only when firstName has no usable letters and no username is set.
 func telegramSeed(languageCode, username, firstName string) provisionSeed {
 	var seed provisionSeed
 	if lang, _, _ := strings.Cut(strings.ToLower(strings.TrimSpace(languageCode)), "-"); lang == "en" || lang == "ru" {
@@ -218,7 +219,13 @@ func telegramSeed(languageCode, username, firstName string) provisionSeed {
 	}
 	name := sanitizeDisplayName(firstName)
 	if name == "" {
-		name = sanitizeDisplayName(username)
+		// The real name yielded nothing usable: fall back to the @username verbatim
 		// (Telegram guarantees a valid handle), only trimmed and capped to the column
 		// width — never character-stripped like the real name.
 		name = strings.TrimSpace(username)
 		if r := []rune(name); len(r) > maxDisplayName {
 			name = strings.TrimRight(string(r[:maxDisplayName]), " ")
 		}
 	}
 	if name == "" {
 		name = placeholderDisplayName(seed.preferredLanguage)
@@ -9,8 +9,9 @@ import (
 // TestTelegramSeed covers the pure mapping from Telegram launch fields to the
 // create-time account seed: supported-language detection (bare and region-tagged),
-// the first-name / username display-name precedence, and the sanitization that
+// the real-name → @username (verbatim) → placeholder display-name precedence, and
-// strips disallowed characters (emoji, digits, punctuation) to the editable format.
+// the sanitization of the real name (emoji, digits, punctuation stripped to the
 // editable format). The username, when used, is kept verbatim.
 func TestTelegramSeed(t *testing.T) {
 	cases := map[string]struct {
 		languageCode, username, firstName string
@@ -28,6 +29,7 @@ func TestTelegramSeed(t *testing.T) {
 		"punct to space":      {"en", "user", "John❤Doe", "en", "John Doe"},
 		"digits dropped":      {"ru", "user", "Маша123", "ru", "Маша"},
 		"garbage to username": {"en", "good", "123!@#", "en", "good"},
 		"username verbatim":   {"en", "co_ol99", "🎮🎮", "en", "co_ol99"},
 	}
 	for name, tc := range cases {
 		t.Run(name, func(t *testing.T) {
@@ -52,7 +54,7 @@ func TestTelegramSeedPlaceholder(t *testing.T) {
 		"en empty":                  {"en", "", "", `^Player-\d{5}$`},
 		"ru empty":                  {"ru", "", "", `^Игрок-\d{5}$`},
 		"default en":                {"fr", "", "", `^Player-\d{5}$`},
-		"both garbage": {"ru", "123", "!!!", `^Игрок-\d{5}$`},
+		"name garbage, no username": {"ru", "", "!!!", `^Игрок-\d{5}$`},
 	}
 	for name, tc := range cases {
 		t.Run(name, func(t *testing.T) {
@@ -21,7 +21,7 @@ const (
 	// ActionResign abandons the game.
 	ActionResign
 	// ActionTimeout is the auto-resignation a missed turn becomes; recorded by
-	// the game domain in a later stage, never produced by the engine itself.
+	// the game domain, never produced by the engine itself.
 	ActionTimeout
 )
@@ -10,7 +10,7 @@
 // characters (see decode.go and docs/ARCHITECTURE.md §9.1), so archived games
 // replay independently of any dictionary. Second, the engine owns rules and
 // scoring only: turn scheduling, the 24-hour timeout, persistence and transport
-// belong to the game domain in a later stage.
+// belong to the game domain.
 package engine
 import (
@@ -31,7 +31,7 @@ type entry struct {
 // Registry holds the dictionaries resident in memory, addressed by variant and
 // dictionary version, and the solvers built over them. Several versions of a
 // variant may be resident at once; a game pins the version it started on. The
-// admin reload flow (a later stage) registers a new version through Load.
+// admin reload flow registers a new version through Load.
 // Registry is safe for concurrent use.
 type Registry struct {
 	mu      sync.RWMutex
@@ -16,5 +16,5 @@
 // word-check tool with complaint capture, per-player game state, history and GCG
 // export, and the per-game turn-timeout sweeper that auto-resigns an overdue
 // player (honouring their daily away window). The HTTP surface that fronts these
-// operations is added with the gateway in a later stage.
+// operations is exposed to the gateway.
 package game
@@ -105,7 +105,7 @@ const MaxActiveQuickGames = 10
 const aiPlayerName = "AI"
 // CreateParams describes a new game. Seats lists the seated accounts in turn
-// order (seat 0 moves first); lobby/matchmaking assembles it in a later stage.
+// order (seat 0 moves first); lobby/matchmaking assembles it.
 type CreateParams struct {
 	Variant        engine.Variant
 	Seats          []uuid.UUID
@@ -62,7 +62,7 @@ func TestEmailConfirmFlow(t *testing.T) {
 }
 // TestEmailAlreadyTakenByAnotherAccount refuses to bind an email confirmed by a
-// different account (merge is a later stage).
+// different account (combining two accounts is the separate link/merge flow).
 func TestEmailAlreadyTakenByAnotherAccount(t *testing.T) {
 	ctx := context.Background()
 	store := account.NewStore(testDB)
@@ -1,10 +1,10 @@
 // Package server wires the backend's HTTP listener: the gin engine, its route
 // groups, the per-request telemetry middleware and the start/stop lifecycle.
 //
-// The /api/v1 route groups (public, user, internal, admin) are created here so
+// The /api/v1 route groups (public, user, internal, admin) attach their endpoints
-// later stages attach their endpoints to a stable structure; the /user group
+// to a stable structure; the /user group requires the X-User-ID identity header.
-// requires the X-User-ID identity header. The probes /healthz (liveness) and
+// The probes /healthz (liveness) and /readyz (database + session-cache readiness)
-// /readyz (database + session-cache readiness) are unauthenticated.
+// are unauthenticated.
 package server
 import (
@@ -245,7 +245,7 @@ func (s *Server) Invitations() *lobby.InvitationService { return s.invitations }
 func (s *Server) Emails() *account.EmailService { return s.emails }
 // Handler returns the underlying HTTP handler. It lets tests drive the server
-// without binding a socket and lets later stages compose the backend behind
+// without binding a socket and lets callers compose the backend behind
 // another listener.
 func (s *Server) Handler() http.Handler { return s.http.Handler }
@@ -8,8 +8,7 @@ import (
 )
 // Service mints, resolves, and revokes sessions over the store and the
-// write-through cache. The gateway is its only caller (from a later stage); the
+// write-through cache. The gateway is its only caller.
 // HTTP surface is wired then.
 type Service struct {
 	store *Store
 	cache *Cache
@@ -3,8 +3,8 @@
 // in as a message kind. It owns the friendships, blocks and chat_messages tables,
 // reads the account-level block toggles through account.Store, and gates chat and
 // nudge on game state through a GameReader so it never imports the engine. The
-// live delivery of chat and nudges (push / in-app stream) belongs to the gateway
+// live delivery of chat and nudges (push / in-app stream) belongs to the gateway;
-// in a later stage; this package only persists and reads them.
+// this package only persists and reads them.
 package social
 import (
@@ -16,7 +16,7 @@ POSTGRES_PASSWORD=change-me            # required
 # the active version lives in the DB. On a live volume a changed value is ignored (the
 # recorded .seed_version marker wins — the seed-drift guard); change a running
 # contour's dictionary through /_gm/dictionary (ARCHITECTURE.md §5).
-DICT_VERSION=v1.2.1
+DICT_VERSION=v1.3.0
 # --- Logging ----------------------------------------------------------------
 LOG_LEVEL=info
@@ -17,11 +17,12 @@ operational reference for **every environment variable**.
 | `backend` | built (`backend/Dockerfile`) | Domain service; bakes in the DAWG dictionaries; runs migrations at boot. |
 | `postgres` | `postgres:17-alpine` | Database (named volume, `pg_isready` healthcheck). |
 | `validator` | built (`platform/telegram/Dockerfile`, target `validator`) | Telegram HMAC validator (no VPN, no Bot API); internal gRPC at `validator:9091`. Game login depends only on this. |
-| `vpn` + `bot` | sidecar + built (`platform/telegram/Dockerfile`, target `bot`) | Telegram bot; egresses through the AmneziaWG sidecar; holds no inbound port — dials the gateway bot-link (mTLS) at `gateway:9443`. |
+| `vpn` + `bot` | sidecar + built (`platform/telegram/Dockerfile`, target `bot`) | Telegram bot, gated to the **`telegram-local`** profile; egresses through the AmneziaWG sidecar and dials the gateway bot-link (mTLS) at `gateway:9443`. The test contour activates the profile; the prod **main** host omits it and runs the bot standalone on its **own host** (`docker-compose.bot.yml`, no VPN — native Bot API egress). |
 | `otelcol` | `otel/opentelemetry-collector-contrib` | OTLP/gRPC `:4317` → Prometheus scrape (`:9464`) + Tempo. |
-| `prometheus` | `prom/prometheus` | Metrics, 15d retention. |
+| `prometheus` | `prom/prometheus` | Metrics, 15d retention (7d in prod). |
 | `tempo` | `grafana/tempo` | Traces, 72h retention. |
 | `grafana` | `grafana/grafana` | Dashboards (provisioned), anonymous-admin behind caddy's `/_gm/grafana`. |
 | `node_exporter` | `quay.io/prometheus/node-exporter` | Host CPU/memory/disk metrics (Prometheus job `node`); the OOM signal on the tight prod main host (2 vCPU / 1.9 GiB). |
 Networking: inter-service traffic is on the private `internal` network
 (project-scoped DNS); only `caddy` joins the shared external `edge` network so the
@@ -59,7 +60,6 @@ compose binds from this directory.
 | Variable | Gitea kind | Purpose |
 | --- | --- | --- |
 | `POSTGRES_PASSWORD` | secret | Postgres password (also embedded in `BACKEND_POSTGRES_DSN`). |
 | `AWG_CONF` | secret | AmneziaWG config for the VPN sidecar (the bot's only Telegram egress in the test contour). **Must not contain a `DNS=` line** — it hijacks the shared netns's resolv.conf and breaks the bot resolving `otelcol` / `gateway`. Without it, Docker's resolver handles `otelcol`, `gateway` and `api.telegram.org`. |
 | `GM_BASICAUTH_HASH` | secret | bcrypt hash gating `/_gm` (admin console + Grafana). Generate with `docker run --rm caddy:2-alpine caddy hash-password --plaintext '<pw>'`. |
 | `TELEGRAM_MINIAPP_URL` | variable | The Mini App URL the bot hands out in deep links / buttons. |
@@ -67,13 +67,20 @@ compose binds from this directory.
 secret) and the bot (Bot API). It defaults to empty in compose, but both **fail at
 boot** when it is empty.
 **Conditionally — `AWG_CONF`** (secret): the AmneziaWG config for the VPN sidecar, needed
 only when the `telegram-local` profile runs (the test contour and local runs with the
 bot). It is **not** `:?`-guarded — compose interpolates profiled-out services too, so the
 prod main host (no VPN) must not require it. It **must not contain a `DNS=` line** — that
 hijacks the shared netns's resolv.conf and breaks the bot resolving `otelcol` / `gateway`;
 without it Docker's resolver handles `otelcol`, `gateway` and `api.telegram.org`.
 ## Optional variables (with defaults)
 | Variable | Gitea kind | Default | Purpose |
 | --- | --- | --- | --- |
 | `POSTGRES_DB` | variable | `scrabble` | Database name. |
 | `POSTGRES_USER` | variable | `scrabble` | Database user. |
-| `DICT_VERSION` | variable | `v1.2.1` | `scrabble-dictionary` release tag baked into the backend image as the **seed for a fresh volume** (build-arg). A live contour changes dictionary through the admin console, not this; on a seeded volume a changed value is ignored (the recorded `.seed_version` marker wins — the seed-drift guard, ARCHITECTURE.md §5). Set per contour as `TEST_`/`PROD_DICT_VERSION`. |
+| `DICT_VERSION` | variable | `v1.3.0` | `scrabble-dictionary` release tag baked into the backend image as the **seed for a fresh volume** (build-arg). A live contour changes dictionary through the admin console, not this; on a seeded volume a changed value is ignored (the recorded `.seed_version` marker wins — the seed-drift guard, ARCHITECTURE.md §5). Set per contour as `TEST_`/`PROD_DICT_VERSION`. |
 | `LOG_LEVEL` | variable | `info` | Shared log level for backend / gateway / validator / bot (`debug\|info\|warn\|error`). |
 | `CADDY_SITE_ADDRESS` | variable | `:80` | Caddy site address. Test: `:80` (host caddy terminates TLS). Prod: a domain, so caddy does its own ACME. |
 | `GM_BASICAUTH_USER` | variable | `gm` | Username for the `/_gm` Basic-Auth. |
@@ -110,6 +117,87 @@ collector's / gateway's internal IP is fine (connected route), but its `AWG_CONF
 which resolves `otelcol`, `gateway` and `api.telegram.org`. `GATEWAY_ADMIN_*` is
 intentionally **unset** — caddy owns `/_gm` in the contour.
 ## Bumping the dictionary version
 The dictionary ships as a versioned **release artifact** (`scrabble-dawg-vX.Y.Z.tar.gz`) from
 [`scrabble-dictionary`](https://gitea.iliadenisov.ru/developer/scrabble-dictionary). The tag is
 a build-time input with **no default** in the images, so it is set in exactly two places to
 move the whole stack — change both to a new release:
 1. **CI tests** — `.gitea/workflows/ci.yaml` `env.DICT_VERSION` (the unit/integration jobs
   download that dawg).
 2. **Deploy seed** — the Gitea repo variables `TEST_DICT_VERSION` / `PROD_DICT_VERSION` (the tag
   the deploy bakes into a **fresh** volume's image; the deploy job feeds it to `compose` as
   `DICT_VERSION`).
 For local builds set `DICT_VERSION` in `deploy/.env` (template: `.env.example`); a bare
 `docker build` needs `--build-arg DICT_VERSION=vX.Y.Z`. The Dockerfiles and `compose` carry no
 default — a missing value fails loudly instead of baking a stale tag.
 Bumping the seed is a **no-op on a live volume** (the `.seed_version` marker wins — the
 seed-drift guard). A running contour/prod moves to a new release **through the admin console**
 `/_gm/dictionary` (upload the tarball, preview the per-variant diff, confirm); in-flight games
 keep their pinned version, new games use the new one (ARCHITECTURE.md §5).
 ## Production rollout
 Prod runs on **two hosts** (main = full stack + ACME on the domain; tg = the bot only,
 native Bot API, no VPN), one-time provisioned by **[`ansible/`](ansible/)** (docker, a
 non-sudo `deploy` user holding the CI key, key-only sshd, default-deny ufw, fail2ban).
 Re-run `ansible/` after a host resize — it is idempotent.
 **To roll out:** merge `development → master` (CI green), then run the **`prod-deploy`**
 workflow manually (Gitea → Actions → prod-deploy → run from `master`, input
 `confirm=deploy`). It builds + pushes the images to the registry, ships the
 compose/config/certs/env over SSH, deploys the main host with `prod-deploy.sh` (rolling,
 health-gated, **auto-rollback to the previous tag**), then the bot host, then probes the
 public site. After `master` is green this workflow is the **only** thing that touches
 prod — nothing auto-deploys there. It runs four visible jobs: **build → deploy-main →
 deploy-bot → verify** (the per-service rolling shows in the deploy-main log).
 **Versioning.** Each release is a git tag `vX.Y.Z` on `master`; the deploy stamps
 `git describe --tags` into every image tag, every binary (`-ldflags` → `pkg/version` →
 the `service.version` telemetry attribute) and the SPA About screen. Tag the release
 before running the deploy:
 ```sh
 git tag -a v1.0.0 -m v1.0.0 && git push origin v1.0.0
 ```
 **Manual rollback** (any time after a successful deploy). Run the **`prod-rollback`**
 workflow (Gitea → Actions → prod-rollback, `confirm=rollback`). Leave `target_version`
 blank to roll back to the previously deployed version (read from the host's
 `PREVIOUS_TAG`), or set it to a release tag from the **Releases** page. It re-deploys
 that already-published image rolling + health-gated — no rebuild, no DB migration
 (image rollback is DB-safe under the expand-contract rule). The registry keeps every
 release tag, so any prior release is reachable.
 **Migrations** must be **expand-contract** (backward-compatible; goose is forward-only):
 the automatic rollback is image-only and never restores the DB. A deploy that changes
 `backend/internal/postgres/migrations/` opens a maintenance window — the backend (sole
 writer) is stopped for a consistent `pg_dump` into `/opt/scrabble/dumps` before the new
 backend migrates. **Manual DB restore** (only if a migration was destructive):
 `docker exec -i scrabble-postgres psql -U scrabble -d scrabble -c 'DROP SCHEMA backend CASCADE'`,
 then pipe the dump into the same `psql`, and redeploy the matching old tag.
 **bot-link cert rotation:** regenerate (`deploy/gen-certs.sh /tmp/c --force`), reset the
 five `PROD_BOTLINK_*` secrets from `/tmp/c`, and re-run the workflow — both hosts redeploy
 together with the fresh CA.
 **Sizing / monitoring:** the main host launches undersized (2 vCPU / 1.9 GiB); the prod
 overlay trims limits + `GOMAXPROCS=2` + 7d Prometheus retention, and `node_exporter` feeds
 host memory to Grafana (`/_gm/grafana/`). Watch host memory and resize at Selectel when
 players arrive.
 **`PROD_` Gitea set** (mirrors `TEST_`, mapped onto the unprefixed names above) — secrets:
 `PROD_{POSTGRES_PASSWORD, GM_BASICAUTH_HASH, GRAFANA_ADMIN_PASSWORD, TELEGRAM_BOT_TOKEN,
 TELEGRAM_PROMO_BOT_TOKEN, REGISTRY_PASSWORD, SSH_KEY, SSH_KNOWN_HOSTS, BOTLINK_CA,
 BOTLINK_GATEWAY_CERT, BOTLINK_GATEWAY_KEY, BOTLINK_BOT_CERT, BOTLINK_BOT_KEY}`; variables:
 `PROD_{REGISTRY_USER, MAIN_HOST, TG_HOST, CADDY_SITE_ADDRESS, GM_BASICAUTH_USER,
 GRAFANA_ROOT_URL, LOG_LEVEL, DICT_VERSION, TELEGRAM_MINIAPP_URL, TELEGRAM_GAME_CHANNEL_ID,
 TELEGRAM_CHAT_ID, TELEGRAM_BOT_USERNAME, VITE_TELEGRAM_BOT_ID, VITE_TELEGRAM_LINK,
 VITE_TELEGRAM_GAME_CHANNEL_NAME}`.
 ## Host-side setup (outside this repo)
 - **`edge` network** must exist on the host (`docker network create edge`).
@@ -0,0 +1,49 @@
 # Prod host provisioning
 Idempotent Ansible that prepares the two production hosts. It installs Docker, a
 non-sudo `deploy` service account, SSH hardening, a default-deny firewall,
 fail2ban, unattended security upgrades and time sync. It does **not** deploy the
 application — that is `.gitea/workflows/prod-deploy.yaml`'s job, running as the
 `deploy` account this playbook creates.
 Hosts are referenced by `~/.ssh/config` aliases (`scrabble-main-ops`,
 `scrabble-tg-ops`), so no IPs or key paths live in the repo.
 ## Prerequisites (controller)
 - `ansible` with the bundled collections (`community.general`, `community.docker`,
  `ansible.posix`).
 - The two hosts reachable as root via the ssh-config aliases, host keys already
  accepted into `known_hosts` (`host_key_checking = True`).
 ## One-time: the CI deploy key
 The CI prod-deploy workflow logs into the hosts as `deploy` using a dedicated
 key. Generate it once on the controller, authorize its public half via the
 playbook, and store its private half **only** in the Gitea `PROD_SSH_KEY` secret:
 ```sh
 ssh-keygen -t ed25519 -N '' -C scrabble-ci-deploy \
  -f ~/.ssh/scrabble_ci_deploy_ed25519
 # private half -> Gitea secret PROD_SSH_KEY (set via API); never commit it
 ```
 ## Run
 ```sh
 cd deploy/ansible
 ansible-playbook site.yml
 ```
 The playbook reads the public key from `~/.ssh/scrabble_ci_deploy_ed25519.pub` by
 default; override with `-e deploy_ci_pubkey_path=/path/to/key.pub`. Re-running is
 safe (idempotent) and survives a host resize.
 ## What each host gets
 - **both** (`common`): docker-ce + compose plugin, `daemon.json` (live-restore,
  10m×3 log rotation), `deploy` user (docker group, no sudo), key-only sshd,
  `ufw` default-deny incoming + allow SSH, fail2ban sshd jail, unattended
  upgrades, chrony, `/opt/scrabble/{config,certs,dumps,images}`.
 - **main**: `ufw` opens 80/443/9443; the external `edge` docker network.
 - **tg**: verifies direct `api.telegram.org` egress (the no-VPN assumption).
@@ -0,0 +1,11 @@
 [defaults]
 inventory = inventory.ini
 roles_path = roles
 interpreter_python = /usr/bin/python3
 host_key_checking = True
 stdout_callback = yaml
 deprecation_warnings = False
 retry_files_enabled = False
 [ssh_connection]
 pipelining = True
@@ -0,0 +1,21 @@
 ---
 # Service account the CI prod-deploy workflow uses to drive docker on the hosts.
 # Membership in the docker group is root-equivalent (docker socket access), which
 # is all the deploy workflow needs; the account is deliberately not given sudo.
 deploy_user: deploy
 # Public half of the dedicated CI deploy SSH key, read from the controller at run
 # time. The private half is generated on the controller during provisioning and
 # stored ONLY in the Gitea PROD_SSH_KEY secret; it is never committed. Override the
 # path with -e deploy_ci_pubkey_path=/path/to/key.pub if the key lives elsewhere.
 deploy_ci_pubkey_path: "{{ lookup('env', 'HOME') }}/.ssh/scrabble_ci_deploy_ed25519.pub"
 deploy_ci_pubkey: "{{ lookup('file', deploy_ci_pubkey_path) }}"
 # Base directory the deploy workflow rsyncs compose files, config, certs and dumps
 # into. Owned by deploy_user so the workflow needs no elevation.
 scrabble_base_dir: /opt/scrabble
 # Docker daemon json-file log rotation, mirroring the compose x-logging anchor so
 # the host's own containers (and any ad-hoc runs) rotate identically.
 docker_log_max_size: "10m"
 docker_log_max_file: "3"
@@ -0,0 +1,19 @@
 # Production inventory for Stage 18.
 #
 # Hosts resolve through the operator's ~/.ssh/config aliases, so HostName (public
 # IP), User and IdentityFile live there — no IPs or key paths are committed here.
 #   scrabble-main-ops -> main stack host (public IP, domain erudit-game.ru)
 #   scrabble-tg-ops   -> Telegram bot host (direct Bot API egress, no VPN)
 [main]
 scrabble-main-ops
 [tg]
 scrabble-tg-ops
 [prod:children]
 main
 tg
 [prod:vars]
 ansible_user=root
@@ -0,0 +1,15 @@
 ---
 - name: restart docker
  ansible.builtin.service:
    name: docker
    state: restarted
 - name: reload sshd
  ansible.builtin.service:
    name: ssh
    state: reloaded
 - name: restart fail2ban
  ansible.builtin.service:
    name: fail2ban
    state: restarted
@@ -0,0 +1,167 @@
 ---
 # Common baseline applied to both prod hosts: Docker engine, a non-sudo deploy
 # service account, SSH hardening, a default-deny firewall, fail2ban, unattended
 # security upgrades and time sync. Every task is idempotent.
 - name: Install base packages
  ansible.builtin.apt:
    name:
      - ca-certificates
      - curl
      - gnupg
      - ufw
      - fail2ban
      - unattended-upgrades
      - chrony
    state: present
    update_cache: true
    cache_valid_time: 3600
 # --- Docker engine (official repo; trixie is published upstream) ---------------
 - name: Create apt keyring directory
  ansible.builtin.file:
    path: /etc/apt/keyrings
    state: directory
    mode: "0755"
 - name: Install Docker apt GPG key
  ansible.builtin.get_url:
    url: https://download.docker.com/linux/debian/gpg
    dest: /etc/apt/keyrings/docker.asc
    mode: "0644"
 - name: Add Docker apt repository
  ansible.builtin.apt_repository:
    repo: >-
      deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.asc]
      https://download.docker.com/linux/debian {{ ansible_distribution_release }} stable
    filename: docker
    state: present
 - name: Install Docker engine and the compose plugin
  ansible.builtin.apt:
    name:
      - docker-ce
      - docker-ce-cli
      - containerd.io
      - docker-buildx-plugin
      - docker-compose-plugin
    state: present
    update_cache: true
 - name: Configure the Docker daemon (live-restore + log rotation)
  ansible.builtin.template:
    src: daemon.json.j2
    dest: /etc/docker/daemon.json
    mode: "0644"
  notify: restart docker
 - name: Enable and start Docker
  ansible.builtin.service:
    name: docker
    enabled: true
    state: started
 # --- Deploy service account ----------------------------------------------------
 - name: Create the deploy service account
  ansible.builtin.user:
    name: "{{ deploy_user }}"
    groups: docker
    append: true
    shell: /bin/bash
    create_home: true
 - name: Ensure the deploy .ssh directory
  ansible.builtin.file:
    path: "/home/{{ deploy_user }}/.ssh"
    state: directory
    owner: "{{ deploy_user }}"
    group: "{{ deploy_user }}"
    mode: "0700"
 - name: Authorize the CI deploy SSH key (exclusive)
  ansible.builtin.copy:
    dest: "/home/{{ deploy_user }}/.ssh/authorized_keys"
    content: "{{ deploy_ci_pubkey }}\n"
    owner: "{{ deploy_user }}"
    group: "{{ deploy_user }}"
    mode: "0600"
 # --- SSH hardening -------------------------------------------------------------
 - name: Harden sshd (key-only auth)
  ansible.builtin.template:
    src: sshd-hardening.conf.j2
    dest: /etc/ssh/sshd_config.d/10-scrabble-hardening.conf
    mode: "0644"
    validate: sshd -t -f %s
  notify: reload sshd
 # --- Firewall (default deny incoming) ------------------------------------------
 # SSH is allowed before the policy flips so enabling ufw never locks us out.
 - name: Allow SSH through the firewall
  community.general.ufw:
    rule: allow
    name: OpenSSH
 - name: Default-deny incoming, allow outgoing
  community.general.ufw:
    direction: "{{ item.direction }}"
    policy: "{{ item.policy }}"
  loop:
    - { direction: incoming, policy: deny }
    - { direction: outgoing, policy: allow }
 - name: Enable the firewall
  community.general.ufw:
    state: enabled
 # --- fail2ban ------------------------------------------------------------------
 - name: Configure the fail2ban sshd jail
  ansible.builtin.template:
    src: jail.local.j2
    dest: /etc/fail2ban/jail.local
    mode: "0644"
  notify: restart fail2ban
 - name: Enable and start fail2ban
  ansible.builtin.service:
    name: fail2ban
    enabled: true
    state: started
 # --- Unattended security upgrades + time sync ----------------------------------
 - name: Enable unattended upgrades
  ansible.builtin.copy:
    dest: /etc/apt/apt.conf.d/20auto-upgrades
    mode: "0644"
    content: |
      APT::Periodic::Update-Package-Lists "1";
      APT::Periodic::Unattended-Upgrade "1";
 - name: Enable and start chrony
  ansible.builtin.service:
    name: chrony
    enabled: true
    state: started
 # --- Deploy directories --------------------------------------------------------
 - name: Create the scrabble base directories
  ansible.builtin.file:
    path: "{{ scrabble_base_dir }}/{{ item }}"
    state: directory
    owner: "{{ deploy_user }}"
    group: "{{ deploy_user }}"
    mode: "0750"
  loop:
    - ""
    - config
    - certs
    - dumps
    - images
@@ -0,0 +1,8 @@
 {
  "live-restore": true,
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "{{ docker_log_max_size }}",
    "max-file": "{{ docker_log_max_file }}"
  }
 }
@@ -0,0 +1,9 @@
 # Managed by Ansible (deploy/ansible).
 [DEFAULT]
 bantime = 1h
 findtime = 10m
 maxretry = 5
 backend = systemd
 [sshd]
 enabled = true
@@ -0,0 +1,6 @@
 # Managed by Ansible (deploy/ansible). Key-only authentication.
 # root stays reachable by key (prohibit-password) for provisioning re-runs.
 PasswordAuthentication no
 PermitRootLogin prohibit-password
 PubkeyAuthentication yes
 KbdInteractiveAuthentication no
@@ -0,0 +1,18 @@
 ---
 # Main stack host: public web + bot-link ports and the external 'edge' network
 # the compose stack attaches caddy to.
 - name: Open public web and bot-link ports
  community.general.ufw:
    rule: allow
    port: "{{ item }}"
    proto: tcp
  loop:
    - "80"    # HTTP (ACME challenge + redirect to HTTPS)
    - "443"   # HTTPS (caddy edge)
    - "9443"  # bot-link mTLS (remote bot dials in; mutual TLS gates access)
 - name: Ensure the external 'edge' docker network exists
  community.docker.docker_network:
    name: edge
    state: present
@@ -0,0 +1,19 @@
 ---
 # Telegram bot host: holds no inbound port beyond SSH (the bot dials out to the
 # Bot API and into the main host's bot-link). We only verify direct Bot API
 # egress here, since the "no VPN" decision depends on it.
 - name: Verify direct Telegram Bot API egress (no VPN on this host)
  ansible.builtin.uri:
    url: https://api.telegram.org/
    method: GET
    status_code: [200, 301, 302, 401, 404]   # any HTTP reply proves reachability
    timeout: 10
  register: tg_egress
  failed_when: false
 - name: Report Telegram reachability
  ansible.builtin.debug:
    msg: >-
      api.telegram.org reachable:
      {{ (tg_egress.status | default(0) | int) > 0 }} (status {{ tg_egress.status | default('none') }})
@@ -0,0 +1,31 @@
 ---
 # Production host provisioning. Idempotent: safe to re-run after a host resize.
 # Prepares hosts only (docker, hardening, service account, firewall); the
 # application is deployed separately by .gitea/workflows/prod-deploy.yaml.
 - name: Common baseline (both hosts)
  hosts: prod
  become: true
  pre_tasks:
    - name: Require a well-formed CI deploy public key
      ansible.builtin.assert:
        that:
          - deploy_ci_pubkey | length > 0
          - deploy_ci_pubkey is search('^(ssh|ecdsa)-')
        fail_msg: >-
          deploy_ci_pubkey is empty or malformed. Generate the key first
          (see deploy/ansible/README.md) or override deploy_ci_pubkey_path.
  roles:
    - common
 - name: Main stack host
  hosts: main
  become: true
  roles:
    - main
 - name: Telegram bot host
  hosts: tg
  become: true
  roles:
    - tg
@@ -0,0 +1,53 @@
 # Production Telegram bot host descriptor (standalone — NOT an overlay). Run only on
 # the bot host:
 #   docker compose -f docker-compose.bot.yml up -d
 #
 # The bot egresses to the Bot API directly (no VPN sidecar) and dials the main host's
 # published bot-link :9443 over mTLS. It exports no telemetry — otelcol lives on the
 # main host and is unreachable from here — so observe it via `docker logs` on this host.
 # Values come from the prod-deploy workflow (PROD_ secrets/variables); BOT_IMAGE is the
 # pushed registry tag and BOTLINK_GATEWAY_ADDR is the main host's <ip>:9443.
 name: scrabble-bot
 services:
  bot:
    container_name: scrabble-telegram-bot
    image: ${BOT_IMAGE:?set BOT_IMAGE to the registry tag}
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    environment:
      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN:?set TELEGRAM_BOT_TOKEN}
      TELEGRAM_GAME_CHANNEL_ID: ${TELEGRAM_GAME_CHANNEL_ID:-}
      TELEGRAM_CHAT_ID: ${TELEGRAM_CHAT_ID:-}
      TELEGRAM_PROMO_BOT_TOKEN: ${TELEGRAM_PROMO_BOT_TOKEN:-}
      TELEGRAM_BOT_USERNAME: ${TELEGRAM_BOT_USERNAME:-}
      TELEGRAM_BOT_LINK: ${TELEGRAM_BOT_LINK:-}
      TELEGRAM_MINIAPP_URL: ${TELEGRAM_MINIAPP_URL:?set TELEGRAM_MINIAPP_URL}
      # Real Bot API in prod (the test contour pins TELEGRAM_TEST_ENV=true instead).
      TELEGRAM_TEST_ENV: "false"
      TELEGRAM_API_BASE_URL: ${TELEGRAM_API_BASE_URL:-}
      TELEGRAM_OWNS_UPDATES: "true"
      # Dials the main host's published bot-link. ServerName stays `gateway` (the cert
      # SAN), so TLS validation is independent of the dial address.
      TELEGRAM_GATEWAY_ADDR: ${BOTLINK_GATEWAY_ADDR:?set BOTLINK_GATEWAY_ADDR (main:9443)}
      TELEGRAM_BOTLINK_SERVER_NAME: gateway
      TELEGRAM_BOTLINK_TLS_CERT: /certs/bot.crt
      TELEGRAM_BOTLINK_TLS_KEY: /certs/bot.key
      TELEGRAM_BOTLINK_TLS_CA: /certs/ca.crt
      TELEGRAM_LOG_LEVEL: ${LOG_LEVEL:-info}
      TELEGRAM_SERVICE_NAME: scrabble-telegram-bot
      # No telemetry export: otelcol is on the main host, unreachable from here.
      TELEGRAM_OTEL_TRACES_EXPORTER: none
      TELEGRAM_OTEL_METRICS_EXPORTER: none
      GOMAXPROCS: "1"
    volumes:
      - ${SCRABBLE_CONFIG_DIR:-.}/certs:/certs:ro
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 256M
@@ -0,0 +1,98 @@
 # Production main-host overlay, applied on top of docker-compose.yml on the main host:
 #   docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
 #
 # It (1) publishes caddy 80/443 — there is no host caddy in prod, so the contour caddy
 # owns the edge and does its own ACME on CADDY_SITE_ADDRESS — and the gateway bot-link
 # :9443 the remote bot dials in over mTLS; and (2) retunes the baseline limits down for the
 # 2 vCPU / 1.9 GiB host (GOMAXPROCS=2, smaller memory caps, shorter Prometheus
 # retention). The contour launches deliberately undersized at zero players; the added
 # node_exporter + Grafana watch host memory so it can be resized at Selectel when
 # traffic arrives.
 #
 # The bot + its VPN sidecar are absent here (the telegram-local profile is not
 # activated); the prod bot runs on its own host from docker-compose.bot.yml.
 services:
  caddy:
    ports:
      - "80:80"
      - "443:443"
    deploy:
      resources:
        limits:
          memory: 96M
  gateway:
    # Prod pulls the pushed image by tag instead of building locally; the base
    # build: section stays dormant because the deploy always pulls first.
    image: ${REGISTRY:?set REGISTRY}/scrabble-gateway:${TAG:?set TAG}
    ports:
      - "9443:9443"
    environment:
      # 2 vCPU host: align the Go scheduler with the cgroup quota (the baseline's 3-core gateway needs 3 cores).
      GOMAXPROCS: "2"
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 384M
  backend:
    image: ${REGISTRY:?set REGISTRY}/scrabble-backend:${TAG:?set TAG}
    deploy:
      resources:
        limits:
          memory: 384M
  postgres:
    deploy:
      resources:
        limits:
          memory: 384M
  validator:
    image: ${REGISTRY:?set REGISTRY}/scrabble-telegram-validator:${TAG:?set TAG}
    deploy:
      resources:
        limits:
          memory: 96M
  landing:
    image: ${REGISTRY:?set REGISTRY}/scrabble-landing:${TAG:?set TAG}
    deploy:
      resources:
        limits:
          memory: 64M
  otelcol:
    deploy:
      resources:
        limits:
          memory: 256M
  prometheus:
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --storage.tsdb.retention.time=7d
    deploy:
      resources:
        limits:
          memory: 256M
  tempo:
    deploy:
      resources:
        limits:
          memory: 384M
  grafana:
    deploy:
      resources:
        limits:
          memory: 256M
  postgres_exporter:
    deploy:
      resources:
        limits:
          memory: 64M
@@ -25,9 +25,9 @@
 #     backend admin relay reaches the gateway at `gateway:9092` (plaintext).
 name: scrabble
-# Bound every container's json-file logs. R7 measured the backend emitting a
+# Bound every container's json-file logs. The backend emits a per-request latency
-# per-request latency line at info (~14 MiB / 30 min under the 500-player stress
+# line at info (~14 MiB / 30 min under the 500-player peak); without rotation the
-# peak); without rotation the volume grows unbounded. 10 MiB x 3 files caps each
+# volume grows unbounded. 10 MiB x 3 files caps each
 # container at 30 MiB. Applied to every service via the *default-logging alias.
 x-logging: &default-logging
  driver: json-file
@@ -52,8 +52,8 @@ services:
      retries: 30
    volumes:
      - postgres-data:/var/lib/postgresql/data
-    # R7 starting limits: 512M leaves headroom over the default 128 MB shared_buffers +
+    # 512M leaves headroom over the default 128 MB shared_buffers + per-connection
-    # per-connection memory (R2 peaked at 28 backends / 69 MiB RSS); tighten after the run.
+    # memory (the load harness peaked at 28 backends / 69 MiB RSS).
    deploy:
      resources:
        limits:
@@ -68,9 +68,13 @@ services:
      context: ..
      dockerfile: backend/Dockerfile
      args:
-        # Seed dictionary for a FRESH volume; the per-contour value comes from the
+        # Seed dictionary for a FRESH volume; required (no default) so the release tag is
-        # deploy env (Gitea TEST_/PROD_DICT_VERSION). See the volume note below.
+        # set in exactly one place per context — the deploy env (Gitea TEST_/PROD_DICT_VERSION)
-        DICT_VERSION: ${DICT_VERSION:-v1.2.1}
+        # or .env for local builds. See the volume note below + deploy/README.md "Bumping the
        # dictionary version".
        DICT_VERSION: ${DICT_VERSION:?set DICT_VERSION — the scrabble-dictionary release tag, e.g. in deploy/.env}
        # Build version stamped into the binary (git tag; see pkg/version).
        VERSION: ${APP_VERSION:-dev}
    restart: unless-stopped
    logging: *default-logging
    depends_on:
@@ -79,8 +83,8 @@ services:
    environment:
      # search_path=backend matches the migrations (00001 creates the schema).
      BACKEND_POSTGRES_DSN: postgres://${POSTGRES_USER:-scrabble}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-scrabble}?sslmode=disable&search_path=backend
-      # R7 tuned: the pool sat at its 25-conn cap (28 backends total) at 500 players;
+      # The pool caps at 25 conns (~28 backends) around 500 players; 40 gives headroom
-      # 40 gives headroom for bursts. Postgres (2 cores / 512 MiB) handles it.
+      # for bursts. Postgres (2 cores / 512 MiB) handles it.
      BACKEND_POSTGRES_MAX_OPEN_CONNS: "40"
      BACKEND_HTTP_ADDR: ":8080"
      BACKEND_GRPC_ADDR: ":9090"
@@ -109,8 +113,8 @@ services:
      - dawg-data:/opt/dawg
    # No container healthcheck: the distroless image has no shell/wget. Readiness
    # is covered by the CI post-deploy probe (GET / through caddy).
-    # R7 starting limits (generous over the R2 ~1-core / <=100 MiB peak); tightened to
+    # Generous over the ~1-core / <=100 MiB measured peak; the prod overlay trims these
-    # the agreed prod values after the final stress run. deploy.resources.limits is
+    # to the launch-host values. deploy.resources.limits is
    # honoured by `docker compose up` (Compose v2), not only by swarm.
    deploy:
      resources:
@@ -132,6 +136,8 @@ services:
        VITE_TELEGRAM_GAME_CHANNEL_NAME: ${VITE_TELEGRAM_GAME_CHANNEL_NAME:-}
        VITE_GATEWAY_URL: ${VITE_GATEWAY_URL:-}
        VITE_APP_VERSION: ${APP_VERSION:-dev}
        # Go binary version (the SPA's VITE_APP_VERSION is the same git tag).
        VERSION: ${APP_VERSION:-dev}
    restart: unless-stopped
    logging: *default-logging
    depends_on: [backend]
@@ -171,7 +177,7 @@ services:
    # deploy/gen-certs.sh for the test contour; supplied from PROD_ secrets in prod.
    volumes:
      - ${SCRABBLE_CONFIG_DIR:-.}/certs:/certs:ro
-    # R7 tuned: the gateway holds one h2c connection per player, so at 500 players it
+    # The gateway holds one h2c connection per player, so at 500 players it
    # bursts into a 2-core cap (~2.49% transport_error on game.state); 3 cores absorbs
    # the bursts. Per-connection overhead is the realistic prod cost — size for it.
    deploy:
@@ -218,6 +224,8 @@ services:
      context: ..
      dockerfile: platform/telegram/Dockerfile
      target: validator
      args:
        VERSION: ${APP_VERSION:-dev}
    restart: unless-stopped
    logging: *default-logging
    environment:
@@ -240,14 +248,22 @@ services:
    networks: [internal]
  # --- Telegram bot (egress via the VPN sidecar in test; dials the gateway) ---
  # vpn + bot are gated to the `telegram-local` profile: the test contour runs them
  # locally (CI passes --profile telegram-local), the prod main host omits them, and
  # the prod bot runs on its own host from deploy/docker-compose.bot.yml.
  vpn:
    container_name: scrabble-telegram-vpn
    image: docker.iliadenisov.ru/developer/amneziawg-sidecar:latest
    profiles: ["telegram-local"]
    restart: unless-stopped
    logging: *default-logging
    privileged: true
    environment:
-      AWG_CONF: ${AWG_CONF:?set AWG_CONF}
+      # Required by the vpn sidecar, which is gated to the telegram-local profile.
      # Compose can't scope a `:?` guard to a profile (interpolation runs for
      # profiled-out services too) and the prod main host has no VPN, so this is a soft
      # default; the test contour always supplies TEST_AWG_CONF and the sidecar validates it.
      AWG_CONF: ${AWG_CONF:-}
    networks:
      internal:
        aliases: [telegram]
@@ -255,10 +271,13 @@ services:
  bot:
    container_name: scrabble-telegram-bot
    image: scrabble-telegram-bot:latest
    profiles: ["telegram-local"]
    build:
      context: ..
      dockerfile: platform/telegram/Dockerfile
      target: bot
      args:
        VERSION: ${APP_VERSION:-dev}
    restart: unless-stopped
    logging: *default-logging
    depends_on: [vpn]
@@ -385,8 +404,8 @@ services:
    volumes:
      - ${SCRABBLE_CONFIG_DIR:-.}/tempo/tempo.yaml:/etc/tempo/tempo.yaml:ro
      - tempo-data:/var/tempo
-    # R7 tuned: tempo reached the 1 GiB cap during the final run (446 MiB in R2);
+    # Tempo reached the 1 GiB cap under sustained load (446 MiB in earlier runs);
-    # raised to 2 GiB for headroom against OOM under sustained tracing load.
+    # raised to 2 GiB for headroom against OOM.
    deploy:
      resources:
        limits:
@@ -444,6 +463,26 @@ services:
          memory: 128M
    networks: [internal]
  # node_exporter exports host CPU/memory/disk metrics. The prod main host runs a tight
  # 1.9 GiB budget, so host memory pressure — not just per-container docker_stats — is
  # what warns before an OOM. Prometheus scrapes it at :9100 (see prometheus.yml).
  node_exporter:
    container_name: scrabble-node-exporter
    image: quay.io/prometheus/node-exporter:v1.8.2
    restart: unless-stopped
    logging: *default-logging
    command:
      - --path.rootfs=/host
      - --collector.filesystem.mount-points-exclude=^/(sys|proc|dev|host)($|/)
    pid: host
    volumes:
      - /:/host:ro,rslave
    deploy:
      resources:
        limits:
          memory: 64M
    networks: [internal]
 networks:
  internal:
    name: scrabble-internal
@@ -0,0 +1,143 @@
 #!/usr/bin/env bash
 # Production main-host deploy driver. Runs ON the main host, invoked over SSH by
 # .gitea/workflows/prod-deploy.yaml as the deploy user (which must already be
 # `docker login`ed to the registry). It pulls the images at the new tag and rolls
 # the stack ONE service at a time in dependency order (least -> most dependent),
 # health-checking after each; any failure rolls the whole stack back to the
 # previously deployed tag.
 #
 # A schema migration adds a maintenance window: the backend (the only writer) is
 # stopped so a consistent pg_dump is taken before the new backend migrates forward.
 # Image rollback alone is safe under the expand-contract migration rule, so the
 # automatic rollback never touches the database; the dump is kept for a MANUAL
 # restore if a migration turned out to be destructive (see deploy/prod/README.md).
 #
 # Required env (exported by the workflow over SSH):
 #   REGISTRY   registry namespace, e.g. docker.iliadenisov.ru/developer
 #   TAG        new image tag (the deployed git SHA)
 #   PREV_TAG   previously deployed tag, or "none" on the first deploy
 #   MIGRATION  "1" when the deploy carries a schema migration, else "0"
 # Optional: COMPOSE_DIR ENV_FILE DUMP_DIR STATE_FILE POSTGRES_USER POSTGRES_DB
 set -uo pipefail
 # Runtime compose vars (POSTGRES_*, GM_*, GRAFANA_*, CADDY_*, TELEGRAM_*, REGISTRY,
 # SCRABBLE_CONFIG_DIR, ...) come from a shell-sourceable env file the workflow writes
 # with single-quoted values. Exporting them into the process environment lets compose
 # interpolate ${...} without re-parsing the value — a plain --env-file would mangle the
 # literal '$' in the bcrypt GM_BASICAUTH_HASH.
 ENV_FILE="${ENV_FILE:-/opt/scrabble/env.sh}"
 # shellcheck disable=SC1090
 [ -f "$ENV_FILE" ] && . "$ENV_FILE"
 REGISTRY="${REGISTRY:?REGISTRY required (env.sh)}"
 TAG="${TAG:?TAG required}"
 PREV_TAG="${PREV_TAG:-none}"
 MIGRATION="${MIGRATION:-0}"
 COMPOSE_DIR="${COMPOSE_DIR:-/opt/scrabble/compose}"
 DUMP_DIR="${DUMP_DIR:-/opt/scrabble/dumps}"
 STATE_FILE="${STATE_FILE:-/opt/scrabble/DEPLOYED_TAG}"
 # The prior deployed tag, preserved on every successful deploy so prod-rollback can
 # target "the previous version" with no operator input.
 PREV_STATE_FILE="${PREV_STATE_FILE:-/opt/scrabble/PREVIOUS_TAG}"
 PG_USER="${POSTGRES_USER:-scrabble}"
 PG_DB="${POSTGRES_DB:-scrabble}"
 cd "$COMPOSE_DIR" || { echo "compose dir $COMPOSE_DIR missing"; exit 1; }
 export REGISTRY
 # otelcol joins the host docker group to read the socket; the GID varies per host.
 DOCKER_GID="$(getent group docker | cut -d: -f3)"
 export DOCKER_GID
 dc() { docker compose -f docker-compose.yml -f docker-compose.prod.yml "$@"; }
 use_tag() { export TAG="$1"; }
 # --- health probes (one-off containers on the contour networks, like CI) --------
 _probe() { docker run --rm --network "$1" alpine:3.20 wget -q -T 5 -O /dev/null "$2"; }
 health_backend() { for _ in $(seq 1 20); do _probe scrabble-internal http://backend:8080/readyz && return 0; sleep 3; done; return 1; }
 health_landing() { for _ in $(seq 1 20); do _probe scrabble-internal http://landing:80/ && return 0; sleep 3; done; return 1; }
 health_postgres() { for _ in $(seq 1 30); do [ "$(docker inspect -f '{{.State.Health.Status}}' scrabble-postgres 2>/dev/null)" = healthy ] && return 0; sleep 2; done; return 1; }
 health_running() { # health_running <container>: running, not restarting, stable restart count
  local n="$1" s r c1 c2
  for _ in $(seq 1 20); do
    s="$(docker inspect -f '{{.State.Status}}' "$n" 2>/dev/null || echo missing)"
    r="$(docker inspect -f '{{.State.Restarting}}' "$n" 2>/dev/null || echo true)"
    if [ "$s" = running ] && [ "$r" = false ]; then
      c1="$(docker inspect -f '{{.RestartCount}}' "$n")"; sleep 5
      c2="$(docker inspect -f '{{.RestartCount}}' "$n")"
      [ "$c1" = "$c2" ] && return 0
    fi
    sleep 3
  done
  return 1
 }
 roll() { # roll <service> <health-cmd...>
  local svc="$1"; shift
  echo ">>> rolling $svc -> $TAG"
  dc up -d --no-build --no-deps "$svc" || return 1
  "$@" || { echo "!!! $svc failed health check"; return 1; }
  echo "<<< $svc healthy"
 }
 rollback() {
  echo "########## ROLLBACK -> $PREV_TAG ##########"
  if [ "$PREV_TAG" = none ]; then
    echo "no previous tag (first deploy): cannot roll back; leaving the stack up for inspection."
    return
  fi
  use_tag "$PREV_TAG"
  dc up -d --no-build --remove-orphans
  echo "rolled back to $PREV_TAG."
  [ "$MIGRATION" = 1 ] && echo "NOTE: the DB is forward-migrated; a pre-deploy dump is in $DUMP_DIR — restore manually ONLY if the migration was destructive (see deploy/README.md, prod runbook)."
 }
 commit_tag() {
  # Record the just-deployed tag as current, preserving the prior one as previous.
  [ -f "$STATE_FILE" ] && cp "$STATE_FILE" "$PREV_STATE_FILE"
  echo "$TAG" > "$STATE_FILE"
 }
 mkdir -p "$DUMP_DIR"
 echo "=== prod deploy: tag=$TAG prev=$PREV_TAG migration=$MIGRATION ==="
 use_tag "$TAG"
 dc pull
 # First deploy: nothing to roll from; bring the whole stack up and gate on health.
 if [ -z "$(docker ps -aq -f name=scrabble-backend)" ]; then
  echo "first deploy: bringing the whole stack up"
  dc up -d --no-build --remove-orphans || { echo "compose up failed"; exit 1; }
  health_backend || { echo "backend not ready"; exit 1; }
  health_landing || { echo "landing not ready"; exit 1; }
  commit_tag
  echo "first deploy healthy ($TAG)."
  exit 0
 fi
 # Migration deploy: freeze writes and snapshot a consistent dump before migrating.
 if [ "$MIGRATION" = 1 ]; then
  echo "migration deploy: opening maintenance window (stopping the backend = the only writer)"
  dc stop backend
  dump="$DUMP_DIR/pre-$TAG-$(date +%Y%m%d-%H%M%S).sql"
  if ! docker exec scrabble-postgres pg_dump -U "$PG_USER" -d "$PG_DB" -n backend > "$dump"; then
    echo "pg_dump failed; restarting the old backend and aborting"
    dc start backend
    exit 1
  fi
  echo "consistent dump: $dump"
 fi
 # Roll one service at a time, least -> most dependent; any failure rolls everything back.
 roll postgres  health_postgres                              || { rollback; exit 1; }
 roll backend   health_backend                               || { rollback; exit 1; }
 roll gateway   health_running scrabble-gateway              || { rollback; exit 1; }
 roll landing   health_landing                               || { rollback; exit 1; }
 roll validator health_running scrabble-telegram-validator   || { rollback; exit 1; }
 roll caddy     health_running scrabble-caddy                || { rollback; exit 1; }
 # Observability + node_exporter: bring up the remainder and pick up any config changes.
 dc up -d --no-build --remove-orphans || { rollback; exit 1; }
 # Final internal sanity before committing the new tag.
 health_backend || { rollback; exit 1; }
 commit_tag
 echo "=== deploy healthy ($TAG) ==="
@@ -18,3 +18,8 @@ scrape_configs:
  - job_name: postgres_exporter
    static_configs:
      - targets: ["postgres_exporter:9187"]
  # Host-level metrics (memory/CPU/disk). Matters most on the prod main host's tight
  # 1.9 GiB budget, where total host memory is the OOM-proximity signal.
  - job_name: node
    static_configs:
      - targets: ["node_exporter:9100"]
@@ -2,10 +2,8 @@
 Source of truth for the platform architecture, transport, security model and
 cross-service contracts. User-visible behaviour per domain lives in
-[`FUNCTIONAL.md`](FUNCTIONAL.md); the staged build order lives in
+[`FUNCTIONAL.md`](FUNCTIONAL.md). This document always describes the **current**
-[`../PLAN.md`](../PLAN.md). This document always describes the **current**
+design, not the history of how it was reached.
 design, not the history of how it was reached. Sections describing
 not-yet-implemented components are marked *(planned)*.
 ## 1. Overview
@@ -1056,8 +1054,10 @@ plaintext relay (`GATEWAY_BOTLINK_RELAY_ADDR`) the backend admin console calls.
 The full contour (`deploy/docker-compose.yml`) runs one `gateway`, one `backend`,
 one Postgres, the static `landing`, the Telegram `validator` and `bot` (+ the bot's VPN
-sidecar) and the **observability stack** —
+sidecar — the `bot`+`vpn` pair is gated to a `telegram-local` compose profile so the prod
-OTel Collector (OTLP/gRPC ingest → Prometheus metrics + Tempo traces) and Grafana
+main host can omit them) and the **observability stack** —
 OTel Collector (OTLP/gRPC ingest → Prometheus metrics + Tempo traces), a `node_exporter`
 for host CPU/memory (the prod main host's OOM signal), and Grafana
 with provisioned datasources and dashboards. All services export OTLP to the
 collector; the bot shares the VPN sidecar's netns, so its `AWG_CONF` must not
 carry a `DNS=` directive (that would hijack resolv.conf and stop it resolving
@@ -1081,16 +1081,36 @@ Two contours, two secret/variable prefixes (`TEST_` / `PROD_`):
  generated by `deploy/gen-certs.sh` before `compose up`; the bot keeps its VPN sidecar
  for Telegram egress and dials the gateway by its internal name, so the bot-link stays
  on the internal network.
- **Prod**: a manual SSH deploy after `development → master`. There is no
+- **Prod**: a **manual** rollout — `.gitea/workflows/prod-deploy.yaml`, `workflow_dispatch`
-  host caddy, so the contour ships its own caddy terminating TLS — set
+  only (from `master`, `confirm=deploy`), run after `development → master` is merged green.
-  `CADDY_SITE_ADDRESS` to the domain and the caddy does its own ACME. The **bot runs
+  It builds and pushes the images to the registry (`docker.iliadenisov.ru`), then deploys
-  on a separate host** with native Telegram access (no VPN), deployed by SSH alongside
+  over SSH onto **two hosts** provisioned by `deploy/ansible/` (docker, a non-sudo `deploy`
-  the main app (rolled together so the bot-link protocol versions never skew); the
+  service account holding a dedicated CI key, key-only sshd, default-deny ufw, fail2ban):
-  gateway **publishes** the bot-link port and the certificates come from `PROD_`
+  the **main host** runs the full stack (`docker-compose.yml` + `docker-compose.prod.yml`),
-  secrets — a long-lived CA with leaves rotated by a scheduled job. The bot dials the
+  the **bot host** runs only the bot (`docker-compose.bot.yml`, no VPN — native Bot API
-  gateway's public bot-link endpoint and holds no inbound port; login is unaffected if
+  egress, telemetry off). There is no host caddy, so the contour caddy terminates TLS —
-  that host or the link is down. *(This prod wiring is the deferred final stage; the
+  `CADDY_SITE_ADDRESS` is the domain and caddy does its own ACME. The gateway **publishes**
-  code and the unified test contour land first — see `PRERELEASE.md`.)*
+  the bot-link `:9443`; the remote bot dials it over mTLS (certs from `PROD_BOTLINK_*`,
  ServerName `gateway`, so TLS validation is independent of the public dial address), holds
  no inbound port, and login is unaffected if that host or the link is down.
  `deploy/prod-deploy.sh` rolls the main stack **one service at a time in dependency order**
  (postgres → backend → gateway → landing → validator → caddy), health-checking after each;
  any failure **rolls the whole stack back to the previous image tag**. A **schema migration**
  adds a maintenance window: the backend (the sole writer) is stopped for a consistent
  `pg_dump` before the new backend migrates forward — image rollback stays DB-safe under the
  expand-contract migration rule, and the dump is kept for a manual restore. The workflow runs
  four visible jobs (build → deploy-main → deploy-bot → verify). Releases are git tags
  `vX.Y.Z`; the version is stamped into the image tag, every binary (`-ldflags` → `pkg/version`
  → the `service.version` telemetry attribute) and the SPA About screen. A separate manual
  **`prod-rollback`** workflow re-deploys any prior release tag (blank input = the previous
  deployed version, tracked on the host) over the same rolling, health-gated path — image-only,
  no DB migration. The main host is
  intentionally **launch-sized** (2 vCPU / 1.9 GiB): the prod overlay trims the baseline limits
  (`GOMAXPROCS=2`, smaller caps, 7d Prometheus retention) and a **node_exporter** feeds
  host-memory metrics to Grafana so it can be resized reactively as players arrive.
  `GATEWAY_ABUSE_BAN_ENABLED=true` in prod (the per-IP ban is meaningful only with real
  client IPs). The `vpn`+`bot` pair is gated to a `telegram-local` compose profile the test
  contour activates; the prod main host omits it.
 ## 14. CI & branches
@@ -31,7 +31,10 @@ ephemeral guest. The gateway validates the credential once and mints a thin
 session token; the backend resolves it to an internal `user_id`. A **Telegram Mini
 App** launch authenticates from the platform's signed `initData`, themes the UI to
 the Telegram colours, and — on first contact — seeds the new account's interface
-language from the Telegram client. Telegram runs a **single bot**: every player uses
+language from the Telegram client. If a launch cannot reach the backend (for example during a
 deployment), the Mini App retries quietly and then shows a small "couldn't load" screen with a
 **Retry** button, rather than dropping to the web sign-in, which has no place inside Telegram.
 Telegram runs a **single bot**: every player uses
 the same bot, and all of its chat and out-of-app notifications are written in the
 player's own **interface language** (en/ru). A separate optional **promo bot** can run alongside the
 main one — its only job is to answer `/start` with a short message and a button that opens the
@@ -56,6 +59,10 @@ reconnect), and pending reads resume on their own — the interface stays usable
 flashing a red banner each time.
 ### Accounts, linking & merge
 _Sign-in is currently provider-only, so the in-profile linking UI is temporarily hidden; it
 returns once the anonymous `/app/` guest (whose upgrade path this is) ships. The flow below
 describes it for when it does._
 First platform contact auto-provisions a durable account. From the profile a player
 links an email (via a confirm code) or their Telegram (via the web sign-in); a guest
 who links their first identity becomes a durable account. The "already taken" status
@@ -32,7 +32,10 @@ top-1 подсказку, безлимитную проверку слова с
 session-токен; backend сопоставляет его с внутренним `user_id`. Запуск **Telegram
 Mini App** авторизует по подписанным `initData` платформы, перекрашивает интерфейс
 в цвета Telegram и — при первом контакте — задаёт язык интерфейса нового аккаунта по
-языку Telegram-клиента. Telegram держит **единого бота**: все игроки пользуются одним
+языку Telegram-клиента. Если запуск не может достучаться до бэкенда (например, во время
 деплоя), Mini App тихо повторяет попытки, а затем показывает небольшой экран «не удалось
 загрузить» с кнопкой **Повторить**, вместо того чтобы сбрасывать на веб-вход, которому внутри
 Telegram не место. Telegram держит **единого бота**: все игроки пользуются одним
 и тем же ботом, а весь его чат и внеприложенческие уведомления пишутся на **языке
 интерфейса** самого игрока (en/ru). Рядом с основным может работать отдельный опциональный
 **промо-бот** — его единственная задача отвечать на `/start` коротким сообщением и кнопкой,
@@ -57,6 +60,10 @@ Mini App** авторизует по подписанным `initData` плат
 рабочим вместо красного баннера каждый раз.
 ### Аккаунты, привязка и слияние
 _Вход сейчас только через провайдера, поэтому UI привязки в профиле временно скрыт; он
 вернётся, когда появится анонимный `/app/`-гость (для апгрейда которого он и нужен). Описание
 ниже — на этот случай._
 Первый контакт с платформы заводит постоянный аккаунт. Из профиля игрок
 привязывает email (по confirm-коду) или свой Telegram (через веб-вход); гость,
 привязавший первую личность, становится постоянным аккаунтом. Факт «личность уже
@@ -121,7 +121,7 @@ tests or touching CI.
  Postgres-backed `inttest` drives the **guest reaper** end to end (an abandoned guest is
  reaped; a too-young guest, a seated guest and a durable account are kept).
 - **Load test & resource baseline** — a reusable `loadtest/` module
-  (`scrabble/loadtest`) is the pre-release stress harness. It **seeds** a large account
+  (`scrabble/loadtest`) is the stress/load harness. It **seeds** a large account
  population with pre-created sessions directly in Postgres (token hashes matching
  `backend/internal/session`), **drives** virtual players through the edge protocol —
  real games assembled via invitations, **mid-ranked** legal moves generated locally by
@@ -154,13 +154,12 @@ tests or touching CI.
 - No network or real platform calls in unit tests; validate platform
  credentials behind an interface seam and test with fixtures.
-## Per-stage CI gate
+## CI gate
-Every completed stage is exercised on `gitea.iliadenisov.ru` before it is marked
+Every change is exercised on `gitea.iliadenisov.ru` before it is merged:
 done in [`../PLAN.md`](../PLAN.md):
-1. Commit the stage on its `feature/*` branch.
+1. Commit the change on its `feature/*` branch.
 2. Push to `origin`.
 3. Watch the run to completion — never hand-roll a poll loop:
   `python3 ~/.claude/bin/gitea-ci-watch.py` (launch in the background).
-4. Only after every workflow that fired is green may the stage be marked done.
+4. Only after every workflow that fired is green may the change be merged.
@@ -109,7 +109,10 @@ dismisses as soon as the lobby is ready. The pure layout and timing live in `lib
 ## Tiles & board
 - **Tiles**: the letter sits in the **top-left** corner (offset a touch more than the
-  value), the point value bottom-right; blanks show no value.
+  value), the point value bottom-right; blanks show no value. In **Erudit** the blank is the
  "звёздочка" (star) chip: an unplaced blank shows the star (`✻`, U+273B) centred on the rack
  tile, and a placed blank carries it in the value corner; the Scrabble variants leave the
  blank unmarked (`usesStarBlank` in `lib/variants.ts`).
 - **Board zoom** (`Board.svelte`): a two-state zoom (full 15×15 ↔ ~9 cells) by **growing
  the board's width** inside a fixed-size viewport (a real layout change → native scroll
  that works consistently across browsers; no `transform`, which broke scrolling
@@ -70,7 +70,9 @@ RUN rm gateway/internal/webui/dist/landing.html
 # Reduce the workspace to what the gateway needs: gateway + pkg (loadtest is not in
 # this context; its scrabble/gateway replace targets ./gateway, which is present here).
 RUN go work edit -dropuse=./backend -dropuse=./platform/telegram -dropuse=./loadtest
-RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -o /out/gateway ./gateway/cmd/gateway
+# VERSION (the deploy passes the git tag) is stamped into the binary via the linker.
 ARG VERSION=dev
 RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "-X scrabble/pkg/version.Version=${VERSION}" -o /out/gateway ./gateway/cmd/gateway
 # --- runtime -----------------------------------------------------------------
 FROM gcr.io/distroless/static-debian12:nonroot AS gateway
@@ -12,7 +12,8 @@
 # --- dictionary artifact -----------------------------------------------------
 FROM alpine:3.20 AS dawg
-ARG DICT_VERSION=v1.2.1
+# Required, no default: the build caller supplies the scrabble-dictionary release tag.
 ARG DICT_VERSION
 RUN apk add --no-cache curl tar
 RUN mkdir -p /dawg \
 && curl -fsSL -o /tmp/dawg.tar.gz \
@@ -1,6 +1,6 @@
 # loadtest — stress harness
-Reusable load harness for the pre-release stress pass. It
+Reusable load/stress harness. It
 seeds a large account population with pre-created sessions, drives virtual players
 through the **gateway edge protocol** in realistic games, hammers the rate limiter,
 and prints a trip-report summary. It stays in the repo for repeats.
@@ -35,8 +35,8 @@ The harness reaches Postgres and the gateway directly, so run it as a one-shot
 container on the contour's docker network (this bypasses the host→gateway hairpin):
 ```sh
-# from the repo root
+# from the repo root (DICT_VERSION has no default — pass the scrabble-dictionary release tag)
-docker build -f loadtest/Dockerfile -t scrabble-loadtest .
+docker build --build-arg DICT_VERSION=v1.3.0 -f loadtest/Dockerfile -t scrabble-loadtest .
 docker run --rm --cpus=3 --name scrabble-loadtest --network scrabble-internal \
  -e POSTGRES_PASSWORD="$TEST_POSTGRES_PASSWORD" \
@@ -107,6 +107,6 @@ gateway→backend connection-pool fix, and the revised sizing — are written up
 The harness shares the host CPU with the contour, so its own `scrabble-loadtest`
 container series is read alongside the system under test; capping it with `--cpus`
-keeps the contour's quota. Per-player transports (R7) removed the shared-transport
+keeps the contour's quota. Per-player transports removed the shared-transport
-artifact that inflated R2's `transport_error`, so the figures reflect the system. A
+artifact that previously inflated `transport_error`, so the figures reflect the system. A
 fully isolated ceiling on separate hardware remains future work.
@@ -129,7 +129,7 @@ func cmdRun(ctx context.Context, log *slog.Logger, args []string) error {
 		drv.Hammer(ctx, pool.Durables[0], scenario.HammerConfig{Workers: *hammerWorkers, Duration: *hammerDur})
 	}
-	fmt.Println("\n==== R2 load-test report ====")
+	fmt.Println("\n==== load-test report ====")
 	fmt.Println(rec.Summary())
 	if *doCleanup {
@@ -29,6 +29,8 @@ import (
 	"go.opentelemetry.io/otel/sdk/resource"
 	sdktrace "go.opentelemetry.io/otel/sdk/trace"
 	"go.opentelemetry.io/otel/trace"
 	"scrabble/pkg/version"
 )
 // Exporter selectors supported per signal.
@@ -95,9 +97,7 @@ func New(ctx context.Context, cfg Config) (*Runtime, error) {
 		return nil, err
 	}
-	res, err := resource.New(ctx, resource.WithAttributes(
+	res, err := serviceResource(ctx, cfg)
 		attribute.String("service.name", cfg.ServiceName),
 	))
 	if err != nil {
 		return nil, fmt.Errorf("telemetry: build resource: %w", err)
 	}
@@ -122,6 +122,16 @@ func New(ctx context.Context, cfg Config) (*Runtime, error) {
 	return &Runtime{tracerProvider: tracerProvider, meterProvider: meterProvider}, nil
 }
 // serviceResource builds the OpenTelemetry resource describing this service: its
 // service.name and the service.version stamped into the binary at build time
 // (pkg/version, set from the git tag by the deploy).
 func serviceResource(ctx context.Context, cfg Config) (*resource.Resource, error) {
 	return resource.New(ctx, resource.WithAttributes(
 		attribute.String("service.name", cfg.ServiceName),
 		attribute.String("service.version", version.Version),
 	))
 }
 // TracerProvider returns the runtime tracer provider, or the global one when r is
 // not initialised.
 func (r *Runtime) TracerProvider() trace.TracerProvider {
@@ -4,6 +4,8 @@ import (
 	"context"
 	"testing"
 	"time"
 	"scrabble/pkg/version"
 )
 // TestConfigValidate covers the supported and rejected exporter selections.
@@ -82,3 +84,22 @@ func TestNilRuntime(t *testing.T) {
 		t.Errorf("nil runtime Shutdown: %v", err)
 	}
 }
 // TestServiceResource checks the resource carries service.name and the embedded
 // service.version (pkg/version, stamped at build time).
 func TestServiceResource(t *testing.T) {
 	res, err := serviceResource(context.Background(), DefaultConfig("svc"))
 	if err != nil {
 		t.Fatalf("serviceResource: %v", err)
 	}
 	attrs := map[string]string{}
 	for _, kv := range res.Attributes() {
 		attrs[string(kv.Key)] = kv.Value.AsString()
 	}
 	if attrs["service.name"] != "svc" {
 		t.Errorf("service.name = %q, want svc", attrs["service.name"])
 	}
 	if attrs["service.version"] != version.Version {
 		t.Errorf("service.version = %q, want %q", attrs["service.version"], version.Version)
 	}
 }
@@ -0,0 +1,10 @@
 // Package version exposes the build version stamped into every Scrabble service
 // binary. The default is "dev"; release builds override it through the linker
 // (`go build -ldflags "-X scrabble/pkg/version.Version=<value>"`), wired from the
 // VERSION build-arg in each service Dockerfile, which the deploy sets to the git
 // tag (`git describe --tags`). It surfaces as the OpenTelemetry service.version
 // resource attribute (see pkg/telemetry) and the SPA About screen.
 package version
 // Version is the build version, "dev" unless overridden at link time.
 var Version = "dev"
@@ -19,8 +19,10 @@ COPY platform/telegram ./platform/telegram
 # Reduce the workspace to what the platform needs: only pkg + platform/telegram.
 RUN go work edit -dropuse=./backend -dropuse=./gateway -dropuse=./loadtest -dropreplace=scrabble/gateway@v0.0.0 -dropreplace=scrabble-solver
-RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -o /out/validator ./platform/telegram/cmd/validator
+# VERSION (the deploy passes the git tag) is stamped into both binaries via the linker.
-RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -o /out/bot ./platform/telegram/cmd/bot
+ARG VERSION=dev
 RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "-X scrabble/pkg/version.Version=${VERSION}" -o /out/validator ./platform/telegram/cmd/validator
 RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "-X scrabble/pkg/version.Version=${VERSION}" -o /out/bot ./platform/telegram/cmd/bot
 # --- validator (home) --------------------------------------------------------
 FROM gcr.io/distroless/static-debian12:nonroot AS validator
@@ -152,7 +152,7 @@ targets, `validator` and `bot`. In the test contour (`deploy/docker-compose.yml`
 for Telegram egress and dials the gateway bot-link by its internal name. The bot-link
 mTLS material is generated by `deploy/gen-certs.sh`. In prod the bot runs on a separate
 host with native Telegram access and dials the gateway's published bot-link port with
-`PROD_` certificates (the deferred final stage — see `PRERELEASE.md`).
+`PROD_` certificates in production.
 A real end-to-end Telegram smoke needs a BotFather bot, its token, a public HTTPS Mini
 App origin, and the bot container; the unit tests cover the wire format, templates,
@@ -238,7 +238,10 @@ test('profile edit disables Save and flags an invalid display name', async ({ pa
  await expect(save).toBeEnabled();
 });
-test('link account: a taken email opens the irreversible merge confirmation', async ({ page }) => {
+// Account linking is hidden in Profile.svelte while we target provider sign-in (the anonymous
 // /app/ guest who upgrades by linking comes later). The flow is kept wired; re-enable these two
 // specs together with the `.emailbox` section.
 test.skip('link account: a taken email opens the irreversible merge confirmation', async ({ page }) => {
  await loginLobby(page);
  await openProfile(page);
@@ -258,7 +261,7 @@ test('link account: a taken email opens the irreversible merge confirmation', as
  await expect(page.getByText('Merge accounts?')).toBeHidden();
 });
-test('link account: the Telegram web sign-in control is offered in a browser', async ({ page }) => {
+test.skip('link account: the Telegram web sign-in control is offered in a browser', async ({ page }) => {
  await loginLobby(page);
  await openProfile(page);
  await expect(page.getByRole('button', { name: 'Link Telegram' })).toBeVisible();
@@ -83,6 +83,30 @@ test('tg-fullscreen header keeps a constant native-nav gap as the font scales',
  expect(large.overflows).toBe(false);
 });
 test('inside Telegram, a failed launch shows the retry screen, not the web login', async ({ page }) => {
  // initData carrying the mock's "bootfail" sentinel makes authTelegram reject, simulating a
  // backend outage during launch (e.g. a deploy rolling). The Mini App must surface its own
  // boot-error/retry screen and never fall back to the web (guest/email) login.
  await page.addInitScript(() => {
    Object.assign(window, {
      Telegram: {
        WebApp: {
          initData: 'query_id=bootfail&user=%7B%22id%22%3A1%7D&auth_date=1&hash=deadbeef',
          initDataUnsafe: {},
          ready() {},
          expand() {},
        },
      },
    });
  });
  await page.goto('/');
  // After the silent retries, the boot-error screen with its Retry button shows…
  await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
  // …and the web login (guest) is never shown inside Telegram.
  await expect(page.getByRole('button', { name: /guest/i })).toHaveCount(0);
 });
 test('outside Telegram, the /telegram/ entry redirects to the site root', async ({ page }) => {
  await page.goto('/telegram/');
@@ -18,6 +18,7 @@
  import CommsHub from './game/CommsHub.svelte';
  import Feedback from './screens/Feedback.svelte';
  import Blocked from './screens/Blocked.svelte';
  import BootError from './screens/BootError.svelte';
  onMount(() => {
    void bootstrap();
@@ -83,6 +84,10 @@
  {#if !routeIsLobby}
    <div class="splash">{t('common.loading')}</div>
  {/if}
 {:else if app.bootError}
  <!-- A Mini App launch that failed to authenticate (e.g. the backend was down mid-deploy):
       show the retry screen instead of falling back to the web login. -->
  <BootError />
 {:else if app.blocked}
  <Blocked />
 {:else}
@@ -123,7 +128,7 @@
 <StaleInviteModal />
 <WelcomeRedeemModal />
-{#if routeIsLobby && !app.splashDone && !app.blocked}
+{#if routeIsLobby && !app.splashDone && !app.blocked && !app.bootError}
  <Splash />
 {/if}
@@ -1,12 +1,14 @@
 <script lang="ts">
  // A best-move word drawn as a row of game tiles, mirroring the board's placed-tile
  // look (letter top-left, point value bottom-right) at a small fixed size. A blank tile
-  // shows its letter but no value, exactly as on the board. Letters are upper-cased for
+  // shows its letter but no value, exactly as on the board; in Erudit it also carries the
-  // display. The tile values ride on each tile, so this renders without the variant's
+  // blank's star (✻) in the value corner. Letters are upper-cased for display. The tile
-  // alphabet table (which the statistics screen has not cached).
+  // values ride on each tile, so this needs only the variant id (for the star) — not the
-  import type { BestMoveTile } from '../lib/model';
+  // variant's alphabet table, which the statistics screen has not cached.
  import type { BestMoveTile, Variant } from '../lib/model';
  import { usesStarBlank, BLANK_STAR } from '../lib/variants';
-  let { word }: { word: BestMoveTile[] } = $props();
+  let { word, variant }: { word: BestMoveTile[]; variant: Variant } = $props();
  const label = $derived(word.map((t) => t.letter).join('').toUpperCase());
 </script>
@@ -15,7 +17,11 @@
  {#each word as tile, i (i)}
    <span class="tile" class:blank={tile.blank} aria-hidden="true">
      <span class="letter">{tile.letter.toUpperCase()}</span>
-      {#if !tile.blank}<span class="val">{tile.value}</span>{/if}
+      {#if !tile.blank}
        <span class="val">{tile.value}</span>
      {:else if usesStarBlank(variant)}
        <span class="val blankmark">{BLANK_STAR}</span>
      {/if}
    </span>
  {/each}
 </span>
@@ -50,4 +56,10 @@
    font-size: 7px;
    font-weight: 600;
  }
  /* A placed Erudit blank ("звёздочка") shows its star where the (absent) point value sits,
     its ink kept on the value digits' line (mirrors the board tile). */
  .blankmark {
    font-size: 8px;
    bottom: 0;
  }
 </style>
@@ -4,6 +4,7 @@
  import type { Premium } from '../lib/premiums';
  import { valueForLetter } from '../lib/alphabet';
  import type { Variant } from '../lib/model';
  import { usesStarBlank, BLANK_STAR } from '../lib/variants';
  import { bonusLabel, type BoardLabelMode } from '../lib/boardlabels';
  import type { Locale } from '../lib/i18n/catalog';
@@ -254,7 +255,11 @@
          >
            {#if letter}
              <span class="letter">{letter}</span>
-              {#if !blank}<span class="val">{valueForLetter(variant, letter)}</span>{/if}
+              {#if !blank}
                <span class="val">{valueForLetter(variant, letter)}</span>
              {:else if usesStarBlank(variant)}
                <span class="val blankmark">{BLANK_STAR}</span>
              {/if}
            {:else if r === centre.row && c === centre.col}
              <span class="star">★</span>
            {:else if bl?.kind === 'single'}
@@ -410,6 +415,12 @@
    font-size: 2.4cqw;
    font-weight: 600;
  }
  /* A placed Erudit blank ("звёздочка") shows its star where the (absent) point value sits,
     its ink centred on the same line as a neighbouring tile's value digit. */
  .blankmark {
    font-size: 2.8cqw;
    bottom: 0;
  }
  .star {
    position: absolute;
    inset: 0;
@@ -17,7 +17,7 @@
  import { badgeKind } from '../lib/unread';
  import { historyGrid } from '../lib/history';
  import { centre, premiumGrid } from '../lib/premiums';
-  import { variantNameKey } from '../lib/variants';
+  import { variantNameKey, usesStarBlank, BLANK_STAR } from '../lib/variants';
  import { alphabetLetters, hasAlphabet } from '../lib/alphabet';
  import { hintsLeft } from '../lib/hints';
  import { shareOrDownloadGcg } from '../lib/share';
@@ -1293,7 +1293,7 @@
 {#if drag}
  <div class="ghost" class:touch={drag.touch} style="left:{drag.x}px; top:{drag.y}px">
-    <span>{drag.blank ? '' : drag.letter}</span>
+    <span>{drag.blank ? (usesStarBlank(variant) ? BLANK_STAR : '') : drag.letter}</span>
  </div>
 {/if}
@@ -3,6 +3,7 @@
  import { BLANK } from '../lib/placement';
  import { valueForLetter } from '../lib/alphabet';
  import type { Variant } from '../lib/model';
  import { usesStarBlank, BLANK_STAR } from '../lib/variants';
  let {
    slots,
@@ -66,8 +67,12 @@
      animate:hop={shuffling}
      onpointerdown={(e) => ondown(e, slot.index)}
    >
-      <span class="letter">{slot.letter === BLANK ? '' : slot.letter}</span>
+      {#if slot.letter === BLANK}
-      {#if slot.letter !== BLANK}<span class="val">{valueForLetter(variant, slot.letter)}</span>{/if}
+        {#if usesStarBlank(variant)}<span class="star">{BLANK_STAR}</span>{/if}
      {:else}
        <span class="letter">{slot.letter}</span>
        <span class="val">{valueForLetter(variant, slot.letter)}</span>
      {/if}
    </button>
  {/each}
 </div>
@@ -133,4 +138,15 @@
    font-size: 0.7rem;
    font-weight: 600;
  }
  /* Erudit's blank ("звёздочка") shows its star horizontally centred on the otherwise empty
     tile face; the top offset centres its ink against the neighbouring letters' block, nudged
     up a pixel to sit right by eye (it is slightly larger than them so it reads). */
  .star {
    position: absolute;
    top: calc(0.5% - 1px);
    left: 0;
    right: 0;
    text-align: center;
    font-size: 1.7rem;
  }
 </style>
@@ -18,6 +18,7 @@ import {
  telegramDisableVerticalSwipes,
  telegramHaptic,
  telegramLaunch,
  type TelegramLaunch,
  telegramOnEvent,
  telegramRequestFullscreen,
  telegramSetChrome,
@@ -41,6 +42,10 @@ export interface Toast {
 export const app = $state<{
  ready: boolean;
  /** Inside a Mini App, set when the launch failed to authenticate after its retries (e.g. the
   *  backend was down during a deploy). App.svelte then renders the boot-error retry screen
   *  instead of the web login — a Mini App has no manual sign-in to fall back to. */
  bootError: boolean;
  /** Whether the lobby's first cold load has settled (success or error). The loading splash
   *  (components/Splash.svelte) watches it to know when to dismiss; set by screens/Lobby. */
  lobbyReady: boolean;
@@ -90,6 +95,7 @@ export const app = $state<{
  resync: number;
 }>({
  ready: false,
  bootError: false,
  lobbyReady: false,
  splashDone: false,
  streamAlive: false,
@@ -563,14 +569,7 @@ export async function bootstrap(): Promise<void> {
    // listener above then re-syncs the safe-area insets. Desktop keeps the bot's full-size
    // window. No-op on clients predating Bot API 8.0.
    telegramRequestFullscreen();
-    try {
+    await bootTelegram(launch);
      await adoptSession(await gateway.authTelegram(launch.initData));
      // A blocked account skips deep-link routing — the blocked screen overlays every route.
      if (!app.blocked) await routeStartParam(launch.startParam);
    } catch (err) {
      handleError(err);
      navigate('/login');
    }
    app.ready = true;
    return;
  }
@@ -585,6 +584,57 @@ export async function bootstrap(): Promise<void> {
  app.ready = true;
 }
 // Inside a Mini App the only identity is the Telegram session, so a failed launch must never fall
 // back to the web login screen. A transient backend outage (a deploy rolling over) is retried a
 // few times in silence; only then does the boot-error screen surface, from which Retry re-runs the
 // same path (retryTelegramBoot).
 const TELEGRAM_BOOT_RETRIES = 2;
 const TELEGRAM_BOOT_RETRY_MS = 1200;
 function delay(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /**
 * bootTelegram authenticates a Mini App launch from its initData and routes any deep-link start
 * parameter, retrying a few times on a transient failure before raising the boot-error screen
 * (app.bootError). A blocked account is terminal — it switches straight to the blocked screen
 * without retrying.
 */
 async function bootTelegram(launch: TelegramLaunch): Promise<void> {
  for (let attempt = 0; ; attempt++) {
    try {
      await adoptSession(await gateway.authTelegram(launch.initData));
      // A blocked account skips deep-link routing — the blocked screen overlays every route.
      if (!app.blocked) await routeStartParam(launch.startParam);
      app.bootError = false;
      return;
    } catch (err) {
      if (err instanceof GatewayError && err.code === 'account_blocked') {
        await enterBlocked();
        return;
      }
      if (attempt >= TELEGRAM_BOOT_RETRIES) {
        app.bootError = true;
        return;
      }
      await delay(TELEGRAM_BOOT_RETRY_MS);
    }
  }
 }
 /**
 * retryTelegramBoot re-attempts the Mini App launch from the boot-error screen's Retry button. It
 * clears the error and shows the loading state again, then runs the same retrying boot; on success
 * the app renders normally, otherwise the boot-error screen returns.
 */
 export async function retryTelegramBoot(): Promise<void> {
  app.bootError = false;
  app.ready = false;
  await bootTelegram(telegramLaunch());
  app.ready = true;
 }
 /**
 * routeStartParam navigates a Telegram deep-link start parameter to its target: a
 * specific game, the friends screen with a friend-code redemption, or the lobby
@@ -11,6 +11,9 @@ export const en = {
  'blocked.temporary': 'Your account is blocked until {until}.',
  'blocked.reason': 'Reason:',
  'boot.errorTitle': "Couldn't load the game",
  'boot.errorBody': 'Please try again in a moment.',
  'common.back': 'Back',
  'common.cancel': 'Cancel',
  'common.ok': 'OK',
@@ -254,6 +257,7 @@ export const en = {
  'invitations.with': 'With {names}',
  'invitations.accept': 'Accept',
  'invitations.decline': 'Decline',
  'invitations.declineConfirm': 'Decline invitation?',
  'invitations.cancel': 'Cancel',
  'invitations.waiting': 'Waiting for replies',
@@ -261,10 +265,10 @@ export const en = {
  'new.withFriends': 'Play with friends',
  'new.pickFriends': 'Choose who to invite',
  'new.searchFriends': 'Search friends',
-  'new.gameType': 'Game type',
+  'new.gameType': 'Variant',
  'new.invite': 'Send invitation',
  'new.moveTime': 'Move time',
-  'new.hintsPerPlayer': 'Hints per player',
+  'new.hintsPerPlayer': 'Hints',
  'new.multipleWordsPerTurn': 'Multiple words per turn',
  'new.start': 'Start game',
  'new.invited': 'Invitation sent.',
@@ -12,6 +12,9 @@ export const ru: Record<MessageKey, string> = {
  'blocked.temporary': 'Ваша учётная запись заблокирована до {until}.',
  'blocked.reason': 'Причина:',
  'boot.errorTitle': 'Не удалось загрузить игру',
  'boot.errorBody': 'Попробуйте ещё раз или зайдите позже.',
  'common.back': 'Назад',
  'common.cancel': 'Отмена',
  'common.ok': 'ОК',
@@ -255,6 +258,7 @@ export const ru: Record<MessageKey, string> = {
  'invitations.with': 'С {names}',
  'invitations.accept': 'Принять',
  'invitations.decline': 'Отклонить',
  'invitations.declineConfirm': 'Отклонить приглашение?',
  'invitations.cancel': 'Отменить',
  'invitations.waiting': 'Ожидаем ответы',
@@ -262,10 +266,10 @@ export const ru: Record<MessageKey, string> = {
  'new.withFriends': 'Игра с друзьями',
  'new.pickFriends': 'Кого пригласить',
  'new.searchFriends': 'Поиск друзей',
-  'new.gameType': 'Тип игры',
+  'new.gameType': 'Вариант',
  'new.invite': 'Отправить приглашение',
  'new.moveTime': 'Время на ход',
-  'new.hintsPerPlayer': 'Подсказок на игрока',
+  'new.hintsPerPlayer': 'Подсказки',
  'new.multipleWordsPerTurn': 'Несколько слов за ход',
  'new.start': 'Начать игру',
  'new.invited': 'Приглашение отправлено.',
@@ -136,7 +136,10 @@ export class MockGateway implements GatewayClient {
  }
  // --- auth ---
-  async authTelegram(): Promise<Session> {
+  async authTelegram(initData: string): Promise<Session> {
    // e2e hook: an initData carrying this sentinel simulates a backend that rejects the launch,
    // so the Mini App boot-failure path (silent retries → boot-error screen) can be exercised.
    if (initData.includes('bootfail')) throw new GatewayError('unavailable');
    return { ...SESSION, isGuest: false };
  }
  async authGuest(): Promise<Session> {
@@ -5,6 +5,8 @@ import {
  availableVariants,
  supportsMultipleWordsToggle,
  multipleWordsForRequest,
  usesStarBlank,
  BLANK_STAR,
 } from './variants';
 describe('ALL_VARIANTS', () => {
@@ -53,3 +55,16 @@ describe('multipleWordsForRequest', () => {
    expect(multipleWordsForRequest('scrabble_en', true)).toBe(true);
  });
 });
 describe('usesStarBlank', () => {
  it('marks the blank with a star for Erudit only', () => {
    expect(usesStarBlank('erudit_ru')).toBe(true);
    expect(usesStarBlank('scrabble_ru')).toBe(false);
    expect(usesStarBlank('scrabble_en')).toBe(false);
  });
  it('BLANK_STAR is the heavy teardrop-spoked asterisk (U+273B)', () => {
    expect(BLANK_STAR).toBe('✻');
    expect(BLANK_STAR.codePointAt(0)).toBe(0x273b);
  });
 });
@@ -48,6 +48,20 @@ export const VARIANT_FLAG: Record<Variant, string> = {
 // ru -> Russian + Эрудит.
 export const VARIANT_LANGUAGE: Record<Variant, 'en' | 'ru'> = { scrabble_en: 'en', scrabble_ru: 'ru', erudit_ru: 'ru' };
 // BLANK_STAR is the glyph drawn on an Эрудит blank tile: the variant's blank is the
 // "звёздочка" (star) chip, so it carries a star rather than a bare face. U+273B HEAVY
 // TEARDROP-SPOKED ASTERISK.
 export const BLANK_STAR = '✻';
 // usesStarBlank reports whether a variant marks its blank tiles with BLANK_STAR. Only
 // Эрудит does: an empty rack blank shows the star centred, and a placed blank carries it
 // in the value corner (the corner is free — a blank has no point value). The Scrabble
 // variants leave the blank unmarked (an empty rack face; a placed blank shown by its
 // designated letter alone).
 export function usesStarBlank(v: Variant): boolean {
  return v === 'erudit_ru';
 }
 // availableVariants gates ALL_VARIANTS by the player's variant preferences (the set
 // they enabled in Settings). An empty or absent set is ungated (returns every variant)
 // — a safety fallback; a real profile always carries at least one preference.
@@ -0,0 +1,63 @@
 <script lang="ts">
  // The Mini App launch failed to authenticate after its silent retries (e.g. the backend was
  // briefly down during a deploy). Inside Telegram there is no web login to fall back to, so this
  // terminal screen offers a manual Retry that re-runs the launch (app.svelte retryTelegramBoot).
  import { retryTelegramBoot } from '../lib/app.svelte';
  import { t } from '../lib/i18n/index.svelte';
  let retrying = $state(false);
  async function retry(): Promise<void> {
    if (retrying) return;
    retrying = true;
    try {
      await retryTelegramBoot();
    } finally {
      retrying = false;
    }
  }
 </script>
 <div class="boot">
  <div class="card">
    <h1>{t('boot.errorTitle')}</h1>
    <p class="msg">{t('boot.errorBody')}</p>
    <button class="retry" onclick={retry} disabled={retrying}>{t('common.retry')}</button>
  </div>
 </div>
 <style>
  .boot {
    height: 100%;
    display: grid;
    place-items: center;
    padding: 24px;
    background: var(--bg);
  }
  .card {
    max-width: 28rem;
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: 1rem;
    text-align: center;
    color: var(--text);
  }
  h1 {
    margin: 0;
    font-size: 1.25rem;
  }
  .msg {
    margin: 0;
    color: var(--text-muted);
  }
  .retry {
    padding: 9px 16px;
    border: 1px solid var(--accent);
    background: var(--accent);
    color: var(--accent-text);
    border-radius: var(--radius-sm);
  }
  .retry:disabled {
    opacity: 0.5;
  }
 </style>
@@ -3,17 +3,19 @@
  import { SvelteMap, SvelteSet } from 'svelte/reactivity';
  import Screen from '../components/Screen.svelte';
  import TabBar from '../components/TabBar.svelte';
  import Modal from '../components/Modal.svelte';
  import { app, handleError, refreshFeedbackBadge, seedChatUnread } from '../lib/app.svelte';
  import { connection } from '../lib/connection.svelte';
  import { gateway } from '../lib/gateway';
  import { navigate } from '../lib/router.svelte';
-  import { t, type MessageKey } from '../lib/i18n/index.svelte';
+  import { t } from '../lib/i18n/index.svelte';
  import { resultBadge } from '../lib/result';
  import { badgeKind } from '../lib/unread';
  import { getLobby, setLobby } from '../lib/lobbycache';
  import { preloadGames } from '../lib/preload';
  import { gamePhase, groupGames, orderedSeats, scoreStanding, shouldBlink, type LobbyPhase } from '../lib/lobbysort';
  import type { AccountRef, GameView, Invitation } from '../lib/model';
  import { VARIANT_FLAG, VARIANT_RULES } from '../lib/variants';
  let games = $state<GameView[]>([]);
  let invitations = $state<Invitation[]>([]);
@@ -209,11 +211,14 @@
    }
  }
-  const variantKey: Record<string, MessageKey> = {
+  // The invitation pending a decline confirmation: the ❌ opens a modal (mirroring the
-    scrabble_en: 'new.english',
+  // in-game resign confirmation) rather than declining on the first tap.
-    scrabble_ru: 'new.russian',
+  let declineTarget = $state<Invitation | null>(null);
-    erudit_ru: 'new.erudit',
+  function confirmDecline() {
-  };
+    const inv = declineTarget;
    declineTarget = null;
    if (inv) declineInvite(inv);
  }
 </script>
 <Screen title={app.profile?.displayName ?? t('app.title')}>
@@ -230,16 +235,23 @@
                <span class="sub">{t('invitations.waiting')}</span>
              {:else}
                <span class="who">{t('invitations.from', { name: inv.inviter.displayName })}</span>
-                <span class="sub">{t(variantKey[inv.variant] ?? 'new.english')}</span>
+                <span class="vrow">
                  {#if VARIANT_FLAG[inv.variant]}
                    <span class="vflag">{VARIANT_FLAG[inv.variant]}</span>
                  {:else}
                    <img class="vflag-img" src="flag-ussr.svg" alt="" />
                  {/if}
                  <span class="sub">{t(VARIANT_RULES[inv.variant])}</span>
                </span>
              {/if}
              {#if !inv.multipleWordsPerTurn}<span class="sub">{t('game.oneWordRule')}</span>{/if}
            </span>
            <span class="acts">
              {#if inv.inviter.accountId === myId}
-                <button class="ghost" onclick={() => cancelInvite(inv)}>{t('invitations.cancel')}</button>
+                <button class="iconbtn" onclick={() => cancelInvite(inv)} aria-label={t('invitations.cancel')}>❌</button>
              {:else}
-                <button class="btn" onclick={() => acceptInvite(inv)}>{t('invitations.accept')}</button>
+                <button class="iconbtn" onclick={() => acceptInvite(inv)} aria-label={t('invitations.accept')}>✅</button>
-                <button class="ghost" onclick={() => declineInvite(inv)}>{t('invitations.decline')}</button>
+                <button class="iconbtn" onclick={() => (declineTarget = inv)} aria-label={t('invitations.decline')}>❌</button>
              {/if}
            </span>
          </div>
@@ -308,6 +320,15 @@
    {/if}
  </div>
  {#if declineTarget}
    <Modal title={t('invitations.declineConfirm')} onclose={() => (declineTarget = null)}>
      <div class="confirm-row">
        <button class="cancel" onclick={() => (declineTarget = null)}>{t('common.cancel')}</button>
        <button class="danger" onclick={confirmDecline} disabled={!connection.online}>{t('invitations.decline')}</button>
      </div>
    </Modal>
  {/if}
  {#snippet tabbar()}
    <TabBar>
      <button class="tab" disabled={atGameLimit} onclick={() => navigate('/new')}>
@@ -365,6 +386,40 @@
    border-radius: var(--radius);
    user-select: none;
  }
  /* The middle column grows; the envelope and the action column stay at their natural width. */
  .invite .info {
    flex: 1;
  }
  /* The variant row in an invitation: flag + the rules summary (mirrors NewGame). */
  .vrow {
    display: flex;
    align-items: baseline;
    gap: 6px;
  }
  .vflag {
    font-size: 1.1rem;
    line-height: 1;
  }
  .vflag-img {
    width: 1.3rem;
    height: auto;
    border-radius: 2px;
    align-self: center;
  }
  /* Borderless icon action (✅ / ❌), like the in-game .hicon buttons. */
  .iconbtn {
    background: none;
    border: none;
    color: var(--text);
    font-size: 1.3rem;
    line-height: 1;
    padding: 4px 6px;
    border-radius: var(--radius-sm);
    cursor: pointer;
  }
  .iconbtn:active {
    background: var(--bg-elev);
  }
  /* Game rows are a compact, flat list: no per-card frame, a hairline divider between
     consecutive rows. */
  .list {
@@ -516,23 +571,31 @@
      opacity: 0;
    }
  }
  /* The ✅ / ❌ actions stack vertically with a small gap — a min-width right column. */
  .acts {
    display: flex;
-    gap: 8px;
+    flex-direction: column;
    gap: 10px;
    flex: 0 0 auto;
    justify-content: center;
  }
-  .btn {
+  /* Decline-confirmation modal (mirrors the in-game resign confirm). */
-    padding: 8px 12px;
+  .confirm-row {
-    border: 1px solid var(--accent);
+    display: flex;
-    background: var(--accent);
+    gap: 8px;
-    color: var(--accent-text);
+  }
  .confirm-row button {
    flex: 1;
    padding: 11px;
    border-radius: var(--radius-sm);
  }
  .ghost {
    padding: 8px 12px;
    border: 1px solid var(--border);
    background: var(--surface);
    color: var(--text);
-    border-radius: var(--radius-sm);
+    font-weight: 600;
  }
  .danger {
    background: var(--danger) !important;
    color: #fff !important;
    border-color: var(--danger) !important;
  }
 </style>
@@ -67,9 +67,12 @@
  let friends = $state<AccountRef[]>([]);
  let selected = $state<string[]>([]);
  let friendFilter = $state('');
-  // No default game type yet — the player must pick one (a smarter default from play
+  // A lone offered variant is pre-selected and its picker disabled (nothing else to choose);
-  // history / language would be a future refinement). '' renders the disabled placeholder option.
+  // with several, the player picks. '' renders the disabled placeholder option.
  let inviteVariant = $state<Variant | ''>('');
  $effect(() => {
    if (variants.length === 1 && !inviteVariant) inviteVariant = variants[0].id;
  });
  let timeoutSecs = $state(86400);
  let hints = $state(1);
@@ -152,6 +155,7 @@
            <input type="checkbox" bind:checked={multipleWords} />
          </label>
        {/if}
        <div class="grow"></div>
        <p class="movelimit">{opponent === 'ai' ? t('new.aiInactiveLimit') : t('new.moveLimit', { n: AUTO_MATCH_HOURS })}</p>
        {#if opponent === 'random'}<p class="searchhint">{t('new.searchHint')}</p>{/if}
        <button
@@ -179,7 +183,7 @@
          <div class="settings-row">
            <label class="field">
              <span>{t('new.gameType')}</span>
-              <select bind:value={inviteVariant} class:placeholder={!inviteVariant}>
+              <select bind:value={inviteVariant} class:placeholder={!inviteVariant} disabled={variants.length === 1}>
                <option value="" disabled>—</option>
                {#each variants as v (v.id)}<option value={v.id}>{t(v.label)}</option>{/each}
              </select>
@@ -387,6 +391,11 @@
    color: var(--text-muted);
    margin: 0;
  }
  /* Pushes the auto-match start cluster (move-limit hint + Start button) to the bottom,
     mirroring the friend-game invite button pinned by the .fg scroll area. */
  .grow {
    flex: 1;
  }
  .invite {
    flex: 0 0 auto;
    padding: 14px;
@@ -244,9 +244,10 @@
      </form>
    {/if}
-    <!-- Linking & merge. Shown to everyone, including guests, who
+    <!-- Linking & merge. Hidden for now: we target provider sign-in, and the anonymous
-         upgrade by binding their first identity. -->
+         /app/ guest (whose upgrade path this is) comes later. Kept wired — drop `hidden`
-    <section class="emailbox">
+         to re-enable, together with the skipped linking specs in e2e/social.spec.ts. -->
    <section class="emailbox" hidden>
      <h3>{t('profile.linkAccount')}</h3>
      {#if !emailSent}
        <div class="addrow">
@@ -73,7 +73,7 @@
            {#each bestMoves as bm (bm.variant)}
              <span class="variant">{t(variantNameKey(bm.variant))}</span>
              <span class="score">{bm.score}</span>
-              <span class="wordcell"><WordTiles word={bm.word} /></span>
+              <span class="wordcell"><WordTiles word={bm.word} variant={bm.variant} /></span>
            {/each}
          </div>
        </div>