Time and Date Documentation Update

CLAUDE.md

@@ -49,6 +49,13 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords:
 - **Storage:** Folder-based discovery at `games/leaderboards/{daily|weekly}/{period}/{file_id}/settings.json`
 - **File ID Format:** `{wordlist_source}-{game_mode}-{sequence}` (e.g., `classic-classic-0`)
 - **Leaderboard Page:** Four tabs (Today, Daily, Weekly, History) accessible via `?page=today|daily|weekly|history`
+- Leaderboard files use UTC for all period boundaries.
+- When displaying daily leaderboards, show the UTC period as a PST date range.
+- Example: For UTC file date 2025-12-08, display:
+  2025-12-08 00:00:00 UTC to 2025-12-08 23:59:59 UTC
+  and
+  2025-12-07 16:00:00 PST to 2025-12-08 15:59:59 PST
+  The leaderboard expander label should show: `Monday, December 08, 2025 4:00 PM PST – Tuesday, December 09, 2025 3:59:59 PM PST [settings badge]`
 
 ### AI Word Generation
 - Topic-based word list generation via HuggingFace Spaces or local transformers

README.md

@@ -94,6 +94,13 @@ Wrdler is a vocabulary learning game with a simplified grid and strategic letter
 - **Storage:** Folder-based discovery in HuggingFace repo (no index.json)
   - Path: `games/leaderboards/{daily|weekly}/{period}/{file_id}/settings.json`
   - File ID format: `{wordlist_source}-{game_mode}-{sequence}` (e.g., `classic-classic-0`)
+- **Time Display:**
+  - Leaderboard files store UTC dates/times for each period.
+  - When viewing daily leaderboards, the app displays the UTC period as a PST date range:
+    - For example, a UTC file date of `2025-12-08` covers `2025-12-08 00:00:00 UTC` to `2025-12-08 23:59:59 UTC`, which is displayed as `2025-12-07 16:00:00 PST` to `2025-12-08 15:59:59 PST`.
+    - The leaderboard expander label should show: `Monday, December 08, 2025 4:00 PM PST – Tuesday, December 09, 2025 3:59:59 PM PST [settings badge]`
+    - Daily leaderboards display the date range in PST for easier local time understanding.
+    - Weekly leaderboards use ISO week dates (e.g., `2025-W49`) and are available every Monday.
 
 **Leaderboard Page Features:**
 - **Today Tab:** Current daily and weekly leaderboards side-by-side

specs/leaderboard_spec.md

@@ -873,4 +873,14 @@ HF_REPO_ID/games/
 - Partial failures:
   - If daily succeeds and weekly fails (or vice versa), return both statuses independently; UI reports partial success.
 
----
+### 14.10 Timezone Handling
+
+- Daily leaderboard files use UTC for period boundaries.
+- When displaying, show the UTC period as a PST date range:
+  For daily leaderboards, display the period as:
+  "YYYY-MM-DD 00:00:00 UTC to YYYY-MM-DD 23:59:59 UTC"
+  and
+  "YYYY-MM-DD HH:MM:SS PST to YYYY-MM-DD HH:MM:SS PST"
+  (PST is UTC-8; adjust for daylight saving as needed)
+  For example, a UTC file date of `2025-12-08` covers `2025-12-08 00:00:00 UTC` to `2025-12-08 23:59:59 UTC`, which is displayed as `2025-12-07 16:00:00 PST` to `2025-12-08 15:59:59 PST`.
+  The leaderboard expander label should show: `Monday, December 08, 2025 4:00 PM PST – Tuesday, December 09, 2025 3:59:59 PM PST [settings badge]`

specs/requirements.md

@@ -191,6 +191,13 @@ This document breaks down the implementation tasks for Wrdler using the game rul
 **Test Results:** ✅ 25/25 tests passing (100%)
 
 ## Leaderboard System (v0.2.1) ✅ IMPLEMENTED
+- Leaderboard files store UTC dates/times for each period.
+- When displaying daily leaderboards, show the UTC period as a PST date range.
+- Example: For UTC file date 2025-12-08, display:
+  2025-12-08 00:00:00 UTC to 2025-12-08 23:59:59 UTC
+  and
+  2025-12-07 16:00:00 PST to 2025-12-08 15:59:59 PST
+  The leaderboard expander label should show: `Monday, December 08, 2025 4:00 PM PST – Tuesday, December 09, 2025 3:59:59 PM PST [settings badge]`
 
 ### Core Implementation
 

specs/specs.md

@@ -86,7 +86,7 @@ Wrdler is a Python/Streamlit vocabulary puzzle game based on BattleWords, but wi
 - ✅ **Top 5 Display:** Leaderboard banner shows top 5 players
 - ✅ **Optional Sharing:** "Show Challenge Share Links" toggle (default OFF) controls URL visibility
 
-### Leaderboard System (v0.2.1) ✅
+### Leaderboard System (v0.2.1) ✅ IMPLEMENTED
 Wrdler features a comprehensive daily and weekly leaderboard system:
 
 **Core Features:**