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
+                    // Update state first so animations can read new card data
-                    this.preRevealState = JSON.parse(JSON.stringify(oldState));
-                    this.postRevealState = newState;
-                    // Update state but DON'T render yet - reveal animation will handle it
                     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;
@@ -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';
         }
@@ -1574,12 +1594,28 @@ class GolfGame {
 
         if (this.pendingGameState) {
             const oldState = this.gameState;
-            this.gameState = this.pendingGameState;
+            const newState = this.pendingGameState;
             this.pendingGameState = null;
-            this.checkForNewPairs(oldState, this.gameState);
+
+            // 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 });
@@ -2063,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;
 
@@ -2072,22 +2118,35 @@ class GolfGame {
             return;
         }
 
-        // First, render the game with the OLD state (pre-reveal) so cards show face-down
+        // Compute what needs revealing (before renderGame changes the DOM)
-        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
         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);
 
@@ -2414,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();
@@ -2425,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;
@@ -2506,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
@@ -2818,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);
         }
     }
@@ -2855,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
@@ -2959,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;
         }
@@ -4129,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';
+                }
             });
         }
 

client/card-animations.js

@@ -220,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
@@ -228,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');
@@ -416,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();
@@ -429,8 +434,16 @@ class CardAnimations {
         const animCard = this.createAnimCard(rect, true, deckColor);
         this.setCardContent(animCard, cardData);
 
-        // Hide original card during animation
+        // Match the front face styling to player hand cards (not deck/discard cards)
-        cardElement.style.opacity = '0';
+        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;
@@ -445,7 +458,7 @@ class CardAnimations {
                 begin: () => this.playSound('flip'),
                 complete: () => {
                     animCard.remove();
-                    cardElement.style.opacity = '1';
+                    cardElement.style.visibility = '';
                     if (onComplete) onComplete();
                 }
             });
@@ -454,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();
         }
     }
@@ -759,26 +772,28 @@ 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,
+                targets: cards.length ? cards : element,
                 translateX: [0, -6, 6, -4, 3, 0],
-                duration: 300,
+                duration: T.duration || 300,
                 easing: 'easeInOutQuad'
             });
         };
 
-        // Delay first shake by 5 seconds, then repeat every 2 seconds
+        // Delay first shake, then repeat at interval
         const timeout = setTimeout(() => {
             if (!this.activeAnimations.has(id)) return;
             doShake();
-            const interval = setInterval(doShake, 2000);
+            const interval = setInterval(doShake, T.interval || 3000);
             const entry = this.activeAnimations.get(id);
             if (entry) entry.interval = interval;
-        }, 5000);
+        }, T.initialDelay || 5000);
         this.activeAnimations.set(id, { timeout });
     }
 
@@ -1112,7 +1127,7 @@ class CardAnimations {
                 });
                 // Now run the swap animation
                 this._runUnifiedSwap(handCardData, heldCardData, handRect, heldRect, discardRect, T, rotation, wasHandFaceDown, onComplete);
-            }, 100);
+            }, 350);
             return;
         }
 

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 -->
+  <!-- Card suits - 2x2 grid -->
-  <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="36" y="40" font-family="Arial, sans-serif" font-size="28" 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="64" y="40" font-family="Arial, sans-serif" font-size="28" 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="36" y="64" font-family="Arial, sans-serif" font-size="28" font-weight="bold" fill="#cc0000" text-anchor="middle">&#9829;</text>
-  <text x="77" y="51" font-family="Arial, sans-serif" font-size="32" 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,10 +16,10 @@
 
         <!-- 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">Alpha &mdash; Things may break. Stats may be wiped.</div>
+            <div class="alpha-banner">Beta Testing - Bear with us while, stuff.</div>
 
             <!-- Auth prompt for unauthenticated users -->
             <div id="auth-prompt" class="auth-prompt">
@@ -53,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 -->
@@ -80,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>
 
@@ -284,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 -->

