Documentation Update

CLAUDE.md

@@ -1,85 +1,31 @@
 # Wrdler - Project Context
 
 ## Project Overview
-Wrdler is a simplified vocabulary puzzle game based on BattleWords, with these key differences:
-- **8x6 grid** (instead of 12x12)
-- **One word per row, horizontal only** (no vertical words)
+Wrdler is a simplified vocabulary puzzle game based on BattleWords:
+- **Python project** (Streamlit, Python 3.12.8)
+- **8x6 grid** (8 columns × 6 rows, one word per row, horizontal only)
 - **No scope/radar visualization**
-- **2 free letter guesses at game start** (all instances of chosen letters are revealed)
+- **2 free letter guesses at game start** (all instances revealed)
+- **Word composition:** 2 four-letter, 2 five-letter, 2 six-letter words per puzzle
 
-**Current Version:** 0.2.0
+**Current Version:** 0.2.1
 **Repository:** https://github.com/Oncorporation/Wrdler.git
-**Live Demo:** [DEPLOYMENT_URL_HERE]
-
-## Recent Changes
-
-**v0.2.0 (Current):**
-- ✅ Daily and Weekly Leaderboard System implemented
-  - Settings-based leaderboard separation (unique leaderboards per settings combination)
-  - Folder-based discovery without index.json
-  - Top 20 displayed entries per leaderboard (can store more)
-  - Automatic score qualification checking
-  - Period-based organization: daily (`YYYY-MM-DD`), weekly (`YYYY-Www`)
-  - File ID format: `{wordlist_source}-{game_mode}-{sequence}`
-  - Unified JSON format with `entry_type` field (daily/weekly/challenge)
-- ✅ Leaderboard Page with full UI
-  - Today tab: Current daily/weekly leaderboards with query param filtering
-  - Daily tab: Last 7 days of daily leaderboards
-  - Weekly tab: Current week leaderboard
-  - History tab: Browse past leaderboards with selectors
-  - Settings badges showing game configuration for each leaderboard
-- ✅ Automatic leaderboard submission on game completion
-- ✅ Integration with challenge mode (source_challenge_id tracking)
-- ✅ Enhanced storage.py with folder listing capabilities
-
-**v0.1.1 (Previous):**
-- ✅ Enhanced AI word generation logic with intelligent word saving
-- ✅ Automatic retry mechanism for insufficient word counts (up to 3 retries)
-- ✅ 1000-word file size limit to prevent dictionary bloat
-- ✅ Better new word detection (separates existing vs. new words before saving)
-- ✅ Improved HF Space API integration with graceful fallback to local models
-- ✅ Additional word generation when initial pass doesn't meet MIN_REQUIRED threshold
-- ✅ Enhanced logging for word generation pipeline visibility
-
-**v0.1.0 (Previous):**
-- ✅ Version updated to 0.1.0 across all files
-- ✅ AI word generation functionality added
-- ✅ Word list management enhanced with AI support
-- ✅ Utility modules integrated
-- ✅ Documentation synchronized across all files
-- ✅ Project structure validated and consistent
-- ✅ All Phase 1 requirements complete (7 sprints)
-- ✅ 100% test coverage (25/25 tests passing)
-- **Status: Ready for deployment!** 🚀
-
-**v0.0.2-0.0.3 (Previous):**
-- ✅ All 7 sprints complete (12.75 hours development time)
-- ✅ Core data models updated for rectangular 8×6 grid
-- ✅ Generator refactored for horizontal-only, one-per-row placement
-- ✅ Radar/scope visualization removed (~217 lines)
-- ✅ Free letter selection UI with circular green gradient buttons
-- ✅ Grid UI updated for 8×6 display with responsive layout
-- ✅ Comprehensive integration testing suite
-- ✅ Complete documentation (GAMEPLAY_GUIDE.md)
-- ✅ Fixed duplicate rendering call bug
-- ✅ PWA support with service worker and manifest
-
-## Core Gameplay
+**Branch:** AI (working branch)
+
+## Current Features (v0.2.1)
+
+### Core Gameplay
 - 8x6 grid with 6 hidden words (one per row, horizontal only)
-- **Word composition:** 2 four-letter words, 2 five-letter words, 2 six-letter words
-- No scope/radar visualization
-- Players start by choosing 2 letters; all instances are revealed
-- Players click cells to reveal letters or empty spaces
-- After revealing a letter, players can guess words
-- Scoring: word length + bonus for unrevealed letters
-- Game ends when all words are guessed or all word letters are revealed
-- Incorrect guess history with optional display (enabled by default)
+- Players choose 2 free letters at start; all instances are revealed
+- Click cells to reveal letters or empty spaces
+- Guess words for points (word length + bonus for unrevealed letters)
+- Game ends when all words guessed or all word letters are revealed
+- Incorrect guess history display (toggleable, default enabled)
 - 10 incorrect guess limit per game
-- **✅ IMPLEMENTED:** Challenge Mode with game sharing via short URLs
-- **✅ IMPLEMENTED:** Remote storage via Hugging Face datasets
-- **✅ IMPLEMENTED:** Daily and Weekly Leaderboards (v0.2.0+)
-- **✅ IMPLEMENTED:** PWA install support (v0.2.28+)
-- **PLANNED:** Local persistent storage for game results and high scores (v0.3.0)
+
+### Game Modes
+1. **Classic Mode:** Allows consecutive guessing after correct answers
+2. **Too Easy Mode:** Single guess per reveal
 
 ### Scoring Tiers
 - **Legendary:** 45+ points
@@ -88,15 +34,44 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords, with these k
 - **Good:** 35-38 points
 - **Keep practicing:** < 35 points
 
+### Challenge Mode & Remote Storage
+- Short URL-based challenge sharing via `?game_id=<sid>`
+- Each player gets different random words from same wordlist
+- Multi-user challenge leaderboards (top 5 display)
+- Remote storage via HuggingFace datasets
+- Word list difficulty calculation
+- "Show Challenge Share Links" toggle (default OFF)
+
+### Daily & Weekly Leaderboards
+- **Settings-Based Separation:** Each unique settings combo creates separate leaderboard
+  - Settings: `game_mode`, `wordlist_source`, `show_incorrect_guesses`, `enable_free_letters`, `puzzle_options` (spacer, may_overlap)
+- **Auto Score Submission:** Checks qualification for top 20 after game completion
+- **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`
+
+### AI Word Generation
+- Topic-based word list generation via HuggingFace Spaces or local transformers
+- Automatic word saving (max 1000 words per file)
+- Retry mechanism (up to 3 attempts) for insufficient word counts
+- Fallback to dictionary words if AI unavailable
+
+### Audio & Visuals
+- Ocean-themed gradient background with wave animations
+- Toggleable background music with volume control
+- Sound effects (hit/miss/correct/incorrect) with volume control
+
+### PWA Support
+- Installable as Progressive Web App on desktop and mobile
+- Service worker for offline caching of static assets
+- Works offline for basic functionality
+
 ## Technical Architecture
 
 ### Technology Stack
 - **Framework:** Streamlit 1.51.0
 - **Language:** Python 3.12.8 (requires >=3.12, <3.13)
-- **Visualization:** Matplotlib (>=3.8)
-- **HTTP Requests:** requests (>=2.31.0)
 - **Remote Storage:** huggingface_hub (>=0.20.0)
-- **Environment:** python-dotenv (>=1.0.0)
 - **AI Generation:** transformers, gradio_client
 - **Testing:** Pytest
 - **Package Manager:** UV or pip
@@ -110,14 +85,13 @@ wrdler/
 │   ├── models.py            # Data models (Coord, Word, Puzzle, GameState)
 │   ├── generator.py         # Puzzle generation with deterministic seeding
 │   ├── logic.py             # Game mechanics (reveal, guess, scoring)
-│   ├── ui.py                # Streamlit UI
+│   ├── ui.py                # Streamlit UI with query param routing
+│   ├── oauth.py             # HuggingFace OAuth utilities (NEW)
+│   ├── settings_page.py     # Settings page UI (IN PROGRESS)
 │   ├── leaderboard.py       # Leaderboard system (daily/weekly)
 │   ├── leaderboard_page.py  # Leaderboard UI page
 │   ├── word_loader.py       # Word list management
 │   ├── word_loader_ai.py    # AI word generation
-│   ├── audio.py             # Background music system
-│   ├── sounds.py            # Sound effects management
-│   ├── generate_sounds.py   # Sound generation utilities
 │   ├── game_storage.py      # HF game storage wrapper
 │   ├── version_info.py      # Version display
 │   ├── modules/             # Shared utility modules (from OpenBadge)
@@ -129,19 +103,9 @@ wrdler/
 │   └── words/               # Word list files
 │       ├── classic.txt      # Default word list
 │       ├── fourth_grade.txt # Elementary word list
-│       └── wordlist.txt     # Full word list
 ├── tests/                   # Unit tests
-│   ├── test_sprint6_integration.py  # Comprehensive integration tests
-│   └── test_leaderboard.py  # Leaderboard system tests
 ├── specs/                   # Documentation
-│   ├── specs.md             # Game specifications
-│   ├── requirements.md      # Implementation requirements
-│   ├── leaderboard_spec.md  # Leaderboard system specification
-│   └── wrdler_implementation_plan.md  # Sprint planning summary
-├── static/                  # PWA assets
-│   ├── manifest.json        # PWA manifest
-│   ├── service-worker.js    # Service worker for offline caching
-│   └── icons/               # App icons
+├── static/                  # PWA assets (manifest.json, service-worker.js)
 ├── .env                     # Environment variables (HF credentials)
 ├── pyproject.toml          # Project metadata
 ├── requirements.txt        # Dependencies
@@ -150,162 +114,21 @@ wrdler/
 ├── README.md               # User-facing documentation
 ├── CLAUDE.md               # This file - project context for Claude
 ├── GAMEPLAY_GUIDE.md       # User guide with tips and strategies
-└── RELEASE_NOTES_v0.1.0.md # Complete release documentation
+├── pyproject.toml          # Project metadata
+├── requirements.txt        # Dependencies
+├── uv.lock                 # UV lock file
+├── Dockerfile              # Container deployment
+├── README.md               # User-facing documentation
+├── CLAUDE.md               # This file - project context for Claude
+├── GAMEPLAY_GUIDE.md       # User guide with tips and strategies
 ```
 
