Bump version to 3.1.6, update docs

Update version across pyproject.toml, FastAPI app, HTML footers,
and V3.17 doc. Mark kicked-ball bug as resolved in docs.

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

.env.example

@@ -20,6 +20,24 @@ DEBUG=false
 # Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL
 LOG_LEVEL=INFO
 
+# Per-module log level overrides (optional)
+# These override LOG_LEVEL for specific modules.
+# LOG_LEVEL_GAME=DEBUG       # Core game logic
+# LOG_LEVEL_AI=DEBUG         # AI decisions (very verbose at DEBUG)
+# LOG_LEVEL_HANDLERS=DEBUG   # WebSocket message handlers
+# LOG_LEVEL_ROOM=DEBUG       # Room/lobby management
+# LOG_LEVEL_AUTH=DEBUG       # Auth stack (auth, routers.auth, services.auth_service)
+# LOG_LEVEL_STORES=DEBUG     # Database/Redis operations
+
+# --- Preset examples ---
+# Staging (debug game logic, quiet everything else):
+#   LOG_LEVEL=INFO
+#   LOG_LEVEL_GAME=DEBUG
+#   LOG_LEVEL_AI=DEBUG
+#
+# Production (minimal logging):
+#   LOG_LEVEL=WARNING
+
 # Environment name (development, staging, production)
 ENVIRONMENT=development
 

.gitignore

@@ -201,6 +201,9 @@ pyvenv.cfg
 # Personal notes
 lookfah.md
 
+# Internal docs (deployment info, credentials references, etc.)
+internal/
+
 # Ruff stuff:
 .ruff_cache/
 

client/app.js

