CLAUDE: Implement voice channel management system

Add comprehensive voice channel system for Discord gameplay with:

## New Features
- `/voice-channel public` - Create public voice channels with random codenames
- `/voice-channel private` - Create private team vs team channels with role permissions
- Automatic cleanup after configurable empty duration (default: 5 minutes)
- Restart-resilient JSON persistence for channel tracking
- Background monitoring service with graceful error handling

## Technical Implementation
- **Voice Commands Package** (`commands/voice/`)
  - `channels.py` - Main slash command implementation with modern command groups
  - `cleanup_service.py` - Background service for automatic channel deletion
  - `tracker.py` - JSON-based persistent channel tracking
  - `__init__.py` - Package setup with resilient loading
- **Bot Integration** - Voice cleanup service integrated into bot lifecycle
- **Service Dependencies** - Integration with team, league, and schedule services
- **Permission System** - Team-based Discord role permissions for private channels

## Key Features
- **Public Channels**: Random codenames, open speaking permissions
- **Private Channels**: "{Away} vs {Home}" naming, team role restrictions
- **Auto-cleanup**: Configurable intervals with empty duration thresholds
- **Restart Resilience**: JSON file persistence survives bot restarts
- **Error Handling**: Comprehensive validation and graceful degradation
- **Migration Support**: Deprecated old prefix commands with helpful messages

## Documentation & Testing
- Comprehensive README.md following project patterns
- Full test suite with 15+ test methods covering all scenarios
- Updated CLAUDE.md files with voice command documentation
- Clean IDE diagnostics with proper type safety

## Integration Points
- Team service for user validation and role lookup
- League service for current season/week information
- Schedule service for opponent detection in private channels
- Background task management in bot startup/shutdown