-## Key Features
-
-### Game Modes
-1. **Classic Mode:** Allows consecutive guessing after correct answers
-2. **Too Easy Mode:** Single guess per reveal
-
-### Audio & Visual Effects
-- **Background Music:** Toggleable ocean-themed background music with volume control
-- **Sound Effects:** Hit/miss/correct/incorrect guess sounds with volume control
-- **Ocean Theme:** Gradient animated background with wave effects
-- **Incorrect Guess History:** Visual display of wrong guesses (toggleable in settings)
-
-### ✅ Daily and Weekly Leaderboards (v0.2.0+)
-- **Settings-Based Leaderboards:** Each unique combination of game settings creates a separate leaderboard
-  - Settings that define a unique leaderboard: `game_mode`, `wordlist_source`, `show_incorrect_guesses`, `enable_free_letters`, `puzzle_options` (spacer, may_overlap)
-  - Players compete only with others using identical settings
-- **Automatic Score Submission:** Every game completion checks qualification for both daily and weekly leaderboards
-  - Top 20 scores displayed per leaderboard (can store more)
-  - Sorting: score (desc) → time (asc) → difficulty (desc)
-- **Storage Structure:**
-  - Folder-based discovery without index.json
-  - Path: `games/leaderboards/{type}/{period}/{file_id}/settings.json`
-  - File ID format: `{wordlist_source}-{game_mode}-{sequence}` (e.g., `classic-classic-0`)
-  - Period IDs: daily (`YYYY-MM-DD`), weekly (`YYYY-Www` ISO week)
-- **Leaderboard Page:**
-  - **Today Tab:** Current daily and weekly leaderboards (query param filtering via `?gidd=` and `?gidw=`)
-  - **Daily Tab:** Last 7 days of daily leaderboards with expandable settings groups
-  - **Weekly Tab:** Current week leaderboard with all settings combinations
-  - **History Tab:** Searchable past leaderboards with date/week selectors
-  - Settings badges display full game configuration for each leaderboard
-- **Integration:**
-  - Source challenge tracking (tracks if score came from a challenge)
-  - Unified JSON format with `entry_type` field ("daily", "weekly", "challenge")
-  - Backward compatible with existing challenge system
-
-### ✅ Challenge Mode & Remote Storage (v0.2.20+)
-- **Game ID System:** Short URL-based challenge sharing
-  - Format: `?game_id=<sid>` in URL (shortened URL reference)
-  - Each player gets different random words from the same wordlist
-  - Enables fair challenges between players
-  - Stored in Hugging Face dataset repository
-- **Remote Storage via HuggingFace Hub:**
-  - Per-game settings JSON in `games/{uid}/settings.json`
-  - Shortened URL mapping in `shortener.json`
-  - Multi-user challenge leaderboards with score, time, and difficulty tracking
-  - Results sorted by: highest score → fastest time → highest difficulty
-- **Challenge Features:**
-  - Submit results to existing challenges
-  - Create new challenges from any completed game
-  - Top 5 leaderboard display in Challenge Mode banner
-  - Optional player names (defaults to "Anonymous")
-  - Word list difficulty calculation and display (v0.2.29)
-  - "Show Challenge Share Links" toggle (default OFF) to control URL visibility (v0.2.27)
-  - Challenge results can contribute to daily/weekly leaderboards (tracked via `source_challenge_id`)
-
-### ✅ Progressive Web App (PWA) Support (v0.2.28+)
-- **PWA Installation:** App is installable as a Progressive Web App on desktop and mobile
-  - Service worker for basic offline caching of static assets
-  - Manifest.json with app metadata and icons
-  - Platform-specific installation instructions in INSTALL_GUIDE.md
-  - No gameplay logic changes required
-  - Works offline for basic functionality
-
-### ✅ AI Word Generation (v0.1.0+)
-- **AI-Powered Word Lists:** Generate custom word lists using Hugging Face Spaces or local transformers
-- **Topic-Based Generation:** Create words related to specific themes (e.g., "Ocean Life", "Space")
-- **Automatic Word Expansion:** New AI-generated words are saved to local files for future use
-  - Intelligent word detection: separates existing dictionary words from new AI-generated words
-  - Only new words are saved to prevent duplicates
-  - Automatic retry mechanism (up to 3 attempts) if insufficient words generated
-  - 1000-word file size limit prevents dictionary bloat
-  - Files auto-sorted by length then alphabetically
-- **Fallback Support:** Gracefully falls back to dictionary words if AI is unavailable
-- **Word Distribution:** Ensures exactly 25 words each of lengths 4, 5, and 6 per topic
-- **Dual Generation Modes:**
-  - **HF Space API** (primary): Uses Hugging Face Space for word generation when `USE_HF_WORDS=true`
-  - **Local Models** (fallback): Falls back to local transformers models if HF Space unavailable
-- **Enhanced Logging:** Detailed pipeline visibility for debugging and monitoring
-
-### PLANNED: Local Player Storage (v0.3.0)
-- **Local Storage:**
-  - Location: `~/.wrdler/data/`
-  - Files: `game_results.json`, `highscores.json`
-  - Privacy-first: no cloud dependency, offline-capable
-- **Personal High Scores:**
-  - Top 100 scores tracked automatically on local machine
-  - Filterable by wordlist and game mode
-  - High score sidebar expander display
-- **Player Statistics:**
-  - Games played, average score, best score
-  - Fastest completion time
-  - Per-player history on local device
-
-### Puzzle Generation
-- Horizontal-only word placement (one per row in 8×6 grid)
-- **Word length distribution:** Each puzzle contains exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
-- Deterministic seeding support for reproducible puzzles
-- No word spacing configuration (fixed one word per row)
-- Validation ensures no overlaps, proper bounds, correct word distribution
-
-### UI Components (v0.0.2 - Implemented)
-- **Game Grid:** Interactive 8×6 button grid (48 cells) with responsive layout
-- **Free Letter Selection:** Circular green gradient buttons (2 at game start)
-- **Score Panel:** Real-time scoring with client-side JavaScript timer
-- **Settings Sidebar:**
-  - Word list picker (classic, fourth_grade, wordlist, AI Generated)
-  - Game mode selector (Classic, Too Easy)
-  - Audio volume controls (music and effects separate)
-  - Toggle for incorrect guess history display
-  - Player name input
-  - "Show Challenge Share Links" toggle (default OFF)
-  - Enable/disable sound effects checkbox
-  - Enable/disable background music checkbox
-- **Theme System:** Ocean gradient background with CSS animations
-- **Game Over Dialog:** Final score display with tier ranking
-- **Incorrect Guess Display:** Shows history of wrong guesses with count
-- **Challenge Mode UI:**
-  - Challenge Mode banner with leaderboard (top 5 players)
-  - Share challenge button in game over dialog
-  - Submit result or create new challenge options
-  - Word list difficulty display
-- **Leaderboard Page UI (v0.2.0):**
-  - Four-tab navigation (Today, Daily, Weekly, History)
-  - Settings badges showing game configuration
-  - Filterable leaderboards by date/week
-  - Rank display with emoji indicators (🥇🥈🥉)
-  - Entry count and last updated timestamps
-  - Challenge indicator badges (🎯) for challenge-sourced scores
-- **PLANNED (v0.3.0):** Local high scores expander and personal statistics display
-
-### Development Status
-
-**Current Version:** 0.2.0 (Complete)
-- ✅ All 7 sprints complete
-- ✅ 100% test coverage (25/25 tests)
-- ✅ AI word generation implemented
-- ✅ Daily and Weekly Leaderboards fully functional
-- ✅ Settings-based leaderboard separation
-- ✅ Folder-based discovery system
-- ✅ Leaderboard page with full UI (Today/Daily/Weekly/History tabs)
-- ✅ Automatic score submission and qualification checking
-- ✅ Ready for production deployment
-- ✅ PWA support implemented
-- ✅ Challenge Mode fully functional
-- 📊 Development time: ~12.75 hours (sprints 1-7) + ~10 hours (leaderboards)
-- 📚 Complete documentation
-
-**Next Version:** v0.3.0 (Planned)
-- 📋 Local storage module (`wrdler/local_storage.py`)
-- 📋 Personal high score tracking (local JSON files)
-- 📋 High score sidebar UI display
-- 📋 Player statistics tracking and display
-- 📋 Leaderboard caching and performance optimizations
+### Page Navigation System
+Uses **query parameter-based routing** (NOT Streamlit multi-page):
+- `?page=today|daily|weekly|history` → Leaderboard pages
+- `?page=settings` → Settings page (IN PROGRESS - OAuth protected)
+- `?game_id=<sid>` → Challenge mode
+- No query params → Main game page
 
 ## Data Models
 