@@ -379,7 +379,7 @@ class GolfGame {
         // Only show tooltips on your turn
         if (!this.isMyTurn() && !this.gameState?.waiting_for_initial_flip) return;
 
-        const value = this.getCardPointValue(cardData);
+        const value = this.getCardPointValueForTooltip(cardData);
         const special = this.getCardSpecialNote(cardData);
 
         let content = `<span class="tooltip-value ${value < 0 ? 'negative' : ''}">${value} pts</span>`;
@@ -409,14 +409,15 @@ class GolfGame {
         if (this.tooltip) this.tooltip.classList.add('hidden');
     }
 
-    getCardPointValue(cardData) {
+    getCardPointValueForTooltip(cardData) {
         const values = this.gameState?.card_values || this.getDefaultCardValues();
-        return values[cardData.rank] ?? 0;
+        const rules = this.gameState?.scoring_rules || {};
+        return this.getCardPointValue(cardData, values, rules);
     }
 
     getCardSpecialNote(cardData) {
         const rank = cardData.rank;
-        const value = this.getCardPointValue(cardData);
+        const value = this.getCardPointValueForTooltip(cardData);
         if (value < 0) return 'Negative - keep it!';
         if (rank === 'K' && value === 0) return 'Safe card';
         if (rank === 'K' && value === -2) return 'Super King!';
@@ -822,11 +823,29 @@ class GolfGame {
                                        newState.phase === 'round_over';
 
                 if (roundJustEnded && oldState) {
-                    // Save pre-reveal state for the reveal animation
-                    this.preRevealState = JSON.parse(JSON.stringify(oldState));
-                    this.postRevealState = newState;
-                    // Update state but DON'T render yet - reveal animation will handle it
+                    // Update state first so animations can read new card data
                     this.gameState = newState;
+
+                    // Fire animations for the last turn (swap/discard) before deferring
+                    try {
+                        this.triggerAnimationsForStateChange(oldState, newState);
+                    } catch (e) {
+                        console.error('Animation error on round end:', e);
+                    }
+
+                    // Build preRevealState from oldState, but mark swap position as
+                    // already handled so reveal animation doesn't double-flip it
+                    const preReveal = JSON.parse(JSON.stringify(oldState));
+                    if (this.opponentSwapAnimation) {
+                        const { playerId, position } = this.opponentSwapAnimation;
+                        const player = preReveal.players.find(p => p.id === playerId);
+                        if (player?.cards[position]) {
+                            player.cards[position].face_up = true;
+                        }
+                    }
+
+                    this.preRevealState = preReveal;
+                    this.postRevealState = newState;
                     break;
                 }
 
@@ -923,16 +942,16 @@ class GolfGame {
                     this.displayHeldCard(data.card, true);
                     this.renderGame();
                 }
-                this.showToast('Swap with a card or discard', '', 3000);
+                this.showToast('Swap with a card or discard', 'your-turn', 3000);
                 break;
 
             case 'can_flip':
                 this.waitingForFlip = true;
                 this.flipIsOptional = data.optional || false;
                 if (this.flipIsOptional) {
-                    this.showToast('Flip a card or skip', '', 3000);
+                    this.showToast('Flip a card or skip', 'your-turn', 3000);
                 } else {
-                    this.showToast('Flip a face-down card', '', 3000);
+                    this.showToast('Flip a face-down card', 'your-turn', 3000);
                 }
                 this.renderGame();
                 break;
@@ -950,7 +969,7 @@ class GolfGame {
                 // Host ended the game or player was kicked
                 this._intentionalClose = true;
                 if (this.ws) this.ws.close();
-                this.showScreen('lobby');
+                this.showLobby();
                 if (data.reason) {
                     this.showError(data.reason);
                 }
@@ -975,7 +994,7 @@ class GolfGame {
 
             case 'queue_left':
                 this.stopMatchmakingTimer();
-                this.showScreen('lobby');
+                this.showLobby();
                 break;
 
             case 'error':
@@ -995,7 +1014,7 @@ class GolfGame {
     cancelMatchmaking() {
         this.send({ type: 'queue_leave' });
         this.stopMatchmakingTimer();
-        this.showScreen('lobby');
+        this.showLobby();
     }
 
     startMatchmakingTimer() {
@@ -1431,8 +1450,9 @@ class GolfGame {
         this.swapAnimationCardEl = handCardEl;
         this.swapAnimationHandCardEl = handCardEl;
 
-        // Hide originals during animation
+        // Hide originals and UI during animation
         handCardEl.classList.add('swap-out');
+        this.discardBtn.classList.add('hidden');
         if (this.heldCardFloating) {
             this.heldCardFloating.style.visibility = 'hidden';
         }
@@ -1573,11 +1593,29 @@ class GolfGame {
         this.heldCardFloating.classList.add('hidden');
 
         if (this.pendingGameState) {
-            this.gameState = this.pendingGameState;
+            const oldState = this.gameState;
+            const newState = this.pendingGameState;
             this.pendingGameState = null;
+
+            // Check if the deferred state is a round_over transition
+            const roundJustEnded = oldState?.phase !== 'round_over' &&
+                                   newState.phase === 'round_over';
+
+            if (roundJustEnded && oldState) {
+                // Same intercept as the game_state handler: store pre/post
+                // reveal states so runRoundEndReveal can animate the reveal
+                this.gameState = newState;
+                const preReveal = JSON.parse(JSON.stringify(oldState));
+                this.preRevealState = preReveal;
+                this.postRevealState = newState;
+                // Don't renderGame - let the reveal sequence handle it
+            } else {
+                this.gameState = newState;
+                this.checkForNewPairs(oldState, newState);
                 this.renderGame();
             }
         }
+    }
 
     flipCard(position) {
         this.send({ type: 'flip_card', position });
@@ -1789,6 +1827,10 @@ class GolfGame {
         document.body.appendChild(modal);
         this.setStatus('Hole complete');
 
+        // Hide bottom bar so it doesn't overlay the modal
+        const bottomBar = document.getElementById('mobile-bottom-bar');
+        if (bottomBar) bottomBar.classList.add('hidden');
+
         // Bind next button
         const nextBtn = document.getElementById('ss-next-btn');
         nextBtn.addEventListener('click', () => {
@@ -1918,6 +1960,10 @@ class GolfGame {
         this.clearScoresheetCountdown();
         const modal = document.getElementById('scoresheet-modal');
         if (modal) modal.remove();
+
+        // Restore bottom bar
+        const bottomBar = document.getElementById('mobile-bottom-bar');
+        if (bottomBar) bottomBar.classList.remove('hidden');
     }
 
     // --- V3_02: Dealing Animation ---
@@ -2053,6 +2099,16 @@ class GolfGame {
 
     async runRoundEndReveal(scores, rankings) {
         const T = window.TIMING?.reveal || {};
+
+        // preRevealState may not be set yet if the game_state was deferred
+        // (e.g., local swap animation was in progress). Wait briefly for it.
+        if (!this.preRevealState) {
+            const waitStart = Date.now();
+            while (!this.preRevealState && Date.now() - waitStart < 3000) {
+                await this.delay(100);
+            }
+        }
+
         const oldState = this.preRevealState;
         const newState = this.postRevealState || this.gameState;
 
@@ -2062,22 +2118,35 @@ class GolfGame {
             return;
         }
 
-        // First, render the game with the OLD state (pre-reveal) so cards show face-down
-        this.gameState = newState;
-        // But render with pre-reveal card visuals
-        this.revealAnimationInProgress = true;
-
-        // Render game to show current layout (opponents, etc)
-        this.renderGame();
-
-        // Compute what needs revealing
+        // Compute what needs revealing (before renderGame changes the DOM)
         const revealsByPlayer = this.getCardsToReveal(oldState, newState);
 
         // Get reveal order: knocker first, then clockwise
         const knockerId = newState.finisher_id;
         const revealOrder = this.getRevealOrder(newState.players, knockerId);
 
-        // Initial pause
+        // Wait for the last player's animation (swap/discard/draw) to finish
+        // so the final play is visible before the reveal sequence starts
+        const maxWait = 3000;
+        const start = Date.now();
+        while (Date.now() - start < maxWait) {
+            if (!this.isDrawAnimating && !this.opponentSwapAnimation &&
+                !this.opponentDiscardAnimating && !this.localDiscardAnimating &&
+                !this.swapAnimationInProgress) {
+                break;
+            }
+            await this.delay(100);
+        }
+
+        // Extra pause so the final play registers visually before we
+        // re-render the board (renderGame below resets card positions)
+        await this.delay(T.lastPlayPause || 2500);
+
+        // Now render with pre-reveal state (face-down cards) for the reveal sequence
+        this.gameState = newState;
+        this.revealAnimationInProgress = true;
+        this.renderGame();
+
         this.setStatus('Revealing cards...', 'reveal');
         await this.delay(T.initialPause || 500);
 
@@ -2404,8 +2473,13 @@ class GolfGame {
                     this.opponentDiscardAnimating = false;
                     // Set isDrawAnimating to block renderGame from updating discard pile
                     this.isDrawAnimating = true;
+                    // Force discard DOM to show the card being drawn before animation starts
+                    // (previous animation may have blocked renderGame from updating it)
+                    if (oldDiscard) {
+                        this.updateDiscardPileDisplay(oldDiscard);
+                    }
                     console.log('[DEBUG] Opponent draw from discard - setting isDrawAnimating=true');
-                    window.drawAnimations.animateDrawDiscard(drawnCard, () => {
+                    window.drawAnimations.animateDrawDiscard(oldDiscard || drawnCard, () => {
                         console.log('[DEBUG] Opponent draw from discard complete - clearing isDrawAnimating');
                         this.isDrawAnimating = false;
                         onAnimComplete();
@@ -2415,7 +2489,7 @@ class GolfGame {
                     this.opponentSwapAnimation = null;
                     this.opponentDiscardAnimating = false;
                     this.isDrawAnimating = true;
-                    console.log('[DEBUG] Opponent draw from deck - setting isDrawAnimating=true');
+                    console.log('[DEBUG] Opponent draw from deck - setting isDrawAnimating=true, drawnCard:', drawnCard ? `${drawnCard.rank} of ${drawnCard.suit}` : 'NULL', 'discardTop:', newDiscard ? `${newDiscard.rank} of ${newDiscard.suit}` : 'EMPTY');
                     window.drawAnimations.animateDrawDeck(drawnCard, () => {
                         console.log('[DEBUG] Opponent draw from deck complete - clearing isDrawAnimating');
                         this.isDrawAnimating = false;
@@ -2496,6 +2570,7 @@ class GolfGame {
                 const cardsIdentical = wasOtherPlayer && JSON.stringify(oldPlayer.cards) === JSON.stringify(newPlayer.cards);
 
                 if (swappedPosition >= 0 && wasOtherPlayer) {
+                    console.log('[DEBUG] Swap detected:', { playerId: previousPlayerId, position: swappedPosition, wasFaceUp, newDiscard: newDiscard?.rank });
                     // Opponent swapped - animate from the actual position that changed
                     this.fireSwapAnimation(previousPlayerId, newDiscard, swappedPosition, wasFaceUp);
                     // Show CPU swap announcement
@@ -2599,6 +2674,7 @@ class GolfGame {
     }
 
     firePairCelebration(playerId, pos1, pos2) {
+        this.playSound('pair');
         const elements = this.getCardElements(playerId, pos1, pos2);
         if (elements.length < 2) return;
 
@@ -2796,16 +2872,7 @@ class GolfGame {
 
         // Use unified swap animation
         if (window.cardAnimations) {
-            // For opponent swaps, size the held card to match the opponent card
-            // rather than the deck size (default holding rect uses deck dimensions,
-            // which looks oversized next to small opponent cards on mobile)
-            const holdingRect = window.cardAnimations.getHoldingRect();
-            const heldRect = holdingRect ? {
-                left: holdingRect.left,
-                top: holdingRect.top,
-                width: sourceRect.width,
-                height: sourceRect.height
-            } : null;
+            const heldRect = window.cardAnimations.getHoldingRect();
 
             window.cardAnimations.animateUnifiedSwap(
                 discardCard,        // handCardData - card going to discard
@@ -2816,22 +2883,28 @@ class GolfGame {
                     rotation: sourceRotation,
                     wasHandFaceDown: !wasFaceUp,
                     onComplete: () => {
-                        sourceCardEl.classList.remove('swap-out');
+                        if (sourceCardEl) sourceCardEl.classList.remove('swap-out');
                         this.opponentSwapAnimation = null;
                         this.opponentDiscardAnimating = false;
                         console.log('[DEBUG] Swap animation complete - clearing opponentSwapAnimation and opponentDiscardAnimating');
+                        // Don't re-render during reveal animation - it handles its own rendering
+                        if (!this.revealAnimationInProgress) {
                             this.renderGame();
                         }
                     }
+                }
             );
         } else {
             // Fallback
             setTimeout(() => {
-                sourceCardEl.classList.remove('swap-out');
+                if (sourceCardEl) sourceCardEl.classList.remove('swap-out');
                 this.opponentSwapAnimation = null;
                 this.opponentDiscardAnimating = false;
                 console.log('[DEBUG] Swap animation fallback complete - clearing flags');
+                // Don't re-render during reveal animation - it handles its own rendering
+                if (!this.revealAnimationInProgress) {
                     this.renderGame();
+                }
             }, 500);
         }
     }
@@ -2853,6 +2926,11 @@ class GolfGame {
         if (window.cardAnimations) {
             window.cardAnimations.animateInitialFlip(cardEl, cardData, () => {
                 this.animatingPositions.delete(key);
+                // Unhide the current card element (may have been rebuilt by renderGame)
+                const currentCards = this.playerCards.querySelectorAll('.card');
+                if (currentCards[position]) {
+                    currentCards[position].style.visibility = '';
+                }
             });
         } else {
             // Fallback if card animations not available
@@ -2957,7 +3035,7 @@ class GolfGame {
                 this.hideToast();
             } else {
                 const remaining = requiredFlips - uniquePositions.length;
-                this.showToast(`Select ${remaining} more card${remaining > 1 ? 's' : ''} to flip`, '', 5000);
+                this.showToast(`Select ${remaining} more card${remaining > 1 ? 's' : ''} to flip`, 'your-turn', 5000);
             }
             return;
         }
@@ -3055,6 +3133,14 @@ class GolfGame {
     }
 
     showLobby() {
+        if (window.cardAnimations) {
+            window.cardAnimations.cancelAll();
+        }
+        this.dealAnimationInProgress = false;
+        this.isDrawAnimating = false;
+        this.localDiscardAnimating = false;
+        this.opponentDiscardAnimating = false;
+        this.opponentSwapAnimation = false;
         this.showScreen(this.lobbyScreen);
         this.lobbyError.textContent = '';
         this.roomCode = null;
@@ -3127,6 +3213,24 @@ class GolfGame {
                 `<span class="rule-tag rule-more" title="${tooltip}">+${moreCount} more</span>`;
         }
         this.activeRulesBar.classList.remove('hidden');
+
+        // Update mobile rules indicator
+        const mobileRulesBtn = document.getElementById('mobile-rules-btn');
+        const mobileRulesIcon = document.getElementById('mobile-rules-icon');
+        const mobileRulesContent = document.getElementById('mobile-rules-content');
+        if (mobileRulesBtn && mobileRulesIcon && mobileRulesContent) {
+            const isHouseRules = rules.length > 0;
+            mobileRulesIcon.textContent = isHouseRules ? '!' : 'RULES';
+            mobileRulesBtn.classList.toggle('house-rules', isHouseRules);
+
+            if (!isHouseRules) {
+                mobileRulesContent.innerHTML = '<div class="mobile-rules-content-list"><span class="rule-tag standard">Standard Rules</span></div>';
+            } else {
+                const tagHtml = (unrankedTag ? '<span class="rule-tag unranked">Unranked</span>' : '') +
+                    rules.map(renderTag).join('');
+                mobileRulesContent.innerHTML = `<div class="mobile-rules-content-list">${tagHtml}</div>`;
+            }
+        }
     }
 
     // V3_14: Map display names to rule keys
@@ -3438,15 +3542,6 @@ class GolfGame {
         // Toggle game area class for border pulse
         this.gameScreen.classList.add('final-turn-active');
 
-        // Calculate remaining turns
-        const remaining = this.countRemainingTurns();
-
-        // Update badge content
-        const remainingEl = this.finalTurnBadge.querySelector('.final-turn-remaining');
-        if (remainingEl) {
-            remainingEl.textContent = remaining === 1 ? '1 turn left' : `${remaining} turns left`;
-        }
-
         // Show badge
         this.finalTurnBadge.classList.remove('hidden');
 
@@ -3542,7 +3637,9 @@ class GolfGame {
         const cardHeight = deckRect.height;
 
         // Position card centered, overlapping both piles (lower than before)
-        const overlapOffset = cardHeight * 0.35; // More overlap = lower position
+        // On mobile portrait, place held card fully above the deck/discard area
+        const isMobilePortrait = document.body.classList.contains('mobile-portrait');
+        const overlapOffset = cardHeight * (isMobilePortrait ? 0.48 : 0.35);
         const cardLeft = centerX - cardWidth / 2;
         const cardTop = deckRect.top - overlapOffset;
         this.heldCardFloating.style.left = `${cardLeft}px`;
@@ -3554,11 +3651,21 @@ class GolfGame {
             this.heldCardFloating.style.fontSize = `${cardWidth * 0.35}px`;
         }
 
-        // Position discard button attached to right side of held card
-        const buttonLeft = cardLeft + cardWidth; // Right edge of card (no gap)
-        const buttonTop = cardTop + cardHeight * 0.3; // Vertically centered on card
+        // Position discard button
+        if (isMobilePortrait) {
+            // Below the held card, centered
+            const btnRect = this.discardBtn.getBoundingClientRect();
+            const buttonLeft = cardLeft + (cardWidth - (btnRect.width || 70)) / 2;
+            const buttonTop = cardTop + cardHeight + 4;
             this.discardBtn.style.left = `${buttonLeft}px`;
             this.discardBtn.style.top = `${buttonTop}px`;
+        } else {
+            // Right side of held card (desktop)
+            const buttonLeft = cardLeft + cardWidth;
+            const buttonTop = cardTop + cardHeight * 0.3;
+            this.discardBtn.style.left = `${buttonLeft}px`;
+            this.discardBtn.style.top = `${buttonTop}px`;
+        }
 
         if (card.rank === '★') {
             this.heldCardFloating.classList.add('joker');
@@ -3604,7 +3711,8 @@ class GolfGame {
         const centerX = (deckRect.left + deckRect.right + discardRect.left + discardRect.right) / 4;
         const cardWidth = deckRect.width;
         const cardHeight = deckRect.height;
-        const overlapOffset = cardHeight * 0.35;
+        const isMobilePortrait = document.body.classList.contains('mobile-portrait');
+        const overlapOffset = cardHeight * (isMobilePortrait ? 0.48 : 0.35);
         const cardLeft = centerX - cardWidth / 2;
         const cardTop = deckRect.top - overlapOffset;
 
@@ -3776,14 +3884,19 @@ class GolfGame {
         if (mobileTotal) mobileTotal.textContent = this.gameState.total_rounds;
 
         // Show/hide final turn badge with enhanced urgency
+        // Note: markKnocker() is deferred until after opponent areas are rebuilt below
         const isFinalTurn = this.gameState.phase === 'final_turn';
         if (isFinalTurn) {
-            this.updateFinalTurnDisplay();
+            this.gameScreen.classList.add('final-turn-active');
+            this.finalTurnBadge.classList.remove('hidden');
+            if (!this.finalTurnAnnounced) {
+                this.playSound('alert');
+                this.finalTurnAnnounced = true;
+            }
         } else {
             this.finalTurnBadge.classList.add('hidden');
             this.gameScreen.classList.remove('final-turn-active');
             this.finalTurnAnnounced = false;
-            this.clearKnockerMark();
         }
 
         // Toggle not-my-turn class to disable hover effects when it's not player's turn
@@ -3805,7 +3918,7 @@ class GolfGame {
             : this.gameState.current_player_id;
         const displayedPlayer = this.gameState.players.find(p => p.id === displayedPlayerId);
         if (displayedPlayer && displayedPlayerId !== this.playerId) {
-            this.setStatus(`${displayedPlayer.name}'s turn`);
+            this.setStatus(`${displayedPlayer.name}'s turn`, 'opponent-turn');
         }
 
         // Update player header (name + score like opponents)
@@ -4092,7 +4205,13 @@ class GolfGame {
                 cardEl.firstChild.addEventListener('click', () => this.handleCardClick(index));
                 // V3_13: Bind tooltip events for face-up cards
                 this.bindCardTooltipEvents(cardEl.firstChild, displayCard);
-                this.playerCards.appendChild(cardEl.firstChild);
+                const appendedCard = cardEl.firstChild;
+                this.playerCards.appendChild(appendedCard);
+
+                // Hide card if flip animation overlay is active on this position
+                if (this.animatingPositions.has(`local-${index}`)) {
+                    appendedCard.style.visibility = 'hidden';
+                }
             });
         }
 
@@ -4149,6 +4268,13 @@ class GolfGame {
         // Update scoreboard panel
         this.updateScorePanel();
 
+        // Mark knocker AFTER opponent areas are rebuilt (otherwise innerHTML='' wipes it)
+        if (this.gameState.phase === 'final_turn') {
+            this.markKnocker(this.gameState.finisher_id);
+        } else {
+            this.clearKnockerMark();
+        }
+
         // Initialize anime.js hover listeners on newly created cards
         if (window.cardAnimations) {
             window.cardAnimations.initHoverListeners(this.playerCards);

client/card-animations.js

@@ -46,7 +46,8 @@ class CardAnimations {
         const centerX = (deckRect.left + deckRect.right + discardRect.left + discardRect.right) / 4;
         const cardWidth = deckRect.width;
         const cardHeight = deckRect.height;
-        const overlapOffset = cardHeight * 0.35;
+        const isMobilePortrait = document.body.classList.contains('mobile-portrait');
+        const overlapOffset = cardHeight * (isMobilePortrait ? 0.48 : 0.35);
 
         return {
             left: centerX - cardWidth / 2,
@@ -155,12 +156,20 @@ class CardAnimations {
         }
         this.activeAnimations.clear();
 
-        // Remove all animation card elements (including those marked as animating)
-        document.querySelectorAll('.draw-anim-card').forEach(el => {
+        // Remove all animation overlay elements
+        document.querySelectorAll('.draw-anim-card, .traveling-card, .deal-anim-container').forEach(el => {
             delete el.dataset.animating;
             el.remove();
         });
 
+        // Restore visibility on any cards hidden during animations
+        document.querySelectorAll('.card[style*="opacity: 0"], .card[style*="opacity:0"]').forEach(el => {
+            el.style.opacity = '';
+        });
+        document.querySelectorAll('.card[style*="visibility: hidden"], .card[style*="visibility:hidden"]').forEach(el => {
+            el.style.visibility = '';
+        });
+
         // Restore discard pile visibility if it was hidden during animation
         const discardPile = document.getElementById('discard');
         if (discardPile && discardPile.style.opacity === '0') {
@@ -211,6 +220,7 @@ class CardAnimations {
     }
 
     _animateDrawDeckCard(cardData, deckRect, holdingRect, onComplete) {
+        console.log('[DEBUG] _animateDrawDeckCard called with cardData:', cardData ? `${cardData.rank} of ${cardData.suit}` : 'NULL');
         const deckColor = this.getDeckColor();
         const animCard = this.createAnimCard(deckRect, true, deckColor);
         animCard.dataset.animating = 'true'; // Mark as actively animating
@@ -219,6 +229,9 @@ class CardAnimations {
 
         if (cardData) {
             this.setCardContent(animCard, cardData);
+            // Debug: verify what was actually set on the front face
+            const front = animCard.querySelector('.draw-anim-front');
+            console.log('[DEBUG] Draw anim card front content:', front?.innerHTML);
         }
 
         this.playSound('draw-deck');
@@ -407,6 +420,7 @@ class CardAnimations {
     }
 
     // Animate initial flip at game start - smooth flip only, no lift
+    // Uses overlay sized to match the source card exactly
     animateInitialFlip(cardElement, cardData, onComplete) {
         if (!cardElement) {
             if (onComplete) onComplete();
@@ -420,8 +434,16 @@ class CardAnimations {
         const animCard = this.createAnimCard(rect, true, deckColor);
         this.setCardContent(animCard, cardData);
 
-        // Hide original card during animation
-        cardElement.style.opacity = '0';
+        // Match the front face styling to player hand cards (not deck/discard cards)
+        const front = animCard.querySelector('.draw-anim-front');
+        if (front) {
+            front.style.background = 'linear-gradient(145deg, #fff 0%, #f5f5f5 100%)';
+            front.style.border = '2px solid #ddd';
+            front.style.boxShadow = '0 2px 8px rgba(0, 0, 0, 0.3)';
+        }
+
+        // Hide original card during animation (overlay covers it)
+        cardElement.style.visibility = 'hidden';
 
         const inner = animCard.querySelector('.draw-anim-inner');
         const duration = window.TIMING?.card?.flip || 320;
@@ -436,7 +458,7 @@ class CardAnimations {
                 begin: () => this.playSound('flip'),
                 complete: () => {
                     animCard.remove();
-                    cardElement.style.opacity = '1';
+                    cardElement.style.visibility = '';
                     if (onComplete) onComplete();
                 }
             });
@@ -445,7 +467,7 @@ class CardAnimations {
         } catch (e) {
             console.error('Initial flip animation error:', e);
             animCard.remove();
-            cardElement.style.opacity = '1';
+            cardElement.style.visibility = '';
             if (onComplete) onComplete();
         }
     }
@@ -750,28 +772,36 @@ class CardAnimations {
         const id = 'turnPulse';
         this.stopTurnPulse(element);
 
-        // Quick shake animation
+        // Quick shake animation - target cards only, not labels
+        const T = window.TIMING?.turnPulse || {};
+        const cards = element.querySelectorAll(':scope > .pile-wrapper > .card, :scope > .pile-wrapper > .discard-stack > #discard');
         const doShake = () => {
             if (!this.activeAnimations.has(id)) return;
 
             anime({
-                targets: element,
-                translateX: [0, -8, 8, -6, 4, 0],
-                duration: 400,
+                targets: cards.length ? cards : element,
+                translateX: [0, -6, 6, -4, 3, 0],
+                duration: T.duration || 300,
                 easing: 'easeInOutQuad'
             });
         };
 
-        // Do initial shake, then repeat every 3 seconds
+        // Delay first shake, then repeat at interval
+        const timeout = setTimeout(() => {
+            if (!this.activeAnimations.has(id)) return;
             doShake();
-        const interval = setInterval(doShake, 3000);
-        this.activeAnimations.set(id, { interval });
+            const interval = setInterval(doShake, T.interval || 3000);
+            const entry = this.activeAnimations.get(id);
+            if (entry) entry.interval = interval;
+        }, T.initialDelay || 5000);
+        this.activeAnimations.set(id, { timeout });
     }
 
     stopTurnPulse(element) {
         const id = 'turnPulse';
         const existing = this.activeAnimations.get(id);
         if (existing) {
+            if (existing.timeout) clearTimeout(existing.timeout);
             if (existing.interval) clearInterval(existing.interval);
             if (existing.pause) existing.pause();
             this.activeAnimations.delete(id);
@@ -1097,7 +1127,7 @@ class CardAnimations {
                 });
                 // Now run the swap animation
                 this._runUnifiedSwap(handCardData, heldCardData, handRect, heldRect, discardRect, T, rotation, wasHandFaceDown, onComplete);
-            }, 100);
+            }, 350);
             return;
         }
 
@@ -1515,6 +1545,7 @@ class CardAnimations {
 
         // Create container for animation cards
         const container = document.createElement('div');
+        container.className = 'deal-anim-container';
         container.style.cssText = 'position:fixed;top:0;left:0;right:0;bottom:0;pointer-events:none;z-index:1000;';
         document.body.appendChild(container);
 

client/golfball-logo.svg

@@ -59,9 +59,9 @@
   <!-- Outer edge highlight -->
   <circle cx="50" cy="44" r="46" fill="none" stroke="#ffffff" stroke-width="0.5" opacity="0.5"/>
 
-  <!-- Card suits - single row, larger -->
-  <text x="22" y="51" font-family="Arial, sans-serif" font-size="32" font-weight="bold" fill="#1a1a1a" text-anchor="middle">&#9827;</text>
-  <text x="41" y="51" font-family="Arial, sans-serif" font-size="32" font-weight="bold" fill="#cc0000" text-anchor="middle">&#9830;</text>
-  <text x="59" y="51" font-family="Arial, sans-serif" font-size="32" font-weight="bold" fill="#1a1a1a" text-anchor="middle">&#9824;</text>
-  <text x="77" y="51" font-family="Arial, sans-serif" font-size="32" font-weight="bold" fill="#cc0000" text-anchor="middle">&#9829;</text>
+  <!-- Card suits - 2x2 grid -->
+  <text x="36" y="40" font-family="Arial, sans-serif" font-size="28" font-weight="bold" fill="#1a1a1a" text-anchor="middle">&#9827;</text>
+  <text x="64" y="40" font-family="Arial, sans-serif" font-size="28" font-weight="bold" fill="#cc0000" text-anchor="middle">&#9830;</text>
+  <text x="36" y="64" font-family="Arial, sans-serif" font-size="28" font-weight="bold" fill="#cc0000" text-anchor="middle">&#9829;</text>
+  <text x="64" y="64" font-family="Arial, sans-serif" font-size="28" font-weight="bold" fill="#1a1a1a" text-anchor="middle">&#9824;</text>
 </svg>

client/index.html

@@ -16,9 +16,11 @@
 
         <!-- Lobby Screen -->
         <div id="lobby-screen" class="screen active">
-            <h1><img src="golfball-logo.svg" alt="" class="golfball-logo"><span class="golfer-swing">🏌️</span><span class="kicked-ball">⚪</span> <span class="golf-title">Golf</span></h1>
+            <h1><span class="logo-row"><img src="golfball-logo.svg" alt="" class="golfball-logo"><span class="golfer-container"><span class="golfer-swing">🏌️</span><span class="kicked-ball">⚪</span></span></span> <span class="golf-title">GolfCards<span class="golf-title-tld">.club</span></span></h1>
             <p class="subtitle">6-Card Golf Card Game <button id="rules-btn" class="btn btn-small btn-rules">Rules</button> <button id="leaderboard-btn" class="btn btn-small leaderboard-btn">Leaderboard</button></p>
 
+            <div class="alpha-banner">Beta Testing - Bear with us while, stuff.</div>
+
             <!-- Auth prompt for unauthenticated users -->
             <div id="auth-prompt" class="auth-prompt">
                 <p>Log in or sign up to play.</p>
@@ -51,6 +53,8 @@
             </div>
 
             <p id="lobby-error" class="error"></p>
+
+            <footer class="app-footer">v3.1.6 &copy; Aaron D. Lee</footer>
         </div>
 
         <!-- Matchmaking Screen -->
@@ -78,16 +82,16 @@
             <div class="waiting-layout">
                 <div class="waiting-left-col">
                     <div class="players-list">
+                        <div class="players-list-header">
                             <h3>Players</h3>
+                            <div id="cpu-controls-section" class="cpu-controls hidden">
+                                <span class="cpu-controls-label">CPU:</span>
+                                <button id="remove-cpu-btn" class="cpu-ctrl-btn btn-danger" title="Remove CPU">−</button>
+                                <button id="add-cpu-btn" class="cpu-ctrl-btn btn-success" title="Add CPU">+</button>
+                            </div>
+                        </div>
                         <ul id="players-list"></ul>
                     </div>
-                    <div id="cpu-controls-section" class="cpu-controls-section hidden">
-                        <h4>Add CPU Opponents</h4>
-                        <div class="cpu-controls">
-                            <button id="remove-cpu-btn" class="btn btn-small btn-danger" title="Remove last CPU">−</button>
-                            <button id="add-cpu-btn" class="btn btn-small btn-success" title="Add CPU player">+</button>
-                        </div>
-                    </div>
                     <button id="leave-room-btn" class="btn btn-danger">Leave Room</button>
                 </div>
 
@@ -282,6 +286,8 @@
 
                 <p id="waiting-message" class="info">Waiting for host to start the game...</p>
             </div>
+
+            <footer class="app-footer">v3.1.6 &copy; Aaron D. Lee</footer>
         </div>
 
         <!-- Game Screen -->
@@ -303,7 +309,6 @@
                             <div id="final-turn-badge" class="final-turn-badge hidden">
                                 <span class="final-turn-icon">⚡</span>
                                 <span class="final-turn-text">FINAL TURN</span>
-                                <span class="final-turn-remaining"></span>
                             </div>
                         </div>
                         <div class="header-col header-col-right">
@@ -327,7 +332,12 @@
                                         </div>
                                         <span class="held-label">Holding</span>
                                     </div>
+                                    <div class="pile-wrapper">
+                                        <span class="pile-label">DRAW</span>
                                         <div id="deck" class="card card-back"></div>
+                                    </div>
+                                    <div class="pile-wrapper">
+                                        <span class="pile-label">DISCARD</span>
                                         <div class="discard-stack">
                                             <div id="discard" class="card">
                                                 <span id="discard-content"></span>
@@ -342,6 +352,7 @@
                                         </div>
                                     </div>
                                 </div>
+                            </div>
 
                             <div class="player-section">
                                 <div class="player-area">
@@ -397,16 +408,23 @@
                         <tbody></tbody>
                     </table>
                 </div>
+
             </div>
 
             <!-- Mobile bottom bar (hidden on desktop) -->
             <div id="mobile-bottom-bar">
                 <div class="mobile-round-info">Hole <span id="mobile-current-round">1</span>/<span id="mobile-total-rounds">9</span></div>
-                <button class="mobile-bar-btn" data-drawer="standings-panel">Standings</button>
-                <button class="mobile-bar-btn" data-drawer="scoreboard">Scores</button>
+                <button class="mobile-bar-btn mobile-rules-btn" id="mobile-rules-btn" data-drawer="rules-drawer"><span id="mobile-rules-icon">RULES</span></button>
+                <button class="mobile-bar-btn" data-drawer="standings-panel">Scorecard</button>
                 <button id="mobile-leave-btn" class="mobile-bar-btn mobile-leave-btn">End Game</button>
             </div>
 
+            <!-- Mobile rules drawer -->
+            <div id="rules-drawer" class="side-panel rules-drawer-panel">
+                <h4>Active Rules</h4>
+                <div id="mobile-rules-content"></div>
+            </div>
+
             <!-- Drawer backdrop for mobile -->
             <div id="drawer-backdrop" class="drawer-backdrop"></div>
         </div>
@@ -414,9 +432,8 @@
         <!-- Rules Screen -->
         <div id="rules-screen" class="screen">
             <div class="rules-container">
-                <button id="rules-back-btn" class="btn rules-back-btn">« Back</button>
-
                 <div class="rules-header">
+                    <button id="rules-back-btn" class="btn rules-back-btn">« Back</button>
                     <h1><span class="golfer-logo">🏌️</span> <span class="golf-title">Golf Rules</span></h1>
                     <p class="rules-subtitle">6-Card Golf Card Game - Complete Guide</p>
                 </div>
@@ -732,9 +749,8 @@ TOTAL: 0 + 8 + 16 = 24 points</pre>
         <!-- Leaderboard Screen -->
         <div id="leaderboard-screen" class="screen">
             <div class="leaderboard-container">
-                <button id="leaderboard-back-btn" class="btn leaderboard-back-btn">&laquo; Back</button>
-
                 <div class="leaderboard-header">
+                    <button id="leaderboard-back-btn" class="btn leaderboard-back-btn">&laquo; Back</button>
                     <h1>Leaderboard</h1>
                     <p class="leaderboard-subtitle">Top players ranked by performance</p>
                 </div>

client/timing-config.js

@@ -77,6 +77,7 @@ const TIMING = {
 
     // V3_03: Round end reveal timing
     reveal: {
+        lastPlayPause: 2000,      // Pause after last play animation before reveals
         voluntaryWindow: 2000,    // Time for players to flip their own cards
         initialPause: 250,        // Pause before auto-reveals start
         cardStagger: 50,          // Between cards in same hand
@@ -128,6 +129,13 @@ const TIMING = {
         pulseDelay: 200,        // Delay before card appears (pulse visible first)
     },
 
+    // Turn pulse (deck shake)
+    turnPulse: {
+        initialDelay: 5000,       // Delay before first shake
+        interval: 5400,           // Time between shakes
+        duration: 300,            // Shake animation duration
+    },
+
     // V3_17: Knock notification
     knock: {
         statusDuration: 2500,       // How long the knock status message persists

docker-compose.prod.yml

@@ -28,8 +28,14 @@ services:
       - RESEND_API_KEY=${RESEND_API_KEY:-}
       - EMAIL_FROM=${EMAIL_FROM:-Golf Cards <noreply@contact.golfcards.club>}
       - SENTRY_DSN=${SENTRY_DSN:-}
-      - ENVIRONMENT=production
-      - LOG_LEVEL=INFO
+      - ENVIRONMENT=${ENVIRONMENT:-production}
+      - LOG_LEVEL=${LOG_LEVEL:-INFO}
+      - LOG_LEVEL_GAME=${LOG_LEVEL_GAME:-}
+      - LOG_LEVEL_AI=${LOG_LEVEL_AI:-}
+      - LOG_LEVEL_HANDLERS=${LOG_LEVEL_HANDLERS:-}
+      - LOG_LEVEL_ROOM=${LOG_LEVEL_ROOM:-}
+      - LOG_LEVEL_AUTH=${LOG_LEVEL_AUTH:-}
+      - LOG_LEVEL_STORES=${LOG_LEVEL_STORES:-}
       - BASE_URL=${BASE_URL:-https://golf.example.com}
       - RATE_LIMIT_ENABLED=true
       - INVITE_ONLY=true
@@ -61,6 +67,15 @@ services:
       - "traefik.http.routers.golf.entrypoints=websecure"
       - "traefik.http.routers.golf.tls=true"
       - "traefik.http.routers.golf.tls.certresolver=letsencrypt"
+      # www -> bare domain redirect
+      - "traefik.http.routers.golf-www.rule=Host(`www.${DOMAIN:-golf.example.com}`)"
+      - "traefik.http.routers.golf-www.entrypoints=websecure"
+      - "traefik.http.routers.golf-www.tls=true"
+      - "traefik.http.routers.golf-www.tls.certresolver=letsencrypt"
+      - "traefik.http.routers.golf-www.middlewares=www-redirect"
+      - "traefik.http.middlewares.www-redirect.redirectregex.regex=^https://www\\.(.+)"
+      - "traefik.http.middlewares.www-redirect.redirectregex.replacement=https://$${1}"
+      - "traefik.http.middlewares.www-redirect.redirectregex.permanent=true"
       - "traefik.http.services.golf.loadbalancer.server.port=8000"
       # WebSocket sticky sessions
       - "traefik.http.services.golf.loadbalancer.sticky.cookie=true"

docker-compose.staging.yml

@@ -0,0 +1,146 @@
+# Staging Docker Compose for Golf Card Game
+#
+# Mirrors production but with reduced memory limits for 512MB droplet.
+#
+# Usage:
+#   docker compose -f docker-compose.staging.yml up -d --build
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    environment:
+      - POSTGRES_URL=postgresql://golf:${DB_PASSWORD}@postgres:5432/golf
+      - DATABASE_URL=postgresql://golf:${DB_PASSWORD}@postgres:5432/golf
+      - REDIS_URL=redis://redis:6379
+      - SECRET_KEY=${SECRET_KEY}
+      - RESEND_API_KEY=${RESEND_API_KEY:-}
+      - EMAIL_FROM=${EMAIL_FROM:-Golf Cards <noreply@contact.golfcards.club>}
+      - SENTRY_DSN=${SENTRY_DSN:-}
+      - ENVIRONMENT=${ENVIRONMENT:-staging}
+      - LOG_LEVEL=${LOG_LEVEL:-INFO}
+      - LOG_LEVEL_GAME=${LOG_LEVEL_GAME:-}
+      - LOG_LEVEL_AI=${LOG_LEVEL_AI:-}
+      - LOG_LEVEL_HANDLERS=${LOG_LEVEL_HANDLERS:-}
+      - LOG_LEVEL_ROOM=${LOG_LEVEL_ROOM:-}
+      - LOG_LEVEL_AUTH=${LOG_LEVEL_AUTH:-}
+      - LOG_LEVEL_STORES=${LOG_LEVEL_STORES:-}
+      - BASE_URL=${BASE_URL:-https://staging.golfcards.club}
+      - RATE_LIMIT_ENABLED=false
+      - INVITE_ONLY=true
+      - BOOTSTRAP_ADMIN_USERNAME=${BOOTSTRAP_ADMIN_USERNAME:-}
+      - BOOTSTRAP_ADMIN_PASSWORD=${BOOTSTRAP_ADMIN_PASSWORD:-}
+      - MATCHMAKING_ENABLED=true
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    deploy:
+      replicas: 1
+      restart_policy:
+        condition: on-failure
+        max_attempts: 3
+      resources:
+        limits:
+          memory: 128M
+        reservations:
+          memory: 48M
+    networks:
+      - internal
+      - web
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=golfgame_web"
+      - "traefik.http.routers.golf.rule=Host(`${DOMAIN:-staging.golfcards.club}`)"
+      - "traefik.http.routers.golf.entrypoints=websecure"
+      - "traefik.http.routers.golf.tls=true"
+      - "traefik.http.routers.golf.tls.certresolver=letsencrypt"
+      - "traefik.http.services.golf.loadbalancer.server.port=8000"
+      - "traefik.http.services.golf.loadbalancer.sticky.cookie=true"
+      - "traefik.http.services.golf.loadbalancer.sticky.cookie.name=golf_server"
+
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: golf
+      POSTGRES_USER: golf
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U golf -d golf"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - internal
+    deploy:
+      resources:
+        limits:
+          memory: 96M
+        reservations:
+          memory: 48M
+
+  redis:
+    image: redis:7-alpine
+    command: redis-server --appendonly yes --maxmemory 16mb --maxmemory-policy allkeys-lru
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - internal
+    deploy:
+      resources:
+        limits:
+          memory: 32M
+        reservations:
+          memory: 16M
+
+  traefik:
+    image: traefik:v3.6
+    environment:
+      - DOCKER_API_VERSION=1.44
+    command:
+      - "--api.dashboard=true"
+      - "--api.insecure=true"
+      - "--accesslog=true"
+      - "--log.level=WARN"
+      - "--providers.docker=true"
+      - "--providers.docker.exposedbydefault=false"
+      - "--entrypoints.web.address=:80"
+      - "--entrypoints.web.http.redirections.entryPoint.to=websecure"
+      - "--entrypoints.web.http.redirections.entryPoint.scheme=https"
+      - "--entrypoints.websecure.address=:443"
+      - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
+      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
+      - "--certificatesresolvers.letsencrypt.acme.email=${ACME_EMAIL}"
+      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - letsencrypt:/letsencrypt
+    networks:
+      - web
+    deploy:
+      resources:
+        limits:
+          memory: 48M
+
+volumes:
+  postgres_data:
+  redis_data:
+  letsencrypt:
+
+networks:
+  internal:
+    driver: bridge
+  web:
+    driver: bridge

docs/BUG-kicked-ball-position.md

@@ -0,0 +1,77 @@
+# BUG: Kicked ball animation starts from golfer's back foot
+
+## Problem
+
+The `⚪` kicked ball animation (`.kicked-ball`) appears to launch from the golfer's **back foot** (left side) instead of the **front foot** (right side). The golfer faces right in both landscape (two-row) and mobile (single-line) views due to `scaleX(-1)`.
+
+## What we want
+
+The ball should appear at the golfer's front foot (right side) and arc up and to the right — matching the "good" landscape behavior seen at wide desktop widths (~1100px+).
+
+## Good reference
+
+- Video: `good.mp4` (landscape wide view)
+- Extracted frames: `/tmp/golf-frames-good/`
+- Frame 025: Ball clearly appears to the RIGHT of the golfer, arcing up-right
+
+## Bad behavior
+
+- Videos: `Screencast_20260224_005555.mp4`, `Screencast_20260224_013326.mp4`
+- The ball appears to the LEFT of the golfer (between the golf ball logo and golfer emoji)
+- Happens at the user's phone viewport width (two-row layout, inline-grid)
+
+## Root cause analysis
+
+### The scaleX(-1) offset problem
+
+The golfer emoji (`.golfer-swing`) has `transform: scaleX(-1)` which flips it visually. This means:
+- The golfer's **layout box** occupies the same inline flow position
+- But the **visual** left/right is flipped — the front foot (visually on the right) is at the LEFT edge of the layout box
+- The `.kicked-ball` span comes right after `.golfer-swing` in inline flow, so its natural position is at the **right edge** of the golfer's layout box
+- But due to `scaleX(-1)`, the right edge of the layout box is the golfer's **visual back** (left side)
+- So `translate(0, 0)` places the ball at the golfer's back, not front
+
+### CSS translate values tested
+
+| Start X | Result |
+|---------|--------|
+| `-30px` (original) | Ball appears way behind golfer (further left) |
+| `+20px` | Ball still appears to LEFT of golfer, but slightly closer |
+| `+80px` | Not confirmed (staging 404 during test) |
+
+### Key finding: The kicked-ball's natural position needs ~60-80px positive X offset to reach the golfer's visual front foot
+
+The golfer emoji is roughly 30-40px wide at this viewport. Since `scaleX(-1)` flips the visual, the ball needs to translate **past the entire emoji width** to reach the visual front.
+
+### Media query issues encountered
+
+1. First attempt: Added `ball-kicked-mobile` keyframes with `@media (max-width: 500px)` override
+2. **CSS source order bug**: The mobile override at line 144 was being overridden by the base `.kicked-ball` rule at line 216 (later = higher priority at equal specificity)
+3. Moved override after base rule — still didn't work
+4. Added `!important` — still didn't work
+5. Raised breakpoint from 500px to 768px, then 1200px — still no visible change
+6. **Breakthrough**: Added `outline: 3px solid red; background: yellow` debug styles to base `.kicked-ball` — these DID appear, confirming CSS was loading
+7. Changed base `ball-kicked` keyframes from `-30px` to `+20px` — ball DID move, confirming the base keyframes are what's being used
+8. The mobile override keyframes may never have been applied (unclear if `ball-kicked-mobile` was actually used)
+
+### What the Chrome extension Claude analysis said
+
+> "The breakpoint is 500px, but the viewport is above 500px. At 700px+, ball-kicked-mobile never kicks in — it still uses the desktop ball-kicked animation. But the layout at this width has already shifted to a more centered layout which changes where .kicked-ball is positioned relative to the golfer."
+
+## Suggested fix approach
+
+1. **Don't use separate mobile keyframes** — just fix the base `ball-kicked` to work at all viewport widths
+2. The starting X needs to be **much larger positive** (60-80px) to account for `scaleX(-1)` placing the natural position at the golfer's visual back
+3. Alternatively, restructure the HTML: move `.kicked-ball` BEFORE `.golfer-swing` in the DOM, so its natural inline position is at the golfer's visual front (since scaleX(-1) flips left/right)
+4. Or use `position: absolute` on `.kicked-ball` and position it relative to the golfer container explicitly
+
+## Files involved
+
+- `client/style.css` — `.kicked-ball`, `@keyframes ball-kicked`, `.golfer-swing`
+- `client/index.html` — line 19: `<span class="golfer-swing">🏌️</span><span class="kicked-ball">⚪</span>`
+
+## Resolution (v3.1.6)
+
+**Fixed** by wrapping `.golfer-swing` + `.kicked-ball` in a `.golfer-container` span with `position: relative`, and changing `.kicked-ball` from `position: relative` to `position: absolute; right: -8px; bottom: 30%`. This anchors the ball to the golfer's front foot regardless of viewport width or inline flow layout.
+
+Also fixed a **CSS source order bug** where the base `.golfer-container` rule was defined after the `@media (max-width: 500px)` override, clobbering the mobile margin-left value.

docs/v3/V3_17_MOBILE_PORTRAIT_LAYOUT.md

@@ -1,6 +1,6 @@
 # V3.17: Mobile Portrait Layout
 
-**Version:** 3.1.1
+**Version:** 3.1.6
 **Commits:** `4fcdf13`, `fb3bd53`
 
 ## Overview

docs/v3/V3_18_POSTGRES_STORAGE_EFFICIENCY.md

@@ -0,0 +1,57 @@
+# V3.18: PostgreSQL Game Data Storage Efficiency
+
+**Status:** Planning
+**Priority:** Medium
+**Category:** Infrastructure / Performance
+
+## Problem
+
+Per-move game logging stores full `hand_state` and `visible_opponents` JSONB on every move. For a typical 6-player, 9-hole game this generates significant redundant data since most of each player's hand doesn't change between moves.
+
+## Areas to Investigate
+
+### 1. Delta Encoding for Move Data
+
+Store only what changed from the previous move instead of full state snapshots.
+
+- First move of each round stores full state (baseline)
+- Subsequent moves store only changed positions (e.g., `{"player_0": {"pos_2": "5H"}}`)
+- Replay reconstruction applies deltas sequentially
+- Trade-off: simpler queries vs. storage savings
+
+### 2. PostgreSQL TOAST and Compression
+
+- TOAST already compresses large JSONB values automatically
+- Measure actual on-disk size vs. logical size for typical game data
+- Consider whether explicit compression (e.g., storing gzipped blobs) adds meaningful savings over TOAST
+
+### 3. Retention Policy
+
+- Archive completed games older than N days to a separate table or cold storage
+- Configurable retention period via env var (e.g., `GAME_LOG_RETENTION_DAYS`)
+- Keep aggregate stats even after pruning raw move data
+
+### 4. Move Logging Toggle
+
+- Env var `GAME_LOGGING_ENABLED=true|false` to disable move-level logging entirely
+- Useful for non-analysis environments (dev, load testing)
+- Game outcomes and stats would still be recorded
+
+### 5. Batch Inserts
+
+- Buffer moves in memory and flush periodically instead of per-move INSERT
+- Reduces database round-trips during active games
+- Risk: data loss if server crashes mid-game (acceptable for non-critical move logs)
+
+## Measurements Needed
+
+Before optimizing, measure current impact:
+
+- Average JSONB size per move (bytes)
+- Average moves per game
+- Total storage per game (moves + overhead)
+- Query patterns: how often is per-move data actually read?
+
+## Dependencies
+
+- None (independent infrastructure improvement)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "golfgame"
-version = "3.1.1"
+version = "3.1.6"
 description = "6-Card Golf card game with AI opponents"
 readme = "README.md"
 requires-python = ">=3.11"

scripts/deploy-staging.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+set -e
+
+DROPLET="root@129.212.150.189"
+REMOTE_DIR="/opt/golfgame"
+
+echo "Syncing to staging ($DROPLET)..."
+rsync -az --delete \
+    --exclude='.git' \
+    --exclude='__pycache__' \
+    --exclude='node_modules' \
+    --exclude='.env' \
+    --exclude='internal/' \
+    server/ "$DROPLET:$REMOTE_DIR/server/"
+rsync -az --delete \
+    --exclude='.git' \
+    --exclude='__pycache__' \
+    --exclude='node_modules' \
+    client/ "$DROPLET:$REMOTE_DIR/client/"
+
+echo "Rebuilding app container..."
+ssh $DROPLET "cd $REMOTE_DIR && docker compose -f docker-compose.staging.yml up -d --build app"
+echo "Staging deploy complete."

server/.env.example

@@ -7,6 +7,24 @@ PORT=8000
 DEBUG=true
 LOG_LEVEL=DEBUG
 
+# Per-module log level overrides (optional)
+# These override LOG_LEVEL for specific modules.
+# LOG_LEVEL_GAME=DEBUG       # Core game logic
+# LOG_LEVEL_AI=DEBUG         # AI decisions (very verbose at DEBUG)
+# LOG_LEVEL_HANDLERS=DEBUG   # WebSocket message handlers
+# LOG_LEVEL_ROOM=DEBUG       # Room/lobby management
+# LOG_LEVEL_AUTH=DEBUG       # Auth stack (auth, routers.auth, services.auth_service)
+# LOG_LEVEL_STORES=DEBUG     # Database/Redis operations
+
+# --- Preset examples ---
+# Staging (debug game logic, quiet everything else):
+#   LOG_LEVEL=INFO
+#   LOG_LEVEL_GAME=DEBUG
+#   LOG_LEVEL_AI=DEBUG
+#
+# Production (minimal logging):
+#   LOG_LEVEL=WARNING
+
 # Environment (development, staging, production)
 # Affects logging format, security headers (HSTS), etc.
 ENVIRONMENT=development

server/ai.py

@@ -43,8 +43,9 @@ CPU_TIMING = {
     # Delay before CPU "looks at" the discard pile
     "initial_look": (0.3, 0.5),
     # Brief pause after draw broadcast - let draw animation complete
-    # Must be >= client draw animation duration (~1s for deck, ~0.4s for discard)
-    "post_draw_settle": 1.1,
+    # Must be >= client draw animation duration (~1.09s for deck, ~0.4s for discard)
+    # Extra margin prevents swap message from arriving before draw flip completes
+    "post_draw_settle": 1.3,
     # Consideration time after drawing (before swap/discard decision)
     "post_draw_consider": (0.2, 0.4),
     # Variance multiplier range for chaotic personality players
@@ -1301,12 +1302,28 @@ class GolfAI:
 
         max_acceptable_go_out = 14 + int(profile.aggression * 4)
 
+        # Check opponent scores - don't go out if we'd lose badly
+        opponent_min = estimate_opponent_min_score(player, game, optimistic=False)
+        # Aggressive players tolerate a bigger gap; conservative ones less
+        opponent_margin = 4 + int(profile.aggression * 4)  # 4-8 points
+        opponent_cap = opponent_min + opponent_margin
+
+        # Use the more restrictive of the two thresholds
+        effective_max = min(max_acceptable_go_out, opponent_cap)
+
         ai_log(f"  Go-out safety check: visible_base={visible_score}, "
                f"score_if_swap={score_if_swap}, score_if_flip={score_if_flip}, "
-               f"max_acceptable={max_acceptable_go_out}")
+               f"max_acceptable={max_acceptable_go_out}, opponent_min={opponent_min}, "
+               f"opponent_cap={opponent_cap}, effective_max={effective_max}")
+
+        # High-card safety: don't swap 8+ into hidden position unless it makes a pair
+        creates_pair = (last_partner.face_up and last_partner.rank == drawn_card.rank)
+        if drawn_value >= HIGH_CARD_THRESHOLD and not creates_pair:
+            ai_log(f"  >> GO-OUT: high card ({drawn_value}) into hidden, preferring flip")
+            return None  # Fall through to normal scoring (will flip)
 
         # If BOTH options are bad, choose the better one
-        if score_if_swap > max_acceptable_go_out and score_if_flip > max_acceptable_go_out:
+        if score_if_swap > effective_max and score_if_flip > effective_max:
             if score_if_swap <= score_if_flip:
                 ai_log(f"  >> SAFETY: both options bad, but swap ({score_if_swap}) "
                        f"<= flip ({score_if_flip}), forcing swap")
@@ -1322,7 +1339,7 @@ class GolfAI:
             return None
 
         # If swap is good, prefer it (known outcome vs unknown flip)
-        elif score_if_swap <= max_acceptable_go_out and score_if_swap <= score_if_flip:
+        elif score_if_swap <= effective_max and score_if_swap <= score_if_flip:
             ai_log(f"  >> SAFETY: swap gives acceptable score {score_if_swap}")
             return last_pos
 
@@ -1739,9 +1756,23 @@ class GolfAI:
         expected_hidden_total = len(face_down) * EXPECTED_HIDDEN_VALUE
         projected_score = visible_score + expected_hidden_total
 
+        # Hard cap: never knock with projected score > 10
+        if projected_score > 10:
+            ai_log(f"  Knock rejected: projected score {projected_score:.1f} > 10 hard cap")
+            return False
+
         # Tighter threshold: range 5 to 9 based on aggression
         max_acceptable = 5 + int(profile.aggression * 4)
 
+        # Check opponent threat - don't knock if an opponent likely beats us
+        opponent_min = estimate_opponent_min_score(player, game, optimistic=False)
+        if opponent_min < projected_score:
+            # Opponent is likely beating us - penalize threshold
+            threat_margin = projected_score - opponent_min
+            max_acceptable -= int(threat_margin * 0.75)
+            ai_log(f"  Knock threat penalty: opponent est {opponent_min}, "
+                   f"margin {threat_margin:.1f}, threshold now {max_acceptable}")
+
         # Exception: if all opponents are showing terrible scores, relax threshold
         all_opponents_bad = all(
             sum(get_ai_card_value(c, game.options) for c in p.cards if c.face_up) >= 25
@@ -1752,12 +1783,14 @@ class GolfAI:
 
         if projected_score <= max_acceptable:
             # Scale knock chance by how good the projected score is
-            if projected_score <= 5:
-                knock_chance = profile.aggression * 0.3  # Max 30%
-            elif projected_score <= 7:
+            if projected_score <= 4:
+                knock_chance = profile.aggression * 0.35  # Max 35%
+            elif projected_score <= 6:
                 knock_chance = profile.aggression * 0.15  # Max 15%
-            else:
-                knock_chance = profile.aggression * 0.05  # Max 5% (very rare)
+            elif projected_score <= 8:
+                knock_chance = profile.aggression * 0.06  # Max 6%
+            else:  # 9-10
+                knock_chance = profile.aggression * 0.02  # Max 2% (very rare)
 
             if random.random() < knock_chance:
                 ai_log(f"  Knock early: taking the gamble! (projected {projected_score:.1f})")
@@ -1934,7 +1967,11 @@ def _log_cpu_action(logger, game_id: Optional[str], cpu_player: Player, game: Ga
 async def process_cpu_turn(
     game: Game, cpu_player: Player, broadcast_callback, game_id: Optional[str] = None
 ) -> None:
-    """Process a complete turn for a CPU player."""
+    """Process a complete turn for a CPU player.
+
+    May raise asyncio.CancelledError if the game is ended mid-turn.
+    The caller (check_and_run_cpu_turn) handles cancellation.
+    """
     import asyncio
     from services.game_logger import get_logger
 
@@ -1962,10 +1999,8 @@ async def process_cpu_turn(
     await asyncio.sleep(thinking_time)
     ai_log(f"{cpu_player.name} done thinking, making decision")
 
-    # Check if we should try to go out early
-    GolfAI.should_go_out_early(cpu_player, game, profile)
-
     # Check if we should knock early (flip all remaining cards at once)
+    # (Opponent threat logic consolidated into should_knock_early)
     if GolfAI.should_knock_early(game, cpu_player, profile):
         if game.knock_early(cpu_player.id):
             _log_cpu_action(logger, game_id, cpu_player, game,

server/handlers.py

@@ -229,7 +229,7 @@ async def handle_start_game(data: dict, ctx: ConnectionContext, *, broadcast_gam
                     "game_state": game_state,
                 })
 
-        await check_and_run_cpu_turn(ctx.current_room)
+        check_and_run_cpu_turn(ctx.current_room)
 
 
 async def handle_flip_initial(data: dict, ctx: ConnectionContext, *, broadcast_game_state, check_and_run_cpu_turn, **kw) -> None:
@@ -240,7 +240,7 @@ async def handle_flip_initial(data: dict, ctx: ConnectionContext, *, broadcast_g
     async with ctx.current_room.game_lock:
         if ctx.current_room.game.flip_initial_cards(ctx.player_id, positions):
             await broadcast_game_state(ctx.current_room)
-            await check_and_run_cpu_turn(ctx.current_room)
+            check_and_run_cpu_turn(ctx.current_room)
 
 
 # ---------------------------------------------------------------------------
@@ -297,7 +297,7 @@ async def handle_swap(data: dict, ctx: ConnectionContext, *, broadcast_game_stat
 
             await broadcast_game_state(ctx.current_room)
             await asyncio.sleep(1.0)
-            await check_and_run_cpu_turn(ctx.current_room)
+            check_and_run_cpu_turn(ctx.current_room)
 
 
 async def handle_discard(data: dict, ctx: ConnectionContext, *, broadcast_game_state, check_and_run_cpu_turn, **kw) -> None:
@@ -329,12 +329,12 @@ async def handle_discard(data: dict, ctx: ConnectionContext, *, broadcast_game_s
                     })
                 else:
                     await asyncio.sleep(0.5)
-                    await check_and_run_cpu_turn(ctx.current_room)
+                    check_and_run_cpu_turn(ctx.current_room)
             else:
                 logger.debug("Player discarded, waiting 0.5s before CPU turn")
                 await asyncio.sleep(0.5)
                 logger.debug("Post-discard delay complete, checking for CPU turn")
-                await check_and_run_cpu_turn(ctx.current_room)
+                check_and_run_cpu_turn(ctx.current_room)
 
 
 async def handle_cancel_draw(data: dict, ctx: ConnectionContext, *, broadcast_game_state, **kw) -> None:
@@ -364,7 +364,7 @@ async def handle_flip_card(data: dict, ctx: ConnectionContext, *, broadcast_game
             )
 
         await broadcast_game_state(ctx.current_room)
-        await check_and_run_cpu_turn(ctx.current_room)
+        check_and_run_cpu_turn(ctx.current_room)
 
 
 async def handle_skip_flip(data: dict, ctx: ConnectionContext, *, broadcast_game_state, check_and_run_cpu_turn, **kw) -> None:
@@ -380,7 +380,7 @@ async def handle_skip_flip(data: dict, ctx: ConnectionContext, *, broadcast_game
             )
 
             await broadcast_game_state(ctx.current_room)
-            await check_and_run_cpu_turn(ctx.current_room)
+            check_and_run_cpu_turn(ctx.current_room)
 
 
 async def handle_flip_as_action(data: dict, ctx: ConnectionContext, *, broadcast_game_state, check_and_run_cpu_turn, **kw) -> None:
@@ -400,7 +400,7 @@ async def handle_flip_as_action(data: dict, ctx: ConnectionContext, *, broadcast
                 )
 
             await broadcast_game_state(ctx.current_room)
-            await check_and_run_cpu_turn(ctx.current_room)
+            check_and_run_cpu_turn(ctx.current_room)
 
 
 async def handle_knock_early(data: dict, ctx: ConnectionContext, *, broadcast_game_state, check_and_run_cpu_turn, **kw) -> None:
@@ -418,7 +418,7 @@ async def handle_knock_early(data: dict, ctx: ConnectionContext, *, broadcast_ga
                 )
 
             await broadcast_game_state(ctx.current_room)
-            await check_and_run_cpu_turn(ctx.current_room)
+            check_and_run_cpu_turn(ctx.current_room)
 
 
 async def handle_next_round(data: dict, ctx: ConnectionContext, *, broadcast_game_state, check_and_run_cpu_turn, **kw) -> None:
@@ -443,7 +443,7 @@ async def handle_next_round(data: dict, ctx: ConnectionContext, *, broadcast_gam
                         "game_state": game_state,
                     })
 
-            await check_and_run_cpu_turn(ctx.current_room)
+            check_and_run_cpu_turn(ctx.current_room)
         else:
             await broadcast_game_state(ctx.current_room)
 
@@ -473,6 +473,15 @@ async def handle_end_game(data: dict, ctx: ConnectionContext, *, room_manager, c
         await ctx.websocket.send_json({"type": "error", "message": "Only the host can end the game"})
         return
 
+    # Cancel any running CPU turn task so the game ends immediately
+    if ctx.current_room.cpu_turn_task:
+        ctx.current_room.cpu_turn_task.cancel()
+        try:
+            await ctx.current_room.cpu_turn_task
+        except (asyncio.CancelledError, Exception):
+            pass
+        ctx.current_room.cpu_turn_task = None
+
     await ctx.current_room.broadcast({
         "type": "game_ended",
         "reason": "Host ended the game",

server/logging_config.py

@@ -148,6 +148,39 @@ class DevelopmentFormatter(logging.Formatter):
         return output
 
 
+# Per-module log level overrides via env vars.
+# Key: env var suffix, Value: list of Python logger names to apply to.
+MODULE_LOGGER_MAP = {
+    "GAME": ["game"],
+    "AI": ["ai"],
+    "HANDLERS": ["handlers"],
+    "ROOM": ["room"],
+    "AUTH": ["auth", "routers.auth", "services.auth_service"],
+    "STORES": ["stores"],
+}
+
+
+def _apply_module_overrides() -> dict[str, str]:
+    """
+    Apply per-module log level overrides from LOG_LEVEL_{MODULE} env vars.
+
+    Returns:
+        Dict of module name -> level for any overrides that were applied.
+    """
+    active = {}
+    for module, logger_names in MODULE_LOGGER_MAP.items():
+        env_val = os.environ.get(f"LOG_LEVEL_{module}", "").upper()
+        if not env_val:
+            continue
+        level = getattr(logging, env_val, None)
+        if level is None:
+            continue
+        active[module] = env_val
+        for name in logger_names:
+            logging.getLogger(name).setLevel(level)
+    return active
+
+
 def setup_logging(
     level: str = "INFO",
     environment: str = "development",
@@ -182,12 +215,19 @@ def setup_logging(
     logging.getLogger("websockets").setLevel(logging.WARNING)
     logging.getLogger("asyncio").setLevel(logging.WARNING)
 
+    # Apply per-module overrides from env vars
+    overrides = _apply_module_overrides()
+
     # Log startup
     logger = logging.getLogger(__name__)
     logger.info(
         f"Logging configured: level={level}, environment={environment}",
         extra={"level": level, "environment": environment},
     )
+    if overrides:
+        logger.info(
+            f"Per-module log level overrides: {', '.join(f'{m}={l}' for m, l in overrides.items())}",
+        )
 
 
 class ContextLogger(logging.LoggerAdapter):

server/main.py

@@ -325,7 +325,7 @@ async def _close_all_websockets():
 app = FastAPI(
     title="Golf Card Game",
     debug=config.DEBUG,
-    version="3.1.1",
+    version="3.1.6",
     lifespan=lifespan,
 )
 
@@ -705,8 +705,40 @@ async def broadcast_game_state(room: Room):
                 })
 
 
-async def check_and_run_cpu_turn(room: Room):
-    """Check if current player is CPU and run their turn."""
+def check_and_run_cpu_turn(room: Room):
+    """Check if current player is CPU and start their turn as a background task.
+
+    The CPU turn chain runs as a fire-and-forget asyncio.Task stored on
+    room.cpu_turn_task. This allows the WebSocket message loop to remain
+    responsive so that end_game/leave messages can cancel the task immediately.
+    """
+    if room.game.phase not in (GamePhase.PLAYING, GamePhase.FINAL_TURN):
+        return
+
+    current = room.game.current_player()
+    if not current:
+        return
+
+    room_player = room.get_player(current.id)
+    if not room_player or not room_player.is_cpu:
+        return
+
+    task = asyncio.create_task(_run_cpu_chain(room))
+    room.cpu_turn_task = task
+
+    def _on_done(t: asyncio.Task):
+        # Clear the reference when the task finishes (success, cancel, or error)
+        if room.cpu_turn_task is t:
+            room.cpu_turn_task = None
+        if not t.cancelled() and t.exception():
+            logger.error(f"CPU turn task error in room {room.code}: {t.exception()}")
+
+    task.add_done_callback(_on_done)
+
+
+async def _run_cpu_chain(room: Room):
+    """Run consecutive CPU turns until a human player's turn or game ends."""
+    while True:
         if room.game.phase not in (GamePhase.PLAYING, GamePhase.FINAL_TURN):
             return
 
@@ -727,12 +759,18 @@ async def check_and_run_cpu_turn(room: Room):
 
         await process_cpu_turn(room.game, current, broadcast_cb, game_id=room.game_log_id)
 
-    # Check if next player is also CPU (chain CPU turns)
-    await check_and_run_cpu_turn(room)
-
 
 async def handle_player_leave(room: Room, player_id: str):
     """Handle a player leaving a room."""
+    # Cancel any running CPU turn task before cleanup
+    if room.cpu_turn_task:
+        room.cpu_turn_task.cancel()
+        try:
+            await room.cpu_turn_task
+        except (asyncio.CancelledError, Exception):
+            pass
+        room.cpu_turn_task = None
+
     room_code = room.code
     room_player = room.remove_player(player_id)
 

server/room.py

@@ -69,6 +69,7 @@ class Room:
     settings: dict = field(default_factory=lambda: {"decks": 1, "rounds": 1})
     game_log_id: Optional[str] = None
     game_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    cpu_turn_task: Optional[asyncio.Task] = None
 
     def add_player(
         self,