🤖 Generated with [Claude Code](https://claude.ai/code)

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

bot.py

@@ -115,6 +115,7 @@ class SBABot(commands.Bot):
         from commands.admin import setup_admin
         from commands.transactions import setup_transactions
         from commands.dice import setup_dice
+        from commands.voice import setup_voice
         
         # Define command packages to load
         command_packages = [
@@ -125,6 +126,7 @@ class SBABot(commands.Bot):
             ("admin", setup_admin),
             ("transactions", setup_transactions),
             ("dice", setup_dice),
+            ("voice", setup_voice),
         ]
         
         total_successful = 0
@@ -161,6 +163,15 @@ class SBABot(commands.Bot):
             from tasks.custom_command_cleanup import setup_cleanup_task
             self.custom_command_cleanup = setup_cleanup_task(self)
 
+            # Initialize voice channel cleanup service
+            from commands.voice.cleanup_service import VoiceChannelCleanupService
+            self.voice_cleanup_service = VoiceChannelCleanupService()
+
+            # Start voice channel monitoring (includes startup verification)
+            import asyncio
+            asyncio.create_task(self.voice_cleanup_service.start_monitoring(self))
+            self.logger.info("✅ Voice channel cleanup service started")
+
             self.logger.info("✅ Background tasks initialized successfully")
 
         except Exception as e:
@@ -301,6 +312,13 @@ class SBABot(commands.Bot):
             except Exception as e:
                 self.logger.error(f"Error stopping cleanup task: {e}")
 
+        if hasattr(self, 'voice_cleanup_service'):
+            try:
+                self.voice_cleanup_service.stop_monitoring()
+                self.logger.info("Voice channel cleanup service stopped")
+            except Exception as e:
+                self.logger.error(f"Error stopping voice cleanup service: {e}")
+        
         # Call parent close method
         await super().close()
         self.logger.info("Bot shutdown complete")

commands/voice/README.md

@@ -0,0 +1,230 @@
+# Voice Channel Commands
+
+This directory contains Discord slash commands for creating and managing voice channels for gameplay.
+
+## Files
+
+### `channels.py`
+- **Commands**:
+  - `/voice-channel public` - Create a public voice channel for gameplay
+  - `/voice-channel private` - Create a private team vs team voice channel
+- **Description**: Main command implementation with VoiceChannelCommands cog
+- **Service Dependencies**:
+  - `team_service.get_teams_by_owner()` - Verify user has a team
+  - `league_service.get_current_state()` - Get current season/week info
+  - `schedule_service.get_team_schedule()` - Find opponent for private channels
+- **Deprecated Commands**:
+  - `!vc`, `!voice`, `!gameplay` → Shows migration message to `/voice-channel public`
+  - `!private` → Shows migration message to `/voice-channel private`
+
+### `cleanup_service.py`
+- **Class**: `VoiceChannelCleanupService`
+- **Description**: Manages automatic cleanup of bot-created voice channels
+- **Features**:
+  - Restart-resilient channel tracking using JSON persistence
+  - Configurable cleanup intervals and empty thresholds
+  - Background monitoring loop with error recovery
+  - Startup verification to clean stale tracking entries
+
+### `tracker.py`
+- **Class**: `VoiceChannelTracker`
+- **Description**: JSON-based persistent tracking of voice channels
+- **Features**:
+  - Channel creation and status tracking
+  - Empty duration monitoring with datetime handling
+  - Cleanup candidate identification
+  - Automatic stale entry removal
+
+### `__init__.py`
+- **Function**: `setup_voice(bot)`
+- **Description**: Package initialization with resilient cog loading
+- **Integration**: Follows established bot architecture patterns
+
+## Key Features
+
+### Public Voice Channels (`/voice-channel public`)
+- **Permissions**: Everyone can connect and speak
+- **Naming**: Random codename generation (e.g., "Gameplay Phoenix", "Gameplay Thunder")
+- **Requirements**: User must be on a current team
+- **Auto-cleanup**: Configurable threshold (default: empty for configured minutes)
+
+### Private Voice Channels (`/voice-channel private`)
+- **Permissions**:
+  - Team members can connect and speak (using `team.lname` Discord roles)
+  - Everyone else can connect but only listen
+- **Naming**: Automatic "{Away} vs {Home}" format based on current week's schedule
+- **Opponent Detection**: Uses current league week to find scheduled opponent
+- **Requirements**:
+  - User must be on a current team
+  - Team must have upcoming games in current week
+- **Role Integration**: Finds Discord roles matching team full names (`team.lname`)
+
+### Automatic Cleanup System
+- **Monitoring Interval**: Configurable (default: 60 seconds)
+- **Empty Threshold**: Configurable (default: 5 minutes empty before deletion)
+- **Restart Resilience**: JSON file persistence survives bot restarts
+- **Startup Verification**: Validates tracked channels still exist on bot startup
+- **Graceful Error Handling**: Continues operation even if individual operations fail
+
+## Architecture
+
+### Command Flow
+1. **Team Verification**: Check user has current team using `team_service`
+2. **Channel Creation**: Create voice channel with appropriate permissions
+3. **Tracking Registration**: Add channel to cleanup service tracking
+4. **User Feedback**: Send success embed with channel details
+
+### Permission System
+```python
+# Public channels - everyone can speak
+overwrites = {
+    guild.default_role: discord.PermissionOverwrite(speak=True, connect=True)
+}
+
+# Private channels - team roles only can speak
+overwrites = {
+    guild.default_role: discord.PermissionOverwrite(speak=False, connect=True),
+    user_team_role: discord.PermissionOverwrite(speak=True, connect=True),
+    opponent_team_role: discord.PermissionOverwrite(speak=True, connect=True)
+}
+```
+
+### Cleanup Service Integration
+```python
+# Bot initialization (bot.py)
+from commands.voice.cleanup_service import VoiceChannelCleanupService
+self.voice_cleanup_service = VoiceChannelCleanupService()
+asyncio.create_task(self.voice_cleanup_service.start_monitoring(self))
+
+# Channel tracking
+if hasattr(self.bot, 'voice_cleanup_service'):
+    cleanup_service = self.bot.voice_cleanup_service
+    cleanup_service.tracker.add_channel(channel, channel_type, interaction.user.id)
+```
+
+### JSON Data Structure
+```json
+{
+  "voice_channels": {
+    "123456789": {
+      "channel_id": "123456789",
+      "guild_id": "987654321",
+      "name": "Gameplay Phoenix",
+      "type": "public",
+      "created_at": "2025-01-15T10:30:00",
+      "last_checked": "2025-01-15T10:35:00",
+      "empty_since": "2025-01-15T10:32:00",
+      "creator_id": "111222333"
+    }
+  }
+}
+```
+
+## Configuration
+
+### Cleanup Service Settings
+- **`cleanup_interval`**: How often to check channels (default: 60 seconds)
+- **`empty_threshold`**: Minutes empty before deletion (default: 5 minutes)
+- **`data_file`**: JSON persistence file path (default: "data/voice_channels.json")
+
+### Channel Categories
+- Channels are created in the "Voice Channels" category if it exists
+- Falls back to no category if "Voice Channels" category not found
+
+### Random Codenames
+```python
+CODENAMES = [
+    "Phoenix", "Thunder", "Lightning", "Storm", "Blaze", "Frost", "Shadow", "Nova",
+    "Viper", "Falcon", "Wolf", "Eagle", "Tiger", "Shark", "Bear", "Dragon",
+    "Alpha", "Beta", "Gamma", "Delta", "Echo", "Foxtrot", "Golf", "Hotel",
+    "Crimson", "Azure", "Emerald", "Golden", "Silver", "Bronze", "Platinum", "Diamond"
+]
+```
+
+## Error Handling
+
+### Common Scenarios
+- **No Team Found**: User-friendly message directing to contact league administrator
+- **No Upcoming Games**: Informative message about being between series
+- **Missing Discord Roles**: Warning in embed about teams without speaking permissions
+- **Permission Errors**: Clear message to contact server administrator
+- **League Info Unavailable**: Graceful fallback with retry suggestion
+
+### Service Dependencies
+- **Graceful Degradation**: Voice channels work without cleanup service
+- **API Failures**: Comprehensive error handling for external service calls
+- **Discord Errors**: Specific handling for Forbidden, NotFound, etc.
+
+## Testing Coverage
+
+### Test Files
+- **`tests/test_commands_voice.py`**: Comprehensive test suite covering:
+  - VoiceChannelTracker JSON persistence and datetime handling
+  - VoiceChannelCleanupService restart resilience and monitoring
+  - VoiceChannelCommands slash command functionality
+  - Error scenarios and edge cases
+  - Deprecated command migration messages
+
+### Mock Objects
+- Discord guild, channels, roles, and interactions
+- Team service responses and player data
+- Schedule service responses and game data
+- League service current state information
+
+## Integration Points
+
+### Bot Integration
+- **Package Loading**: Integrated into `bot.py` command package loading sequence
+- **Background Tasks**: Cleanup service started in `_setup_background_tasks()`
+- **Shutdown Handling**: Cleanup service stopped in `bot.close()`
+
+### Service Layer
+- **Team Service**: User team verification and ownership lookup
+- **League Service**: Current season/week information retrieval
+- **Schedule Service**: Team schedule and opponent detection
+
+### Discord Integration
+- **Application Commands**: Modern slash command interface with command groups
+- **Permission Overwrites**: Fine-grained voice channel permission control
+- **Embed Templates**: Consistent styling using established embed patterns
+- **Error Handling**: Integration with global application command error handler
+
+## Usage Examples
+
+### Creating Public Channel
+```
+/voice-channel public
+```
+**Result**: Creates "Gameplay [Codename]" with public speaking permissions
+
+### Creating Private Channel
+```
+/voice-channel private
+```
+**Result**: Creates "[Away] vs [Home]" with team-only speaking permissions
+
+### Migration from Old Commands
+```
+!vc
+```
+**Result**: Shows deprecation message suggesting `/voice-channel public`
+
+## Future Enhancements
+
+### Potential Features
+- **Channel Limits**: Per-user or per-team channel creation limits
+- **Custom Names**: Allow users to specify custom channel names
+- **Extended Permissions**: More granular permission control options
+- **Channel Templates**: Predefined setups for different game types
+- **Integration Webhooks**: Notifications when channels are created/deleted
+
+### Configuration Options
+- **Environment Variables**: Make cleanup intervals configurable via env vars
+- **Per-Guild Settings**: Different settings for different Discord servers
+- **Role Mapping**: Custom role name patterns for team permissions
+
+---
+
+**Last Updated**: January 2025
+**Architecture**: Modern async Discord.py with JSON persistence
+**Dependencies**: discord.py, team_service, league_service, schedule_service

commands/voice/__init__.py

@@ -0,0 +1,50 @@
+"""
+Voice Commands Package
+
+This package contains voice channel management commands for gameplay.
+"""
+import logging
+from discord.ext import commands
+
+from .channels import VoiceChannelCommands
+
+logger = logging.getLogger(__name__)
+
+
+async def setup_voice(bot: commands.Bot):
+    """
+    Setup all voice command modules.
+
+    Returns:
+        tuple: (successful_count, failed_count, failed_modules)
+    """
+    # Define all voice command cogs to load
+    voice_cogs = [
+        ("VoiceChannelCommands", VoiceChannelCommands),
+    ]
+
+    successful = 0
+    failed = 0
+    failed_modules = []
+
+    for cog_name, cog_class in voice_cogs:
+        try:
+            await bot.add_cog(cog_class(bot))
+            logger.info(f"✅ Loaded {cog_name}")
+            successful += 1
+        except Exception as e:
+            logger.error(f"❌ Failed to load {cog_name}: {e}", exc_info=True)
+            failed += 1
+            failed_modules.append(cog_name)
+
+    # Log summary
+    if failed == 0:
+        logger.info(f"🎉 All {successful} voice command modules loaded successfully")
+    else:
+        logger.warning(f"⚠️  Voice commands loaded with issues: {successful} successful, {failed} failed")
+
+    return successful, failed, failed_modules
+
+
+# Export the setup function for easy importing
+__all__ = ['setup_voice', 'VoiceChannelCommands']

commands/voice/channels.py

@@ -0,0 +1,348 @@
+"""
+Voice Channel Commands
+
+Implements slash commands for creating and managing voice channels for gameplay.
+"""
+import logging
+import random
+from typing import Optional
+
+import discord
+from discord.ext import commands
+
+from services.team_service import team_service
+from services.schedule_service import ScheduleService
+from services.league_service import league_service
+from utils.logging import get_contextual_logger
+from utils.decorators import logged_command
+from constants import SBA_CURRENT_SEASON
+from views.embeds import EmbedTemplate
+
+logger = logging.getLogger(f'{__name__}.VoiceChannelCommands')
+
+# Random codenames for public channels
+CODENAMES = [
+    "Phoenix", "Thunder", "Lightning", "Storm", "Blaze", "Frost", "Shadow", "Nova",
+    "Viper", "Falcon", "Wolf", "Eagle", "Tiger", "Shark", "Bear", "Dragon",
+    "Alpha", "Beta", "Gamma", "Delta", "Echo", "Foxtrot", "Golf", "Hotel",
+    "Crimson", "Azure", "Emerald", "Golden", "Silver", "Bronze", "Platinum", "Diamond"
+]
+
+
+def random_codename() -> str:
+    """Generate a random codename for public channels."""
+    return random.choice(CODENAMES)
+
+
+class VoiceChannelCommands(commands.Cog):
+    """Voice channel management commands for gameplay."""
+
+    def __init__(self, bot: commands.Bot):
+        self.bot = bot
+        self.logger = get_contextual_logger(f'{__name__}.VoiceChannelCommands')
+        self.schedule_service = ScheduleService()
+
+    # Modern slash command group
+    voice_group = discord.app_commands.Group(
+        name="voice-channel",
+        description="Create voice channels for gameplay"
+    )
+
+    async def _get_user_team(self, user_id: int, season: Optional[int] = None):
+        """
+        Get the user's current team.
+
+        Args:
+            user_id: Discord user ID
+            season: Season to check (defaults to current)
+
+        Returns:
+            Team object or None if not found
+        """
+        season = season or SBA_CURRENT_SEASON
+        teams = await team_service.get_teams_by_owner(user_id, season)
+        return teams[0] if teams else None
+
+    async def _create_tracked_channel(
+        self,
+        interaction: discord.Interaction,
+        channel_name: str,
+        channel_type: str,
+        overwrites: dict
+    ) -> discord.VoiceChannel:
+        """
+        Create a voice channel and add it to tracking.
+
+        Args:
+            interaction: Discord interaction
+            channel_name: Name for the voice channel
+            channel_type: Type of channel ('public' or 'private')
+            overwrites: Permission overwrites for the channel
+
+        Returns:
+            Created Discord voice channel
+        """
+        guild = interaction.guild
+        voice_category = discord.utils.get(guild.categories, name="Voice Channels")
+
+        # Create the voice channel
+        channel = await guild.create_voice_channel(
+            name=channel_name,
+            overwrites=overwrites,
+            category=voice_category
+        )
+
+        # Add to cleanup service tracking
+        if hasattr(self.bot, 'voice_cleanup_service'):
+            cleanup_service = self.bot.voice_cleanup_service  # type: ignore[attr-defined]
+            cleanup_service.tracker.add_channel(channel, channel_type, interaction.user.id)
+        else:
+            self.logger.warning("Voice cleanup service not available, channel won't be tracked")
+
+        return channel
+
+    @voice_group.command(name="public", description="Create a public voice channel")
+    @logged_command("/voice-channel public")
+    async def create_public_channel(self, interaction: discord.Interaction):
+        """Create a public voice channel for gameplay."""
+        await interaction.response.defer()
+
+        # Verify user has a team
+        user_team = await self._get_user_team(interaction.user.id)
+        if not user_team:
+            embed = EmbedTemplate.error(
+                title="No Team Found",
+                description="❌ You must be on a team to create voice channels.\n\n"
+                           "Contact a league administrator if you believe this is an error."
+            )
+            await interaction.followup.send(embed=embed, ephemeral=True)
+            return
+
+        # Create channel with public permissions
+        overwrites = {
+            interaction.guild.default_role: discord.PermissionOverwrite(speak=True, connect=True)
+        }
+
+        channel_name = f"Gameplay {random_codename()}"
+
+        try:
+            channel = await self._create_tracked_channel(
+                interaction, channel_name, "public", overwrites
+            )
+
+            # Get actual cleanup time from service
+            cleanup_minutes = getattr(self.bot, 'voice_cleanup_service', None)
+            cleanup_time = cleanup_minutes.empty_threshold if cleanup_minutes else 15
+
+            embed = EmbedTemplate.success(
+                title="Voice Channel Created",
+                description=f"✅ Created public voice channel {channel.mention}\n\n"
+                           f"**Channel:** {channel.name}\n"
+                           f"**Type:** Public (everyone can speak)\n"
+                           f"**Auto-cleanup:** {cleanup_time} minutes after becoming empty"
+            )
+
+            await interaction.followup.send(embed=embed)
+
+        except discord.Forbidden:
+            embed = EmbedTemplate.error(
+                title="Permission Error",
+                description="❌ I don't have permission to create voice channels.\n\n"
+                           "Please contact a server administrator."
+            )
+            await interaction.followup.send(embed=embed, ephemeral=True)
+        except Exception as e:
+            self.logger.error(f"Error creating public voice channel: {e}")
+            embed = EmbedTemplate.error(
+                title="Creation Failed",
+                description="❌ An error occurred while creating the voice channel.\n\n"
+                           "Please try again or contact support."
+            )
+            await interaction.followup.send(embed=embed, ephemeral=True)
+
+    @voice_group.command(name="private", description="Create a private team vs team voice channel")
+    @logged_command("/voice-channel private")
+    async def create_private_channel(self, interaction: discord.Interaction):
+        """Create a private voice channel for team matchup."""
+        await interaction.response.defer()
+
+        # Verify user has a team
+        user_team = await self._get_user_team(interaction.user.id)
+        if not user_team:
+            embed = EmbedTemplate.error(
+                title="No Team Found",
+                description="❌ You must be on a team to create voice channels.\n\n"
+                           "Contact a league administrator if you believe this is an error."
+            )
+            await interaction.followup.send(embed=embed, ephemeral=True)
+            return
+
+        # Get current league info
+        try:
+            current_info = await league_service.get_current_state()
+            if current_info is None:
+                embed = EmbedTemplate.error(
+                    title="League Info Error",
+                    description="❌ Unable to retrieve current league information.\n\n"
+                               "Please try again later."
+                )
+                await interaction.followup.send(embed=embed, ephemeral=True)
+                return
+
+            current_season = current_info.season
+            current_week = current_info.week
+        except Exception as e:
+            self.logger.error(f"Error getting current league info: {e}")
+            embed = EmbedTemplate.error(
+                title="League Info Error",
+                description="❌ Unable to retrieve current league information.\n\n"
+                           "Please try again later."
+            )
+            await interaction.followup.send(embed=embed, ephemeral=True)
+            return
+
+        # Find opponent from current week's schedule
+        try:
+            team_games = await self.schedule_service.get_team_schedule(
+                current_season, user_team.abbrev, weeks=1
+            )
+
+            current_week_games = [g for g in team_games
+                                 if g.week == current_week and not g.is_completed]
+
+            if not current_week_games:
+                embed = EmbedTemplate.warning(
+                    title="No Games Found",
+                    description=f"❌ No upcoming games found for {user_team.abbrev} in week {current_week}.\n\n"
+                               f"You may be between series or all games for this week are complete."
+                )
+                await interaction.followup.send(embed=embed, ephemeral=True)
+                return
+
+            game = current_week_games[0]  # Use first upcoming game
+            opponent_team = game.away_team if game.home_team.id == user_team.id else game.home_team
+
+        except Exception as e:
+            self.logger.error(f"Error getting team schedule: {e}")
+            embed = EmbedTemplate.error(
+                title="Schedule Error",
+                description="❌ Unable to retrieve your team's schedule.\n\n"
+                           "Please try again later."
+            )
+            await interaction.followup.send(embed=embed, ephemeral=True)
+            return
+
+        # Setup permissions for team roles
+        user_team_role = discord.utils.get(interaction.guild.roles, name=user_team.lname)
+        opponent_team_role = discord.utils.get(interaction.guild.roles, name=opponent_team.lname)
+
+        # Start with default permissions (everyone can connect but not speak)
+        overwrites = {
+            interaction.guild.default_role: discord.PermissionOverwrite(speak=False, connect=True)
+        }
+
+        # Add speaking permissions for team roles
+        team_roles_found = []
+        if user_team_role:
+            overwrites[user_team_role] = discord.PermissionOverwrite(speak=True, connect=True)
+            team_roles_found.append(user_team.lname)
+
+        if opponent_team_role:
+            overwrites[opponent_team_role] = discord.PermissionOverwrite(speak=True, connect=True)
+            team_roles_found.append(opponent_team.lname)
+
+        # Create private channel with team names
+        away_name = game.away_team.sname
+        home_name = game.home_team.sname
+        channel_name = f"{away_name} vs {home_name}"
+
+        try:
+            channel = await self._create_tracked_channel(
+                interaction, channel_name, "private", overwrites
+            )
+
+            # Get actual cleanup time from service
+            cleanup_minutes = getattr(self.bot, 'voice_cleanup_service', None)
+            cleanup_time = cleanup_minutes.empty_threshold if cleanup_minutes else 15
+
+            embed = EmbedTemplate.success(
+                title="Private Voice Channel Created",
+                description=f"✅ Created private voice channel {channel.mention}\n\n"
+                           f"**Matchup:** {away_name} vs {home_name}\n"
+                           f"**Type:** Private (team members only can speak)\n"
+                           f"**Auto-cleanup:** {cleanup_time} minutes after becoming empty"
+            )
+
+            embed.add_field(
+                name="Speaking Permissions",
+                value=f"🎤 **{user_team.abbrev}** - {user_team.lname}\n"
+                      f"🎤 **{opponent_team.abbrev}** - {opponent_team.lname}\n"
+                      f"👂 Everyone else can listen",
+                inline=False
+            )
+
+            if len(team_roles_found) < 2:
+                missing_roles = []
+                if not user_team_role:
+                    missing_roles.append(user_team.lname)
+                if not opponent_team_role:
+                    missing_roles.append(opponent_team.lname)
+
+                embed.add_field(
+                    name="⚠️ Missing Roles",
+                    value=f"Could not find Discord roles for: {', '.join(missing_roles)}\n"
+                          f"These teams may not have speaking permissions.",
+                    inline=False
+                )
+
+            await interaction.followup.send(embed=embed)
+
+        except discord.Forbidden:
+            embed = EmbedTemplate.error(
+                title="Permission Error",
+                description="❌ I don't have permission to create voice channels.\n\n"
+                           "Please contact a server administrator."
+            )
+            await interaction.followup.send(embed=embed, ephemeral=True)
+        except Exception as e:
+            self.logger.error(f"Error creating private voice channel: {e}")
+            embed = EmbedTemplate.error(
+                title="Creation Failed",
+                description="❌ An error occurred while creating the voice channel.\n\n"
+                           "Please try again or contact support."
+            )
+            await interaction.followup.send(embed=embed, ephemeral=True)
+
+    # Deprecated prefix commands with migration messages
+    @commands.command(name="vc", aliases=["voice", "gameplay"])
+    async def deprecated_public_voice(self, ctx: commands.Context):
+        """Deprecated command - redirect to new slash command."""
+        embed = EmbedTemplate.info(
+            title="📢 Command Deprecated",
+            description=(
+                "The `!vc` command has been deprecated.\n\n"
+                "**Please use:** `/voice-channel public` for your voice channel needs.\n\n"
+                "The new slash commands provide better functionality and organization!"
+            )
+        )
+        embed.set_footer(text="💡 Tip: Type /voice-channel and see the available options!")
+        await ctx.send(embed=embed)
+
+    @commands.command(name="private")
+    async def deprecated_private_voice(self, ctx: commands.Context):
+        """Deprecated command - redirect to new slash command."""
+        embed = EmbedTemplate.info(
+            title="📢 Command Deprecated",
+            description=(
+                "The `!private` command has been deprecated.\n\n"
+                "**Please use:** `/voice-channel private` for your private team channel needs.\n\n"
+                "The new slash commands provide better functionality and organization!"
+            )
+        )
+        embed.set_footer(text="💡 Tip: Type /voice-channel and see the available options!")
+        await ctx.send(embed=embed)
+
+
+async def setup(bot: commands.Bot):
+    """Load the voice channel commands cog."""
+    await bot.add_cog(VoiceChannelCommands(bot))

commands/voice/cleanup_service.py

@@ -0,0 +1,275 @@
+"""
+Voice Channel Cleanup Service
+
+Provides automatic cleanup of empty voice channels with restart resilience.
+"""
+import asyncio
+import logging
+
+import discord
+from discord.ext import commands
+
+from .tracker import VoiceChannelTracker
+
+logger = logging.getLogger(f'{__name__}.VoiceChannelCleanupService')
+
+
+class VoiceChannelCleanupService:
+    """
+    Manages automatic cleanup of bot-created voice channels.
+
+    Features:
+    - Restart-resilient channel tracking
+    - Automatic empty channel cleanup
+    - Configurable cleanup intervals and thresholds
+    - Stale entry removal and recovery
+    """
+
+    def __init__(self, data_file: str = "data/voice_channels.json"):
+        """
+        Initialize the cleanup service.
+
+        Args:
+            data_file: Path to the JSON data file for persistence
+        """
+        self.tracker = VoiceChannelTracker(data_file)
+        self.cleanup_interval = 60   # 5 minutes check interval
+        self.empty_threshold = 5    # Delete after 15 minutes empty
+        self._running = False
+
+    async def start_monitoring(self, bot: commands.Bot) -> None:
+        """
+        Start the cleanup monitoring loop.
+
+        Args:
+            bot: Discord bot instance
+        """
+        if self._running:
+            logger.warning("Cleanup service is already running")
+            return
+
+        self._running = True
+        logger.info("Starting voice channel cleanup service")
+
+        # On startup, verify tracked channels still exist and clean up stale entries
+        await self.verify_tracked_channels(bot)
+
+        # Start the monitoring loop
+        while self._running:
+            try:
+                await self.cleanup_cycle(bot)
+                await asyncio.sleep(self.cleanup_interval)
+            except Exception as e:
+                logger.error(f"Cleanup cycle error: {e}", exc_info=True)
+                # Use shorter retry interval on errors
+                await asyncio.sleep(60)
+
+        logger.info("Voice channel cleanup service stopped")
+
+    def stop_monitoring(self) -> None:
+        """Stop the cleanup monitoring loop."""
+        self._running = False
+        logger.info("Stopping voice channel cleanup service")
+
+    async def verify_tracked_channels(self, bot: commands.Bot) -> None:
+        """
+        Verify tracked channels still exist and clean up stale entries.
+
+        Args:
+            bot: Discord bot instance
+        """
+        logger.info("Verifying tracked voice channels on startup")
+
+        valid_channel_ids = []
+        channels_to_remove = []
+
+        for channel_data in self.tracker.get_all_tracked_channels():
+            try:
+                guild_id = int(channel_data["guild_id"])
+                channel_id = int(channel_data["channel_id"])
+
+                guild = bot.get_guild(guild_id)
+                if not guild:
+                    logger.warning(f"Guild {guild_id} not found, removing channel {channel_data['name']}")
+                    channels_to_remove.append(channel_id)
+                    continue
+
+                channel = guild.get_channel(channel_id)
+                if not channel:
+                    logger.warning(f"Channel {channel_data['name']} (ID: {channel_id}) no longer exists")
+                    channels_to_remove.append(channel_id)
+                    continue
+
+                # Channel exists and is valid
+                valid_channel_ids.append(channel_id)
+
+            except (ValueError, TypeError, KeyError) as e:
+                logger.warning(f"Invalid channel data: {e}, removing entry")
+                if "channel_id" in channel_data:
+                    try:
+                        channels_to_remove.append(int(channel_data["channel_id"]))
+                    except (ValueError, TypeError):
+                        pass
+
+        # Remove stale entries
+        for channel_id in channels_to_remove:
+            self.tracker.remove_channel(channel_id)
+
+        # Also clean up any additional stale entries
+        stale_removed = self.tracker.cleanup_stale_entries(valid_channel_ids)
+        total_removed = len(channels_to_remove) + stale_removed
+
+        if total_removed > 0:
+            logger.info(f"Cleaned up {total_removed} stale channel tracking entries")
+
+        logger.info(f"Verified {len(valid_channel_ids)} valid tracked channels")
+
+    async def cleanup_cycle(self, bot: commands.Bot) -> None:
+        """
+        Check all tracked channels and cleanup empty ones.
+
+        Args:
+            bot: Discord bot instance
+        """
+        logger.debug("Starting cleanup cycle")
+
+        # Update status of all tracked channels
+        await self.update_all_channel_statuses(bot)
+
+        # Get channels ready for cleanup
+        channels_for_cleanup = self.tracker.get_channels_for_cleanup(self.empty_threshold)
+
+        if channels_for_cleanup:
+            logger.info(f"Found {len(channels_for_cleanup)} channels ready for cleanup")
+
+        # Delete empty channels
+        for channel_data in channels_for_cleanup:
+            await self.cleanup_channel(bot, channel_data)
+
+    async def update_all_channel_statuses(self, bot: commands.Bot) -> None:
+        """
+        Update the empty status of all tracked channels.
+
+        Args:
+            bot: Discord bot instance
+        """
+        for channel_data in self.tracker.get_all_tracked_channels():
+            await self.check_channel_status(bot, channel_data)
+
+    async def check_channel_status(self, bot: commands.Bot, channel_data: dict) -> None:
+        """
+        Check if a channel is empty and update tracking.
+
+        Args:
+            bot: Discord bot instance
+            channel_data: Channel tracking data
+        """
+        try:
+            guild_id = int(channel_data["guild_id"])
+            channel_id = int(channel_data["channel_id"])
+
+            guild = bot.get_guild(guild_id)
+            if not guild:
+                logger.debug(f"Guild {guild_id} not found for channel {channel_data['name']}")
+                return
+
+            channel = guild.get_channel(channel_id)
+            if not channel:
+                logger.debug(f"Channel {channel_data['name']} no longer exists, will be cleaned up")
+                self.tracker.remove_channel(channel_id)
+                return
+
+            # Ensure it's a voice channel before checking members
+            if not isinstance(channel, discord.VoiceChannel):
+                logger.warning(f"Channel {channel_data['name']} is not a voice channel, removing from tracking")
+                self.tracker.remove_channel(channel_id)
+                return
+
+            # Check if channel is empty
+            is_empty = len(channel.members) == 0
+            self.tracker.update_channel_status(channel_id, is_empty)
+
+            logger.debug(f"Channel {channel_data['name']}: {'empty' if is_empty else 'occupied'} "
+                        f"({len(channel.members)} members)")
+
+        except Exception as e:
+            logger.error(f"Error checking channel status for {channel_data.get('name', 'unknown')}: {e}")
+
+    async def cleanup_channel(self, bot: commands.Bot, channel_data: dict) -> None:
+        """
+        Delete an empty channel and remove from tracking.
+
+        Args:
+            bot: Discord bot instance
+            channel_data: Channel tracking data
+        """
+        try:
+            guild_id = int(channel_data["guild_id"])
+            channel_id = int(channel_data["channel_id"])
+            channel_name = channel_data["name"]
+
+            guild = bot.get_guild(guild_id)
+            if not guild:
+                logger.info(f"Guild {guild_id} not found, removing tracking for {channel_name}")
+                self.tracker.remove_channel(channel_id)
+                return
+
+            channel = guild.get_channel(channel_id)
+            if not channel:
+                logger.info(f"Channel {channel_name} already deleted, removing from tracking")
+                self.tracker.remove_channel(channel_id)
+                return
+
+            # Ensure it's a voice channel before checking members
+            if not isinstance(channel, discord.VoiceChannel):
+                logger.warning(f"Channel {channel_name} is not a voice channel, removing from tracking")
+                self.tracker.remove_channel(channel_id)
+                return
+
+            # Final check: make sure channel is still empty before deleting
+            if len(channel.members) > 0:
+                logger.info(f"Channel {channel_name} is no longer empty, skipping cleanup")
+                self.tracker.update_channel_status(channel_id, False)
+                return
+
+            # Delete the channel
+            await channel.delete(reason="Automatic cleanup - empty for 15+ minutes")
+            self.tracker.remove_channel(channel_id)
+
+            logger.info(f"✅ Cleaned up empty voice channel: {channel_name} (ID: {channel_id})")
+
+        except discord.NotFound:
+            # Channel was already deleted
+            logger.info(f"Channel {channel_data.get('name', 'unknown')} was already deleted")
+            self.tracker.remove_channel(int(channel_data["channel_id"]))
+        except discord.Forbidden:
+            logger.error(f"Missing permissions to delete channel {channel_data.get('name', 'unknown')}")
+        except Exception as e:
+            logger.error(f"Error cleaning up channel {channel_data.get('name', 'unknown')}: {e}")
+
+    def get_tracker(self) -> VoiceChannelTracker:
+        """
+        Get the voice channel tracker instance.
+
+        Returns:
+            VoiceChannelTracker instance
+        """
+        return self.tracker
+
+    def get_stats(self) -> dict:
+        """
+        Get cleanup service statistics.
+
+        Returns:
+            Dictionary with service statistics
+        """
+        all_channels = self.tracker.get_all_tracked_channels()
+        empty_channels = [ch for ch in all_channels if ch.get("empty_since")]
+
+        return {
+            "running": self._running,
+            "total_tracked": len(all_channels),
+            "empty_channels": len(empty_channels),
+            "cleanup_interval": self.cleanup_interval,
+            "empty_threshold": self.empty_threshold
+        }

commands/voice/tracker.py

@@ -0,0 +1,222 @@
+"""
+Voice Channel Tracker
+
+Provides persistent tracking of bot-created voice channels using JSON file storage.
+"""
+import json
+import logging
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+
+import discord
+
+logger = logging.getLogger(f'{__name__}.VoiceChannelTracker')
+
+
+class VoiceChannelTracker:
+    """
+    Tracks bot-created voice channels with JSON file persistence.
+
+    Features:
+    - Persistent storage across bot restarts
+    - Channel creation and status tracking
+    - Cleanup candidate identification
+    - Automatic stale entry removal
+    """
+
+    def __init__(self, data_file: str = "data/voice_channels.json"):
+        """
+        Initialize the voice channel tracker.
+
+        Args:
+            data_file: Path to the JSON data file
+        """
+        self.data_file = Path(data_file)
+        self.data_file.parent.mkdir(exist_ok=True)
+        self._data: Dict[str, Any] = {}
+        self.load_data()
+
+    def load_data(self) -> None:
+        """Load channel data from JSON file."""
+        try:
+            if self.data_file.exists():
+                with open(self.data_file, 'r') as f:
+                    self._data = json.load(f)
+                    logger.debug(f"Loaded {len(self._data.get('voice_channels', {}))} tracked channels")
+            else:
+                self._data = {"voice_channels": {}}
+                logger.info("No existing voice channel data found, starting fresh")
+        except Exception as e:
+            logger.error(f"Failed to load voice channel data: {e}")
+            self._data = {"voice_channels": {}}
+
+    def save_data(self) -> None:
+        """Save channel data to JSON file."""
+        try:
+            with open(self.data_file, 'w') as f:
+                json.dump(self._data, f, indent=2, default=str)
+            logger.debug("Voice channel data saved successfully")
+        except Exception as e:
+            logger.error(f"Failed to save voice channel data: {e}")
+
+    def add_channel(
+        self,
+        channel: discord.VoiceChannel,
+        channel_type: str,
+        creator_id: int
+    ) -> None:
+        """
+        Add a new channel to tracking.
+
+        Args:
+            channel: Discord voice channel object
+            channel_type: Type of channel ('public' or 'private')
+            creator_id: Discord user ID who created the channel
+        """
+        self._data.setdefault("voice_channels", {})[str(channel.id)] = {
+            "channel_id": str(channel.id),
+            "guild_id": str(channel.guild.id),
+            "name": channel.name,
+            "type": channel_type,
+            "created_at": datetime.utcnow().isoformat(),
+            "last_checked": datetime.utcnow().isoformat(),
+            "empty_since": None,
+            "creator_id": str(creator_id)
+        }
+        self.save_data()
+        logger.info(f"Added channel to tracking: {channel.name} (ID: {channel.id})")
+
+    def update_channel_status(self, channel_id: int, is_empty: bool) -> None:
+        """
+        Update channel empty status.
+
+        Args:
+            channel_id: Discord channel ID
+            is_empty: Whether the channel is currently empty
+        """
+        channels = self._data.get("voice_channels", {})
+        channel_key = str(channel_id)
+
+        if channel_key in channels:
+            channel_data = channels[channel_key]
+            channel_data["last_checked"] = datetime.utcnow().isoformat()
+
+            if is_empty and channel_data["empty_since"] is None:
+                # Channel just became empty
+                channel_data["empty_since"] = datetime.utcnow().isoformat()
+                logger.debug(f"Channel {channel_data['name']} became empty")
+            elif not is_empty and channel_data["empty_since"] is not None:
+                # Channel is no longer empty
+                channel_data["empty_since"] = None
+                logger.debug(f"Channel {channel_data['name']} is no longer empty")
+
+            self.save_data()
+
+    def remove_channel(self, channel_id: int) -> None:
+        """
+        Remove channel from tracking.
+
+        Args:
+            channel_id: Discord channel ID
+        """
+        channels = self._data.get("voice_channels", {})
+        channel_key = str(channel_id)
+
+        if channel_key in channels:
+            channel_name = channels[channel_key]["name"]
+            del channels[channel_key]
+            self.save_data()
+            logger.info(f"Removed channel from tracking: {channel_name} (ID: {channel_id})")
+
+    def get_channels_for_cleanup(self, empty_threshold_minutes: int = 15) -> List[Dict[str, Any]]:
+        """
+        Get channels that should be deleted based on empty duration.
+
+        Args:
+            empty_threshold_minutes: Minutes a channel must be empty before cleanup
+
+        Returns:
+            List of channel data dictionaries ready for cleanup
+        """
+        cleanup_candidates = []
+        cutoff_time = datetime.utcnow() - timedelta(minutes=empty_threshold_minutes)
+
+        for channel_data in self._data.get("voice_channels", {}).values():
+            if channel_data["empty_since"]:
+                try:
+                    # Parse empty_since timestamp
+                    empty_since_str = channel_data["empty_since"]
+                    # Handle both with and without timezone info
+                    if empty_since_str.endswith('Z'):
+                        empty_since_str = empty_since_str[:-1] + '+00:00'
+
+                    empty_since = datetime.fromisoformat(empty_since_str.replace('Z', '+00:00'))
+
+                    # Remove timezone info for comparison (both times are UTC)
+                    if empty_since.tzinfo:
+                        empty_since = empty_since.replace(tzinfo=None)
+
+                    if empty_since <= cutoff_time:
+                        cleanup_candidates.append(channel_data)
+                        logger.debug(f"Channel {channel_data['name']} ready for cleanup (empty since {empty_since})")
+
+                except (ValueError, TypeError) as e:
+                    logger.warning(f"Invalid timestamp for channel {channel_data.get('name', 'unknown')}: {e}")
+
+        return cleanup_candidates
+
+    def get_all_tracked_channels(self) -> List[Dict[str, Any]]:
+        """
+        Get all currently tracked channels.
+
+        Returns:
+            List of all tracked channel data dictionaries
+        """
+        return list(self._data.get("voice_channels", {}).values())
+
+    def get_tracked_channel(self, channel_id: int) -> Optional[Dict[str, Any]]:
+        """
+        Get data for a specific tracked channel.
+
+        Args:
+            channel_id: Discord channel ID
+
+        Returns:
+            Channel data dictionary or None if not tracked
+        """
+        channels = self._data.get("voice_channels", {})
+        return channels.get(str(channel_id))
+
+    def cleanup_stale_entries(self, valid_channel_ids: List[int]) -> int:
+        """
+        Remove tracking entries for channels that no longer exist.
+
+        Args:
+            valid_channel_ids: List of channel IDs that still exist in Discord
+
+        Returns:
+            Number of stale entries removed
+        """
+        channels = self._data.get("voice_channels", {})
+        stale_entries = []
+
+        for channel_id_str, channel_data in channels.items():
+            try:
+                channel_id = int(channel_id_str)
+                if channel_id not in valid_channel_ids:
+                    stale_entries.append(channel_id_str)
+            except (ValueError, TypeError):
+                logger.warning(f"Invalid channel ID in tracking data: {channel_id_str}")
+                stale_entries.append(channel_id_str)
+
+        # Remove stale entries
+        for channel_id_str in stale_entries:
+            channel_name = channels[channel_id_str].get("name", "unknown")
+            del channels[channel_id_str]
+            logger.info(f"Removed stale tracking entry: {channel_name} (ID: {channel_id_str})")
+
+        if stale_entries:
+            self.save_data()
+
+        return len(stale_entries)

models/README.md

@@ -0,0 +1,325 @@
+# Models Directory
+
+The models directory contains Pydantic data models for Discord Bot v2.0, providing type-safe representations of all SBA (Strat-o-Matic Baseball Association) entities. All models inherit from `SBABaseModel` and follow consistent validation patterns.
+
+## Architecture
+
+### Pydantic Foundation
+All models use Pydantic v2 with:
+- **Automatic validation** of field types and constraints
+- **Serialization/deserialization** for API interactions
+- **Type safety** with full IDE support
+- **JSON schema generation** for documentation
+- **Field validation** with custom validators
+
+### Base Model (`base.py`)
+The foundation for all SBA models:
+
+```python
+class SBABaseModel(BaseModel):
+    model_config = {
+        "validate_assignment": True,
+        "use_enum_values": True,
+        "arbitrary_types_allowed": True,
+        "json_encoders": {datetime: lambda v: v.isoformat() if v else None}
+    }
+
+    id: Optional[int] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+```
+
+### Breaking Changes (August 2025)
+**Database entities now require `id` fields** since they're always fetched from the database:
+- `Player` model: `id: int = Field(..., description="Player ID from database")`
+- `Team` model: `id: int = Field(..., description="Team ID from database")`
+
+## Model Categories
+
+### Core Entities
+
+#### League Structure
+- **`team.py`** - Team information, abbreviations, divisions
+- **`division.py`** - Division structure and organization
+- **`manager.py`** - Team managers and ownership
+- **`standings.py`** - Team standings and rankings
+
+#### Player Data
+- **`player.py`** - Core player information and identifiers
+- **`sbaplayer.py`** - Extended SBA-specific player data
+- **`batting_stats.py`** - Batting statistics and performance metrics
+- **`pitching_stats.py`** - Pitching statistics and performance metrics
+- **`roster.py`** - Team roster assignments and positions
+
+#### Game Operations
+- **`game.py`** - Individual game results and scheduling
+- **`transaction.py`** - Player transactions (trades, waivers, etc.)
+
+#### Draft System
+- **`draft_pick.py`** - Individual draft pick information
+- **`draft_data.py`** - Draft round and selection data
+- **`draft_list.py`** - Complete draft lists and results
+
+#### Custom Features
+- **`custom_command.py`** - User-created Discord commands
+
+### Legacy Models
+- **`current.py`** - Legacy model definitions for backward compatibility
+
+## Model Validation Patterns
+
+### Required Fields
+Models distinguish between required and optional fields:
+
+```python
+class Player(SBABaseModel):
+    id: int = Field(..., description="Player ID from database")  # Required
+    name: str = Field(..., description="Player full name")        # Required
+    team_id: Optional[int] = None                                  # Optional
+    position: Optional[str] = None                                 # Optional
+```
+
+### Field Constraints
+Models use Pydantic validators for data integrity:
+
+```python
+class BattingStats(SBABaseModel):
+    at_bats: int = Field(ge=0, description="At bats (non-negative)")
+    hits: int = Field(ge=0, le=Field('at_bats'), description="Hits (cannot exceed at_bats)")
+
+    @field_validator('batting_average')
+    @classmethod
+    def validate_batting_average(cls, v):
+        if v is not None and not 0.0 <= v <= 1.0:
+            raise ValueError('Batting average must be between 0.0 and 1.0')
+        return v
+```
+
+### Custom Validators
+Models implement business logic validation:
+
+```python
+class Transaction(SBABaseModel):
+    transaction_type: str
+    player_id: int
+    from_team_id: Optional[int] = None
+    to_team_id: Optional[int] = None
+
+    @model_validator(mode='after')
+    def validate_team_requirements(self):
+        if self.transaction_type == 'trade':
+            if not self.from_team_id or not self.to_team_id:
+                raise ValueError('Trade transactions require both from_team_id and to_team_id')
+        return self
+```
+
+## API Integration
+
+### Data Transformation
+Models provide methods for API interaction:
+
+```python
+class Player(SBABaseModel):
+    @classmethod
+    def from_api_data(cls, data: Dict[str, Any]):
+        """Create model instance from API response data."""
+        if not data:
+            raise ValueError(f"Cannot create {cls.__name__} from empty data")
+        return cls(**data)
+
+    def to_dict(self, exclude_none: bool = True) -> Dict[str, Any]:
+        """Convert model to dictionary for API requests."""
+        return self.model_dump(exclude_none=exclude_none)
+```
+
+### Serialization Examples
+Models handle various data formats:
+
+```python
+# From API JSON
+player_data = {"id": 123, "name": "Player Name", "team_id": 5}
+player = Player.from_api_data(player_data)
+
+# To API JSON
+api_payload = player.to_dict(exclude_none=True)
+
+# JSON string serialization
+json_string = player.model_dump_json()
+
+# From JSON string
+player_copy = Player.model_validate_json(json_string)
+```
+
+## Testing Requirements
+
+### Model Validation Testing
+All model tests must provide complete data:
+
+```python
+def test_player_creation():
+    # ✅ Correct - provides required ID field
+    player = Player(
+        id=123,
+        name="Test Player",
+        team_id=5,
+        position="1B"
+    )
+    assert player.id == 123
+
+def test_incomplete_data():
+    # ❌ This will fail - missing required ID
+    with pytest.raises(ValidationError):
+        Player(name="Test Player")  # Missing required id field
+```
+
+### Test Data Patterns
+Use helper functions for consistent test data:
+
+```python
+def create_test_player(**overrides) -> Player:
+    """Create a test player with default values."""
+    defaults = {
+        "id": 123,
+        "name": "Test Player",
+        "team_id": 1,
+        "position": "1B"
+    }
+    defaults.update(overrides)
+    return Player(**defaults)
+
+def test_player_with_stats():
+    player = create_test_player(name="Star Player")
+    assert player.name == "Star Player"
+    assert player.id == 123  # Default from helper
+```
+
+## Field Types and Constraints
+
+### Common Field Patterns
+
+#### Identifiers
+```python
+id: int = Field(..., description="Database primary key")
+player_id: int = Field(..., description="Foreign key to player")
+team_id: Optional[int] = Field(None, description="Foreign key to team")
+```
+
+#### Names and Text
+```python
+name: str = Field(..., min_length=1, max_length=100)
+abbreviation: str = Field(..., min_length=2, max_length=5)
+description: Optional[str] = Field(None, max_length=500)
+```
+
+#### Statistics
+```python
+games_played: int = Field(ge=0, description="Games played (non-negative)")
+batting_average: Optional[float] = Field(None, ge=0.0, le=1.0)
+era: Optional[float] = Field(None, ge=0.0, description="Earned run average")
+```
+
+#### Dates and Times
+```python
+game_date: Optional[datetime] = None
+created_at: Optional[datetime] = None
+season_year: int = Field(..., ge=1900, le=2100)
+```
+
+## Model Relationships
+
+### Foreign Key Patterns
+Models reference related entities via ID fields:
+
+```python
+class Player(SBABaseModel):
+    id: int
+    team_id: Optional[int] = None  # References Team.id
+
+class BattingStats(SBABaseModel):
+    player_id: int  # References Player.id
+    season: int
+    team_id: int    # References Team.id
+```
+
+### Nested Objects
+Some models contain nested structures:
+
+```python
+class CustomCommand(SBABaseModel):
+    name: str
+    creator: Manager  # Nested Manager object
+    response: str
+
+class DraftPick(SBABaseModel):
+    pick_number: int
+    player: Optional[Player] = None  # Optional nested Player
+    team: Team                       # Required nested Team
+```
+
+## Validation Error Handling
+
+### Common Validation Errors
+- **Missing required fields** - Provide all required model fields
+- **Type mismatches** - Ensure field types match model definitions
+- **Constraint violations** - Check field validators and constraints
+- **Invalid nested objects** - Validate all nested model data
+
+### Error Examples
+```python
+try:
+    player = Player(name="Test")  # Missing required id
+except ValidationError as e:
+    print(e.errors())
+    # [{'type': 'missing', 'loc': ('id',), 'msg': 'Field required'}]
+
+try:
+    stats = BattingStats(hits=5, at_bats=3)  # hits > at_bats
+except ValidationError as e:
+    print(e.errors())
+    # Constraint violation error
+```
+
+## Performance Considerations
+
+### Model Instantiation
+- Use `model_validate()` for external data
+- Use `model_construct()` for trusted internal data (faster)
+- Cache model instances when possible
+- Avoid repeated validation of the same data
+
+### Memory Usage
+- Models are relatively lightweight
+- Nested objects can increase memory footprint
+- Consider using `__slots__` for high-volume models
+- Use `exclude_none=True` to reduce serialization size
+
+## Development Guidelines
+
+### Adding New Models
+1. **Inherit from SBABaseModel** for consistency
+2. **Define required fields explicitly** with proper types
+3. **Add field descriptions** for documentation
+4. **Include validation rules** for data integrity
+5. **Provide `from_api_data()` class method** if needed
+6. **Write comprehensive tests** covering edge cases
+
+### Model Evolution
+- **Backward compatibility** - Add optional fields for new features
+- **Migration patterns** - Handle schema changes gracefully
+- **Version management** - Document breaking changes
+- **API alignment** - Keep models synchronized with API
+
+### Testing Strategy
+- **Unit tests** for individual model validation
+- **Integration tests** with service layer
+- **Edge case testing** for validation rules
+- **Performance tests** for large data sets
+
+---
+
+**Next Steps for AI Agents:**
+1. Review existing model implementations for patterns
+2. Understand the validation rules and field constraints
+3. Check the service layer integration in `/services`
+4. Follow the testing patterns with complete model data
+5. Consider the API data format when creating new models

services/README.md

@@ -0,0 +1,190 @@
+# Services Directory
+
+The services directory contains the service layer for Discord Bot v2.0, providing clean abstractions for API interactions and business logic. All services inherit from `BaseService` and follow consistent patterns for data operations.
+
+## Architecture
+
+### Service Layer Pattern
+Services act as the interface between Discord commands and the external API, providing:
+- **Data validation** using Pydantic models
+- **Error handling** with consistent exception patterns
+- **Caching support** via Redis decorators
+- **Type safety** with generic TypeVar support
+- **Logging integration** with structured logging
+
+### Base Service (`base_service.py`)
+The foundation for all services, providing:
+- **Generic CRUD operations** (Create, Read, Update, Delete)
+- **API client management** with connection pooling
+- **Response format handling** for API responses
+- **Cache key generation** and management
+- **Error handling** with APIException wrapping
+
+```python
+class BaseService(Generic[T]):
+    def __init__(self, model_class: Type[T], endpoint: str)
+    async def get_by_id(self, object_id: int) -> Optional[T]
+    async def get_all(self, params: Optional[List[tuple]] = None) -> Tuple[List[T], int]
+    async def create(self, model_data: Dict[str, Any]) -> Optional[T]
+    async def update(self, object_id: int, model_data: Dict[str, Any]) -> Optional[T]
+    async def delete(self, object_id: int) -> bool
+```
+
+## Service Files
+
+### Core Entity Services
+- **`player_service.py`** - Player data operations and search functionality
+- **`team_service.py`** - Team information and roster management
+- **`league_service.py`** - League-wide data and current season info
+- **`standings_service.py`** - Team standings and division rankings
+- **`schedule_service.py`** - Game scheduling and results
+- **`stats_service.py`** - Player statistics (batting, pitching, fielding)
+- **`roster_service.py`** - Team roster composition and position assignments
+
+### Transaction Services
+- **`transaction_service.py`** - Player transaction operations (trades, waivers, etc.)
+- **`transaction_builder.py`** - Complex transaction building and validation
+
+### Custom Features
+- **`custom_commands_service.py`** - User-created custom Discord commands
+
+## Caching Integration
+
+Services support optional Redis caching via decorators:
+
+```python
+from utils.decorators import cached_api_call, cached_single_item
+
+class PlayerService(BaseService[Player]):
+    @cached_api_call(ttl=600)  # Cache for 10 minutes
+    async def get_players_by_team(self, team_id: int, season: int) -> List[Player]:
+        return await self.get_all_items(params=[('team_id', team_id), ('season', season)])
+
+    @cached_single_item(ttl=300)  # Cache for 5 minutes
+    async def get_player_by_name(self, name: str) -> Optional[Player]:
+        players = await self.get_by_field('name', name)
+        return players[0] if players else None
+```
+
+### Caching Features
+- **Graceful degradation** - Works without Redis
+- **Automatic key generation** based on method parameters
+- **TTL support** with configurable expiration
+- **Cache invalidation** patterns for data updates
+
+## Error Handling
+
+All services use consistent error handling:
+
+```python
+try:
+    result = await some_service.get_data()
+    return result
+except APIException as e:
+    logger.error("API error occurred", error=e)
+    raise  # Re-raise for command handlers
+except Exception as e:
+    logger.error("Unexpected error", error=e)
+    raise APIException(f"Service operation failed: {e}")
+```
+
+### Exception Types
+- **`APIException`** - API communication errors
+- **`ValueError`** - Data validation errors
+- **`ConnectionError`** - Network connectivity issues
+
+## Usage Patterns
+
+### Service Initialization
+Services are typically initialized once and reused:
+
+```python
+# In services/__init__.py
+from .player_service import PlayerService
+from models.player import Player
+
+player_service = PlayerService(Player, 'players')
+```
+
+### Command Integration
+Services integrate with Discord commands via the `@logged_command` decorator:
+
+```python
+@discord.app_commands.command(name="player")
+@logged_command("/player")
+async def player_info(self, interaction: discord.Interaction, name: str):
+    player = await player_service.get_player_by_name(name)
+    if not player:
+        await interaction.followup.send("Player not found")
+        return
+
+    embed = create_player_embed(player)
+    await interaction.followup.send(embed=embed)
+```
+
+## API Response Format
+
+Services handle the standard API response format:
+```json
+{
+  "count": 150,
+  "players": [
+    {"id": 1, "name": "Player Name", ...},
+    {"id": 2, "name": "Another Player", ...}
+  ]
+}
+```
+
+The `BaseService._extract_items_and_count_from_response()` method automatically parses this format and returns typed model instances.
+
+## Development Guidelines
+
+### Adding New Services
+1. **Inherit from BaseService** with appropriate model type
+2. **Define specific business methods** beyond CRUD operations
+3. **Add caching decorators** for expensive operations
+4. **Include comprehensive logging** with structured context
+5. **Handle edge cases** and provide meaningful error messages
+
+### Service Method Patterns
+- **Query methods** should return `List[T]` or `Optional[T]`
+- **Mutation methods** should return the updated model or `None`
+- **Search methods** should accept flexible parameters
+- **Bulk operations** should handle batching efficiently
+
+### Testing Services
+- Use `aioresponses` for HTTP client mocking
+- Test both success and error scenarios
+- Validate model parsing and transformation
+- Verify caching behavior when Redis is available
+
+## Environment Integration
+
+Services respect environment configuration:
+- **`DB_URL`** - Database API endpoint
+- **`API_TOKEN`** - Authentication token
+- **`REDIS_URL`** - Optional caching backend
+- **`LOG_LEVEL`** - Logging verbosity
+
+## Performance Considerations
+
+### Optimization Strategies
+- **Connection pooling** via global API client
+- **Response caching** for frequently accessed data
+- **Batch operations** for bulk data processing
+- **Lazy loading** for expensive computations
+
+### Monitoring
+- All operations are logged with timing information
+- Cache hit/miss ratios are tracked
+- API error rates are monitored
+- Service response times are measured
+
+---
+
+**Next Steps for AI Agents:**
+1. Review existing service implementations for patterns
+2. Check the corresponding model definitions in `/models`
+3. Understand the caching decorators in `/utils/decorators.py`
+4. Follow the error handling patterns established in `BaseService`
+5. Use structured logging with contextual information

tasks/README.md

@@ -0,0 +1,364 @@
+# Tasks Directory
+
+The tasks directory contains automated background tasks for Discord Bot v2.0. These tasks handle periodic maintenance, data cleanup, and scheduled operations that run independently of user interactions.
+
+## Architecture
+
+### Task System Design
+Tasks in Discord Bot v2.0 follow these patterns:
+- **Discord.py tasks** using the `@tasks.loop` decorator
+- **Structured logging** with contextual information
+- **Error handling** with graceful degradation
+- **Guild-specific operations** respecting bot permissions
+- **Configurable intervals** via task decorators
+
+### Base Task Pattern
+All tasks follow a consistent structure:
+
+```python
+from discord.ext import tasks
+from utils.logging import get_contextual_logger
+
+class ExampleTask:
+    def __init__(self, bot: commands.Bot):
+        self.bot = bot
+        self.logger = get_contextual_logger(f'{__name__}.ExampleTask')
+        self.task_loop.start()
+
+    def cog_unload(self):
+        """Stop the task when cog is unloaded."""
+        self.task_loop.cancel()
+
+    @tasks.loop(hours=24)  # Run daily
+    async def task_loop(self):
+        """Main task implementation."""
+        try:
+            # Task logic here
+            pass
+        except Exception as e:
+            self.logger.error("Task failed", error=e)
+
+    @task_loop.before_loop
+    async def before_task(self):
+        """Wait for bot to be ready before starting."""
+        await self.bot.wait_until_ready()
+```
+
+## Current Tasks
+
+### Custom Command Cleanup (`custom_command_cleanup.py`)
+**Purpose:** Automated cleanup system for user-created custom commands
+
+**Schedule:** Daily (24 hours)
+
+**Operations:**
+- **Warning Phase:** Notifies users about commands at risk (unused for 60+ days)
+- **Deletion Phase:** Removes commands unused for 90+ days
+- **Admin Reporting:** Sends cleanup summaries to admin channels
+
+#### Key Features
+- **User Notifications:** Direct messages to command creators
+- **Grace Period:** 30-day warning before deletion
+- **Admin Transparency:** Optional summary reports
+- **Bulk Operations:** Efficient batch processing
+- **Error Resilience:** Continues operation despite individual failures
+
+#### Configuration
+The cleanup task respects guild settings and permissions:
+
+```python
+# Configuration via get_config()
+guild_id = config.guild_id          # Target guild
+admin_channels = ['admin', 'bot-logs']  # Admin notification channels
+```
+
+#### Notification System
+**Warning Embed (30 days before deletion):**
+- Lists commands at risk
+- Shows days since last use
+- Provides usage instructions
+- Links to command management
+
+**Deletion Embed (after deletion):**
+- Lists deleted commands
+- Shows final usage statistics
+- Provides recreation instructions
+- Explains cleanup policy
+
+#### Admin Summary
+Optional admin channel reporting includes:
+- Number of warnings sent
+- Number of commands deleted
+- Current system statistics
+- Next cleanup schedule
+
+## Task Lifecycle
+
+### Initialization
+Tasks are initialized when the bot starts:
+
+```python
+# In bot startup
+def setup_cleanup_task(bot: commands.Bot) -> CustomCommandCleanupTask:
+    return CustomCommandCleanupTask(bot)
+
+# Usage
+cleanup_task = setup_cleanup_task(bot)
+```
+
+### Execution Flow
+1. **Bot Ready Check:** Wait for `bot.wait_until_ready()`
+2. **Guild Validation:** Verify bot has access to configured guild
+3. **Permission Checks:** Ensure bot can send messages/DMs
+4. **Main Operation:** Execute task logic with error handling
+5. **Logging:** Record operation results and performance metrics
+6. **Cleanup:** Reset state for next iteration
+
+### Error Handling
+Tasks implement comprehensive error handling:
+
+```python
+async def task_operation(self):
+    try:
+        # Main task logic
+        result = await self.perform_operation()
+        self.logger.info("Task completed", result=result)
+    except SpecificException as e:
+        self.logger.warning("Recoverable error", error=e)
+        # Continue with degraded functionality
+    except Exception as e:
+        self.logger.error("Task failed", error=e)
+        # Task will retry on next interval
+```
+
+## Development Patterns
+
+### Creating New Tasks
+
+1. **Inherit from Base Pattern**
+```python
+class NewTask:
+    def __init__(self, bot: commands.Bot):
+        self.bot = bot
+        self.logger = get_contextual_logger(f'{__name__}.NewTask')
+        self.main_loop.start()
+```
+
+2. **Configure Task Schedule**
+```python
+@tasks.loop(minutes=30)  # Every 30 minutes
+# or
+@tasks.loop(hours=6)     # Every 6 hours
+# or
+@tasks.loop(time=datetime.time(hour=3))  # Daily at 3 AM UTC
+```
+
+3. **Implement Before Loop**
+```python
+@main_loop.before_loop
+async def before_loop(self):
+    await self.bot.wait_until_ready()
+    self.logger.info("Task initialized and ready")
+```
+
+4. **Add Cleanup Handling**
+```python
+def cog_unload(self):
+    self.main_loop.cancel()
+    self.logger.info("Task stopped")
+```
+
+### Task Categories
+
+#### Maintenance Tasks
+- **Data cleanup** (expired records, unused resources)
+- **Cache management** (clear stale entries, optimize storage)
+- **Log rotation** (archive old logs, manage disk space)
+
+#### User Management
+- **Inactive user cleanup** (remove old user data)
+- **Permission auditing** (validate role assignments)
+- **Usage analytics** (collect usage statistics)
+
+#### System Monitoring
+- **Health checks** (verify system components)
+- **Performance monitoring** (track response times)
+- **Error rate tracking** (monitor failure rates)
+
+### Task Configuration
+
+#### Environment Variables
+Tasks respect standard bot configuration:
+```python
+GUILD_ID=12345...         # Target Discord guild
+LOG_LEVEL=INFO           # Logging verbosity
+REDIS_URL=redis://...    # Optional caching backend
+```
+
+#### Runtime Configuration
+Tasks use the central config system:
+```python
+from config import get_config
+
+config = get_config()
+guild = self.bot.get_guild(config.guild_id)
+```
+
+## Logging and Monitoring
+
+### Structured Logging
+Tasks use contextual logging for observability:
+
+```python
+self.logger.info(
+    "Cleanup task starting",
+    guild_id=guild.id,
+    commands_at_risk=len(at_risk_commands)
+)
+
+self.logger.warning(
+    "User DM failed",
+    user_id=user.id,
+    reason="DMs disabled"
+)
+
+self.logger.error(
+    "Task operation failed",
+    operation="delete_commands",
+    error=str(e)
+)
+```
+
+### Performance Tracking
+Tasks log timing and performance metrics:
+
+```python
+start_time = datetime.utcnow()
+# ... task operations ...
+duration = (datetime.utcnow() - start_time).total_seconds()
+
+self.logger.info(
+    "Task completed",
+    duration_seconds=duration,
+    operations_completed=operation_count
+)
+```
+
+### Error Recovery
+Tasks implement retry logic and graceful degradation:
+
+```python
+async def process_with_retry(self, operation, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            return await operation()
+        except RecoverableError as e:
+            if attempt == max_retries - 1:
+                raise
+            await asyncio.sleep(2 ** attempt)  # Exponential backoff
+```
+
+## Testing Strategies
+
+### Unit Testing Tasks
+```python
+@pytest.mark.asyncio
+async def test_custom_command_cleanup():
+    # Mock bot and services
+    bot = AsyncMock()
+    task = CustomCommandCleanupTask(bot)
+
+    # Mock service responses
+    with patch('services.custom_commands_service') as mock_service:
+        mock_service.get_commands_needing_warning.return_value = []
+
+        # Test task execution
+        await task.cleanup_task()
+
+        # Verify service calls
+        mock_service.get_commands_needing_warning.assert_called_once()
+```
+
+### Integration Testing
+```python
+@pytest.mark.integration
+async def test_cleanup_task_with_real_data():
+    # Test with actual Discord bot instance
+    # Use test guild and test data
+    # Verify real Discord API interactions
+```
+
+### Performance Testing
+```python
+@pytest.mark.performance
+async def test_cleanup_task_performance():
+    # Test with large datasets
+    # Measure execution time
+    # Verify memory usage
+```
+
+## Security Considerations
+
+### Permission Validation
+Tasks verify bot permissions before operations:
+
+```python
+async def check_permissions(self, guild: discord.Guild) -> bool:
+    """Verify bot has required permissions."""
+    bot_member = guild.me
+
+    # Check for required permissions
+    if not bot_member.guild_permissions.send_messages:
+        self.logger.warning("Missing send_messages permission")
+        return False
+
+    return True
+```
+
+### Data Privacy
+Tasks handle user data responsibly:
+- **Minimal data access** - Only access required data
+- **Secure logging** - Avoid logging sensitive information
+- **GDPR compliance** - Respect user data rights
+- **Permission respect** - Honor user privacy settings
+
+### Rate Limiting
+Tasks implement Discord API rate limiting:
+
+```python
+async def send_notifications_with_rate_limiting(self, notifications):
+    """Send notifications with rate limiting."""
+    for notification in notifications:
+        try:
+            await self.send_notification(notification)
+            await asyncio.sleep(1)  # Avoid rate limits
+        except discord.HTTPException as e:
+            if e.status == 429:  # Rate limited
+                retry_after = e.response.headers.get('Retry-After', 60)
+                await asyncio.sleep(int(retry_after))
+```
+
+## Future Task Ideas
+
+### Potential Additions
+- **Database maintenance** - Optimize database performance
+- **Backup automation** - Create data backups
+- **Usage analytics** - Generate usage reports
+- **Health monitoring** - System health checks
+- **Cache warming** - Pre-populate frequently accessed data
+
+### Scalability Patterns
+- **Task queues** - Distribute work across multiple workers
+- **Sharding support** - Handle multiple Discord guilds
+- **Load balancing** - Distribute task execution
+- **Monitoring integration** - External monitoring systems
+
+---
+
+**Next Steps for AI Agents:**
+1. Review the existing cleanup task implementation
+2. Understand the Discord.py tasks framework
+3. Follow the structured logging patterns
+4. Implement proper error handling and recovery
+5. Consider guild permissions and user privacy
+6. Test tasks thoroughly before deployment

tests/test_commands_voice.py

@@ -0,0 +1,550 @@
+"""
+Tests for voice channel commands
+
+Validates voice channel creation, cleanup, and migration message functionality.
+"""
+import asyncio
+import json
+import tempfile
+from datetime import datetime, timedelta
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import discord
+import pytest
+from discord.ext import commands
+
+from commands.voice.channels import VoiceChannelCommands
+from commands.voice.cleanup_service import VoiceChannelCleanupService
+from commands.voice.tracker import VoiceChannelTracker
+from models.game import Game
+from models.team import Team
+
+
+class TestVoiceChannelTracker:
+    """Test voice channel tracker functionality."""
+
+    def test_tracker_initialization(self):
+        """Test that tracker initializes correctly."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            data_file = Path(temp_dir) / "test_channels.json"
+            tracker = VoiceChannelTracker(str(data_file))
+
+            assert tracker.data_file == data_file
+            assert tracker._data == {"voice_channels": {}}
+            assert data_file.parent.exists()
+
+    def test_add_channel(self):
+        """Test adding a channel to tracking."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            data_file = Path(temp_dir) / "test_channels.json"
+            tracker = VoiceChannelTracker(str(data_file))
+
+            # Mock channel
+            mock_channel = MagicMock(spec=discord.VoiceChannel)
+            mock_channel.id = 123456789
+            mock_channel.name = "Test Channel"
+            mock_guild = MagicMock()
+            mock_guild.id = 987654321
+            mock_channel.guild = mock_guild
+
+            tracker.add_channel(mock_channel, "public", 555666777)
+
+            # Verify data structure
+            channels = tracker._data["voice_channels"]
+            assert "123456789" in channels
+            channel_data = channels["123456789"]
+
+            assert channel_data["channel_id"] == "123456789"
+            assert channel_data["guild_id"] == "987654321"
+            assert channel_data["name"] == "Test Channel"
+            assert channel_data["type"] == "public"
+            assert channel_data["creator_id"] == "555666777"
+            assert channel_data["empty_since"] is None
+
+            # Verify file persistence
+            assert data_file.exists()
+
+    def test_update_channel_status(self):
+        """Test updating channel empty status."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            data_file = Path(temp_dir) / "test_channels.json"
+            tracker = VoiceChannelTracker(str(data_file))
+
+            # Add a test channel
+            mock_channel = MagicMock(spec=discord.VoiceChannel)
+            mock_channel.id = 123456789
+            mock_channel.name = "Test Channel"
+            mock_guild = MagicMock()
+            mock_guild.id = 987654321
+            mock_channel.guild = mock_guild
+
+            tracker.add_channel(mock_channel, "public", 555666777)
+
+            # Test becoming empty
+            tracker.update_channel_status(123456789, True)
+            channel_data = tracker._data["voice_channels"]["123456789"]
+            assert channel_data["empty_since"] is not None
+
+            # Test becoming occupied
+            tracker.update_channel_status(123456789, False)
+            channel_data = tracker._data["voice_channels"]["123456789"]
+            assert channel_data["empty_since"] is None
+
+    def test_get_channels_for_cleanup(self):
+        """Test getting channels ready for cleanup."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            data_file = Path(temp_dir) / "test_channels.json"
+            tracker = VoiceChannelTracker(str(data_file))
+
+            # Create test data with different timestamps
+            current_time = datetime.utcnow()
+            old_empty_time = current_time - timedelta(minutes=20)
+            recent_empty_time = current_time - timedelta(minutes=5)
+
+            tracker._data = {
+                "voice_channels": {
+                    "123": {
+                        "channel_id": "123",
+                        "name": "Old Empty",
+                        "empty_since": old_empty_time.isoformat()
+                    },
+                    "456": {
+                        "channel_id": "456",
+                        "name": "Recent Empty",
+                        "empty_since": recent_empty_time.isoformat()
+                    },
+                    "789": {
+                        "channel_id": "789",
+                        "name": "Not Empty",
+                        "empty_since": None
+                    }
+                }
+            }
+
+            # Get channels for cleanup (15 minute threshold)
+            cleanup_candidates = tracker.get_channels_for_cleanup(15)
+
+            # Only the old empty channel should be ready for cleanup
+            assert len(cleanup_candidates) == 1
+            assert cleanup_candidates[0]["channel_id"] == "123"
+
+    def test_remove_channel(self):
+        """Test removing a channel from tracking."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            data_file = Path(temp_dir) / "test_channels.json"
+            tracker = VoiceChannelTracker(str(data_file))
+
+            # Add a test channel
+            mock_channel = MagicMock(spec=discord.VoiceChannel)
+            mock_channel.id = 123456789
+            mock_channel.name = "Test Channel"
+            mock_guild = MagicMock()
+            mock_guild.id = 987654321
+            mock_channel.guild = mock_guild
+
+            tracker.add_channel(mock_channel, "public", 555666777)
+            assert "123456789" in tracker._data["voice_channels"]
+
+            # Remove channel
+            tracker.remove_channel(123456789)
+            assert "123456789" not in tracker._data["voice_channels"]
+
+    def test_cleanup_stale_entries(self):
+        """Test cleaning up stale tracking entries."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            data_file = Path(temp_dir) / "test_channels.json"
+            tracker = VoiceChannelTracker(str(data_file))
+
+            # Create test data with some valid and invalid channel IDs
+            tracker._data = {
+                "voice_channels": {
+                    "123": {"channel_id": "123", "name": "Valid 1"},
+                    "456": {"channel_id": "456", "name": "Valid 2"},
+                    "789": {"channel_id": "789", "name": "Stale 1"},
+                    "999": {"channel_id": "999", "name": "Stale 2"}
+                }
+            }
+
+            # Clean up stale entries (only 123 and 456 are valid)
+            removed_count = tracker.cleanup_stale_entries([123, 456])
+
+            assert removed_count == 2
+            assert len(tracker._data["voice_channels"]) == 2
+            assert "123" in tracker._data["voice_channels"]
+            assert "456" in tracker._data["voice_channels"]
+            assert "789" not in tracker._data["voice_channels"]
+            assert "999" not in tracker._data["voice_channels"]
+
+
+class TestVoiceChannelCleanupService:
+    """Test voice channel cleanup service functionality."""
+
+    @pytest.fixture
+    def cleanup_service(self):
+        """Create a cleanup service instance."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            data_file = Path(temp_dir) / "test_channels.json"
+            return VoiceChannelCleanupService(str(data_file))
+
+    @pytest.fixture
+    def mock_bot(self):
+        """Create a mock bot instance."""
+        bot = AsyncMock(spec=commands.Bot)
+        return bot
+
+    @pytest.mark.asyncio
+    async def test_verify_tracked_channels(self, cleanup_service, mock_bot):
+        """Test verification of tracked channels on startup."""
+        # Add test data
+        cleanup_service.tracker._data = {
+            "voice_channels": {
+                "123": {
+                    "channel_id": "123",
+                    "guild_id": "999",
+                    "name": "Valid Channel"
+                },
+                "456": {
+                    "channel_id": "456",
+                    "guild_id": "888",
+                    "name": "Invalid Guild"
+                },
+                "789": {
+                    "channel_id": "789",
+                    "guild_id": "999",
+                    "name": "Invalid Channel"
+                }
+            }
+        }
+
+        # Mock guild and channel
+        mock_guild = MagicMock()
+        mock_guild.id = 999
+        mock_channel = MagicMock()
+        mock_channel.id = 123
+
+        mock_bot.get_guild.side_effect = lambda guild_id: mock_guild if guild_id == 999 else None
+        mock_guild.get_channel.side_effect = lambda channel_id: mock_channel if channel_id == 123 else None
+
+        await cleanup_service.verify_tracked_channels(mock_bot)
+
+        # Only valid channel should remain
+        assert len(cleanup_service.tracker._data["voice_channels"]) == 1
+        assert "123" in cleanup_service.tracker._data["voice_channels"]
+
+    @pytest.mark.asyncio
+    async def test_check_channel_status(self, cleanup_service, mock_bot):
+        """Test checking individual channel status."""
+        # Mock guild and channel
+        mock_guild = MagicMock()
+        mock_guild.id = 999
+        mock_channel = MagicMock()
+        mock_channel.id = 123
+        mock_channel.members = []  # Empty channel
+
+        mock_bot.get_guild.return_value = mock_guild
+        mock_guild.get_channel.return_value = mock_channel
+
+        channel_data = {
+            "channel_id": "123",
+            "guild_id": "999",
+            "name": "Test Channel"
+        }
+
+        await cleanup_service.check_channel_status(mock_bot, channel_data)
+
+        # Should have called update_channel_status with is_empty=True
+        tracked_data = cleanup_service.tracker.get_tracked_channel(123)
+        # Since the channel wasn't previously tracked, update_channel_status won't work
+        # This test mainly verifies the method runs without error
+
+    @pytest.mark.asyncio
+    async def test_cleanup_channel(self, cleanup_service, mock_bot):
+        """Test cleaning up an individual channel."""
+        # Mock guild and channel
+        mock_guild = MagicMock()
+        mock_guild.id = 999
+        mock_channel = AsyncMock()
+        mock_channel.id = 123
+        mock_channel.members = []  # Empty channel
+
+        mock_bot.get_guild.return_value = mock_guild
+        mock_guild.get_channel.return_value = mock_channel
+
+        # Add channel to tracking first
+        cleanup_service.tracker._data["voice_channels"]["123"] = {
+            "channel_id": "123",
+            "guild_id": "999",
+            "name": "Test Channel"
+        }
+
+        channel_data = {
+            "channel_id": "123",
+            "guild_id": "999",
+            "name": "Test Channel"
+        }
+
+        await cleanup_service.cleanup_channel(mock_bot, channel_data)
+
+        # Should have deleted the channel
+        mock_channel.delete.assert_called_once_with(reason="Automatic cleanup - empty for 15+ minutes")
+
+        # Should have removed from tracking
+        assert "123" not in cleanup_service.tracker._data["voice_channels"]
+
+
+class TestVoiceChannelCommands:
+    """Test voice channel command functionality."""
+
+    @pytest.fixture
+    def bot(self):
+        """Create a mock bot instance."""
+        bot = AsyncMock(spec=commands.Bot)
+        # Mock voice cleanup service
+        bot.voice_cleanup_service = MagicMock()
+        bot.voice_cleanup_service.tracker = MagicMock()
+        return bot
+
+    @pytest.fixture
+    def voice_cog(self, bot):
+        """Create VoiceChannelCommands cog instance."""
+        return VoiceChannelCommands(bot)
+
+    @pytest.fixture
+    def mock_interaction(self):
+        """Create a mock Discord interaction."""
+        interaction = AsyncMock(spec=discord.Interaction)
+
+        # Mock the user
+        user = MagicMock(spec=discord.User)
+        user.id = 12345
+        user.display_name = "TestUser"
+        interaction.user = user
+
+        # Mock the guild
+        guild = MagicMock(spec=discord.Guild)
+        guild.id = 67890
+        guild.default_role = MagicMock()
+        interaction.guild = guild
+
+        # Mock response methods
+        interaction.response.defer = AsyncMock()
+        interaction.followup.send = AsyncMock()
+
+        return interaction
+
+    @pytest.fixture
+    def mock_context(self):
+        """Create a mock Discord context for prefix commands."""
+        ctx = AsyncMock(spec=commands.Context)
+
+        # Mock the author (user)
+        author = MagicMock(spec=discord.User)
+        author.id = 12345
+        author.display_name = "TestUser"
+        ctx.author = author
+
+        # Mock send method
+        ctx.send = AsyncMock()
+
+        return ctx
+
+    @pytest.mark.asyncio
+    async def test_create_public_channel_success(self, voice_cog, mock_interaction):
+        """Test successful public channel creation."""
+        # Mock user team
+        mock_team = MagicMock(spec=Team)
+        mock_team.id = 1
+        mock_team.abbrev = "NYY"
+        mock_team.lname = "New York Yankees"
+
+        # Mock voice category
+        mock_category = MagicMock()
+        mock_interaction.guild.categories = [mock_category]
+
+        # Mock created channel
+        mock_channel = AsyncMock(spec=discord.VoiceChannel)
+        mock_channel.id = 999888777
+        mock_channel.name = "Gameplay Phoenix"
+        mock_channel.mention = "#gameplay-phoenix"
+
+        with patch('commands.voice.channels.team_service') as mock_team_service:
+            with patch.object(mock_interaction.guild, 'create_voice_channel', return_value=mock_channel) as mock_create:
+                with patch('commands.voice.channels.random_codename', return_value="Phoenix"):
+                    with patch('discord.utils.get', return_value=mock_category):
+                        mock_team_service.get_teams_by_owner.return_value = [mock_team]
+
+                        await voice_cog.create_public_channel.callback(voice_cog, mock_interaction)
+
+                        # Verify response was deferred
+                        mock_interaction.response.defer.assert_called_once()
+
+                        # Verify channel was created
+                        mock_create.assert_called_once()
+                        args, kwargs = mock_create.call_args
+                        assert kwargs['name'] == "Gameplay Phoenix"
+                        assert kwargs['category'] == mock_category
+
+                        # Verify success message was sent
+                        mock_interaction.followup.send.assert_called_once()
+                        call_args = mock_interaction.followup.send.call_args
+                        assert 'embed' in call_args.kwargs
+                        embed = call_args.kwargs['embed']
+                        assert "Created public voice channel" in embed.title
+
+    @pytest.mark.asyncio
+    async def test_create_public_channel_no_team(self, voice_cog, mock_interaction):
+        """Test public channel creation with no team."""
+        with patch('commands.voice.channels.team_service') as mock_team_service:
+            mock_team_service.get_teams_by_owner.return_value = []
+
+            await voice_cog.create_public_channel.callback(voice_cog, mock_interaction)
+
+            # Verify response was deferred
+            mock_interaction.response.defer.assert_called_once()
+
+            # Verify error message was sent
+            mock_interaction.followup.send.assert_called_once()
+            call_args = mock_interaction.followup.send.call_args
+            assert call_args.kwargs['ephemeral'] is True
+            embed = call_args.kwargs['embed']
+            assert "No Team Found" in embed.title
+
+    @pytest.mark.asyncio
+    async def test_create_private_channel_success(self, voice_cog, mock_interaction):
+        """Test successful private channel creation."""
+        # Mock user team
+        mock_user_team = MagicMock(spec=Team)
+        mock_user_team.id = 1
+        mock_user_team.abbrev = "NYY"
+        mock_user_team.lname = "New York Yankees"
+        mock_user_team.sname = "Yankees"
+
+        # Mock opponent team
+        mock_opponent_team = MagicMock(spec=Team)
+        mock_opponent_team.id = 2
+        mock_opponent_team.abbrev = "BOS"
+        mock_opponent_team.lname = "Boston Red Sox"
+        mock_opponent_team.sname = "Red Sox"
+
+        # Mock game
+        mock_game = MagicMock(spec=Game)
+        mock_game.week = 5
+        mock_game.away_team = mock_user_team
+        mock_game.home_team = mock_opponent_team
+        mock_game.is_completed = False
+
+        # Mock current league info
+        mock_current = MagicMock()
+        mock_current.season = 12
+        mock_current.week = 5
+
+        # Mock voice category and roles
+        mock_category = MagicMock()
+        mock_user_role = MagicMock()
+        mock_opponent_role = MagicMock()
+
+        # Mock created channel
+        mock_channel = AsyncMock(spec=discord.VoiceChannel)
+        mock_channel.id = 999888777
+        mock_channel.name = "Yankees vs Red Sox"
+        mock_channel.mention = "#yankees-vs-red-sox"
+
+        with patch('commands.voice.channels.team_service') as mock_team_service:
+            with patch('commands.voice.channels.league_service') as mock_league_service:
+                with patch.object(voice_cog.schedule_service, 'get_team_schedule') as mock_schedule:
+                    with patch.object(mock_interaction.guild, 'create_voice_channel', return_value=mock_channel) as mock_create:
+                        with patch('discord.utils.get') as mock_utils_get:
+
+                            mock_team_service.get_teams_by_owner.return_value = [mock_user_team]
+                            mock_league_service.get_current.return_value = mock_current
+                            mock_schedule.return_value = [mock_game]
+
+                            # Mock discord.utils.get calls
+                            def mock_get(collection, **kwargs):
+                                if 'name' in kwargs and kwargs['name'] == "Voice Channels":
+                                    return mock_category
+                                elif 'name' in kwargs and kwargs['name'] == "New York Yankees":
+                                    return mock_user_role
+                                elif 'name' in kwargs and kwargs['name'] == "Boston Red Sox":
+                                    return mock_opponent_role
+                                return None
+
+                            mock_utils_get.side_effect = mock_get
+
+                            await voice_cog.create_private_channel.callback(voice_cog, mock_interaction)
+
+                            # Verify response was deferred
+                            mock_interaction.response.defer.assert_called_once()
+
+                            # Verify channel was created
+                            mock_create.assert_called_once()
+                            args, kwargs = mock_create.call_args
+                            assert kwargs['name'] == "Yankees vs Red Sox"
+                            assert kwargs['category'] == mock_category
+
+                            # Verify success message was sent
+                            mock_interaction.followup.send.assert_called_once()
+                            call_args = mock_interaction.followup.send.call_args
+                            assert 'embed' in call_args.kwargs
+                            embed = call_args.kwargs['embed']
+                            assert "Private Voice Channel Created" in embed.title
+
+    @pytest.mark.asyncio
+    async def test_deprecated_vc_command(self, voice_cog, mock_context):
+        """Test deprecated !vc command shows migration message."""
+        await voice_cog.deprecated_public_voice.callback(voice_cog, mock_context)
+
+        # Verify migration message was sent
+        mock_context.send.assert_called_once()
+        call_args = mock_context.send.call_args
+        embed = call_args.kwargs['embed']
+        assert "Command Deprecated" in embed.title
+        assert "/voice-channel public" in embed.description
+
+    @pytest.mark.asyncio
+    async def test_deprecated_private_command(self, voice_cog, mock_context):
+        """Test deprecated !private command shows migration message."""
+        await voice_cog.deprecated_private_voice.callback(voice_cog, mock_context)
+
+        # Verify migration message was sent
+        mock_context.send.assert_called_once()
+        call_args = mock_context.send.call_args
+        embed = call_args.kwargs['embed']
+        assert "Command Deprecated" in embed.title
+        assert "/voice-channel private" in embed.description
+
+    def test_random_codename_generation(self):
+        """Test that random codename generation works."""
+        from commands.voice.channels import random_codename, CODENAMES
+
+        # Generate multiple codenames
+        generated = [random_codename() for _ in range(10)]
+
+        # All should be from the codenames list
+        for codename in generated:
+            assert codename in CODENAMES
+
+        # Should have some variety (unlikely all same)
+        unique_names = set(generated)
+        assert len(unique_names) > 1  # Should have at least some variety
+
+    def test_voice_group_attributes(self, voice_cog):
+        """Test that voice command group has correct attributes."""
+        assert hasattr(voice_cog, 'voice_group')
+        assert voice_cog.voice_group.name == "voice-channel"
+        assert voice_cog.voice_group.description == "Create voice channels for gameplay"
+
+    def test_command_attributes(self, voice_cog):
+        """Test that commands have correct attributes."""
+        # Test prefix commands exist
+        assert hasattr(voice_cog, 'deprecated_public_voice')
+        assert hasattr(voice_cog, 'deprecated_private_voice')
+
+        # Check command names and aliases
+        public_cmd = voice_cog.deprecated_public_voice
+        assert public_cmd.name == "vc"
+        assert public_cmd.aliases == ["voice", "gameplay"]
+
+        private_cmd = voice_cog.deprecated_private_voice
+        assert private_cmd.name == "private"

views/README.md

@@ -0,0 +1,423 @@
+# Views Directory
+
+The views directory contains Discord UI components for Discord Bot v2.0, providing consistent visual interfaces and interactive elements. This includes embeds, modals, buttons, select menus, and other Discord UI components.
+
+## Architecture
+
+### Component-Based UI Design
+Views in Discord Bot v2.0 follow these principles:
+- **Consistent styling** via centralized templates
+- **Reusable components** for common UI patterns
+- **Error handling** with graceful degradation
+- **User interaction tracking** and validation
+- **Accessibility** with proper labeling and feedback
+
+### Base Components
+All view components inherit from Discord.py base classes with enhanced functionality:
+- **BaseView** - Enhanced discord.ui.View with logging and user validation
+- **BaseModal** - Enhanced discord.ui.Modal with error handling
+- **EmbedTemplate** - Centralized embed creation with consistent styling
+
+## View Components
+
+### Base View System (`base.py`)
+
+#### BaseView Class
+Foundation for all interactive views:
+
+```python
+class BaseView(discord.ui.View):
+    def __init__(self, timeout=180.0, user_id=None):
+        super().__init__(timeout=timeout)
+        self.user_id = user_id
+        self.logger = get_contextual_logger(f'{__name__}.BaseView')
+
+    async def interaction_check(self, interaction) -> bool:
+        """Validate user permissions for interaction."""
+
+    async def on_timeout(self) -> None:
+        """Handle view timeout gracefully."""
+
+    async def on_error(self, interaction, error, item) -> None:
+        """Handle view errors with user feedback."""
+```
+
+#### ConfirmationView Class
+Standard Yes/No confirmation dialogs:
+
+```python
+confirmation = ConfirmationView(
+    user_id=interaction.user.id,
+    confirm_callback=handle_confirm,
+    cancel_callback=handle_cancel
+)
+await interaction.followup.send("Confirm action?", view=confirmation)
+```
+
+#### PaginationView Class
+Multi-page navigation for large datasets:
+
+```python
+pages = [embed1, embed2, embed3]
+pagination = PaginationView(
+    pages=pages,
+    user_id=interaction.user.id,
+    show_page_numbers=True
+)
+await interaction.followup.send(embed=pagination.get_current_embed(), view=pagination)
+```
+
+### Embed Templates (`embeds.py`)
+
+#### EmbedTemplate Class
+Centralized embed creation with consistent styling:
+
+```python
+# Success embed
+embed = EmbedTemplate.success(
+    title="Operation Completed",
+    description="Your request was processed successfully."
+)
+
+# Error embed
+embed = EmbedTemplate.error(
+    title="Operation Failed",
+    description="Please check your input and try again."
+)
+
+# Warning embed
+embed = EmbedTemplate.warning(
+    title="Careful!",
+    description="This action cannot be undone."
+)
+
+# Info embed
+embed = EmbedTemplate.info(
+    title="Information",
+    description="Here's what you need to know."
+)
+```
+
+#### EmbedColors Dataclass
+Consistent color scheme across all embeds:
+
+```python
+@dataclass(frozen=True)
+class EmbedColors:
+    PRIMARY: int = 0xa6ce39      # SBA green
+    SUCCESS: int = 0x28a745      # Green
+    WARNING: int = 0xffc107      # Yellow
+    ERROR: int = 0xdc3545        # Red
+    INFO: int = 0x17a2b8         # Blue
+    SECONDARY: int = 0x6c757d    # Gray
+```
+
+### Modal Forms (`modals.py`)
+
+#### BaseModal Class
+Foundation for interactive forms:
+
+```python
+class BaseModal(discord.ui.Modal):
+    def __init__(self, title: str, timeout=300.0):
+        super().__init__(title=title, timeout=timeout)
+        self.logger = get_contextual_logger(f'{__name__}.BaseModal')
+        self.result = None
+
+    async def on_submit(self, interaction):
+        """Handle form submission."""
+
+    async def on_error(self, interaction, error):
+        """Handle form errors."""
+```
+
+#### Usage Pattern
+```python
+class CustomCommandModal(BaseModal):
+    def __init__(self):
+        super().__init__(title="Create Custom Command")
+
+    name = discord.ui.TextInput(
+        label="Command Name",
+        placeholder="Enter command name...",
+        required=True,
+        max_length=50
+    )
+
+    response = discord.ui.TextInput(
+        label="Response",
+        placeholder="Enter command response...",
+        style=discord.TextStyle.paragraph,
+        required=True,
+        max_length=2000
+    )
+
+    async def on_submit(self, interaction):
+        # Process form data
+        command_data = {
+            "name": self.name.value,
+            "response": self.response.value
+        }
+        # Handle creation logic
+```
+
+### Common UI Elements (`common.py`)
+
+#### Shared Components
+- **Loading indicators** for async operations
+- **Status messages** for operation feedback
+- **Navigation elements** for multi-step processes
+- **Validation displays** for form errors
+
+### Specialized Views
+
+#### Custom Commands (`custom_commands.py`)
+Views specific to custom command management:
+- Command creation forms
+- Command listing with actions
+- Bulk management interfaces
+
+#### Transaction Management (`transaction_embed.py`)
+Views for player transaction interfaces:
+- Transaction proposal forms
+- Approval/rejection workflows
+- Transaction history displays
+
+## Styling Guidelines
+
+### Embed Consistency
+All embeds should use EmbedTemplate methods:
+
+```python
+# ✅ Consistent styling
+embed = EmbedTemplate.success("Player Added", "Player successfully added to roster")
+
+# ❌ Inconsistent styling
+embed = discord.Embed(title="Player Added", color=0x00ff00)
+```
+
+### Color Usage
+Use the standard color palette:
+- **PRIMARY (SBA Green)** - Default for neutral information
+- **SUCCESS (Green)** - Successful operations
+- **ERROR (Red)** - Errors and failures
+- **WARNING (Yellow)** - Warnings and cautions
+- **INFO (Blue)** - General information
+- **SECONDARY (Gray)** - Less important information
+
+### User Feedback
+Provide clear feedback for all user interactions:
+
+```python
+# Loading state
+embed = EmbedTemplate.info("Processing", "Please wait while we process your request...")
+
+# Success state
+embed = EmbedTemplate.success("Complete", "Your request has been processed successfully.")
+
+# Error state with helpful information
+embed = EmbedTemplate.error(
+    "Request Failed",
+    "The player name was not found. Please check your spelling and try again."
+)
+```
+
+## Interactive Components
+
+### Button Patterns
+
+#### Action Buttons
+```python
+@discord.ui.button(label="Confirm", style=discord.ButtonStyle.success, emoji="✅")
+async def confirm_button(self, interaction, button):
+    self.increment_interaction_count()
+    # Handle confirmation
+    await interaction.response.edit_message(content="Confirmed!", view=None)
+```
+
+#### Navigation Buttons
+```python
+@discord.ui.button(emoji="◀️", style=discord.ButtonStyle.primary)
+async def previous_page(self, interaction, button):
+    self.current_page = max(0, self.current_page - 1)
+    await interaction.response.edit_message(embed=self.get_current_embed(), view=self)
+```
+
+### Select Menu Patterns
+
+#### Option Selection
+```python
+@discord.ui.select(placeholder="Choose an option...")
+async def select_option(self, interaction, select):
+    selected_value = select.values[0]
+    # Handle selection
+    await interaction.response.send_message(f"You selected: {selected_value}")
+```
+
+#### Dynamic Options
+```python
+class PlayerSelectMenu(discord.ui.Select):
+    def __init__(self, players: List[Player]):
+        options = [
+            discord.SelectOption(
+                label=player.name,
+                value=str(player.id),
+                description=f"{player.position} - {player.team.abbrev}"
+            )
+            for player in players[:25]  # Discord limit
+        ]
+        super().__init__(placeholder="Select a player...", options=options)
+```
+
+## Error Handling
+
+### View Error Handling
+All views implement comprehensive error handling:
+
+```python
+async def on_error(self, interaction, error, item):
+    """Handle view errors gracefully."""
+    self.logger.error("View error", error=error, item_type=type(item).__name__)
+
+    try:
+        embed = EmbedTemplate.error(
+            "Interaction Error",
+            "Something went wrong. Please try again."
+        )
+
+        if not interaction.response.is_done():
+            await interaction.response.send_message(embed=embed, ephemeral=True)
+        else:
+            await interaction.followup.send(embed=embed, ephemeral=True)
+    except Exception as e:
+        self.logger.error("Failed to send error message", error=e)
+```
+
+### User Input Validation
+Forms validate user input before processing:
+
+```python
+async def on_submit(self, interaction):
+    # Validate input
+    if len(self.name.value) < 2:
+        embed = EmbedTemplate.error(
+            "Invalid Input",
+            "Command name must be at least 2 characters long."
+        )
+        await interaction.response.send_message(embed=embed, ephemeral=True)
+        return
+
+    # Process valid input
+    await self.create_command(interaction)
+```
+
+## Accessibility Features
+
+### User-Friendly Labels
+- **Clear button labels** with descriptive text
+- **Helpful placeholders** in form fields
+- **Descriptive error messages** with actionable guidance
+- **Consistent emoji usage** for visual recognition
+
+### Permission Validation
+Views respect user permissions and provide appropriate feedback:
+
+```python
+async def interaction_check(self, interaction) -> bool:
+    """Check if user can interact with this view."""
+    if self.user_id and interaction.user.id != self.user_id:
+        await interaction.response.send_message(
+            "❌ You cannot interact with this menu.",
+            ephemeral=True
+        )
+        return False
+    return True
+```
+
+## Performance Considerations
+
+### View Lifecycle Management
+- **Timeout handling** prevents orphaned views
+- **Resource cleanup** in view destructors
+- **Interaction tracking** for usage analytics
+- **Memory management** for large datasets
+
+### Efficient Updates
+```python
+# ✅ Efficient - Only update what changed
+await interaction.response.edit_message(embed=new_embed, view=self)
+
+# ❌ Inefficient - Sends new message
+await interaction.response.send_message(embed=new_embed, view=new_view)
+```
+
+## Testing Strategies
+
+### View Testing
+```python
+@pytest.mark.asyncio
+async def test_confirmation_view():
+    view = ConfirmationView(user_id=123)
+
+    # Mock interaction
+    interaction = Mock()
+    interaction.user.id = 123
+
+    # Test button click
+    await view.confirm_button.callback(interaction)
+
+    assert view.result is True
+```
+
+### Modal Testing
+```python
+@pytest.mark.asyncio
+async def test_custom_command_modal():
+    modal = CustomCommandModal()
+
+    # Set form values
+    modal.name.value = "test"
+    modal.response.value = "Test response"
+
+    # Mock interaction
+    interaction = Mock()
+
+    # Test form submission
+    await modal.on_submit(interaction)
+
+    # Verify processing
+    assert modal.result is not None
+```
+
+## Development Guidelines
+
+### Creating New Views
+1. **Inherit from base classes** for consistency
+2. **Use EmbedTemplate** for all embed creation
+3. **Implement proper error handling** in all interactions
+4. **Add user permission checks** where appropriate
+5. **Include comprehensive logging** with context
+6. **Follow timeout patterns** to prevent resource leaks
+
+### View Composition
+- **Keep views focused** on single responsibilities
+- **Use composition** over complex inheritance
+- **Separate business logic** from UI logic
+- **Make views testable** with dependency injection
+
+### UI Guidelines
+- **Follow Discord design patterns** for familiarity
+- **Use consistent colors** from EmbedColors
+- **Provide clear user feedback** for all actions
+- **Handle edge cases** gracefully
+- **Consider mobile users** in layout design
+
+---
+
+**Next Steps for AI Agents:**
+1. Review existing view implementations for patterns
+2. Understand the Discord UI component system
+3. Follow the EmbedTemplate system for consistent styling
+4. Implement proper error handling and user validation
+5. Test interactive components thoroughly
+6. Consider accessibility and user experience in design