@@ -326,14 +149,14 @@ class Word:
 @dataclass
 class Puzzle:
     words: List[Word]
-    radar: List[Coord]
     may_overlap: bool
     spacer: int
-    uid: str  # Unique identifier for caching
+    uid: str  # Unique identifier
 
 @dataclass
 class GameState:
-    grid_size: int
+    grid_rows: int  # 6 for Wrdler
+    grid_cols: int  # 8 for Wrdler
     puzzle: Puzzle
     revealed: Set[Coord]
     guessed: Set[str]
@@ -346,6 +169,33 @@ class GameState:
     end_time: Optional[datetime]
 ```
 
+## Environment Variables
+
+Create a `.env` file in the project root:
+
+```bash
+# Challenge Mode & Leaderboards (Remote Storage)
+HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx  # HuggingFace API token with write access
+HF_REPO_ID=YourUsername/YourRepo       # Dataset repo for challenge storage
+
+# AI Word Generation
+USE_HF_WORDS=false                     # Enable HF Space API for word generation
+HF_WORD_LIST_REPO_ID=YourUsername/WordRepo  # Dataset repo for AI word lists
+
+# OAuth Admin Access (NEW)
+ADMIN_USERS=username1,username2        # Comma-separated list of admin usernames
+```
+
+### HF_REPO_ID Structure
+```
+HF_REPO_ID/
+├── shortener.json                   # URL shortener mappings
+├── games/{uid}/settings.json        # Challenge data (entry_type: "challenge")
+└── games/leaderboards/
+    ├── daily/{YYYY-MM-DD}/{file_id}/settings.json    # Daily leaderboards
+    └── weekly/{YYYY-Www}/{file_id}/settings.json     # Weekly leaderboards
+```
+
 ## Development Workflow
 
 ### Running Locally
@@ -354,318 +204,97 @@ class GameState:
 uv pip install -r requirements.txt --link-mode=copy
 
 # Run app
-uv run streamlit run app.py
-# or
 streamlit run app.py
 ```
 
-### Docker Deployment
-```bash
-docker build -t wrdler .
-docker run -p 8501:8501 wrdler
-```
-
 ### Testing
 ```bash
 pytest tests/
 ```
 