client/style.css

@@ -42,15 +42,25 @@ body {
 
 /* Lobby Screen */
 #lobby-screen {
-    max-width: 400px;
+    max-width: 550px;
     margin: 0 auto;
     padding: 20px;
     text-align: center;
 }
 
+/* App footer (lobby & waiting room) */
+.app-footer {
+    margin-top: 2rem;
+    padding: 1rem 0;
+    font-size: 0.75rem;
+    color: rgba(255, 255, 255, 0.35);
+    text-align: center;
+}
+
 /* Golf title - golf ball with dimples and shine */
 .golf-title {
-    font-size: 1.3em;
+    display: block;
+    font-size: 1.05em;
     font-weight: 800;
     letter-spacing: 0.02em;
     /* Shiny gradient like a golf ball surface */
@@ -77,15 +87,72 @@ body {
     filter: drop-shadow(1px 1px 1px rgba(0,0,0,0.15));
 }
 
+.golf-title-tld {
+    font-size: 0.45em;
+    font-weight: 600;
+    letter-spacing: 0.15em;
+}
+
 /* Golf ball logo with card suits */
 .golfball-logo {
     width: 1.1em;
     height: 1.1em;
     vertical-align: middle;
-    margin-right: 18px;
+    margin-right: 8px;
     filter: drop-shadow(1px 2px 2px rgba(0,0,0,0.25));
 }
 
+#lobby-screen h1 {
+    display: inline-grid;
+    grid-template-columns: auto;
+    justify-items: start;
+    text-align: left;
+    row-gap: 0;
+}
+
+.logo-row {
+    margin-bottom: 0;
+}
+
+/* Golfer + ball container */
+.golfer-container {
+    position: relative;
+    display: inline-block;
+    margin-left: -2px;
+}
+
+#lobby-game-controls,
+#auth-prompt {
+    max-width: 400px;
+    margin-left: auto;
+    margin-right: auto;
+}
+
+@media (max-width: 500px) {
+    #lobby-screen h1 {
+        display: block;
+        text-align: center;
+        text-indent: -18px;
+    }
+    .logo-row {
+        display: inline;
+        margin-bottom: 0;
+    }
+    .golf-title {
+        display: inline;
+    }
+    .golfball-logo {
+        margin-right: 6px;
+    }
+    .golfer-swing {
+        margin-left: 0;
+        margin-right: 10px;
+    }
+    .golfer-container {
+        margin-left: 15px;
+    }
+}
+
 /* Golfer swing animation */
 .golfer-swing {
     display: inline-block;
@@ -124,44 +191,46 @@ body {
 .kicked-ball {
     display: inline-block;
     font-size: 0.2em;
-    position: relative;
+    position: absolute;
+    right: -8px;
+    bottom: 30%;
     opacity: 0;
     animation: ball-kicked 0.7s linear forwards;
     animation-delay: 0.72s;
 }
 
-/* Trajectory: y = 0.0124x² - 1.42x (parabola with peak at x=57) */
+/* Trajectory: parabolic arc from golfer's front foot, up and to the right */
 @keyframes ball-kicked {
     0% {
-        transform: translate(-12px, 8px) scale(1);
+        transform: translate(0, 0) scale(1);
         opacity: 1;
     }
     15% {
-        transform: translate(8px, -16px) scale(1);
+        transform: translate(20px, -24px) scale(1);
         opacity: 1;
     }
     30% {
-        transform: translate(28px, -31px) scale(1);
+        transform: translate(40px, -39px) scale(1);
         opacity: 1;
     }
     45% {
-        transform: translate(48px, -38px) scale(0.95);
+        transform: translate(60px, -46px) scale(0.95);
         opacity: 1;
     }
     55% {
-        transform: translate(63px, -38px) scale(0.9);
+        transform: translate(75px, -46px) scale(0.9);
         opacity: 1;
     }
     70% {
-        transform: translate(83px, -27px) scale(0.85);
+        transform: translate(95px, -35px) scale(0.85);
         opacity: 0.9;
     }
     85% {
-        transform: translate(103px, -6px) scale(0.75);
+        transform: translate(115px, -14px) scale(0.75);
         opacity: 0.6;
     }
     100% {
-        transform: translate(118px, 25px) scale(0.65);
+        transform: translate(130px, 17px) scale(0.65);
         opacity: 0;
     }
 }
@@ -208,10 +277,11 @@ body {
     background: rgba(0,0,0,0.2);
     border-radius: 10px;
     padding: 15px;
+    margin-bottom: 0;
 }
 
 .waiting-left-col .players-list h3 {
-    margin: 0 0 10px 0;
+    margin: 0;
     font-size: 1rem;
 }
 
@@ -330,29 +400,36 @@ body {
 .deck-cyan { background: linear-gradient(135deg, #00bcd4 0%, #0097a7 100%); }
 .deck-brown { background: linear-gradient(135deg, #8b4513 0%, #5d2f0d 100%); }
 
-/* CPU Controls Section - below players list */
+/* Players List Header with inline CPU controls */
-.cpu-controls-section {
+.players-list-header {
-    background: rgba(0,0,0,0.2);
-    border-radius: 8px;
-    padding: 10px 12px;
-}
-
-.cpu-controls-section h4 {
-    margin: 0 0 6px 0;
-    font-size: 0.8rem;
-    color: #f4a460;
-}
-
-.cpu-controls-section .cpu-controls {
     display: flex;
-    gap: 6px;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 8px;
 }
 
-.cpu-controls-section .cpu-controls .btn {
+.cpu-ctrl-btn {
-    flex: 1;
+    width: 28px;
-    padding: 6px 0;
+    height: 28px;
-    font-size: 1rem;
+    border: none;
+    border-radius: 50%;
+    color: white;
+    font-size: 1.1rem;
     font-weight: bold;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: opacity 0.15s;
+    line-height: 1;
+}
+
+.cpu-ctrl-btn:hover {
+    opacity: 0.85;
+}
+
+.cpu-ctrl-btn:active {
+    opacity: 0.7;
 }
 
 #waiting-message {
@@ -363,12 +440,76 @@ body {
 
 /* Mobile: stack vertically */
 @media (max-width: 700px) {
+    #waiting-screen {
+        padding: 10px 15px;
+    }
+
     .waiting-layout {
         grid-template-columns: 1fr;
+        gap: 10px;
+        padding-top: 72px;
+    }
+
+    .waiting-left-col {
+        gap: 10px;
+    }
+
+    .waiting-left-col .players-list {
+        padding: 12px;
+    }
+
+    .players-list li {
+        padding: 8px 10px;
+        margin-bottom: 6px;
+    }
+
+    #waiting-screen .settings {
+        padding: 15px;
+    }
+
+    #waiting-screen .settings h3 {
+        margin-bottom: 10px;
+    }
+
+    #leave-room-btn {
+        padding: 10px 16px;
+        font-size: 0.9rem;
     }
 
     .basic-settings-row {
-        grid-template-columns: 1fr 1fr;
+        grid-template-columns: auto minmax(80px, auto) 1fr;
+        gap: 8px;
+    }
+
+    .basic-settings-row .form-group label {
+        font-size: 0.75rem;
+    }
+
+    .stepper-control {
+        gap: 4px;
+        padding: 4px 4px;
+    }
+
+    .stepper-btn {
+        width: 24px;
+        height: 24px;
+        font-size: 1rem;
+    }
+
+    .stepper-value {
+        min-width: 18px;
+        font-size: 0.95rem;
+    }
+
+    .basic-settings-row select {
+        padding: 6px 2px;
+        font-size: 0.85rem;
+        text-align: center;
+    }
+
+
+    .deck-color-selector select {
+        min-width: 0;
     }
 }
 
@@ -376,7 +517,7 @@ body {
 .room-code-banner {
     position: fixed;
     top: 0;
-    left: 20px;
+    left: 7px;
     z-index: 100;
     background: linear-gradient(180deg, #d4845a 0%, #c4723f 50%, #b8663a 100%);
     padding: 10px 14px 18px;
@@ -668,7 +809,15 @@ input::placeholder {
 
 .cpu-controls {
     display: flex;
-    gap: 10px;
+    align-items: center;
+    gap: 4px;
+}
+
+.cpu-controls-label {
+    font-size: 0.8rem;
+    color: #f4a460;
+    font-weight: 600;
+    margin-right: 2px;
 }
 
 .checkbox-group {
@@ -1665,6 +1814,12 @@ input::placeholder {
     text-align: center;
     white-space: nowrap;
     color: #fff;
+    background: linear-gradient(135deg, #4a6741 0%, #3d5a35 100%);
+}
+
+/* Empty status - hide completely */
+.status-message:empty {
+    display: none;
 }
 
 .status-message.your-turn {
@@ -1684,6 +1839,19 @@ input::placeholder {
     color: #fff;
 }
 
+/* Round/game over status */
+.status-message.round-over,
+.status-message.game-over {
+    background: linear-gradient(135deg, #f0c040 0%, #d4a017 100%);
+    color: #2d3436;
+}
+
+/* Reveal status */
+.status-message.reveal {
+    background: linear-gradient(135deg, #8b7eb8 0%, #6b5b95 100%);
+    color: #fff;
+}
+
 /* Final turn badge - enhanced V3 with countdown */
 .final-turn-badge {
     display: flex;
@@ -1691,8 +1859,8 @@ input::placeholder {
     gap: 6px;
     background: linear-gradient(135deg, #ff6b35 0%, #d63031 100%);
     color: #fff;
-    padding: 6px 14px;
+    padding: 6px 16px;
-    border-radius: 8px;
+    border-radius: 4px;
     font-weight: 700;
     letter-spacing: 0.05em;
     white-space: nowrap;
@@ -1701,7 +1869,7 @@ input::placeholder {
 }
 
 .final-turn-badge .final-turn-text {
-    font-size: 0.85rem;
+    font-size: 0.9rem;
 }
 
 .final-turn-badge.hidden {
@@ -3329,7 +3497,7 @@ input::placeholder {
 .auth-bar {
     position: fixed;
     top: 10px;
-    right: 15px;
+    right: 7px;
     display: flex;
     align-items: center;
     gap: 10px;
@@ -4795,10 +4963,10 @@ body.screen-shake {
 .scoresheet-content {
     background: linear-gradient(145deg, #1a472a 0%, #0d3320 100%);
     border-radius: 16px;
-    padding: 24px 28px;
+    padding: 14px 18px;
     max-width: 520px;
     width: 92%;
-    max-height: 85vh;
+    max-height: 90vh;
     overflow-y: auto;
     box-shadow:
         0 16px 50px rgba(0, 0, 0, 0.6),
@@ -4810,23 +4978,23 @@ body.screen-shake {
 
 .ss-header {
     text-align: center;
-    font-size: 1.1rem;
+    font-size: 1rem;
     font-weight: 700;
     color: #f4a460;
-    margin-bottom: 18px;
+    margin-bottom: 10px;
     letter-spacing: 0.05em;
 }
 
 .ss-players {
     display: flex;
     flex-direction: column;
-    gap: 14px;
+    gap: 8px;
 }
 
 .ss-player-row {
     background: rgba(0, 0, 0, 0.2);
     border-radius: 10px;
-    padding: 12px 14px;
+    padding: 8px 10px;
     border: 1px solid rgba(255, 255, 255, 0.06);
 }
 
@@ -4834,7 +5002,7 @@ body.screen-shake {
     display: flex;
     align-items: center;
     gap: 8px;
-    margin-bottom: 8px;
+    margin-bottom: 4px;
 }
 
 .ss-player-name {
@@ -4898,10 +5066,10 @@ body.screen-shake {
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    width: 36px;
+    width: 32px;
-    height: 28px;
+    height: 24px;
     border-radius: 3px;
-    font-size: 0.72rem;
+    font-size: 0.68rem;
     font-weight: 700;
     line-height: 1;
     background: #f5f0e8;
@@ -4976,9 +5144,9 @@ body.screen-shake {
 .ss-next-btn {
     display: block;
     width: 100%;
-    margin-top: 18px;
+    margin-top: 10px;
-    padding: 10px;
+    padding: 8px;
-    font-size: 0.95rem;
+    font-size: 0.9rem;
 }
 
 /* --- V3_11: Swap Animation --- */
@@ -5002,14 +5170,21 @@ body.screen-shake {
 }
 
 body.mobile-portrait {
-    height: var(--app-height, 100vh);
-    overflow: hidden;
     overscroll-behavior: contain;
     touch-action: manipulation;
 }
 
 body.mobile-portrait #app {
     padding: 0;
+}
+
+/* Lock viewport only when game screen is active (allow scrolling on rules, lobby, etc.) */
+body.mobile-portrait:has(#game-screen.active) {
+    height: var(--app-height, 100vh);
+    overflow: hidden;
+}
+
+body.mobile-portrait:has(#game-screen.active) #app {
     height: var(--app-height, 100vh);
     overflow: hidden;
 }
@@ -5090,6 +5265,10 @@ body.mobile-portrait #matchmaking-screen {
     margin-top: 50px;
 }
 
+body.mobile-portrait .header-col-center {
+    justify-content: flex-start;
+}
+
 body.mobile-portrait .status-message {
     font-size: 1.02rem;
     white-space: nowrap;
@@ -5114,11 +5293,14 @@ body.mobile-portrait .mute-btn {
 }
 
 body.mobile-portrait .final-turn-badge {
-    font-size: 0.6rem;
+    padding: 6px 16px;
-    padding: 2px 6px;
     white-space: nowrap;
 }
 
+body.mobile-portrait .final-turn-badge .final-turn-text {
+    font-size: 1.02rem;
+}
+
 /* --- Mobile: Game table — opponents pinned top, rest centered in remaining space --- */
 body.mobile-portrait .game-table {
     display: flex;
@@ -5526,11 +5708,12 @@ body.mobile-portrait #lobby-screen {
 }
 
 body.mobile-portrait #waiting-screen {
-    padding: 10px 12px;
+    padding: 10px 15px;
     overflow-y: auto;
     max-height: 100dvh;
 }
 
+
 /* --- Mobile: Compact scoresheet modal --- */
 body.mobile-portrait .scoresheet-content {
     padding: 14px 16px;
@@ -5591,6 +5774,7 @@ body.mobile-portrait .ss-next-btn {
     font-size: 0.85rem;
 }
 
+
 /* --- Mobile: Very short screens (e.g. iPhone SE) --- */
 @media (max-height: 600px) {
     body.mobile-portrait .opponents-row {

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
+      - ENVIRONMENT=${ENVIRONMENT:-production}
-      - LOG_LEVEL=INFO
+      - 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

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)
+    # Must be >= client draw animation duration (~1.09s for deck, ~0.4s for discard)
-    "post_draw_settle": 1.1,
+    # 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:
+            if projected_score <= 4:
-                knock_chance = profile.aggression * 0.3  # Max 30%
+                knock_chance = profile.aggression * 0.35  # Max 35%
-            elif projected_score <= 7:
+            elif projected_score <= 6:
                 knock_chance = profile.aggression * 0.15  # Max 15%
-            else:
+            elif projected_score <= 8:
-                knock_chance = profile.aggression * 0.05  # Max 5% (very rare)
+                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})")
@@ -1966,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/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,
 )