Leaderboard - Storage strategy Simplification

specs/leaderboard_spec.md

@@ -1,6 +1,6 @@
 # Wrdler Leaderboard System Specification
 
-**Document Version:** 1.2.0  
+**Document Version:** 1.3.0  
 **Target Project Version:** 0.2.0  
 **Author:** GitHub Copilot  
 **Date:** 2025-01-27  
@@ -35,6 +35,7 @@ This specification describes the implementation of a **Daily and Weekly Leaderbo
 - Automatically add qualifying scores from any game completion (including challenge mode)
 - Provide a dedicated leaderboard page with historical lookup capabilities
 - Store leaderboard data in HuggingFace repository using existing storage infrastructure
+- **Use folder-based discovery (no index.json) with descriptive folder names**
 - **Use a unified JSON format consistent with existing challenge settings.json files**
 
 ---
@@ -45,9 +46,9 @@ This specification describes the implementation of a **Daily and Weekly Leaderbo
 
 1. **Settings-Based Leaderboards**: Each unique combination of game-affecting settings creates a separate leaderboard. Players using different settings compete on different leaderboards.
 
-2. **Daily Leaderboards**: Create and maintain daily leaderboards with top 20 entries displayed (can store more), organized by date folders (e.g., `leaderboards/daily/2025-01-27/`)
+2. **Daily Leaderboards**: Create and maintain daily leaderboards with top 20 entries displayed (can store more), organized by date folders (e.g., `games/leaderboards/daily/2025-01-27/`)
 
-3. **Weekly Leaderboards**: Create and maintain weekly leaderboards with top 20 entries displayed (can store more), organized by ISO week folders (e.g., `leaderboards/weekly/2025-W04/`)
+3. **Weekly Leaderboards**: Create and maintain weekly leaderboards with top 20 entries displayed (can store more), organized by ISO week folders (e.g., `games/leaderboards/weekly/2025-W04/`)
 
 4. **Automatic Qualification**: Every game completion (challenge or solo) checks if score qualifies for the matching daily/weekly leaderboard based on current settings
 
@@ -56,7 +57,9 @@ This specification describes the implementation of a **Daily and Weekly Leaderbo
    - Current weekly leaderboard (filtered by current settings)
    - Historical lookup via dropdown
 
-6. **Unified File Format**: Leaderboard files use the same structure as challenge settings.json with an `entry_type` field to distinguish between "daily", "weekly", and "challenge" entries
+6. **Folder-Based Discovery**: No index.json file. Leaderboards are discovered by scanning folder names. Folder names include settings info for fast filtering.
+
+7. **Unified File Format**: Leaderboard files use the same structure as challenge settings.json with an `entry_type` field to distinguish between "daily", "weekly", and "challenge" entries
 
 ### Secondary Goals
 
@@ -85,74 +88,69 @@ The following settings define a unique leaderboard:
 
 ### 3.1 Storage Structure
 
-Each date/week can have multiple leaderboard folders, one per unique settings combination. The folder name includes the file_id suffix, and all leaderboards use `settings.json` as the filename (consistent with challenges):
+Each date/week has settings-based subfolders. The folder name (file_id) encodes the settings for fast discovery. All leaderboards use `settings.json` as the filename (consistent with challenges):
 
 ```
 HF_REPO_ID/
-??? games/                          # Existing challenge storage
-?   ??? {challenge_id}/
-?       ??? settings.json           # entry_type: "challenge"
-??? leaderboards/
-?   ??? daily/
-?   ?   ??? 2025-01-27-0/           # First settings combination for 2025-01-27
-?   ?   ?   ??? settings.json
-?   ?   ??? 2025-01-27-1/           # Second settings combination for 2025-01-27
-?   ?   ?   ??? settings.json
-?   ?   ??? 2025-01-26-0/
-?   ?       ??? settings.json
-?   ??? weekly/
-?   ?   ??? 2025-W04-0/             # First settings combination for week 4
-?   ?   ?   ??? settings.json
-?   ?   ??? 2025-W04-1/
-?   ?   ?   ??? settings.json
-?   ?   ??? 2025-W03-0/
-?   ?       ??? settings.json
-?   ??? index.json                  # Index of all leaderboards (maps settings to folder IDs)
+??? games/                          # All game-related storage
+?   ??? {challenge_id}/             # Existing challenge storage
+?   ?   ??? settings.json           # entry_type: "challenge"
+?   ??? leaderboards/
+?       ??? daily/
+?       ?   ??? 2025-01-27/
+?       ?   ?   ??? classic-classic-0/
+?       ?   ?   ?   ??? settings.json
+?       ?   ?   ??? easy-easy-0/
+?       ?   ?       ??? settings.json
+?       ?   ??? 2025-01-26/
+?       ?       ??? classic-classic-0/
+?       ?           ??? settings.json
+?       ??? weekly/
+?           ??? 2025-W04/
+?           ?   ??? classic-classic-0/
+?           ?   ?   ??? settings.json
+?           ?   ??? easy-too_easy-0/
+?           ?       ??? settings.json
+?           ??? 2025-W03/
+?               ??? classic-classic-0/
+?                   ??? settings.json
 ??? shortener.json                  # Existing URL shortener
 ```
 
-### 3.2 Leaderboard Index File
+### 3.2 File ID Format
 
-The `index.json` file maps settings combinations to folder identifiers for fast lookup:
+The `file_id` (folder name) encodes settings for discovery without an index:
 
-```json
-{
-  "daily": {
-    "2025-01-27": [
-      {
-        "file_id": 0,
-        "game_mode": "classic",
-        "wordlist_source": "classic.txt",
-        "show_incorrect_guesses": true,
-        "enable_free_letters": true,
-        "puzzle_options": {"spacer": 0, "may_overlap": false}
-      },
-      {
-        "file_id": 1,
-        "game_mode": "easy",
-        "wordlist_source": "easy.txt",
-        "show_incorrect_guesses": true,
-        "enable_free_letters": true,
-        "puzzle_options": {"spacer": 0, "may_overlap": false}
-      }
-    ]
-  },
-  "weekly": {
-    "2025-W04": [
-      {
-        "file_id": 0,
-        "game_mode": "classic",
-        "wordlist_source": "classic.txt",
-        "show_incorrect_guesses": true,
-        "enable_free_letters": true,
-        "puzzle_options": {"spacer": 0, "may_overlap": false}
-      }
-    ]
-  }
-}
 ```
+{wordlist_source}-{game_mode}-{sequence}
+```
+
+**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
+
+**Sanitization Rules:**
+- `.txt` extension is removed from wordlist_source
+- Spaces are replaced with underscores
+- All lowercase
+
+### 3.3 Folder-Based Discovery
 
-### 3.3 Data Flow
+Instead of maintaining an `index.json` file, leaderboards are discovered by:
+
+1. **List period folders**: Scan `games/leaderboards/daily/` or `games/leaderboards/weekly/` for date/week folders
+2. **List file_id folders**: For each period, scan for settings folders
+3. **Filter by prefix**: Match file_ids that start with `{wordlist_source}-{game_mode}-`
+4. **Load and verify**: Load `settings.json` to verify full settings match
+
+**Benefits:**
+- No index synchronization issues
+- Self-documenting folder structure
+- Can browse folders directly
+- Reduced write operations (no index updates)
+
+### 3.4 Data Flow
 
 ```
 ??????????????????????
@@ -167,33 +165,40 @@ The `index.json` file maps settings combinations to folder identifiers for fast
           ?
           ?
 ??????????????????????
-? Find matching      ?
-? leaderboard or     ?
-? create new one     ?
+? Build file_id      ?
+? prefix from        ?
+? settings           ?
+??????????????????????
+          ?
+          ?
+??????????????????????
+? Scan folders for   ?
+? matching file_id   ?
+? or create new      ?
 ??????????????????????
           ?
     ?????????????
     ?           ?
     ?           ?
-????????? ???????????
-? Daily ? ? Weekly  ?
-? LB    ? ? LB      ?
-????????? ???????????
+????????? ?????????????
+? Daily ? ? Weekly    ?
+? LB    ? ? LB        ?
+????????? ?????????????
     ?          ?
     ????????????
          ?
          ?
-?????????????????????
-? Check if score    ?
-? qualifies (top    ?
-? 20 displayed)     ?
-?????????????????????
+???????????????????????
+? Check if score      ?
+? qualifies (top      ?
+? 20 displayed)       ?
+???????????????????????
           ?
           ?