-### Environment Variables
-
-Wrdler uses environment variables for optional features. Create a `.env` file in the project root:
-
-```bash
-# ============================================
-# Challenge Mode (Remote Storage)
-# ============================================
-# Required for Challenge Mode features (game sharing, leaderboards)
-HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx  # or HF_TOKEN - HuggingFace API token with write access
-HF_REPO_ID=YourUsername/YourRepo       # Target HF dataset repo for challenge storage
-SPACE_NAME=YourUsername/Wrdler         # Your HF Space name (for deployment)
-
-# Optional
-CRYPTO_PK=                             # Reserved for future challenge signing features
-
-# ============================================
-# AI Word Generation
-# ============================================
-# Controls AI-powered word list generation
-USE_HF_WORDS=false                     # Enable HF Space API for word generation
-                                       # - true: Use Hugging Face Space API (primary)
-                                       # - false: Use local transformers models (fallback)
-
-HF_WORD_LIST_REPO_ID=YourUsername/WordRepo  # HF dataset repo for AI-generated word lists
-                                            # (Required if USE_HF_WORDS=true)
-
-IS_LOCAL=                              # Override environment detection
-                                       # - true: Force local development mode
-                                       # - false: Force production mode
-                                       # - (empty): Auto-detect based on environment
+## Next Step: OAuth-Protected Settings Page
+
+### Goal
+Move all game settings from sidebar to a dedicated settings page at `?page=settings`, protected by HuggingFace OAuth (admin-only access).
+
+### Implementation Approach
+1. **Use existing query parameter routing** (like leaderboard pages)
+2. **HuggingFace OAuth integration:**
+   - Add `hf_oauth: true` to README.md YAML header ✅ DONE
+   - Create `wrdler/oauth.py` with utility functions ✅ DONE
+   - OAuth user info available at `st.session_state["oauth_user"]`
+   - Check admin access via `ADMIN_USERS` environment variable
+3. **Create `wrdler/settings_page.py`:**
+   - Check authentication with `require_admin()` from oauth.py
+   - Move settings UI from sidebar (word list, game mode, audio, etc.)
+   - Persist settings to session state
+   - Accessible via `?page=settings`
+4. **Modify `wrdler/ui.py`:**
+   - Add settings page route handler (similar to leaderboard routing)
+   - Remove settings from sidebar (keep minimal controls only)
+   - Add "⚙️ Settings" link in footer navigation
+5. **Keep sidebar minimal:**
+   - Version info
+   - User info (if logged in)
+   - Link to settings page
+
+### HuggingFace OAuth Flow
+1. User clicks login button (HF Spaces provides this automatically)
+2. User authorizes with HF account
+3. HF redirects back with OAuth token
+4. User info stored in `st.session_state["oauth_user"]`
+5. Check `username` against `ADMIN_USERS` env var
+6. Grant/deny access to settings page
+
+### Files to Modify
+- `wrdler/ui.py` - Add settings page routing, remove sidebar settings
+- `wrdler/settings_page.py` - NEW FILE - Settings UI with OAuth protection
+- `wrdler/oauth.py` - Already created ✅
+
+### Key OAuth Functions (wrdler/oauth.py)
+```python
+get_user_info() → Dict | None           # Get authenticated user info
+get_username() → str | None             # Get username (preferred_username)
+is_authenticated() → bool               # Check if user is logged in
+is_admin(allowed_users) → bool          # Check if user is admin
+require_admin(page_name) → bool         # Validate admin access or show error
 ```
 
-#### Getting Your HF_API_TOKEN
-1. Go to https://huggingface.co/settings/tokens
-2. Create a new token with `write` access
-3. Add to `.env` file as `HF_API_TOKEN=hf_...`
-
-#### HF_REPO_ID Structure (Challenge Mode & Leaderboards)
-The dataset repository will contain:
-- `shortener.json` - Short URL mappings
-- `games/{uid}/settings.json` - Per-game challenge data (entry_type: "challenge")
-- `games/{uid}/result.json` - Optional detailed results
-- `games/leaderboards/daily/{date}/{file_id}/settings.json` - Daily leaderboards (entry_type: "daily")
-- `games/leaderboards/weekly/{week}/{file_id}/settings.json` - Weekly leaderboards (entry_type: "weekly")
-
-#### HF_WORD_LIST_REPO_ID Structure (AI Word Generation)
-The dataset repository will contain:
-- `words/{topic}.txt` - AI-generated word lists by topic
-- Auto-managed by `word_loader_ai.py`
-- Maximum 1000 words per file
-- Sorted by length then alphabetically
-
-#### Environment Variable Behavior
-**Without these variables:**
-- Challenge Mode features (sharing, leaderboards) will be disabled
-- AI word generation will fall back to local transformers models
-- Core game functionality remains fully operational
-
-**With these variables:**
-- Challenge Mode enables game sharing via short URLs
-- AI generation can use HF Space API (faster, more reliable)
-- Remote storage for multi-user leaderboards
-
-## Git Configuration & Deployment
-**Current Branch:** main
-**Purpose:** Wrdler - vocabulary puzzle game with simplified 8x6 grid
-**Main Branch:** main
-
-### Remotes
-- **ONCORP (origin):** https://github.com/Oncorporation/Wrdler.git (main repository)
-- **Hugging Face Spaces:** https://huggingface.co/spaces/[USERNAME]/Wrdler (live deployment)
-
-### Deployment Platforms
-1. **Hugging Face Spaces** (Primary) - Dockerfile deployment
-2. **Local Development** - Streamlit run
-3. **Docker** - Containerized deployment
-4. **PWA** - Installable web app on any platform
-
-## Sprint Summary (v0.0.2 - Complete)
-
-| Sprint | Description | Time | Tests | Status |
-|--------|-------------|------|-------|--------|
-| Sprint 1 | Core Data Models | 3h | 13/13 ✅ | Complete |
-| Sprint 2 | Puzzle Generator | 3h | 5/5 ✅ | Complete |
-| Sprint 3 | Remove Radar | 0.5h | N/A | Complete |
-| Sprint 4 | Free Letters UI | 2h | Manual ✅ | Complete |
-| Sprint 5 | Grid UI Updates | 1.25h | Syntax ✅ | Complete |
-| Sprint 6 | Integration Testing | 2h | 7/7 ✅ | Complete |
-| Sprint 7 | Documentation | 1h | N/A | Complete |
-| **Total** | **All Features** | **12.75h** | **25/25** | **Complete ✅** |
-
-**Status:** Ready for deployment! 🚀
-
-## Post-v0.0.2 Enhancements
-
-### v0.2.0 (Daily and Weekly Leaderboards)
-- Daily and weekly leaderboard system with settings-based separation
-- Folder-based discovery without index.json
-- Automatic score qualification and submission
-- Leaderboard page with four-tab navigation (Today, Daily, Weekly, History)
-- Settings badges and query parameter filtering
-- Integration with challenge mode (source_challenge_id tracking)
-- Unified JSON format with entry_type field
-- Enhanced storage.py with folder listing functions
-
-### v0.1.1 (AI Word Generation Enhancement)
-- Enhanced AI word generation with intelligent word saving
-- Automatic retry mechanism for insufficient word counts (up to 3 retries)
-- 1000-word file size limit to prevent dictionary bloat
-- Improved new word detection (separates existing vs. new words)
-- Better HF Space API integration with fallback to local models
-- Additional word generation when MIN_REQUIRED threshold not met
-- Enhanced logging for generation pipeline visibility
-
-### v0.1.0 (AI Word Generation)
-- AI-powered word list generation using Hugging Face Spaces
-- Topic-based word creation with automatic saving
-- Enhanced word list management with AI fallback
-- Utility modules integration for storage and file handling
-
-### v0.2.20-0.2.29 (Challenge Mode & PWA)
-- Remote storage and game sharing via HF datasets
-- Multi-user leaderboards
-- PWA support with offline caching
-- Word list difficulty calculation
-- Privacy controls for challenge sharing
-- Sound effect and music system improvements
-
-## Future Roadmap
-
-### v0.3.0 (Next Phase)
-- Local persistent storage module (`~/.wrdler/data/`)
-- High score tracking and display
-- Player statistics tracking
-- Enhanced UI animations
-
-### v1.0.0 (Long Term)
-- Multiple difficulty levels
-- Daily puzzle mode
-- Internationalization (i18n)
-- Performance optimizations
-- Advanced word list management
-
-## Deployment Targets
-- **Hugging Face Spaces:** Primary deployment platform (Dockerfile-based)
-- **Docker:** Containerized deployment for any platform
-- **Local:** Development and testing
-- **PWA:** Installable on desktop and mobile devices
-
-### Privacy & Data (v0.1.0)
-- **Challenge Mode:** Optional remote storage via Hugging Face datasets
-  - Player names optional (defaults to "Anonymous")
-  - Only stores: word lists, scores, times, game modes
-  - No PII beyond optional player name
-  - User controls URL visibility via "Show Challenge Share Links" toggle
-- **Local Storage (v0.3.0 - Planned):**
-  - Location: `~/.wrdler/data/`
-  - Privacy-first, offline-capable
-  - Easy to delete
-  - No cloud dependency
-
-## Notes for Claude
-
-### Technical Implementation
-- ✅ Project uses modern Python features (3.12.8)
-- ✅ Requires Python >=3.12, <3.13 per pyproject.toml
-- ✅ Heavy use of Streamlit session state for game state management
-- ✅ Client-side JavaScript for timer updates without page refresh
-- ✅ CSS heavily customized for ocean theme aesthetics
-- ✅ All file paths should be absolute when working in WSL environment
-- ✅ Game IDs are deterministic for consistent sharing
-- ✅ 8×6 rectangular grid (grid_rows=6, grid_cols=8)
-- ✅ Horizontal-only word placement (one per row)
-- ✅ Radar/scope visualization removed entirely
-- �� Free letter selection UI implemented with circular buttons
-- ✅ PWA injection via Docker build script (`inject-pwa-head.sh`)
-- ✅ AI word generation via `word_loader_ai.py` with Hugging Face integration
-- ✅ Utility modules provide reusable functions for storage and file ops
-- ✅ Leaderboard system with folder-based discovery and settings separation
-- ✅ Daily/Weekly period-based organization with ISO week numbering
-- ⚠️ **IMPORTANT: Use Python syntax (colons `:`) NOT JavaScript syntax (curly braces `{}`)**
-  - Python: `if condition:` followed by indented block
-  - NOT: `if condition {` - this is JavaScript/C-style syntax
-  - Python: `try:` / `except Exception:` / `else:`
-  - NOT: `try {` / `} catch (Exception) {` / `} else {`
-
-## Leaderboard System Architecture
-
-### Storage Organization
-```
-HF_REPO_ID/
-├── games/
-│   ├── {challenge_id}/              # Challenge storage
-│   │   └── settings.json            # entry_type: "challenge"
-│   └── leaderboards/
-│       ├── daily/
-│       │   └── {YYYY-MM-DD}/        # Daily period folders
-│       │       └── {file_id}/       # Settings-specific leaderboard
-│       │           └── settings.json # entry_type: "daily"
-│       └── weekly/
-│           └── {YYYY-Www}/          # Weekly period folders (ISO week)
-│               └── {file_id}/       # Settings-specific leaderboard
-│                   └── settings.json # entry_type: "weekly"
-└── shortener.json                   # URL shortener mappings
-```
+## Technical Notes
 
-### File ID Format
-File IDs encode settings for fast discovery: `{wordlist_source}-{game_mode}-{sequence}`
+### Important Implementation Details
+- **Python syntax only** - Use colons `:` not braces `{}`
+- **8×6 grid:** `grid_rows=6`, `grid_cols=8`
+- **Horizontal-only placement:** One word per row
+- **Query param routing:** All pages use `?page=<name>` system
+- **Session state management:** Heavy use of `st.session_state`
+- **OAuth detection:** Check `st.session_state.get("oauth_user")`
 
-**Examples:**
-- `classic-classic-0` - Classic wordlist, classic mode, first instance
-- `easy-easy-0` - Easy wordlist, easy mode, first instance
-- `classic-too_easy-1` - Classic wordlist, "too easy" mode, second instance
+### Current Routing Pattern (ui.py)
+```python
+params = st.query_params
+page = params.get("page", "")
 
-### Settings Matching
-Two leaderboards are considered the same if ALL of the following match:
-- `game_mode` (classic, easy, too easy)
-- `wordlist_source` (sanitized: .txt removed, lowercase)
-- `show_incorrect_guesses` (boolean)
-- `enable_free_letters` (boolean)
-- `puzzle_options.spacer` (0-2)
-- `puzzle_options.may_overlap` (boolean)
+if page in {"today", "daily", "weekly", "history"}:
+    render_leaderboard_page(default_tab=page)
+    return
 
-### Data Models
+if page == "settings":  # TO BE IMPLEMENTED
+    render_settings_page()
+    return
 
-#### LeaderboardSettings
-```python
-@dataclass
-class LeaderboardSettings:
-    challenge_id: str          # Period + file_id (e.g., "2025-01-27/classic-classic-0")
-    entry_type: EntryType      # "daily", "weekly", or "challenge"
-    game_mode: str             # "classic", "easy", "too easy"
-    wordlist_source: str       # Wordlist file
-    show_incorrect_guesses: bool
-    enable_free_letters: bool
-    puzzle_options: Dict       # spacer, may_overlap
-    users: List[UserEntry]     # Sorted entries
-    max_display_entries: int   # Default 20
-    created_at: str
-    version: str
-    game_title: str
+# Default: main game page
+run_app()
 ```
 
-#### UserEntry
-```python
-@dataclass
-class UserEntry:
-    uid: str                         # Unique entry ID
-    username: str                    # Player name
-    word_list: List[str]             # 6 words played
-    score: int                       # Final score
-    time: int                        # Seconds to complete
-    word_list_difficulty: float      # Calculated difficulty
-    timestamp: str                   # ISO 8601 timestamp
-    source_challenge_id: Optional[str]  # If from challenge, original ID
-```
+## Deployment Platforms
+1. **HuggingFace Spaces** (Primary) - Dockerfile deployment with OAuth support
+2. **Local Development** - Streamlit run
+3. **Docker** - Containerized deployment
 
-### Key Functions
-
-#### `leaderboard.py`
-- `submit_score_to_all_leaderboards()` - Main entry point for score submission
-- `find_matching_leaderboard()` - Find leaderboard by scanning folders
-- `create_or_get_leaderboard()` - Get or create a leaderboard
-- `check_qualification()` - Check if score qualifies for top 20
-- `load_leaderboard()` - Load specific leaderboard by file ID
-- `list_available_periods()` - List available dates/weeks from folders
-- `list_settings_for_period()` - List all settings combos for a period
-- `get_current_daily_id()` - Get today's period ID (YYYY-MM-DD)
-- `get_current_weekly_id()` - Get this week's period ID (YYYY-Www)
-
-#### `leaderboard_page.py`
-- `render_leaderboard_page()` - Main page rendering with tab navigation
-- `_render_today_tab()` - Current daily/weekly leaderboards
-- `_render_daily_tab()` - Last 7 days of daily leaderboards
-- `_render_weekly_tab()` - Current week leaderboard
-- `_render_history_tab()` - Historical leaderboard browser
-- `_render_leaderboard_table()` - Styled table rendering with rank emojis
-
-### Discovery Strategy
-1. **List period folders**: Scan `games/leaderboards/{type}/` for date/week folders
-2. **List file_id folders**: For each period, scan for settings folders
-3. **Filter by prefix**: Match file_ids starting with `{wordlist_source}-{game_mode}-`
-4. **Load and verify**: Load `settings.json` to verify full settings match
-
-### Period Boundaries
-- **Daily**: Resets at UTC midnight (00:00:00)
-- **Weekly**: Resets Monday at UTC midnight, uses ISO week numbering
-  - Week 1 is the week containing the first Thursday of the year
-  - Format: `YYYY-Www` (e.g., `2025-W04`)
-
-### Leaderboard URL Format
-Query parameters for direct leaderboard access:
-- `?gidd={file_id}` - Show specific daily leaderboard
-- `?gidw={file_id}` - Show specific weekly leaderboard
-- `?page=today` - Show Today tab
-- `?page=daily` - Show Daily tab
-- `?page=weekly` - Show Weekly tab
-- `?page=history` - Show History tab
+## Git Configuration
+- **Current Branch:** AI (working branch)
+- **Main Branch:** main
+- **Remotes:**
+  - origin: https://github.com/Oncorporation/Wrdler.git
+  - Hugging: https://huggingface.co/spaces/Surn/Wrdler

README.md

@@ -21,10 +21,12 @@ thumbnail: >-
 
 # Wrdler
 
-> **This project is based on BattleWords, but adapted for a simpler word puzzle game with an 8x6 grid, horizontal words only, and free letter guesses at the start.**
+> **Wrdler is a Python/Streamlit vocabulary puzzle game based on BattleWords, adapted for a simpler 8x6 grid, horizontal words only, and free letter guesses at the start.**
 
 Wrdler is a vocabulary learning game with a simplified grid and strategic letter guessing. The objective is to discover hidden words on a grid by making smart guesses before all letters are revealed.
 
+**Current Version:** v0.2.1
+
 ## Key Differences from BattleWords
 
 - **8x6 grid** (instead of 12x12) with **6 words total** (one per row)
@@ -80,7 +82,7 @@ Wrdler is a vocabulary learning game with a simplified grid and strategic letter
 - **"Show Challenge Share Links" toggle** (default OFF) to control URL visibility
 - Each player gets different random words from the same wordlist
 
-### 🏆 Daily & Weekly Leaderboards (v0.2.0) ✅
+### 🏆 Daily & Weekly Leaderboards (v0.2.1) ✅
 **Comprehensive Leaderboard System:**
 - **Daily Leaderboards:** Top 20 scores for each day (resets UTC midnight)
 - **Weekly Leaderboards:** Top 20 scores for each ISO week (resets Monday UTC 00:00)
@@ -118,11 +120,12 @@ Wrdler is a vocabulary learning game with a simplified grid and strategic letter
 - Includes `service worker` and `manifest.json` with basic offline caching of static assets
 - See `INSTALL_GUIDE.md` for platform-specific steps
 
-### Planned
-- Local persistent storage for personal game history
-- Personal high scores sidebar (offline-capable)
-- Player statistics tracking
-- Deterministic seed UI for custom puzzles
+### Planned/Upcoming
+- Move all game settings from sidebar to a dedicated settings page (`?page=settings`) requiring a logged in user (OAuth)
+- Local persistent storage for personal game history (future)
+- Personal high scores sidebar (future)
+- Player statistics tracking (future)
+- Deterministic seed UI for custom puzzles (future)
 
 ## Challenge Mode & Leaderboard
 
@@ -204,11 +207,12 @@ CRYPTO_PK=                             # Reserved for future signing
  - `generator.py` – word placement logic (8x6, horizontal only)
  - `logic.py` – game mechanics (reveal, guess, scoring, free letters)
  - `ui.py` – Streamlit UI composition
- - `leaderboard.py` – Daily/weekly leaderboard system (v0.2.0)
- - `leaderboard_page.py` – Leaderboard UI page (v0.2.0)
+ - `oauth.py` – HuggingFace OAuth utilities (NEW)
+ - `settings_page.py` – Settings page UI (IN PROGRESS)
+ - `leaderboard.py` – Daily/weekly leaderboard system (v0.2.1)
+ - `leaderboard_page.py` – Leaderboard UI page (v0.2.1)
  - `game_storage.py` – Hugging Face remote storage integration and challenge sharing
  - `local_storage.py` – local JSON storage for results and high scores
- - `storage.py` – (legacy) local storage and high scores
  - `modules/` – shared utilities (storage with folder listing, constants, file_utils)
  - `words/` – word list files (classic.txt, fourth_grade.txt, wordlist.txt)
 - `specs/` – documentation (`specs.md`, `requirements.md`, `leaderboard_spec.md`)
@@ -230,8 +234,8 @@ All test files must be placed in the `/tests` folder. This ensures a clean proje
 
 ## Changelog
 
-### v0.2.0 (Current) ✅
-**Daily and Weekly Leaderboards Implemented**
+### v0.2.1 (Current) ✅
+**Daily and Weekly Leaderboards Improved**
 - ✅ Settings-based leaderboard separation (unique leaderboards per settings combo)
 - ✅ Folder-based discovery system (no index.json)
 - ✅ Top 20 displayed entries per leaderboard
@@ -243,6 +247,7 @@ All test files must be placed in the `/tests` folder. This ensures a clean proje
 - ✅ Period-based organization: daily (YYYY-MM-DD), weekly (YYYY-Www)
 - ✅ Enhanced storage.py with folder listing capabilities
 - ✅ Updated scoring tiers with "Legendary" (45+)
+- ✅ Settings page planned (move from sidebar, OAuth login required)
 
 ### v0.1.1
 - ✅ Enhanced AI word generation with intelligent word saving
@@ -267,7 +272,7 @@ All test files must be placed in the `/tests` folder. This ensures a clean proje
 ### v0.0.7 
  - fix guess bug - allowing guesses only after word guessed or letter revealed
 
-### v0.0.2 (Current - All Sprints Complete) 🎉
+### v0.0.2 (All Sprints Complete) 🎉
  - **Sprint 1-3:** Core data models, generator refactor, radar removal
  - **Sprint 4:** Implemented free letter selection UI with circular green gradient buttons
  - **Sprint 5:** Updated grid UI rendering for 8×6 display
@@ -415,7 +420,7 @@ For any issues or enhancements, please refer to the project documentation or con
 
 Happy gaming and sound designing!
 
-## What's New in v0.2.0: Daily & Weekly Leaderboards 🏆
+## What's New in v0.2.1: Daily & Weekly Leaderboards 🏆
 
 ### Comprehensive Leaderboard System
 - **Settings-Based Competition:** Separate leaderboards for each unique settings combination
@@ -425,6 +430,7 @@ Happy gaming and sound designing!
   - Puzzle options (spacer, may_overlap)
 - **Daily & Weekly Periods:** Top 20 scores per day and per ISO week
 - **Automatic Qualification:** Submit scores after any game completion
+- **Settings page planned:** Move from sidebar to dedicated page, login required
 
 ### Leaderboard Page Navigation
 - **Today Tab:** Current daily and weekly leaderboards with direct link filtering
@@ -450,21 +456,127 @@ Happy gaming and sound designing!
 - Top 5 players displayed in Challenge Mode banner
 - "Show Challenge Share Links" toggle for privacy control (default OFF)
 
-## What's Planned for v0.3.0
+## Known Issues / TODO
+
+- Word list loading bug: the app may not select the proper word lists in some environments. Investigate `word_loader.get_wordlist_files()` / `load_word_list()` and sidebar selection persistence to ensure the chosen file is correctly used by the generator.
+
+## Development Phases
+
+- **Proof of Concept (0.1.0):** No overlaps, basic UI, single session.
+- **Beta (0.5.0):** Responsive layout, leaderboards, keyboard support, deterministic seed.
+- **Full (1.0.0):** Enhanced UX, Overlaps allowed on shared letters, persistence, daily/practice modes, advanced features.
+
+See `specs/requirements.md` and `specs/specs.md` for full details and roadmap.
+
+## License
+
+Wrdler is based on BattleWords. BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner.
+
+## Hugging Face Spaces Configuration
+
+Wrdler is deployable as a Hugging Face Space. You can use either the YAML config block or a Dockerfile for advanced/custom deployments.
+
+To configure your Space with the YAML block, add it at the top of your `README.md`:
+
+```yaml
+---
+title: Wrdler
+emoji: 🎲
+colorFrom: blue
+colorTo: indigo
+sdk: streamlit
+sdk_version: 1.51.0
+python_version: 3.12.8
+app_file: app.py
+tags:
+ - game
+ - vocabulary
+ - streamlit
+ - education
+---
+```
+
+**Key parameters:**
+- `title`, `emoji`, `colorFrom`, `colorTo`: Visuals for your Space.
+- `sdk`: Use `streamlit` for Streamlit apps.
+- `sdk_version`: Latest supported Streamlit version.
+- `python_version`: Python version (default is3.10).
+- `app_file`: Entry point for your app.
+- `tags`: List of descriptive tags.
+
+**Dependencies:** 
+Add a `requirements.txt` with your Python dependencies (e.g., `streamlit`, etc.).
+
+**Port:** 
+Streamlit Spaces use port `8501` by default.
 
-### Local Player History (Coming Soon)
-- Personal game results saved locally in `~/.wrdler/data/`
-- Offline-capable high score tracking
-- Player statistics (games played, averages, bests)
-- Privacy-first: no cloud dependency for personal data
-- Easy data management (delete `~/.wrdler/data/` to reset)
+**Embedding:**
+Spaces can be embedded in other sites using an `<iframe>`:
+
+```html
+<iframe src="https://[YourUsername]-Wrdler.hf.space?embed=true" title="Wrdler"></iframe>
+```
+
+For full configuration options, see [Spaces Config Reference](https://huggingface.co/docs/hub/spaces-config-reference) and [Streamlit SDK Guide](https://huggingface.co/docs/hub/spaces-sdks-streamlit).
 
-### Leaderboard Optimizations
-- In-memory caching with TTL (60s for periods, 15s for leaderboards)
-- Pagination for entries beyond top 20
-- Retry logic with exponential backoff
-- Rate limiting per IP/session
-- Archival script for old periods (>365 days daily, >156 weeks weekly)
+# Assets Setup
+
+To fully experience Wrdler, especially the audio elements, ensure you set up the following assets:
+
+- Place your background music `.mp3` files in `wrdler/assets/audio/music/` to enable music.
+- Place your sound effect files (`.mp3` or `.wav`) in `wrdler/assets/audio/effects/` for sound effects.
+
+Refer to the documentation for guidance on compatible audio formats and common troubleshooting tips.
+
+# Sound Asset Generation
+
+To generate and save custom sound effects for Wrdler, you can use the `generate_sound_effect` function.
+
+## Function: `generate_sound_effect`
+
+```python
+def generate_sound_effect(effect: str, save_to_assets: bool = False, use_api: str = "huggingface") -> str:
+ """
+ Generate a sound effect and save it as a file.
+
+ Parameters:
+ - `effect`: Name of the effect to generate.
+ - `save_to_assets`: If `True`, saves the effect to the assets directory; 
+ if `False`, saves to a temporary location. Default is `False`.
+ - `use_api`: API to use for generation. Options are "huggingface" or "replicate". Default is "huggingface".
+
+ Returns:
+ - File path to the saved sound effect.
+ ```
+
+## Parameters
+
+- `effect`: The name of the sound effect you want to generate (e.g., "explosion", "powerup").
+- `save_to_assets` (optional): Set to `True` to save the generated sound effect to the game's assets directory. If `False`, the effect is saved to a temporary location. Default is `False`.
+- `use_api` (optional): The API to use for generating the sound. Options are `"huggingface"` or `"replicate"`. Default is `"huggingface"`.
+
+## Returns
+
+- The function returns the file path to the saved sound effect, whether it's in the assets directory or a temporary location.
+
+## Usage Example
+
+To generate a sound effect and save it to the assets directory:
+
+```python
+generate_sound_effect("your_effect_name", save_to_assets=True)
+```
+
+To generate a sound effect and keep it in a temporary location:
+
+```python
+temp_path = generate_sound_effect("your_effect_name", save_to_assets=False)
+```
+
+## Note
+
+Ensure you have the necessary permissions and API access (if required) to use the sound generation service. Generated sounds are subject to the terms of use of the respective API.
+
+For any issues or enhancements, please refer to the project documentation or contact the project maintainer.
 
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+Happy gaming and sound designing!

specs/requirements.md

@@ -1,20 +1,21 @@
 # Wrdler: Implementation Requirements
-**Version:** 0.2.0
+**Version:** 0.2.1
 **Status:** Production Ready - Leaderboards Implemented
 **Last Updated:** 2025-12-08
 
-This document breaks down the implementation tasks for Wrdler using the game rules described in `specs.md`. Wrdler is based on BattleWords but with a simplified 8x6 grid, horizontal-only words, and free letter guesses at the start.
+This document breaks down the implementation tasks for Wrdler using the game rules described in `specs.md`. Wrdler is a Python/Streamlit project based on BattleWords but with a simplified 8x6 grid, horizontal-only words, and free letter guesses at the start.
 
-**Current Status:** ✅ All Phase 1 requirements complete, 100% tested (25/25 tests passing), AI word generation enhanced in v0.1.1, Daily/Weekly leaderboards implemented in v0.2.0
+**Current Status:** ✅ All Phase 1 requirements complete, 100% tested (25/25 tests passing), AI word generation enhanced in v0.1.1, Daily/Weekly leaderboards implemented in v0.2.1
 
 ## Key Differences from BattleWords
+- Python project (Streamlit, Python 3.12.8)
 - 8x6 grid instead of 12x12
 - One word per row (6 total) instead of flexible placement
 - Horizontal words only (no vertical)
 - No radar/scope visualization
 - 2 free letter guesses at game start
 
-## Implementation Details (v0.1.1)
+## Implementation Details (v0.2.1)
 - **Tech Stack:** Python 3.12.8, Streamlit 1.51.0, numpy, matplotlib, transformers, gradio_client
 - **Architecture:** Single-player, local state in Streamlit session state
 - **Grid:** 8 columns × 6 rows (48 cells) with exactly six words
@@ -60,18 +61,20 @@ This document breaks down the implementation tasks for Wrdler using the game rul
 ## Folder Structure (Implemented)
 - `app.py` – Streamlit entry point ✅
 - `wrdler/` – Python package ✅
-  - `__init__.py` (version 0.2.0)
+  - `__init__.py` (version 0.2.1)
   - `models.py` – data models and types (rectangular grid support)
   - `word_loader.py` – load/validate/cached word lists
   - `word_loader_ai.py` – AI word generation with retry logic
   - `generator.py` – word placement (8x6, horizontal only, one per row)
   - `logic.py` – game mechanics (reveal, guess, scoring, tiers, free letters)
   - `ui.py` – Streamlit UI composition (8×6 grid rendering)
-  - `leaderboard.py` – Daily/weekly leaderboard system (v0.2.0)
-  - `leaderboard_page.py` – Leaderboard UI page (v0.2.0)
+  - `leaderboard.py` – Daily/weekly leaderboard system (v0.2.1)
+  - `leaderboard_page.py` – Leaderboard UI page (v0.2.1)
   - `audio.py` – background music system
   - `sounds.py` – sound effects management
   - `game_storage.py` – HF storage wrapper for Challenge Mode
+  - `oauth.py` – HuggingFace OAuth utilities (NEW)
+  - `settings_page.py` – Settings page UI (IN PROGRESS)
   - `modules/` – shared utilities (storage with folder listing, constants, file_utils)
   - `words/` – word list files (classic.txt, fourth_grade.txt, wordlist.txt)
 - `specs/` – documentation (specs.md, requirements.md, sprint reports)
@@ -187,14 +190,16 @@ This document breaks down the implementation tasks for Wrdler using the game rul
 
 **Test Results:** ✅ 25/25 tests passing (100%)
 
-## Leaderboard System (v0.2.0) ✅ IMPLEMENTED
+## Leaderboard System (v0.2.1) ✅ IMPLEMENTED
 
 ### Core Implementation
 
 **Files:**
-- `wrdler/leaderboard.py` - Core leaderboard logic (v0.2.0)
-- `wrdler/leaderboard_page.py` - Leaderboard UI page (v0.2.0)
+- `wrdler/leaderboard.py` - Core leaderboard logic (v0.2.1)
+- `wrdler/leaderboard_page.py` - Leaderboard UI page (v0.2.1)
 - `wrdler/modules/storage.py` - Enhanced with folder listing functions
+- `wrdler/oauth.py` - HuggingFace OAuth utilities (NEW)
+- `wrdler/settings_page.py` - Settings page UI (IN PROGRESS)
 
 **Data Models:**
 - `GameSettings` - Settings that define a unique leaderboard
@@ -263,127 +268,17 @@ games/
 - No PII beyond optional player name
 - All data in HuggingFace repository
 
-**Known Limitations (v0.2.0):**
-- No caching (deferred to v0.3.0)
+**Known Limitations (v0.2.1):**
+- No caching (future)
 - No pagination beyond top 20
 - Basic error handling
 - No rate limiting
 - No archival script
 
-**Future Enhancements (v0.3.0+):**
-- In-memory caching with TTL
-- Pagination for >20 entries
-- Retry logic with exponential backoff
-- Rate limiting per IP/session
-- Archival script for old periods
-
-## Sprint Completion Summary (v0.0.2)
-
-| Sprint | Description | Time | Tests | Status |
-|--------|-------------|------|-------|--------|
-| Sprint 1 | Core Data Models | 3h | 13/13 ✅ | Complete |
-| Sprint 2 | Puzzle Generator | 3h | 5/5 ✅ | Complete |
-| Sprint 3 | Remove Radar | 0.5h | N/A | Complete |
-| Sprint 4 | Free Letters UI | 2h | Manual ✅ | Complete |
-| Sprint 5 | Grid UI Updates | 1.25h | Syntax ✅ | Complete |
-| Sprint 6 | Integration Testing | 2h | 7/7 ✅ | Complete |
-| Sprint 7 | Documentation | 1h | N/A | Complete |
-| **Total** | **All Features** | **12.75h** | **25/25** | **Complete ✅** |
-
-**All known issues resolved. All TODO items completed.**
-
-## Future Roadmap
-
-### v0.3.0 (Next Phase)
-- 📋 Local persistent storage in `~/.wrdler/data/`
-- 📋 High score tracking and display
-- 📋 Player statistics
-- 📋 Enhanced UI animations
-- 📋 Leaderboard caching and performance optimizations
-- 📋 Retry logic with exponential backoff
-- 📋 Rate limiting for submissions
-- 📋 Archival script for old leaderboard periods
-
-### v0.4.0 (AI Expansion)
-- 📋 AI difficulty tuning based on player performance
-- 📋 Custom topic suggestions
-- 📋 Multi-language word generation
-- 📋 Word difficulty analysis and visualization
-
-### v1.0.0 (Long Term)
-- 📋 Multiple difficulty levels
-- 📋 Daily puzzle mode
-- 📋 Internationalization (i18n)
-- 📋 Performance optimizations
-
-## Deployment Targets ✅
-
-### Supported Platforms (v0.0.2)
-- ✅ **Hugging Face Spaces** (primary) - Dockerfile deployment
-- ✅ **Docker** - Containerization with provided Dockerfile
-- ✅ **Local Development** - Run with `streamlit run app.py`
-- ✅ **PWA** - Installable as Progressive Web App on desktop and mobile
-
-### Deployment Status
-**Ready for production deployment!** All features tested and documented.
-
----
-
-**Last Updated:** 2025-12-08
-**Version:** 0.2.0
-**Status:** Production Ready - Leaderboards Implemented 🚀
-
-## AI Word Generation Pipeline (v0.1.1)
-
-### Architecture
-```
-User Input (Topic)
-    ↓
-Check USE_HF_WORDS flag
-    ↓
-┌─────────────────────────────────────┐
-│ HF Space API (Primary)              │
-│ - gradio_client integration         │
-│ - Temperature: 0.95                 │
-│ - Max tokens: 512                   │
-└─────────────────────────────────────┘
-    ↓ (if fails or USE_HF_WORDS=false)
-┌─────────────────────────────────────┐
-│ Local Transformers (Fallback)       │
-│ - Auto model selection              │
-│ - Device auto-detection             │
-│ - Temperature: 0.7                  │
-└─────────────────────────────────────┘
-    ↓
-Parse & Filter Words
-    ↓
-Identify New vs Existing
-    ↓
-Check MIN_REQUIRED threshold
-    ↓ (if insufficient)
-Generate Additional Words (up to 3 retries)
-    ↓
-Save New Words to File
-    ↓
-Validate & Sort File
-    ↓
-Return 75 Words for Game
-```
-
-### Word Saving Strategy
-1. **Detection Phase**: Separate new AI words from existing dictionary words
-2. **Validation Phase**: Check if file meets MIN_REQUIRED (25 words per length)
-3. **Retry Phase**: If insufficient, generate additional words (up to 3 attempts)
-4. **Save Phase**: Write only new words to topic-based file
-5. **Sort Phase**: Auto-sort by length then alphabetically
-6. **Limit Phase**: Stop adding if file reaches 1000 words
-
-### Error Handling
-- **HF Space API failure**: Graceful fallback to local model
-- **Model loading failure**: Try multiple models in priority order
-- **Device compatibility**: Retry pipeline without device parameter on error 422
-- **Insufficient words**: Automatic retry with targeted prompts
-- **File operations**: Detailed logging and error recovery
+**Future Enhancements (planned):**
+- Local persistent storage, high score tracking, player statistics, leaderboard caching
+- Enhanced UI animations, retry logic, rate limiting, archival script
+- AI difficulty tuning, multi-language word generation, i18n
 
 ## Test File Location
 All test files must be placed in the `/tests` folder. This ensures a clean project structure and makes it easy to discover and run all tests.

specs/specs.md

@@ -1,14 +1,15 @@
 # Wrdler Game Specifications (specs.md)
-**Version:** 0.2.0
+**Version:** 0.2.1
 **Status:** Production Ready - Leaderboards Implemented
 **Last Updated:** 2025-12-08
 
 ## Overview
-Wrdler is a simplified vocabulary puzzle game based on BattleWords, but with key differences. The objective is to discover hidden words on a grid by making strategic guesses and using free letter reveals at the game start.
+Wrdler is a Python/Streamlit vocabulary puzzle game based on BattleWords, but with key differences. The objective is to discover hidden words on a grid by making strategic guesses and using free letter reveals at the game start.
 
 **Current Status:** All 7 sprints complete, 100% tested, fully documented
 
 ## Key Differences from BattleWords
+- **Python project** (Streamlit, Python 3.12.8)
 - **8x6 grid** (instead of 12x12)
 - **One word per row** (instead of 6 words placed anywhere)
 - **Horizontal words only** (no vertical placement)
@@ -60,7 +61,7 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords, but with key
 - ✅ 10 incorrect guess limit per game
 - ✅ Two game modes: Classic (chain guesses) and Too Easy (single guess per reveal)
 
-## Implemented Features (v0.1.1)
+## Implemented Features (v0.2.1)
 
 ### AI Word Generation (v0.1.0+)
 - ✅ **Topic-Based Generation:** Create custom word lists for any theme using AI
@@ -85,7 +86,7 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords, but with key
 - ✅ **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.0) ✅
+### Leaderboard System (v0.2.1) ✅
 Wrdler features a comprehensive daily and weekly leaderboard system:
 
 **Core Features:**
@@ -144,18 +145,21 @@ HF_REPO_ID/games/
   - INSTALL_GUIDE.md added with platform-specific install steps
   - No gameplay logic changes
 
+### Settings Page (Planned/Upcoming)
+- Move all game settings from sidebar to a dedicated settings page (`?page=settings`) requiring a logged in user (OAuth)
+
 ## Storage
 
-### Current (v0.0.2)
+### Current (v0.2.1)
 - ✅ Challenge Mode uses remote storage via Hugging Face datasets
 - ✅ Game ID is generated from the word list for replay/sharing
 
-### Planned (v0.3.0)
-- 📋 Local persistent storage for game results and high scores (JSON files)
-- 📋 Local storage location: `~/.wrdler/data/`
-- 📋 Privacy-first offline access
+### Planned (Future)
+- Local persistent storage for game results and high scores (JSON files)
+- Local storage location: `~/.wrdler/data/`
+- Privacy-first offline access
 
-## UI Elements (v0.0.2 - Implemented)
+## UI Elements (v0.2.1 - Implemented)
 - ✅ 8x6 grid (48 cells total)
 - ✅ Free letter guess buttons (2 at game start) - circular green gradient design
 - ✅ Text box for word guesses
@@ -253,10 +257,10 @@ HF_REPO_ID/
 
 ## Development Status
 
-**Current Version:** 0.2.0 (Production Ready - Leaderboards Implemented)
+**Current Version:** 0.2.1 (Production Ready - Leaderboards Implemented)
 
 ### Completed ✅
-- **v0.2.0:** Daily and Weekly Leaderboards
+- **v0.2.1:** Daily and Weekly Leaderboards
   - Settings-based leaderboard separation
   - Folder-based discovery (no index.json)
   - Top 20 displayed entries per leaderboard
@@ -264,6 +268,7 @@ HF_REPO_ID/
   - Automatic score qualification and submission
   - Integration with challenge mode
   - Query parameter filtering for direct links
+  - Settings page planned (move from sidebar, OAuth login required)
 
 - **v0.1.1:** Enhanced AI word generation
   - Intelligent word saving with duplicate prevention
@@ -283,8 +288,9 @@ HF_REPO_ID/
   - 📚 Complete documentation
 
 ### Future Roadmap
-- **v0.3.0:** Local persistent storage, high score tracking, player statistics, leaderboard caching
-- **v1.0.0:** Enhanced UX, multiple difficulty levels, daily puzzle mode
+- Local persistent storage, high score tracking, player statistics, leaderboard caching (future)
+- Enhanced UI animations, retry logic, rate limiting, archival script (future)
+- AI difficulty tuning, multi-language word generation, i18n (future)
 
 ## Copyright
 Wrdler is based on BattleWords. BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner.

wrdler/oauth.py

@@ -0,0 +1,229 @@
+"""
+OAuth utilities for HuggingFace Spaces authentication.
+
+This module provides helper functions to work with HuggingFace OAuth
+in Streamlit apps deployed on HF Spaces.
+
+Required README.md configuration:
+```yaml
+hf_oauth: true
+hf_oauth_scopes:
+  - openid
+  - profile
+```
+
+HF OAuth documentation:
+https://huggingface.co/docs/hub/en/spaces-oauth
+"""
+
+import streamlit as st
+import os
+from typing import Optional, Dict, Any
+
+
+def get_user_info() -> Optional[Dict[str, Any]]:
+    """
+    Get the authenticated user's information from HF OAuth.
+    
+    HF Spaces automatically injects user info into st.session_state["oauth_user"]
+    when OAuth is enabled in README.md
+    
+    Returns:
+        Dictionary with user info (username, email, etc.) or None if not authenticated.
+    """
+    try:
+        # HF OAuth stores the user info in session state
+        oauth_user = st.session_state.get("oauth_user")
+        if oauth_user:
+            return oauth_user
+    except Exception:
+        pass
+    
+    return None
+
+
+def get_username() -> Optional[str]:
+    """
+    Get the authenticated user's username (preferred_username).
+    
+    Returns:
+        Username string or None if not authenticated.
+    """
+    user_info = get_user_info()
+    if user_info:
+        # HF OAuth provides 'preferred_username' in the user info dict
+        return user_info.get("preferred_username") or user_info.get("name")
+    return None
+
+
+def get_email() -> Optional[str]:
+    """
+    Get the authenticated user's email.
+    
+    Returns:
+        Email string or None if not authenticated.
+    """
+    user_info = get_user_info()
+    if user_info:
+        return user_info.get("email")
+    return None
+
+
+def is_authenticated() -> bool:
+    """
+    Check if user is currently authenticated via HF OAuth.
+    
+    Returns:
+        True if user is authenticated, False otherwise.
+    """
+    return get_user_info() is not None
+
+
+def get_admin_users() -> set:
+    """
+    Get the set of allowed admin usernames from environment variable.
+    
+    Returns:
+        Set of admin usernames (empty set if not configured)
+    """
+    admin_users_str = os.getenv("ADMIN_USERS", "")
+    return {u.strip().lower() for u in admin_users_str.split(",") if u.strip()}
+
+
+def is_admin(allowed_users: Optional[set] = None) -> bool:
+    """
+    Check if authenticated user is in the admin list.
+    
+    Args:
+        allowed_users: Set of allowed admin usernames. If None, uses
+                      environment variable ADMIN_USERS (comma-separated).
+    
+    Returns:
+        True if user is an admin, False otherwise.
+    """
+    username = get_username()
+    if not username:
+        return False
+    
+    # Get allowed users from parameter or environment
+    if allowed_users is None:
+        allowed_users = get_admin_users()
+    
+    # Case-insensitive comparison
+    return username.lower() in {u.lower() for u in allowed_users}
+
+
+def require_login(page_name: str = "this page") -> bool:
+    """
+    Display login prompt if user is not authenticated.
+    Returns True if user is authenticated and can proceed.
+    
+    Args:
+        page_name: Name of page to display in prompt
+    
+    Returns:
+        True if authenticated, False if login required
+    """
+    if is_authenticated():
+        return True
+    
+    st.warning(f"?? You need to be logged in to access {page_name}.")
+    st.info(
+        "Sign in with your HuggingFace account using the login button in the top-right corner."
+    )
+    st.markdown(
+        """
+        <style>
+        .login-prompt {
+            background: rgba(29, 100, 200, 0.1);
+            border: 1px solid rgba(29, 100, 200, 0.3);
+            padding: 1rem;
+            border-radius: 0.5rem;
+            margin-top: 1rem;
+        }
+        </style>
+        <div class="login-prompt">
+            <p><strong>How to login:</strong></p>
+            <ol>
+                <li>Click the <strong>Login</strong> button at the top-right of the page</li>
+                <li>Authorize with your HuggingFace account</li>
+                <li>You'll be redirected back to this page</li>
+            </ol>
+        </div>
+        """,
+        unsafe_allow_html=True
+    )
+    return False
+
+
+def require_admin(allowed_users: Optional[set] = None, page_name: str = "this page") -> bool:
+    """
+    Check if user is admin, displaying appropriate message if not.
+    Returns True if user is admin and can proceed.
+    
+    Args:
+        allowed_users: Set of allowed admin usernames
+        page_name: Name of page to display in prompt
+    
+    Returns:
+        True if admin, False otherwise
+    """
+    username = get_username()
+    
+    if not username:
+        st.error("? You must be logged in to access the settings page.")
+        st.info(
+            "Sign in with your HuggingFace account using the login button in the top-right corner."
+        )
+        return False
+    
+    if not is_admin(allowed_users):
+        admin_users = allowed_users if allowed_users else get_admin_users()
+        st.error(f"? Access denied. Only administrators can access {page_name}.")
+        st.info(f"Logged in as: **{username}**")
+        
+        # Show admin list if in debug mode
+        if os.getenv("DEBUG") == "true":
+            st.caption(f"Configured admins: {', '.join(admin_users) if admin_users else '(none)'}")
+        
+        return False
+    
+    return True
+
+
+def display_user_info(in_sidebar: bool = False):
+    """
+    Display current authenticated user's information.
+    
+    Args:
+        in_sidebar: If True, renders in sidebar; otherwise in main area
+    """
+    container = st.sidebar if in_sidebar else st
+    
+    if is_authenticated():
+        username = get_username()
+        email = get_email()
+        
+        container.markdown(
+            f"""
+            <style>
+            .user-info-box {{
+                background: rgba(32, 212, 108, 0.1);
+                border: 1px solid rgba(32, 212, 108, 0.3);
+                padding: 0.75rem;
+                border-radius: 0.5rem;
+                margin-bottom: 1rem;
+            }}
+            </style>
+            <div class="user-info-box">
+                <strong>?? {username}</strong><br/>
+                <small>{email if email else 'No email'}</small>
+            </div>
+            """,
+            unsafe_allow_html=True
+        )
+        
+        if is_admin():
+            container.success("? Administrator")
+    else:
+        container.info("?? Not logged in")