-?????????????????????
-? Update & Upload   ?
-? to HF repo        ?
-?????????????????????
+???????????????????????
+? Update & Upload     ?
+? to HF repo          ?
+???????????????????????
 ```
 
 ---
@@ -207,8 +212,8 @@ The `entry_type` field distinguishes between different types of game entries:
 | entry_type | Description | Storage Location |
 |------------|-------------|------------------|
 | `"challenge"` | Player-created challenge for others to compete | `games/{challenge_id}/settings.json` |
-| `"daily"` | Daily leaderboard entry | `leaderboards/daily/{date}-{file_id}/settings.json` |
-| `"weekly"` | Weekly leaderboard entry | `leaderboards/weekly/{week}-{file_id}/settings.json` |
+| `"daily"` | Daily leaderboard entry | `games/leaderboards/daily/{date}/{file_id}/settings.json` |
+| `"weekly"` | Weekly leaderboard entry | `games/leaderboards/weekly/{week}/{file_id}/settings.json` |
 
 ### 4.2 Unified File Schema (Consistent with Challenge settings.json)
 
@@ -216,7 +221,7 @@ Both leaderboard files and challenge files use the **same base structure**. The
 
 ```json
 {
-  "challenge_id": "2025-01-27-0",
+  "challenge_id": "2025-01-27/classic-classic-0",
   "entry_type": "daily",
   "game_mode": "classic",
   "grid_size": 8,
@@ -250,7 +255,7 @@ Both leaderboard files and challenge files use the **same base structure**. The
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `challenge_id` | string | Unique identifier. For daily: `"2025-01-27-0"`, weekly: `"2025-W04-0"`, challenge: `"20251130T190249Z-ABCDEF"` |
+| `challenge_id` | string | Unique identifier. For daily: `"2025-01-27/classic-classic-0"`, weekly: `"2025-W04/easy-easy-0"`, challenge: `"20251130T190249Z-ABCDEF"` |
 | `entry_type` | string | One of: `"daily"`, `"weekly"`, `"challenge"` |
 | `game_mode` | string | Game difficulty: `"classic"`, `"easy"`, `"too easy"` |
 | `grid_size` | int | Grid width (8 for Wrdler) |
@@ -296,7 +301,7 @@ Each user entry in the `users` array:
 
 Two leaderboards are considered the same if ALL of the following match:
 - `game_mode`
-- `wordlist_source`
+- `wordlist_source` (after sanitization - .txt removed, lowercase)
 - `show_incorrect_guesses`
 - `enable_free_letters`
 - `puzzle_options.spacer`
@@ -315,762 +320,26 @@ Uses ISO 8601 week numbering:
 
 ### 5.1 `wrdler/leaderboard.py` (NEW FILE)
 
-**Purpose:** Core leaderboard logic for managing daily and weekly leaderboards with settings-based separation.
-
-```python
-# wrdler/leaderboard.py
-"""
-Wrdler Leaderboard System
-
-Manages daily and weekly leaderboards with automatic score submission,
-qualification checking, and historical lookup.
-
-Leaderboard Configuration:
-- Max display entries: 20 per leaderboard (can store more)
-- Daily reset: UTC midnight
-- Weekly reset: Monday UTC 00:00 (ISO week)
-- Sorting: score (desc), time (asc), difficulty (desc)
-- File format: Unified with challenge settings.json
-- Settings-based separation: Each unique settings combination gets its own leaderboard
-"""
-__version__ = "0.2.0"
-
-from dataclasses import dataclass, field
-from datetime import datetime, timezone, timedelta
-from typing import Dict, Any, List, Optional, Tuple, Literal
-import logging
-
-from wrdler.modules.storage import (
-    _get_json_from_repo,
-    _upload_json_to_repo
-)
-from wrdler.modules.constants import HF_REPO_ID, APP_SETTINGS
-from wrdler.game_storage import generate_uid
-
-logger = logging.getLogger(__name__)
-
-# Configuration
-MAX_DISPLAY_ENTRIES = 20
-DAILY_LEADERBOARD_PATH = "leaderboards/daily"
-WEEKLY_LEADERBOARD_PATH = "leaderboards/weekly"
-LEADERBOARD_INDEX_PATH = "leaderboards/index.json"
-
-# Entry types
-EntryType = Literal["daily", "weekly", "challenge"]
-
-
-@dataclass
-class GameSettings:
-    """Settings that define a unique leaderboard."""
-    game_mode: str = "classic"
-    wordlist_source: str = "classic.txt"
-    show_incorrect_guesses: bool = True
-    enable_free_letters: bool = True
-    puzzle_options: Dict[str, Any] = field(default_factory=lambda: {"spacer": 0, "may_overlap": False})
-
-    def matches(self, other: "GameSettings") -> bool:
-        """Check if two settings are equivalent (same leaderboard)."""
-        return (
-            self.game_mode == other.game_mode and
-            self.wordlist_source == other.wordlist_source and
-            self.show_incorrect_guesses == other.show_incorrect_guesses and
-            self.enable_free_letters == other.enable_free_letters and
-            self.puzzle_options.get("spacer", 0) == other.puzzle_options.get("spacer", 0) and
-            self.puzzle_options.get("may_overlap", False) == other.puzzle_options.get("may_overlap", False)
-        )
-
-    def to_dict(self) -> Dict[str, Any]:
-        """Convert to dictionary."""
-        return {
-            "game_mode": self.game_mode,
-            "wordlist_source": self.wordlist_source,
-            "show_incorrect_guesses": self.show_incorrect_guesses,
-            "enable_free_letters": self.enable_free_letters,
-            "puzzle_options": self.puzzle_options,
-        }
-
-    @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> "GameSettings":
-        """Create from dictionary."""
-        return cls(
-            game_mode=data.get("game_mode", "classic"),
-            wordlist_source=data.get("wordlist_source", "classic.txt"),
-            show_incorrect_guesses=data.get("show_incorrect_guesses", True),
-            enable_free_letters=data.get("enable_free_letters", True),
-            puzzle_options=data.get("puzzle_options", {"spacer": 0, "may_overlap": False}),
-        )
-
-    @classmethod
-    def from_leaderboard(cls, leaderboard: "LeaderboardSettings") -> "GameSettings":
-        """Extract settings from a leaderboard."""
-        return cls(
-            game_mode=leaderboard.game_mode,
-            wordlist_source=leaderboard.wordlist_source,
-            show_incorrect_guesses=leaderboard.show_incorrect_guesses,
-            enable_free_letters=leaderboard.enable_free_letters,
-            puzzle_options=leaderboard.puzzle_options,
-        )
-
-
-@dataclass
-class UserEntry:
-    """Single user entry in a leaderboard (matches challenge user format)."""
-    uid: str
-    username: str
-    word_list: List[str]
-    score: int
-    time: int  # seconds (matches existing 'time' field, not 'time_seconds')
-    timestamp: str
-    word_list_difficulty: Optional[float] = None
-    source_challenge_id: Optional[str] = None  # If entry came from a challenge
-
-    def to_dict(self) -> Dict[str, Any]:
-        """Convert to dictionary for JSON serialization."""
-        result = {
-            "uid": self.uid,
-            "username": self.username,
-            "word_list": self.word_list,
-            "score": self.score,
-            "time": self.time,
-            "timestamp": self.timestamp,
-        }
-        if self.word_list_difficulty is not None:
-            result["word_list_difficulty"] = self.word_list_difficulty
-        if self.source_challenge_id is not None:
-            result["source_challenge_id"] = self.source_challenge_id
-        return result
-
-    @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> "UserEntry":
-        """Create from dictionary."""
-        return cls(
-            uid=data["uid"],
-            username=data["username"],
-            word_list=data["word_list"],
-            score=data["score"],
-            time=data.get("time", data.get("time_seconds", 0)),  # Handle both field names
-            timestamp=data["timestamp"],
-            word_list_difficulty=data.get("word_list_difficulty"),
-            source_challenge_id=data.get("source_challenge_id"),
-        )
-
-
-@dataclass
-class LeaderboardSettings:
-    """
-    Unified leaderboard/challenge settings format.
-    
-    This matches the existing challenge settings.json structure with added
-    entry_type field to distinguish between daily, weekly, and challenge entries.
-    The settings fields define what makes this leaderboard unique.
-    """
-    challenge_id: str  # Date-fileId for daily, week-fileId for weekly, UID for challenge
-    entry_type: EntryType  # "daily", "weekly", or "challenge"
-    game_mode: str = "classic"
-    grid_size: int = 8
-    puzzle_options: Dict[str, Any] = field(default_factory=lambda: {"spacer": 0, "may_overlap": False})
-    users: List[UserEntry] = field(default_factory=list)
-    created_at: str = ""
-    version: str = __version__
-    show_incorrect_guesses: bool = True
-    enable_free_letters: bool = True
-    wordlist_source: str = "classic.txt"
-    game_title: str = "Wrdler"
-    max_display_entries: int = MAX_DISPLAY_ENTRIES
-
-    def __post_init__(self):
-        if not self.created_at:
-            self.created_at = datetime.now(timezone.utc).isoformat()
-        if not self.game_title:
-            self.game_title = APP_SETTINGS.get("game_title", "Wrdler")
-
-    def to_dict(self) -> Dict[str, Any]:
-        """Convert to dictionary for JSON serialization."""
-        return {
-            "challenge_id": self.challenge_id,
-            "entry_type": self.entry_type,
-            "game_mode": self.game_mode,
-            "grid_size": self.grid_size,
-            "puzzle_options": self.puzzle_options,
-            "users": [u.to_dict() for u in self.users],
-            "created_at": self.created_at,
-            "version": self.version,
-            "show_incorrect_guesses": self.show_incorrect_guesses,
-            "enable_free_letters": self.enable_free_letters,
-            "wordlist_source": self.wordlist_source,
-            "game_title": self.game_title,
-            "max_display_entries": self.max_display_entries,
-        }
-
-    @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> "LeaderboardSettings":
-        """Create from dictionary."""
-        users = [UserEntry.from_dict(u) for u in data.get("users", [])]
-        return cls(
-            challenge_id=data["challenge_id"],
-            entry_type=data.get("entry_type", "challenge"),  # Default for legacy
-            game_mode=data.get("game_mode", "classic"),
-            grid_size=data.get("grid_size", 8),
-            puzzle_options=data.get("puzzle_options", {"spacer": 0, "may_overlap": False}),
-            users=users,
-            created_at=data.get("created_at", ""),
-            version=data.get("version", "0.1.0"),
-            show_incorrect_guesses=data.get("show_incorrect_guesses", True),
-            enable_free_letters=data.get("enable_free_letters", True),
-            wordlist_source=data.get("wordlist_source", "classic.txt"),
-            game_title=data.get("game_title", "Wrdler"),
-            max_display_entries=data.get("max_display_entries", MAX_DISPLAY_ENTRIES),
-        )
-
-    def get_display_users(self) -> List[UserEntry]:
-        """Get users limited to max_display_entries."""
-        return self.users[:self.max_display_entries]
-
-    def get_settings(self) -> GameSettings:
-        """Extract game settings from this leaderboard."""
-        return GameSettings.from_leaderboard(self)
-
-
-def get_current_daily_id() -> str:
-    """Get the date portion of the leaderboard ID for today (UTC)."""
-    return datetime.now(timezone.utc).strftime("%Y-%m-%d")
-
-
-def get_current_weekly_id() -> str:
-    """Get the week portion of the leaderboard ID for the current ISO week."""
-    now = datetime.now(timezone.utc)
-    iso_cal = now.isocalendar()
-    return f"{iso_cal.year}-W{iso_cal.week:02d}"
-
-
-def get_daily_leaderboard_path(date_id: str, file_id: int) -> str:
-    """Get the file path for a daily leaderboard."""
-    return f"{DAILY_LEADERBOARD_PATH}/{date_id}-{file_id}/settings.json"
-
-
-def get_weekly_leaderboard_path(week_id: str, file_id: int) -> str:
-    """Get the file path for a weekly leaderboard."""
-    return f"{WEEKLY_LEADERBOARD_PATH}/{week_id}-{file_id}/settings.json"
-
-
-def _sort_users(users: List[UserEntry]) -> List[UserEntry]:
-    """Sort users by score (desc), time (asc), difficulty (desc)."""
-    return sorted(
-        users,
-        key=lambda u: (
-            -u.score,
-            u.time,
-            -(u.word_list_difficulty or 0)
-        )
-    )
-
-
-def _load_index(repo_id: Optional[str] = None) -> Dict[str, Any]:
-    """Load the leaderboard index."""
-    if repo_id is None:
-        repo_id = HF_REPO_ID
-    
-    data = _get_json_from_repo(repo_id, LEADERBOARD_INDEX_PATH, "dataset")
-    if not data:
-        return {"daily": {}, "weekly": {}}
-    return data
-
-
-def _save_index(index: Dict[str, Any], repo_id: Optional[str] = None) -> bool:
-    """Save the leaderboard index."""
-    if repo_id is None:
-        repo_id = HF_REPO_ID
-    
-    return _upload_json_to_repo(index, repo_id, LEADERBOARD_INDEX_PATH, "dataset")
-
-
-def find_matching_leaderboard(
-    entry_type: EntryType,
-    period_id: str,
-    settings: GameSettings,
-    repo_id: Optional[str] = None
-) -> Tuple[Optional[int], Optional[LeaderboardSettings]]:
-    """
-    Find a leaderboard matching the given settings for a period.
-    
-    Args:
-        entry_type: "daily" or "weekly"
-        period_id: Date string or week identifier
-        settings: Game settings to match
-        repo_id: Repository ID
-    
-    Returns:
-        Tuple of (file_id, leaderboard) or (None, None) if not found
-    """
-    if repo_id is None:
-        repo_id = HF_REPO_ID
-    
-    index = _load_index(repo_id)
-    period_entries = index.get(entry_type, {}).get(period_id, [])
-    
-    for entry in period_entries:
-        entry_settings = GameSettings.from_dict(entry)
-        if settings.matches(entry_settings):
-            file_id = entry["file_id"]
-            # Load the actual leaderboard
-            if entry_type == "daily":
-                path = get_daily_leaderboard_path(period_id, file_id)
-            else:
-                path = get_weekly_leaderboard_path(period_id, file_id)
-            
-            data = _get_json_from_repo(repo_id, path, "dataset")
-            if data:
-                return file_id, LeaderboardSettings.from_dict(data)
-    
-    return None, None
-
-
-def create_or_get_leaderboard(
-    entry_type: EntryType,
-    period_id: str,
-    settings: GameSettings,
-    repo_id: Optional[str] = None
-) -> Tuple[int, LeaderboardSettings]:
-    """
-    Get existing leaderboard or create a new one for the settings.
-    
-    Args:
-        entry_type: "daily" or "weekly"
-        period_id: Date string or week identifier
-        settings: Game settings
-        repo_id: Repository ID
-    
-    Returns:
-        Tuple of (file_id, leaderboard)
-    """
-    if repo_id is None:
-        repo_id = HF_REPO_ID
-    
-    # Try to find existing
-    file_id, leaderboard = find_matching_leaderboard(entry_type, period_id, settings, repo_id)
-    
-    if leaderboard is not None:
-        return file_id, leaderboard
-    
-    # Create new leaderboard
-    index = _load_index(repo_id)
-    if entry_type not in index:
-        index[entry_type] = {}
-    if period_id not in index[entry_type]:
-        index[entry_type][period_id] = []
-    
-    # Get next file_id
-    existing_ids = [e["file_id"] for e in index[entry_type][period_id]]
-    file_id = max(existing_ids, default=-1) + 1
-    
-    # Create challenge_id
-    challenge_id = f"{period_id}-{file_id}"
-    
-    # Create new leaderboard
-    leaderboard = LeaderboardSettings(
-        challenge_id=challenge_id,
-        entry_type=entry_type,
-        game_mode=settings.game_mode,
-        wordlist_source=settings.wordlist_source,
-        show_incorrect_guesses=settings.show_incorrect_guesses,
-        enable_free_letters=settings.enable_free_letters,
-        puzzle_options=settings.puzzle_options,
-        users=[]
-    )
-    
-    # Update index
-    index_entry = settings.to_dict()
-    index_entry["file_id"] = file_id
-    index[entry_type][period_id].append(index_entry)
-    _save_index(index, repo_id)
-    
-    return file_id, leaderboard
-
-
-def load_leaderboard(
-    entry_type: EntryType,
-    period_id: str,
-    file_id: int,
-    repo_id: Optional[str] = None
-) -> Optional[LeaderboardSettings]:
-    """
-    Load a specific leaderboard by file ID.
-
-    Args:
-        entry_type: "daily" or "weekly"
-        period_id: Date or week identifier
-        file_id: File identifier
-        repo_id: Repository ID (uses HF_REPO_ID if None)
-
-    Returns:
-        LeaderboardSettings object or None if not found
-    """
-    if repo_id is None:
-        repo_id = HF_REPO_ID
-
-    if entry_type == "daily":
-        path = get_daily_leaderboard_path(period_id, file_id)
-    elif entry_type == "weekly":
-        path = get_weekly_leaderboard_path(period_id, file_id)
-    else:
-        logger.error(f"Invalid entry_type for leaderboard: {entry_type}")
-        return None
-
-    logger.info(f"?? Loading leaderboard: {path}")
-    data = _get_json_from_repo(repo_id, path, "dataset")
-
-    if not data:
-        logger.info(f"?? No existing leaderboard found at {path}")
-        return None
-
-    return LeaderboardSettings.from_dict(data)
-
-
-def save_leaderboard(
-    leaderboard: LeaderboardSettings,
-    file_id: int,
-    repo_id: Optional[str] = None
-) -> bool:
-    """
-    Save a leaderboard to the repository.
-
-    Args:
-        leaderboard: LeaderboardSettings object to save
-        file_id: File identifier
-        repo_id: Repository ID (uses HF_REPO_ID if None)
-
-    Returns:
-        True if saved successfully, False otherwise
-    """
-    if repo_id is None:
-        repo_id = HF_REPO_ID
-
-    # Extract period_id from challenge_id (format: "2025-01-27-0" or "2025-W04-0")
-    parts = leaderboard.challenge_id.rsplit("-", 1)
-    period_id = parts[0] if len(parts) > 1 else leaderboard.challenge_id
-
-    if leaderboard.entry_type == "daily":
-        path = get_daily_leaderboard_path(period_id, file_id)
-    elif leaderboard.entry_type == "weekly":
-        path = get_weekly_leaderboard_path(period_id, file_id)
-    else:
-        logger.error(f"Cannot save leaderboard with entry_type: {leaderboard.entry_type}")
-        return False
-
-    logger.info(f"?? Saving leaderboard: {path}")
-    return _upload_json_to_repo(leaderboard.to_dict(), repo_id, path, "dataset")
-
-
-def create_user_entry(
-    username: str,
-    score: int,
-    time_seconds: int,
-    word_list: List[str],
-    word_list_difficulty: Optional[float] = None,
-    source_challenge_id: Optional[str] = None
-) -> UserEntry:
-    """Create a new user entry."""
-    return UserEntry(
-        uid=generate_uid(),
-        username=username,
-        word_list=word_list,
-        score=score,
-        time=time_seconds,
-        word_list_difficulty=word_list_difficulty,
-        source_challenge_id=source_challenge_id,
-        timestamp=datetime.now(timezone.utc).isoformat()
-    )
-
-
-def check_qualification(
-    leaderboard: Optional[LeaderboardSettings],
-    score: int,
-    time_seconds: int,
-    word_list_difficulty: Optional[float] = None
-) -> bool:
-    """
-    Check if a score qualifies for the leaderboard display (top 20).
-
-    Note: The leaderboard can store more than 20 entries, but only top 20 are displayed.
-    This function checks if the score would be in the top 20.
-
-    Args:
-        leaderboard: Existing leaderboard (or None if new)
-        score: Score to check
-        time_seconds: Time to complete
-        word_list_difficulty: Difficulty score
-
-    Returns:
-        True if qualifies for display, False otherwise
-    """
-    if leaderboard is None or len(leaderboard.users) < MAX_DISPLAY_ENTRIES:
-        return True
-
-    # Get the 20th entry (last displayed)
-    display_users = leaderboard.get_display_users()
-    if len(display_users) < MAX_DISPLAY_ENTRIES:
-        return True
-
-    lowest = display_users[-1]
-
-    # Primary: higher score qualifies
-    if score > lowest.score:
-        return True
-    if score < lowest.score:
-        return False
-
-    # Secondary: faster time qualifies (for equal score)
-    if time_seconds < lowest.time:
-        return True
-    if time_seconds > lowest.time:
-        return False
-
-    # Tertiary: higher difficulty qualifies (for equal score and time)
-    entry_diff = word_list_difficulty or 0
-    lowest_diff = lowest.word_list_difficulty or 0
-    return entry_diff > lowest_diff
-
-
-def submit_to_leaderboard(
-    entry_type: EntryType,
-    period_id: str,
-    user_entry: UserEntry,
-    settings: GameSettings,
-    repo_id: Optional[str] = None
-) -> Tuple[bool, Optional[int]]:
-    """
-    Submit a user entry to a leaderboard if it qualifies.
-
-    Args:
-        entry_type: "daily" or "weekly"
-        period_id: Date or week identifier
-        user_entry: UserEntry to submit
-        settings: Game settings to match leaderboard
-        repo_id: Repository ID
-
-    Returns:
-        Tuple of (success, rank) where rank is 1-indexed position or None if didn't qualify
-    """
-    if repo_id is None:
-        repo_id = HF_REPO_ID
-
-    # Get or create matching leaderboard
-    file_id, leaderboard = create_or_get_leaderboard(entry_type, period_id, settings, repo_id)
-
-    # Check qualification for display
-    qualifies = check_qualification(
-        leaderboard,
-        user_entry.score,
-        user_entry.time,
-        user_entry.word_list_difficulty
-    )
-
-    if not qualifies:
-        logger.info(f"? Score {user_entry.score} did not qualify for top {MAX_DISPLAY_ENTRIES} in {period_id}")
-        return False, None
-
-    # Add entry and sort
-    leaderboard.users.append(user_entry)
-    leaderboard.users = _sort_users(leaderboard.users)
-
-    # Find rank (1-indexed) - check if in display range
-    rank = None
-    for i, u in enumerate(leaderboard.users[:MAX_DISPLAY_ENTRIES]):
-        if u.uid == user_entry.uid:
-            rank = i + 1
-            break
-
-    if rank is None:
-        # Entry was sorted out of top 20
-        logger.info(f"? Score {user_entry.score} was sorted out of top {MAX_DISPLAY_ENTRIES}")
-        # Still save the entry (stored but not displayed)
-        save_leaderboard(leaderboard, file_id, repo_id)
-        return False, None
-
-    # Save leaderboard
-    if save_leaderboard(leaderboard, file_id, repo_id):
-        logger.info(f"? Added to {entry_type} leaderboard at rank {rank}")
-        return True, rank
-    else:
-        logger.error(f"? Failed to save leaderboard {period_id}")
-        return False, None
-
-
-def submit_score_to_all_leaderboards(
-    username: str,
-    score: int,
-    time_seconds: int,
-    word_list: List[str],
-    settings: GameSettings,
-    word_list_difficulty: Optional[float] = None,
-    source_challenge_id: Optional[str] = None,
-    repo_id: Optional[str] = None
-) -> Dict[str, Any]:
-    """
-    Submit a score to both daily and weekly leaderboards matching the settings.
-
-    This is the main entry point for game completions.
-
-    Args:
-        username: Player name
-        score: Final score
-        time_seconds: Time to complete
-        word_list: Words played
-        settings: Game settings (determines which leaderboard)
-        word_list_difficulty: Difficulty score
-        source_challenge_id: If from a challenge, the original challenge_id
-        repo_id: Repository ID
-
-    Returns:
-        Dict with results:
-        {
-            "daily": {"qualified": bool, "rank": int|None, "id": str},
-            "weekly": {"qualified": bool, "rank": int|None, "id": str},
-            "entry_uid": str,
-            "settings": {...}
-        }
-    """
-    logger.info(f"?? Submitting score: {score} by {username} with settings: {settings.game_mode}")
-
-    # Get current period IDs
-    daily_id = get_current_daily_id()
-    weekly_id = get_current_weekly_id()
-
-    # Create user entry for daily
-    daily_entry = create_user_entry(
-        username=username,
-        score=score,
-        time_seconds=time_seconds,
-        word_list=word_list,
-        word_list_difficulty=word_list_difficulty,
-        source_challenge_id=source_challenge_id
-    )
-
-    # Submit to daily
-    daily_qualified, daily_rank = submit_to_leaderboard(
-        "daily", daily_id, daily_entry, settings, repo_id
-    )
-
-    # Create separate user entry for weekly (different UID)
-    weekly_entry = create_user_entry(
-        username=username,
-        score=score,
-        time_seconds=time_seconds,
-        word_list=word_list,
-        word_list_difficulty=word_list_difficulty,
-        source_challenge_id=source_challenge_id
-    )
-
-    # Submit to weekly
-    weekly_qualified, weekly_rank = submit_to_leaderboard(
-        "weekly", weekly_id, weekly_entry, settings, repo_id
-    )
-
-    results = {
-        "daily": {"qualified": daily_qualified, "rank": daily_rank, "id": daily_id},
-        "weekly": {"qualified": weekly_qualified, "rank": weekly_rank, "id": weekly_id},
-        "entry_uid": daily_entry.uid,
-        "settings": settings.to_dict()
-    }
-
-    logger.info(f"?? Leaderboard results: {results}")
-    return results
-
-
-def get_leaderboards_for_settings(
-    entry_type: EntryType,
-    period_id: str,
-    settings: GameSettings,
-    repo_id: Optional[str] = None
-) -> Optional[LeaderboardSettings]:
-    """
-    Get leaderboard matching specific settings for a period.
-    
-    Args:
-        entry_type: "daily" or "weekly"
-        period_id: Date or week identifier
-        settings: Game settings to match
-        repo_id: Repository ID
-    
-    Returns:
-        LeaderboardSettings or None if not found
-    """
-    _, leaderboard = find_matching_leaderboard(entry_type, period_id, settings, repo_id)
-    return leaderboard
-
-
-def get_last_n_daily_leaderboards(
-    n: int = 7,
-    settings: Optional[GameSettings] = None,
-    repo_id: Optional[str] = None
-) -> List[Tuple[str, Optional[LeaderboardSettings]]]:
-    """
-    Get the last N days of daily leaderboards for specific settings.
-
-    Args:
-        n: Number of days to retrieve
-        settings: Game settings to filter by (None = default settings)
-        repo_id: Repository ID
-
-    Returns:
-        List of tuples (date_id, leaderboard) in reverse chronological order
-    """
-    if settings is None:
-        settings = GameSettings()
-    
-    results = []
-    today = datetime.now(timezone.utc).date()
-
-    for i in range(n):
-        date = today - timedelta(days=i)
-        date_id = date.strftime("%Y-%m-%d")
-        leaderboard = get_leaderboards_for_settings("daily", date_id, settings, repo_id)
-        results.append((date_id, leaderboard))
-
-    return results
+**Purpose:** Core leaderboard logic for managing daily and weekly leaderboards with settings-based separation and folder-based discovery.
 
+Key classes:
+- `GameSettings` - Settings that define a unique leaderboard
+- `UserEntry` - Single user entry in a leaderboard
+- `LeaderboardSettings` - Unified leaderboard/challenge settings format
 
-def list_available_periods(
-    entry_type: EntryType,
-    limit: int = 30,
-    repo_id: Optional[str] = None
-) -> List[str]:
-    """
-    List available period IDs from the index.
+Key functions:
+- `_sanitize_wordlist_source()` - Remove .txt extension and normalize
+- `_build_file_id()` - Create file_id from settings
+- `_parse_file_id()` - Parse file_id into components
+- `find_matching_leaderboard()` - Find leaderboard by scanning folders
+- `create_or_get_leaderboard()` - Get or create a leaderboard
+- `submit_score_to_all_leaderboards()` - Main entry point for submissions
 
-    Args:
-        entry_type: "daily" or "weekly"
-        limit: Maximum number of IDs to return
-        repo_id: Repository ID
+### 5.2 `wrdler/modules/storage.py` (UPDATED)
 
-    Returns:
-        List of period IDs in reverse chronological order
-    """
-    index = _load_index(repo_id)
-    periods = list(index.get(entry_type, {}).keys())
-    periods.sort(reverse=True)
-    return periods[:limit]
-
-
-def list_settings_for_period(
-    entry_type: EntryType,
-    period_id: str,
-    repo_id: Optional[str] = None
-) -> List[Dict[str, Any]]:
-    """
-    List all settings combinations available for a period.
-    
-    Args:
-        entry_type: "daily" or "weekly"
-        period_id: Date or week identifier
-        repo_id: Repository ID
-    
-    Returns:
-        List of settings dictionaries with file_id
-    """
-    index = _load_index(repo_id)
-    return index.get(entry_type, {}).get(period_id, [])
-```
+Added functions:
+- `_list_repo_folders()` - List folder names under a path in HuggingFace repo
+- `_list_repo_files_in_folder()` - List files in a folder
 
 ---
 
@@ -1081,8 +350,8 @@ def list_settings_for_period(
 | Step | Task | Files | Effort |
 |------|------|-------|--------|
 | 1.1 | Create `wrdler/leaderboard.py` with `GameSettings` and data models | NEW | 2h |
-| 1.2 | Implement index management (`_load_index`, `_save_index`) | leaderboard.py | 1h |
-| 1.3 | Implement `find_matching_leaderboard()` and `create_or_get_leaderboard()` | leaderboard.py | 1.5h |
+| 1.2 | Implement folder listing in storage.py | storage.py | 1h |
+| 1.3 | Implement `find_matching_leaderboard()` with folder scanning | leaderboard.py | 1.5h |
 | 1.4 | Implement `check_qualification()` and sorting | leaderboard.py | 1h |
 | 1.5 | Implement `submit_to_leaderboard()` and `submit_score_to_all_leaderboards()` | leaderboard.py | 1h |
 | 1.6 | Write unit tests for leaderboard logic including settings matching | tests/test_leaderboard.py | 2h |
@@ -1152,6 +421,12 @@ __version__ = "0.2.0"
 __version__ = "0.2.0"
 ```
 
+### wrdler/modules/storage.py
+
+```python
+__version__ = "0.1.6"  # Updated to add folder listing functions
+```
+
 ---
 
 ## 8. File Changes Summary
@@ -1160,7 +435,7 @@ __version__ = "0.2.0"
 
 | File | Purpose |
 |------|---------|
-| `wrdler/leaderboard.py` | Core leaderboard logic with unified format |
+| `wrdler/leaderboard.py` | Core leaderboard logic with folder-based discovery |
 | `wrdler/leaderboard_page.py` | Streamlit leaderboard page |
 | `tests/test_leaderboard.py` | Unit tests for leaderboard |
 | `specs/leaderboard_spec.md` | This specification |
@@ -1171,6 +446,7 @@ __version__ = "0.2.0"
 |------|---------|
 | `pyproject.toml` | Version bump to 0.2.0 |
 | `wrdler/__init__.py` | Version bump, add leaderboard exports |
+| `wrdler/modules/storage.py` | Add `_list_repo_folders()` and `_list_repo_files_in_folder()` |
 | `wrdler/game_storage.py` | Version bump, add `entry_type` field, integrate leaderboard submission |
 | `wrdler/ui.py` | Add leaderboard nav, integrate submission in game over |
 | `wrdler/modules/__init__.py` | Export new functions if needed |
@@ -1186,9 +462,8 @@ def submit_score_to_all_leaderboards(
     username: str,
     score: int,
     time_seconds: int,
-    game_mode: str,
-    wordlist_source: str,
     word_list: List[str],
+    settings: GameSettings,
     word_list_difficulty: Optional[float] = None,
     source_challenge_id: Optional[str] = None,
     repo_id: Optional[str] = None
@@ -1198,10 +473,18 @@ def submit_score_to_all_leaderboards(
 def load_leaderboard(
     entry_type: EntryType,
     period_id: str,
-    file_id: int,
+    file_id: str,
     repo_id: Optional[str] = None
 ) -> Optional[LeaderboardSettings]:
-    """Load a specific leaderboard."""
+    """Load a specific leaderboard by file ID."""
+
+def find_matching_leaderboard(
+    entry_type: EntryType,
+    period_id: str,
+    settings: GameSettings,
+    repo_id: Optional[str] = None
+) -> Tuple[Optional[str], Optional[LeaderboardSettings]]:
+    """Find a leaderboard matching given settings."""
 
 def get_last_n_daily_leaderboards(
     n: int = 7,
@@ -1210,11 +493,25 @@ def get_last_n_daily_leaderboards(
 ) -> List[Tuple[str, Optional[LeaderboardSettings]]]:
     """Get recent daily leaderboards for display."""
 
+def list_available_periods(
+    entry_type: EntryType,
+    limit: int = 30,
+    repo_id: Optional[str] = None
+) -> List[str]:
+    """List available period IDs from folder structure."""
+
+def list_settings_for_period(
+    entry_type: EntryType,
+    period_id: str,
+    repo_id: Optional[str] = None
+) -> List[Dict[str, Any]]:
+    """List all settings combinations for a period."""
+
 def get_current_daily_id() -> str:
-    """Get today's leaderboard ID (challenge_id)."""
+    """Get today's period ID."""
 
 def get_current_weekly_id() -> str:
-    """Get this week's leaderboard ID (challenge_id)."""
+    """Get this week's period ID."""
 ```
 
 ---
@@ -1256,7 +553,7 @@ In `run_app()`:
 if st.session_state.get("show_leaderboard_page", False):
     from wrdler.leaderboard_page import render_leaderboard_page
     render_leaderboard_page()
-    if st.button("?? Back to Game"):
+    if st.button("? Back to Game"):
         st.session_state["show_leaderboard_page"] = False
         st.rerun()
     return  # Don't render game UI
@@ -1280,6 +577,17 @@ class TestLeaderboardSettings:
     def test_get_display_users_limit(self): ...
     def test_format_matches_challenge(self): ...
 
+class TestGameSettings:
+    def test_settings_matching_same(self): ...
+    def test_settings_matching_different_mode(self): ...
+    def test_settings_matching_txt_extension_ignored(self): ...
+    def test_get_file_id_prefix(self): ...
+
+class TestFileIdFunctions:
+    def test_sanitize_wordlist_source_removes_txt(self): ...
+    def test_build_file_id(self): ...
+    def test_parse_file_id(self): ...
+
 class TestQualification:
     def test_qualify_empty_leaderboard(self): ...
     def test_qualify_not_full(self): ...
@@ -1291,11 +599,8 @@ class TestQualification:
 class TestDateIds:
     def test_daily_id_format(self): ...
     def test_weekly_id_format(self): ...
-
-class TestUnifiedFormat:
-    def test_leaderboard_matches_challenge_structure(self): ...
-    def test_entry_type_field_present(self): ...
-    def test_challenge_id_as_primary_identifier(self): ...
+    def test_daily_path(self): ...  # Tests new folder structure
+    def test_weekly_path(self): ...  # Tests new folder structure
 ```
 
 
@@ -1303,6 +608,7 @@ class TestUnifiedFormat:
 
 - Test full flow: game completion ? leaderboard submission ? retrieval
 - Test with mock HuggingFace repository
+- Test folder-based discovery logic
 - Test concurrent submissions (edge case)
 - Test backward compatibility with legacy challenge files (no entry_type)
 
@@ -1315,6 +621,7 @@ class TestUnifiedFormat:
 - Existing challenges continue to work unchanged (entry_type defaults to "challenge")
 - No changes to `shortener.json` format
 - Challenge `settings.json` format is extended (new fields are optional)
+- **No index.json migration needed** - folder-based discovery is self-contained
 
 ### Schema Evolution
 
@@ -1322,11 +629,13 @@ class TestUnifiedFormat:
 |---------|---------|
 | 0.1.x | Original challenge format |
 | 0.2.0 | Added `entry_type`, `max_display_entries`, `source_challenge_id` fields |
+| 0.2.0 | Changed to folder-based discovery (no index.json) |
+| 0.2.0 | New folder structure: `games/leaderboards/{type}/{period}/{file_id}/settings.json` |
 
 ### Data Migration
 
 - No migration required for existing challenges
-- New leaderboard files use unified format from start
+- New leaderboard files use folder-based storage from start
 - Legacy challenges without `entry_type` default to `"challenge"`
 
 ### Rollback Plan
@@ -1334,15 +643,17 @@ class TestUnifiedFormat:
 1. Remove leaderboard imports from `ui.py`
 2. Remove sidebar navigation button
 3. Remove game over submission calls
-4. Optionally: delete `leaderboards/` directory from HF repo
+4. Optionally: delete `games/leaderboards/` directory from HF repo
 
 ---
 
-## Appendix A: Example Daily Leaderboard JSON (Settings-Based)
+## Appendix A: Example Daily Leaderboard JSON (Folder-Based)
+
+**Path:** `games/leaderboards/daily/2025-01-27/classic-classic-0/settings.json`
 
 ```json
 {
-  "challenge_id": "2025-01-27-0",
+  "challenge_id": "2025-01-27/classic-classic-0",
   "entry_type": "daily",
   "game_mode": "classic",
   "grid_size": 8,
@@ -1374,44 +685,14 @@ class TestUnifiedFormat:
 
 ---
 
-## Appendix B: Example Index JSON
+## Appendix B: File ID Examples
 
-```json
-{
-  "daily": {
-    "2025-01-27": [
-      {
-        "file_id": 0,
-        "game_mode": "classic",
-        "wordlist_source": "classic.txt",
-        "show_incorrect_guesses": true,
-        "enable_free_letters": true,
-        "puzzle_options": {"spacer": 0, "may_overlap": false}
-      },
-      {
-        "file_id": 1,
-        "game_mode": "easy",
-        "wordlist_source": "easy.txt",
-        "show_incorrect_guesses": true,
-        "enable_free_letters": true,
-        "puzzle_options": {"spacer": 0, "may_overlap": false}
-      }
-    ]
-  },
-  "weekly": {
-    "2025-W04": [
-      {
-        "file_id": 0,
-        "game_mode": "classic",
-        "wordlist_source": "classic.txt",
-        "show_incorrect_guesses": true,
-        "enable_free_letters": true,
-        "puzzle_options": {"spacer": 0, "may_overlap": false}
-      }
-    ]
-  }
-}
-```
+| Wordlist Source | Game Mode | Sequence | File ID |
+|-----------------|-----------|----------|---------|
+| `classic.txt` | `classic` | 0 | `classic-classic-0` |
+| `easy.txt` | `easy` | 0 | `easy-easy-0` |
+| `classic.txt` | `too easy` | 1 | `classic-too_easy-1` |
+| `fourth_grade.txt` | `classic` | 0 | `fourth_grade-classic-0` |
 
 ---
 
@@ -1419,12 +700,13 @@ class TestUnifiedFormat:
 
 | Field | daily | weekly | challenge |
 |-------|-------|--------|-----------|
-| `challenge_id` format | `"2025-01-27-0"` | `"2025-W04-0"` | `"20251130T190249Z-ABC123"` |
+| `challenge_id` format | `"2025-01-27/classic-classic-0"` | `"2025-W04/easy-easy-0"` | `"20251130T190249Z-ABC123"` |
 | `entry_type` | `"daily"` | `"weekly"` | `"challenge"` |
-| Storage path | `leaderboards/daily/{date}-{file_id}/settings.json` | `leaderboards/weekly/{week}-{file_id}/settings.json` | `games/{id}/settings.json` |
+| Storage path | `games/leaderboards/daily/{date}/{file_id}/settings.json` | `games/leaderboards/weekly/{week}/{file_id}/settings.json` | `games/{id}/settings.json` |
 | Reset frequency | Daily (UTC midnight) | Weekly (Monday UTC midnight) | Never (permanent) |
-| Settings-based | Yes (separate folder per settings) | Yes (separate folder per settings) | N/A (settings fixed per challenge) |
+| Settings-based | Yes (file_id encodes settings) | Yes (file_id encodes settings) | N/A (settings fixed per challenge) |
 | `max_display_entries` | 20 | 20 | N/A (all users shown) |
+| Discovery method | Folder scan + prefix match | Folder scan + prefix match | Direct by ID |
 
 ---
 

tests/test_leaderboard.py

@@ -7,6 +7,8 @@ Tests cover:
 - Qualification logic
 - Sorting functions
 - Date/week ID generation
+- File ID generation and parsing
+- GameSettings matching
 """
 
 import pytest
@@ -16,6 +18,7 @@ from unittest.mock import patch, MagicMock
 from wrdler.leaderboard import (
     UserEntry,
     LeaderboardSettings,
+    GameSettings,
     get_current_daily_id,
     get_current_weekly_id,
     get_daily_leaderboard_path,
@@ -23,6 +26,9 @@ from wrdler.leaderboard import (
     _sort_users,
     check_qualification,
     create_user_entry,
+    _sanitize_wordlist_source,
+    _build_file_id,
+    _parse_file_id,
     MAX_DISPLAY_ENTRIES,
 )
 
@@ -124,10 +130,10 @@ class TestLeaderboardSettings:
     def test_create_leaderboard(self):
         """Test basic LeaderboardSettings creation."""
         lb = LeaderboardSettings(
-            challenge_id="2025-01-27",
+            challenge_id="2025-01-27/classic-classic-0",
             entry_type="daily",
         )
-        assert lb.challenge_id == "2025-01-27"
+        assert lb.challenge_id == "2025-01-27/classic-classic-0"
         assert lb.entry_type == "daily"
         assert lb.game_mode == "classic"
         assert lb.grid_size == 8
@@ -180,7 +186,7 @@ class TestLeaderboardSettings:
         )
         
         lb = LeaderboardSettings(
-            challenge_id="2025-01-27",
+            challenge_id="2025-01-27/easy-easy-0",
             entry_type="daily",
             game_mode="easy",
             users=[user],
@@ -199,7 +205,7 @@ class TestLeaderboardSettings:
     def test_format_matches_challenge_structure(self):
         """Test that leaderboard format matches challenge settings.json structure."""
         lb = LeaderboardSettings(
-            challenge_id="2025-01-27",
+            challenge_id="2025-01-27/classic-classic-0",
             entry_type="daily",
             game_mode="classic",
             grid_size=8,
@@ -221,6 +227,96 @@ class TestLeaderboardSettings:
         assert "wordlist_source" in d
 
 
+class TestGameSettings:
+    """Tests for GameSettings dataclass."""
+
+    def test_create_default_settings(self):
+        """Test default GameSettings creation."""
+        settings = GameSettings()
+        assert settings.game_mode == "classic"
+        assert settings.wordlist_source == "classic.txt"
+        assert settings.show_incorrect_guesses is True
+        assert settings.enable_free_letters is True
+
+    def test_settings_matching_same(self):
+        """Test that identical settings match."""
+        s1 = GameSettings(game_mode="classic", wordlist_source="classic.txt")
+        s2 = GameSettings(game_mode="classic", wordlist_source="classic.txt")
+        assert s1.matches(s2) is True
+
+    def test_settings_matching_different_mode(self):
+        """Test that different game modes don't match."""
+        s1 = GameSettings(game_mode="classic", wordlist_source="classic.txt")
+        s2 = GameSettings(game_mode="easy", wordlist_source="classic.txt")
+        assert s1.matches(s2) is False
+
+    def test_settings_matching_different_wordlist(self):
+        """Test that different wordlists don't match."""
+        s1 = GameSettings(game_mode="classic", wordlist_source="classic.txt")
+        s2 = GameSettings(game_mode="classic", wordlist_source="easy.txt")
+        assert s1.matches(s2) is False
+
+    def test_settings_matching_txt_extension_ignored(self):
+        """Test that .txt extension is ignored in comparison."""
+        s1 = GameSettings(game_mode="classic", wordlist_source="classic.txt")
+        s2 = GameSettings(game_mode="classic", wordlist_source="classic")
+        # Both should have same sanitized source
+        assert s1._get_sanitized_source() == s2._get_sanitized_source()
+
+    def test_get_file_id_prefix(self):
+        """Test file_id prefix generation."""
+        settings = GameSettings(game_mode="classic", wordlist_source="classic.txt")
+        assert settings.get_file_id_prefix() == "classic-classic"
+
+        settings2 = GameSettings(game_mode="too easy", wordlist_source="easy.txt")
+        assert settings2.get_file_id_prefix() == "easy-too_easy"
+
+
+class TestFileIdFunctions:
+    """Tests for file ID generation and parsing."""
+
+    def test_sanitize_wordlist_source_removes_txt(self):
+        """Test that .txt extension is removed."""
+        assert _sanitize_wordlist_source("classic.txt") == "classic"
+        assert _sanitize_wordlist_source("easy.txt") == "easy"
+        assert _sanitize_wordlist_source("my_words.txt") == "my_words"
+
+    def test_sanitize_wordlist_source_lowercase(self):
+        """Test that output is lowercase."""
+        assert _sanitize_wordlist_source("CLASSIC.txt") == "classic"
+        assert _sanitize_wordlist_source("MyWords.TXT") == "mywords"
+
+    def test_sanitize_wordlist_source_no_extension(self):
+        """Test sources without .txt extension."""
+        assert _sanitize_wordlist_source("classic") == "classic"
+
+    def test_build_file_id(self):
+        """Test file_id building."""
+        assert _build_file_id("classic.txt", "classic", 0) == "classic-classic-0"
+        assert _build_file_id("easy.txt", "easy", 1) == "easy-easy-1"
+        assert _build_file_id("classic.txt", "too easy", 2) == "classic-too_easy-2"
+
+    def test_parse_file_id(self):
+        """Test file_id parsing."""
+        source, mode, seq = _parse_file_id("classic-classic-0")
+        assert source == "classic"
+        assert mode == "classic"
+        assert seq == 0
+
+        source, mode, seq = _parse_file_id("easy-too_easy-5")
+        assert source == "easy"
+        assert mode == "too easy"
+        assert seq == 5
+
+    def test_parse_file_id_invalid(self):
+        """Test file_id parsing with invalid format."""
+        with pytest.raises(ValueError):
+            _parse_file_id("invalid")
+        
+        with pytest.raises(ValueError):
+            _parse_file_id("classic-classic-notanumber")
+
+
 class TestQualification:
     """Tests for qualification logic."""
 
@@ -379,14 +475,14 @@ class TestDateIds:
         assert len(parts[1]) == 2  # Week number with leading zero
 
     def test_daily_path(self):
-        """Test daily leaderboard path generation."""
-        path = get_daily_leaderboard_path("2025-01-27")
-        assert path == "leaderboards/daily/2025-01-27.json"
+        """Test daily leaderboard path generation with new folder structure."""
+        path = get_daily_leaderboard_path("2025-01-27", "classic-classic-0")
+        assert path == "games/leaderboards/daily/2025-01-27/classic-classic-0/settings.json"
 
     def test_weekly_path(self):
-        """Test weekly leaderboard path generation."""
-        path = get_weekly_leaderboard_path("2025-W04")
-        assert path == "leaderboards/weekly/2025-W04.json"
+        """Test weekly leaderboard path generation with new folder structure."""
+        path = get_weekly_leaderboard_path("2025-W04", "easy-easy-1")
+        assert path == "games/leaderboards/weekly/2025-W04/easy-easy-1/settings.json"
 
 
 class TestSorting:
@@ -395,9 +491,9 @@ class TestSorting:
     def test_sort_by_score_desc(self):
         """Test users are sorted by score descending."""
         users = [
-            UserEntry(uid="1", username="A", word_list=[], score=30, time=100, timestamp=""),
-            UserEntry(uid="2", username="B", word_list=[], score=50, time=100, timestamp=""),
-            UserEntry(uid="3", username="C", word_list=[], score=40, time=100, timestamp=""),
+            UserEntry(uid="1", username="A", word_list=[], score=30, time=100, timestamp="" ),
+            UserEntry(uid="2", username="B", word_list=[], score=50, time=100, timestamp="" ),
+            UserEntry(uid="3", username="C", word_list=[], score=40, time=100, timestamp="" ),
         ]
         
         sorted_users = _sort_users(users)
@@ -409,9 +505,9 @@ class TestSorting:
     def test_sort_by_time_asc_for_equal_score(self):
         """Test users with equal score are sorted by time ascending."""
         users = [
-            UserEntry(uid="1", username="A", word_list=[], score=50, time=120, timestamp=""),
-            UserEntry(uid="2", username="B", word_list=[], score=50, time=80, timestamp=""),
-            UserEntry(uid="3", username="C", word_list=[], score=50, time=100, timestamp=""),
+            UserEntry(uid="1", username="A", word_list=[], score=50, time=120, timestamp="" ),
+            UserEntry(uid="2", username="B", word_list=[], score=50, time=80, timestamp="" ),
+            UserEntry(uid="3", username="C", word_list=[], score=50, time=100, timestamp="" ),
         ]
         
         sorted_users = _sort_users(users)
@@ -475,7 +571,7 @@ class TestUnifiedFormat:
     def test_leaderboard_matches_challenge_structure(self):
         """Test leaderboard to_dict matches expected challenge structure."""
         lb = LeaderboardSettings(
-            challenge_id="2025-01-27",
+            challenge_id="2025-01-27/classic-classic-0",
             entry_type="daily",
         )
         d = lb.to_dict()
@@ -512,13 +608,13 @@ class TestUnifiedFormat:
 
     def test_challenge_id_as_primary_identifier(self):
         """Test challenge_id serves as primary identifier for all types."""
-        # Daily uses date format
-        daily = LeaderboardSettings(challenge_id="2025-01-27", entry_type="daily")
-        assert daily.challenge_id == "2025-01-27"
+        # Daily uses new folder format
+        daily = LeaderboardSettings(challenge_id="2025-01-27/classic-classic-0", entry_type="daily")
+        assert daily.challenge_id == "2025-01-27/classic-classic-0"
         
-        # Weekly uses week format
-        weekly = LeaderboardSettings(challenge_id="2025-W04", entry_type="weekly")
-        assert weekly.challenge_id == "2025-W04"
+        # Weekly uses new folder format
+        weekly = LeaderboardSettings(challenge_id="2025-W04/easy-easy-0", entry_type="weekly")
+        assert weekly.challenge_id == "2025-W04/easy-easy-0"
         
         # Challenge uses UID format
         challenge = LeaderboardSettings(challenge_id="20251130T190249Z-ABCDEF", entry_type="challenge")

wrdler/leaderboard.py

@@ -12,6 +12,16 @@ Leaderboard Configuration:
 - Sorting: score (desc), time (asc), difficulty (desc)
 - File format: Unified with challenge settings.json
 - Settings-based separation: Each unique settings combination gets its own leaderboard folder
+- Folder-based discovery: No index.json, folder names contain settings info
+
+Folder Structure:
+  games/leaderboards/daily/{date}/{wordlist_source}-{game_mode}-{sequence}/settings.json
+  games/leaderboards/weekly/{week}/{wordlist_source}-{game_mode}-{sequence}/settings.json
+  games/{challenge_id}/settings.json
+
+File ID Format:
+  {wordlist_source}-{game_mode}-{sequence}
+  Example: classic-classic-0, easy-easy-1
 """
 __version__ = "0.2.0"
 
@@ -19,10 +29,12 @@ from dataclasses import dataclass, field
 from datetime import datetime, timezone, timedelta
 from typing import Dict, Any, List, Optional, Tuple, Literal
 import logging
+import re
 
 from wrdler.modules.storage import (
     _get_json_from_repo,
-    _upload_json_to_repo
+    _upload_json_to_repo,
+    _list_repo_folders
 )
 from wrdler.modules.constants import HF_REPO_ID, APP_SETTINGS
 from wrdler.game_storage import generate_uid
@@ -31,14 +43,91 @@ logger = logging.getLogger(__name__)
 
 # Configuration
 MAX_DISPLAY_ENTRIES = 20
-DAILY_LEADERBOARD_PATH = "leaderboards/daily"
-WEEKLY_LEADERBOARD_PATH = "leaderboards/weekly"
-LEADERBOARD_INDEX_PATH = "leaderboards/index.json"
+LEADERBOARD_BASE_PATH = "games/leaderboards"
+DAILY_LEADERBOARD_PATH = f"{LEADERBOARD_BASE_PATH}/daily"
+WEEKLY_LEADERBOARD_PATH = f"{LEADERBOARD_BASE_PATH}/weekly"
 
 # Entry types
 EntryType = Literal["daily", "weekly", "challenge"]
 
 
+def _sanitize_wordlist_source(wordlist_source: str) -> str:
+    """
+    Sanitize wordlist source for use in folder names.
+    Removes .txt extension and any problematic characters.
+    
+    Args:
+        wordlist_source: Original wordlist source (e.g., "classic.txt")
+    
+    Returns:
+        Sanitized string (e.g., "classic")
+    """
+    # Remove .txt extension
+    name = wordlist_source
+    if name.endswith(".txt"):
+        name = name[:-4]
+    # Replace any problematic characters with underscores
+    name = re.sub(r'[^\w\-]', '_', name)
+    return name.lower()
+
+
+def _build_file_id(wordlist_source: str, game_mode: str, sequence: int) -> str:
+    """
+    Build a file_id from settings components.
+    
+    Format: {wordlist_source}-{game_mode}-{sequence}
+    Example: classic-classic-0, easy-easy-1
+    
+    Args:
+        wordlist_source: Wordlist source file (will be sanitized)
+        game_mode: Game mode string
+        sequence: Sequence number for this settings combination
+    
+    Returns:
+        File ID string
+    """
+    sanitized_source = _sanitize_wordlist_source(wordlist_source)
+    sanitized_mode = game_mode.lower().replace(" ", "_")
+    return f"{sanitized_source}-{sanitized_mode}-{sequence}"
+
+
+def _parse_file_id(file_id: str) -> Tuple[str, str, int]:
+    """
+    Parse a file_id into its components.
+    
+    Args:
+        file_id: File ID string (e.g., "classic-classic-0")
+    
+    Returns:
+        Tuple of (wordlist_source, game_mode, sequence)
+    
+    Raises:
+        ValueError: If file_id format is invalid
+    """
+    parts = file_id.rsplit("-", 1)
+    if len(parts) != 2:
+        raise ValueError(f"Invalid file_id format: {file_id}")
+    
+    prefix = parts[0]
+    try:
+        sequence = int(parts[1])
+    except ValueError:
+        raise ValueError(f"Invalid sequence in file_id: {file_id}")
+    
+    # Split prefix into wordlist_source and game_mode
+    # Format is {wordlist_source}-{game_mode}
+    prefix_parts = prefix.rsplit("-", 1)
+    if len(prefix_parts) == 2:
+        wordlist_source = prefix_parts[0]
+        game_mode = prefix_parts[1].replace("_", " ")
+    else:
+        # Fallback: treat entire prefix as wordlist_source
+        wordlist_source = prefix
+        game_mode = "classic"
+    
+    return wordlist_source, game_mode, sequence
+
+
 @dataclass
 class GameSettings:
     """Settings that define a unique leaderboard."""
@@ -52,13 +141,23 @@ class GameSettings:
         """Check if two settings are equivalent (same leaderboard)."""
         return (
             self.game_mode == other.game_mode and
-            self.wordlist_source == other.wordlist_source and
+            self._get_sanitized_source() == other._get_sanitized_source() and
             self.show_incorrect_guesses == other.show_incorrect_guesses and
             self.enable_free_letters == other.enable_free_letters and
             self.puzzle_options.get("spacer", 0) == other.puzzle_options.get("spacer", 0) and
             self.puzzle_options.get("may_overlap", False) == other.puzzle_options.get("may_overlap", False)
         )
 
+    def _get_sanitized_source(self) -> str:
+        """Get sanitized wordlist source for comparison."""
+        return _sanitize_wordlist_source(self.wordlist_source)
+
+    def get_file_id_prefix(self) -> str:
+        """Get the file_id prefix (without sequence) for this settings combination."""
+        sanitized_source = _sanitize_wordlist_source(self.wordlist_source)
+        sanitized_mode = self.game_mode.lower().replace(" ", "_")
+        return f"{sanitized_source}-{sanitized_mode}"
+
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary."""
         return {
@@ -144,7 +243,7 @@ class LeaderboardSettings:
     entry_type field to distinguish between daily, weekly, and challenge entries.
     The settings fields define what makes this leaderboard unique.
     """
-    challenge_id: str  # Date-fileId for daily, week-fileId for weekly, UID for challenge
+    challenge_id: str  # {period_id}/{file_id} for daily/weekly, UID for challenge
     entry_type: EntryType  # "daily", "weekly", or "challenge"
     game_mode: str = "classic"
     grid_size: int = 8
@@ -223,14 +322,14 @@ def get_current_weekly_id() -> str:
     return f"{iso_cal.year}-W{iso_cal.week:02d}"
 
 
-def get_daily_leaderboard_path(date_id: str, file_id: int) -> str:
+def get_daily_leaderboard_path(period_id: str, file_id: str) -> str:
     """Get the file path for a daily leaderboard (folder-based with settings.json)."""
-    return f"{DAILY_LEADERBOARD_PATH}/{date_id}-{file_id}/settings.json"
+    return f"{DAILY_LEADERBOARD_PATH}/{period_id}/{file_id}/settings.json"
 
 
-def get_weekly_leaderboard_path(week_id: str, file_id: int) -> str:
+def get_weekly_leaderboard_path(period_id: str, file_id: str) -> str:
     """Get the file path for a weekly leaderboard (folder-based with settings.json)."""
-    return f"{WEEKLY_LEADERBOARD_PATH}/{week_id}-{file_id}/settings.json"
+    return f"{WEEKLY_LEADERBOARD_PATH}/{period_id}/{file_id}/settings.json"
 
 
 def _sort_users(users: List[UserEntry]) -> List[UserEntry]:
@@ -245,23 +344,56 @@ def _sort_users(users: List[UserEntry]) -> List[UserEntry]:
     )
 
 
-def _load_index(repo_id: Optional[str] = None) -> Dict[str, Any]:
-    """Load the leaderboard index."""
+def _list_period_folders(entry_type: EntryType, repo_id: Optional[str] = None) -> List[str]:
+    """
+    List all period folders (dates for daily, weeks for weekly) in a leaderboard type.
+    
+    Args:
+        entry_type: "daily" or "weekly"
+        repo_id: Repository ID
+    
+    Returns:
+        List of period IDs in reverse chronological order
+    """
     if repo_id is None:
         repo_id = HF_REPO_ID
     
-    data = _get_json_from_repo(repo_id, LEADERBOARD_INDEX_PATH, "dataset")
-    if not data:
-        return {"daily": {}, "weekly": {}}
-    return data
+    if entry_type == "daily":
+        base_path = DAILY_LEADERBOARD_PATH
+    elif entry_type == "weekly":
+        base_path = WEEKLY_LEADERBOARD_PATH
+    else:
+        return []
+    
+    folders = _list_repo_folders(repo_id, base_path, "dataset")
+    # Sort in reverse chronological order
+    folders.sort(reverse=True)
+    return folders
 
 
-def _save_index(index: Dict[str, Any], repo_id: Optional[str] = None) -> bool:
-    """Save the leaderboard index."""
+def _list_file_ids_for_period(entry_type: EntryType, period_id: str, repo_id: Optional[str] = None) -> List[str]:
+    """
+    List all file_ids (settings combinations) for a given period.
+    
+    Args:
+        entry_type: "daily" or "weekly"
+        period_id: Date or week identifier
+        repo_id: Repository ID
+    
+    Returns:
+        List of file_id strings
+    """
     if repo_id is None:
         repo_id = HF_REPO_ID
     
-    return _upload_json_to_repo(index, repo_id, LEADERBOARD_INDEX_PATH, "dataset")
+    if entry_type == "daily":
+        base_path = f"{DAILY_LEADERBOARD_PATH}/{period_id}"
+    elif entry_type == "weekly":
+        base_path = f"{WEEKLY_LEADERBOARD_PATH}/{period_id}"
+    else:
+        return []
+    
+    return _list_repo_folders(repo_id, base_path, "dataset")
 
 
 def find_matching_leaderboard(
@@ -269,9 +401,10 @@ def find_matching_leaderboard(
     period_id: str,
     settings: GameSettings,
     repo_id: Optional[str] = None
-) -> Tuple[Optional[int], Optional[LeaderboardSettings]]:
+) -> Tuple[Optional[str], Optional[LeaderboardSettings]]:
     """
     Find a leaderboard matching the given settings for a period.
+    Uses folder-based discovery instead of index.json.
     
     Args:
         entry_type: "daily" or "weekly"
@@ -285,34 +418,78 @@ def find_matching_leaderboard(
     if repo_id is None:
         repo_id = HF_REPO_ID
     
-    index = _load_index(repo_id)
-    period_entries = index.get(entry_type, {}).get(period_id, [])
-    
-    for entry in period_entries:
-        entry_settings = GameSettings.from_dict(entry)
-        if settings.matches(entry_settings):
-            file_id = entry["file_id"]
-            # Load the actual leaderboard
-            if entry_type == "daily":
-                path = get_daily_leaderboard_path(period_id, file_id)
-            else:
-                path = get_weekly_leaderboard_path(period_id, file_id)
-            
-            data = _get_json_from_repo(repo_id, path, "dataset")
-            if data:
-                return file_id, LeaderboardSettings.from_dict(data)
+    # Get the file_id prefix for this settings combination
+    prefix = settings.get_file_id_prefix()
+    
+    # List all file_ids for this period
+    file_ids = _list_file_ids_for_period(entry_type, period_id, repo_id)
+    
+    # Find matching file_ids by prefix
+    matching_file_ids = [fid for fid in file_ids if fid.startswith(prefix + "-")]
+    
+    for file_id in matching_file_ids:
+        # Load the leaderboard and verify settings match
+        if entry_type == "daily":
+            path = get_daily_leaderboard_path(period_id, file_id)
+        else:
+            path = get_weekly_leaderboard_path(period_id, file_id)
+        
+        data = _get_json_from_repo(repo_id, path, "dataset")
+        if data:
+            leaderboard = LeaderboardSettings.from_dict(data)
+            lb_settings = leaderboard.get_settings()
+            if settings.matches(lb_settings):
+                return file_id, leaderboard
     
     return None, None
 
 
+def _get_next_sequence(entry_type: EntryType, period_id: str, settings: GameSettings, repo_id: Optional[str] = None) -> int:
+    """
+    Get the next sequence number for a new leaderboard with given settings.
+    
+    Args:
+        entry_type: "daily" or "weekly"
+        period_id: Date or week identifier
+        settings: Game settings
+        repo_id: Repository ID
+    
+    Returns:
+        Next sequence number (0 if none exist)
+    """
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+    
+    prefix = settings.get_file_id_prefix()
+    file_ids = _list_file_ids_for_period(entry_type, period_id, repo_id)
+    
+    # Find all file_ids with matching prefix
+    matching = [fid for fid in file_ids if fid.startswith(prefix + "-")]
+    
+    if not matching:
+        return 0
+    
+    # Extract sequence numbers
+    sequences = []
+    for fid in matching:
+        try:
+            _, _, seq = _parse_file_id(fid)
+            sequences.append(seq)
+        except ValueError:
+            continue
+    
+    return max(sequences, default=-1) + 1
+
+
 def create_or_get_leaderboard(
     entry_type: EntryType,
     period_id: str,
     settings: GameSettings,
     repo_id: Optional[str] = None
-) -> Tuple[int, LeaderboardSettings]:
+) -> Tuple[str, LeaderboardSettings]:
     """
     Get existing leaderboard or create a new one for the settings.
+    Uses folder-based storage without index.json.
     
     Args:
         entry_type: "daily" or "weekly"
@@ -333,18 +510,11 @@ def create_or_get_leaderboard(
         return file_id, leaderboard
     
     # Create new leaderboard
-    index = _load_index(repo_id)
-    if entry_type not in index:
-        index[entry_type] = {}
-    if period_id not in index[entry_type]:
-        index[entry_type][period_id] = []
-    
-    # Get next file_id
-    existing_ids = [e["file_id"] for e in index[entry_type][period_id]]
-    file_id = max(existing_ids, default=-1) + 1
+    sequence = _get_next_sequence(entry_type, period_id, settings, repo_id)
+    file_id = _build_file_id(settings.wordlist_source, settings.game_mode, sequence)
     
-    # Create challenge_id (folder name)
-    challenge_id = f"{period_id}-{file_id}"
+    # Create challenge_id (identifies this leaderboard)
+    challenge_id = f"{period_id}/{file_id}"
     
     # Create new leaderboard
     leaderboard = LeaderboardSettings(
@@ -358,19 +528,13 @@ def create_or_get_leaderboard(
         users=[]
     )
     
-    # Update index
-    index_entry = settings.to_dict()
-    index_entry["file_id"] = file_id
-    index[entry_type][period_id].append(index_entry)
-    _save_index(index, repo_id)
-    
     return file_id, leaderboard
 
 
 def load_leaderboard(
     entry_type: EntryType,
     period_id: str,
-    file_id: int,
+    file_id: str,
     repo_id: Optional[str] = None
 ) -> Optional[LeaderboardSettings]:
     """
@@ -379,7 +543,7 @@ def load_leaderboard(
     Args:
         entry_type: "daily" or "weekly"
         period_id: Date string or week identifier
-        file_id: File identifier
+        file_id: File identifier (e.g., "classic-classic-0")
         repo_id: Repository ID (uses HF_REPO_ID if None)
 
     Returns:
@@ -408,7 +572,7 @@ def load_leaderboard(
 
 def save_leaderboard(
     leaderboard: LeaderboardSettings,
-    file_id: int,
+    file_id: str,
     repo_id: Optional[str] = None
 ) -> bool:
     """
@@ -416,7 +580,7 @@ def save_leaderboard(
 
     Args:
         leaderboard: LeaderboardSettings object to save
-        file_id: File identifier
+        file_id: File identifier (e.g., "classic-classic-0")
         repo_id: Repository ID (uses HF_REPO_ID if None)
 
     Returns:
@@ -425,15 +589,12 @@ def save_leaderboard(
     if repo_id is None:
         repo_id = HF_REPO_ID
 
-    # Extract period_id from challenge_id (format: "2025-01-27-0" or "2025-W04-0")
-    # The challenge_id is the folder name, which includes the file_id
-    parts = leaderboard.challenge_id.rsplit("-", 1)
-    if len(parts) == 2 and parts[1].isdigit():
-        period_id = parts[0]
+    # Extract period_id from challenge_id (format: "2025-01-27/classic-classic-0" or "2025-W04/easy-easy-0")
+    if "/" in leaderboard.challenge_id:
+        period_id = leaderboard.challenge_id.split("/")[0]
     else:
-        # Handle weekly format like "2025-W04-0"
-        parts = leaderboard.challenge_id.rsplit("-", 1)
-        period_id = parts[0] if len(parts) > 1 else leaderboard.challenge_id
+        # Fallback: try to parse from challenge_id directly
+        period_id = leaderboard.challenge_id
 
     if leaderboard.entry_type == "daily":
         path = get_daily_leaderboard_path(period_id, file_id)
@@ -722,7 +883,7 @@ def list_available_periods(
     repo_id: Optional[str] = None
 ) -> List[str]:
     """
-    List available period IDs from the index.
+    List available period IDs from folder structure.
 
     Args:
         entry_type: "daily" or "weekly"
@@ -732,9 +893,7 @@ def list_available_periods(
     Returns:
         List of period IDs in reverse chronological order
     """
-    index = _load_index(repo_id)
-    periods = list(index.get(entry_type, {}).keys())
-    periods.sort(reverse=True)
+    periods = _list_period_folders(entry_type, repo_id)
     return periods[:limit]
 
 
@@ -754,5 +913,19 @@ def list_settings_for_period(
     Returns:
         List of settings dictionaries with file_id
     """
-    index = _load_index(repo_id)
-    return index.get(entry_type, {}).get(period_id, [])
+    file_ids = _list_file_ids_for_period(entry_type, period_id, repo_id)
+    
+    settings_list = []
+    for file_id in file_ids:
+        try:
+            wordlist_source, game_mode, sequence = _parse_file_id(file_id)
+            settings_list.append({
+                "file_id": file_id,
+                "wordlist_source": wordlist_source,
+                "game_mode": game_mode,
+                "sequence": sequence
+            })
+        except ValueError:
+            continue
+    
+    return settings_list

wrdler/leaderboard_page.py

@@ -16,7 +16,10 @@ from wrdler.leaderboard import (
     get_last_n_daily_leaderboards,
     get_current_daily_id,
     get_current_weekly_id,
-    list_available_leaderboards,
+    list_available_periods,
+    list_settings_for_period,
+    find_matching_leaderboard,
+    GameSettings,
     LeaderboardSettings,
     MAX_DISPLAY_ENTRIES
 )
@@ -32,11 +35,11 @@ def _format_time(seconds: int) -> str:
 def _get_rank_emoji(rank: int) -> str:
     """Get emoji for rank."""
     if rank == 1:
-        return "??"
+        return "🥇"
     elif rank == 2:
-        return "??"
+        return "🥈"
     elif rank == 3:
-        return "??"
+        return "🥉"
     return f"{rank}."
 
 
@@ -60,7 +63,7 @@ def _render_leaderboard_table(leaderboard: Optional[LeaderboardSettings], title:
         difficulty = f"{user.word_list_difficulty:.2f}" if user.word_list_difficulty else "-"
 
         # Show challenge indicator if from a challenge
-        challenge_badge = " ??" if user.source_challenge_id else ""
+        challenge_badge = " 🎯" if user.source_challenge_id else ""
 
         rows.append(f"""
         <tr>
@@ -117,18 +120,32 @@ def _render_leaderboard_table(leaderboard: Optional[LeaderboardSettings], title:
     # Show entry count and last updated
     total_entries = len(leaderboard.users)
     if total_entries > MAX_DISPLAY_ENTRIES:
-        st.caption(f"Showing top {MAX_DISPLAY_ENTRIES} of {total_entries} entries � Last updated: {leaderboard.created_at}")
+        st.caption(f"Showing top {MAX_DISPLAY_ENTRIES} of {total_entries} entries · Last updated: {leaderboard.created_at}")
     else:
-        st.caption(f"{total_entries} entries � Last updated: {leaderboard.created_at}")
+        st.caption(f"{total_entries} entries · Last updated: {leaderboard.created_at}")
+
+
+def _get_current_game_settings() -> GameSettings:
+    """Get the current game settings from session state."""
+    return GameSettings(
+        game_mode=st.session_state.get("game_mode", "classic"),
+        wordlist_source=st.session_state.get("selected_wordlist", "classic.txt"),
+        show_incorrect_guesses=st.session_state.get("show_incorrect_guesses", True),
+        enable_free_letters=st.session_state.get("enable_free_letters", False),
+        puzzle_options={
+            "spacer": st.session_state.get("spacer", 1),
+            "may_overlap": False
+        }
+    )
 
 
 def render_leaderboard_page():
     """Render the full leaderboard page."""
     game_title = APP_SETTINGS.get("game_title", "Wrdler")
-    st.title(f"?? {game_title} Leaderboards")
+    st.title(f"🏆 {game_title} Leaderboards")
 
     # Tab selection
-    tab1, tab2, tab3 = st.tabs(["?? Daily", "?? Weekly", "?? History"])
+    tab1, tab2, tab3 = st.tabs(["📅 Daily", "📆 Weekly", "📚 History"])
 
     with tab1:
         _render_daily_tab()
@@ -142,18 +159,22 @@ def render_leaderboard_page():
 
 def _render_daily_tab():
     """Render daily leaderboards tab."""
-    st.header("?? Daily Leaderboards")
+    st.header("📅 Daily Leaderboards")
     st.write(f"Top {MAX_DISPLAY_ENTRIES} scores for each day. Resets at UTC midnight.")
 
+    # Get current game settings for filtering
+    settings = _get_current_game_settings()
+    st.info(f"Showing leaderboards for: **{settings.game_mode}** mode, **{settings.wordlist_source}**")
+
     # Get last 7 days
-    daily_boards = get_last_n_daily_leaderboards(7)
+    daily_boards = get_last_n_daily_leaderboards(7, settings)
 
     for date_id, leaderboard in daily_boards:
         # Format date nicely
         try:
             date_obj = datetime.strptime(date_id, "%Y-%m-%d")
             if date_id == get_current_daily_id():
-                title = f"?? Today ({date_obj.strftime('%B %d, %Y')})"
+                title = f"🌟 Today ({date_obj.strftime('%B %d, %Y')})"
             else:
                 title = date_obj.strftime("%A, %B %d, %Y")
         except ValueError:
@@ -165,11 +186,15 @@ def _render_daily_tab():
 
 def _render_weekly_tab():
     """Render weekly leaderboard tab."""
-    st.header("?? Weekly Leaderboard")
+    st.header("📆 Weekly Leaderboard")
     st.write(f"Top {MAX_DISPLAY_ENTRIES} scores for the current week. Resets Monday at UTC midnight.")
 
+    # Get current game settings for filtering
+    settings = _get_current_game_settings()
+    st.info(f"Showing leaderboard for: **{settings.game_mode}** mode, **{settings.wordlist_source}**")
+
     weekly_id = get_current_weekly_id()
-    leaderboard = load_leaderboard("weekly", weekly_id)
+    _, leaderboard = find_matching_leaderboard("weekly", weekly_id, settings)
 
     # Parse week for display
     try:
@@ -178,48 +203,80 @@ def _render_weekly_tab():
     except ValueError:
         title = weekly_id
 
-    _render_leaderboard_table(leaderboard, f"?? {title}")
+    _render_leaderboard_table(leaderboard, f"🗓️ {title}")
 
 
 def _render_history_tab():
     """Render historical leaderboards tab."""
-    st.header("?? Historical Leaderboards")
+    st.header("📚 Historical Leaderboards")
     st.write("Look up past leaderboards.")
 
     col1, col2 = st.columns(2)
 
     with col1:
         st.subheader("Daily History")
-        daily_ids = list_available_leaderboards("daily", limit=30)
-        selected_daily = st.selectbox(
-            "Select a date",
-            options=daily_ids,
-            key="history_daily_select"
-        )
-
-        if st.button("Load Daily", key="load_daily"):
-            leaderboard = load_leaderboard("daily", selected_daily)
-            _render_leaderboard_table(leaderboard, f"Daily: {selected_daily}")
+        daily_periods = list_available_periods("daily", limit=30)
+        if daily_periods:
+            selected_daily = st.selectbox(
+                "Select a date",
+                options=daily_periods,
+                key="history_daily_select"
+            )
+
+            # Show available settings for this period
+            settings_list = list_settings_for_period("daily", selected_daily)
+            if settings_list:
+                file_id_options = [s["file_id"] for s in settings_list]
+                selected_file_id = st.selectbox(
+                    "Select settings",
+                    options=file_id_options,
+                    format_func=lambda x: x.replace("-", " / "),
+                    key="history_daily_file_id"
+                )
+
+                if st.button("Load Daily", key="load_daily"):
+                    leaderboard = load_leaderboard("daily", selected_daily, selected_file_id)
+                    _render_leaderboard_table(leaderboard, f"Daily: {selected_daily} ({selected_file_id})")
+            else:
+                st.info("No leaderboards found for this date.")
+        else:
+            st.info("No daily leaderboards found.")
 
     with col2:
         st.subheader("Weekly History")
-        weekly_ids = list_available_leaderboards("weekly", limit=20)
-        selected_weekly = st.selectbox(
-            "Select a week",
-            options=weekly_ids,
-            key="history_weekly_select"
-        )
-
-        if st.button("Load Weekly", key="load_weekly"):
-            leaderboard = load_leaderboard("weekly", selected_weekly)
-            _render_leaderboard_table(leaderboard, f"Weekly: {selected_weekly}")
+        weekly_periods = list_available_periods("weekly", limit=20)
+        if weekly_periods:
+            selected_weekly = st.selectbox(
+                "Select a week",
+                options=weekly_periods,
+                key="history_weekly_select"
+            )
+
+            # Show available settings for this period
+            settings_list = list_settings_for_period("weekly", selected_weekly)
+            if settings_list:
+                file_id_options = [s["file_id"] for s in settings_list]
+                selected_file_id = st.selectbox(
+                    "Select settings",
+                    options=file_id_options,
+                    format_func=lambda x: x.replace("-", " / "),
+                    key="history_weekly_file_id"
+                )
+
+                if st.button("Load Weekly", key="load_weekly"):
+                    leaderboard = load_leaderboard("weekly", selected_weekly, selected_file_id)
+                    _render_leaderboard_table(leaderboard, f"Weekly: {selected_weekly} ({selected_file_id})")
+            else:
+                st.info("No leaderboards found for this week.")
+        else:
+            st.info("No weekly leaderboards found.")
 
 
 # Entry point for standalone testing
 if __name__ == "__main__":
     st.set_page_config(
         page_title="Wrdler Leaderboards",
-        page_icon="??",
+        page_icon="🏆",
         layout="wide"
     )
     render_leaderboard_page()

wrdler/modules/storage.md

@@ -6,6 +6,7 @@ The `storage.py` module provides helper functions for:
 - Managing URL shortening by storing (short URL, full URL) pairs in a JSON file on the repository.
 - Retrieving full URLs from short URL IDs and vice versa.
 - Handle specific file types for 3D models, images, video and audio.
+- **📁 Listing folders and files in HuggingFace repositories.**
 - **🔑 Cryptographic key management for Open Badge 3.0 issuers.**
 
 ## Key Functions
@@ -142,9 +143,49 @@ status, retrieved_full_url = gen_full_url(
 print("Status:", status)
 if status == "success_retrieved_full":
     print("Retrieved Full URL:", retrieved_full_url)
+## 📁 Repository Folder Listing Functions
+
+### 5. `_list_repo_folders(repo_id, path_prefix, repo_type="dataset")`
+- **Purpose:**  
+  List folder names under a given path in a HuggingFace repository. Enables folder-based discovery without index files.
+- **Parameters:**
+  - `repo_id` (str): The repository ID on Hugging Face
+  - `path_prefix` (str): The path prefix to list folders under
+  - `repo_type` (str): Repository type. Default is `"dataset"`.
+- **Returns:** `List[str]` - List of folder names found under the path_prefix.
+- **Usage Example:**
+```python
+from modules.storage import _list_repo_folders
+
+# List all date folders in daily leaderboards
+folders = _list_repo_folders("Surn/Wrdler-Data", "games/leaderboards/daily")
+print("Available dates:", folders)
+# Output: ['2025-01-27', '2025-01-26', '2025-01-25']
+```
+
+### 6. `_list_repo_files_in_folder(repo_id, folder_path, repo_type="dataset")`
+- **Purpose:**  
+  List file names directly under a folder in a HuggingFace repository.
+- **Parameters:**
+  - `repo_id` (str): The repository ID on Hugging Face
+  - `folder_path` (str): The folder path to list files under
+  - `repo_type` (str): Repository type. Default is `"dataset"`.
+- **Returns:** `List[str]` - List of file names found directly in the folder.
+- **Usage Example:**
+```python
+from modules.storage import _list_repo_files_in_folder
+
+files = _list_repo_files_in_folder(
+    "Surn/Wrdler-Data",
+    "games/leaderboards/daily/2025-01-27/classic-classic-0"
+)
+print("Files:", files)
+# Output: ['settings.json']
+```
+
 ## 🔑 Cryptographic Key Management Functions
 
-### 5. `store_issuer_keypair(issuer_id, public_key, private_key, repo_id=None)`
+### 7. `store_issuer_keypair(issuer_id, public_key, private_key, repo_id=None)`
 - **Purpose:**  
   Securely store cryptographic keys for an issuer in a private Hugging Face repository. Private keys are encrypted before storage.
 - **⚠️ IMPORTANT:** This function requires a PRIVATE Hugging Face repository to ensure the security of stored private keys. Never use this with public repositories.
@@ -163,7 +204,7 @@ if success:
     print("Keys stored successfully")
 else:
     print("Failed to store keys")
-### 6. `get_issuer_keypair(issuer_id, repo_id=None)`
+### 8. `get_issuer_keypair(issuer_id, repo_id=None)`
 - **Purpose:**  
   Retrieve and decrypt stored cryptographic keys for an issuer from the private Hugging Face repository.
 - **⚠️ IMPORTANT:** This function accesses a PRIVATE Hugging Face repository containing encrypted private keys. Ensure proper access control and security measures.
@@ -179,7 +220,7 @@ if public_key and private_key:
     # Use private_key for signing operations
 else:
     print("Keys not found or error occurred")
-### 7. `get_verification_methods_registry(repo_id=None)`
+### 9. `get_verification_methods_registry(repo_id=None)`
 - **Purpose:**  
   Retrieve the global verification methods registry containing all registered issuer public keys.
 - **Returns:** `Dict[str, Any]` - Registry data containing all verification methods.
@@ -193,7 +234,7 @@ for method in methods:
     print(f"Public Key: {method['public_key']}")
     print(f"Key Type: {method['key_type']}")
     print("---")
-### 8. `list_issuer_ids(repo_id=None)`
+### 10. `list_issuer_ids(repo_id=None)`
 - **Purpose:**  
   List all issuer IDs that have stored keys in the repository.
 - **Returns:** `List[str]` - List of issuer IDs.
@@ -224,4 +265,4 @@ for issuer_id in issuer_ids:
 
 ---
 
-This guide provides the essential usage examples for interacting with the storage, URL-shortening, and cryptographic key management functionality. You can integrate these examples into your application or use them as a reference when extending functionality.
+This guide provides the essential usage examples for interacting with the storage, URL-shortening, folder listing, and cryptographic key management functionality. You can integrate these examples into your application or use them as a reference when extending functionality.

wrdler/modules/storage.py

@@ -1,5 +1,5 @@
 # modules/storage.py
-__version__ = "0.1.5"
+__version__ = "0.1.6"
 import os
 import urllib.parse
 import tempfile
@@ -691,18 +691,109 @@ def list_issuer_ids(repo_id: str = None) -> List[str]:
         logger.error(f"Error listing issuer IDs: {e}")
         return []
 
+def _list_repo_folders(repo_id: str, path_prefix: str, repo_type: str = "dataset") -> List[str]:
+    """
+    List folder names under a given path in a HuggingFace repository.
+    
+    Args:
+        repo_id: The repository ID on Hugging Face
+        path_prefix: The path prefix to list folders under (e.g., "leaderboards/daily/2025-01-27")
+        repo_type: Repository type ("dataset", "model", "space"). Default is "dataset".
+    
+    Returns:
+        List of folder names (not full paths) found under the path_prefix.
+        Returns empty list if path not found or on error.
+    """
+    try:
+        login(token=HF_API_TOKEN)
+        api = HfApi()
+        
+        # List all files in the repo under the prefix
+        # The list_repo_files returns file paths, so we extract unique folder names
+        all_files = api.list_repo_files(
+            repo_id=repo_id,
+            repo_type=repo_type,
+            token=HF_API_TOKEN
+        )
+        
+        # Ensure path_prefix ends with /
+        if path_prefix and not path_prefix.endswith("/"):
+            path_prefix = path_prefix + "/"
+        
+        folders = set()
+        for file_path in all_files:
+            if file_path.startswith(path_prefix):
+                # Get the relative path after the prefix
+                relative_path = file_path[len(path_prefix):]
+                # Extract the first folder name (before any /)
+                if "/" in relative_path:
+                    folder_name = relative_path.split("/")[0]
+                    folders.add(folder_name)
+        
+        return sorted(list(folders))
+    
+    except RepositoryNotFoundError:
+        logger.warning(f"Repository {repo_id} not found.")
+        return []
+    except Exception as e:
+        logger.error(f"Error listing folders in {repo_id}/{path_prefix}: {e}")
+        return []
+
+
+def _list_repo_files_in_folder(repo_id: str, folder_path: str, repo_type: str = "dataset") -> List[str]:
+    """
+    List file names (not full paths) directly under a folder in a HuggingFace repository.
+    
+    Args:
+        repo_id: The repository ID on Hugging Face
+        folder_path: The folder path to list files under
+        repo_type: Repository type. Default is "dataset".
+    
+    Returns:
+        List of file names found directly in the folder.
+    """
+    try:
+        login(token=HF_API_TOKEN)
+        api = HfApi()
+        
+        all_files = api.list_repo_files(
+            repo_id=repo_id,
+            repo_type=repo_type,
+            token=HF_API_TOKEN
+        )
+        
+        # Ensure folder_path ends with /
+        if folder_path and not folder_path.endswith("/"):
+            folder_path = folder_path + "/"
+        
+        files = []
+        for file_path in all_files:
+            if file_path.startswith(folder_path):
+                relative_path = file_path[len(folder_path):]
+                # Only include files directly in this folder (no subdirectories)
+                if "/" not in relative_path and relative_path:
+                    files.append(relative_path)
+        
+        return sorted(files)
+    
+    except RepositoryNotFoundError:
+        logger.warning(f"Repository {repo_id} not found.")
+        return []
+    except Exception as e:
+        logger.error(f"Error listing files in {repo_id}/{folder_path}: {e}")
+        return []
 
-    if __name__ == "__main__":
-       issuer_id = "https://example.edu/issuers/565049"
-       # Example usage
-       public_key, private_key = get_issuer_keypair(issuer_id)
-       print(f"Public Key: {public_key}")
-       print(f"Private Key: {private_key}")
+if __name__ == "__main__":
+   issuer_id = "https://example.edu/issuers/565049"
+   # Example usage
+   public_key, private_key = get_issuer_keypair(issuer_id)
+   print(f"Public Key: {public_key}")
+   print(f"Private Key: {private_key}")
 
-       # Example to store keys
-       store_issuer_keypair(issuer_id, public_key, private_key)
+   # Example to store keys
+   store_issuer_keypair(issuer_id, public_key, private_key)
 
-       # Example to list issuer IDs
-       issuer_ids = list_issuer_ids()
+   # Example to list issuer IDs
+   issuer_ids = list_issuer_ids()
 
-       print(f"Issuer IDs: {issuer_ids}")
+   print(f"Issuer IDs: {issuer_ids}")