AI Context files

internal/audio/context.md

@@ -0,0 +1,110 @@
+# Audio System Context
+
+## Overview
+
+The `internal/audio` package provides a simple audio configuration management system for the GoMud game engine. It handles loading and retrieving audio file configurations that can be used throughout the game for sound effects and music.
+
+## Key Components
+
+### Core Files
+- **audio.go**: Main audio configuration management functionality
+
+### Key Structures
+
+#### AudioConfig
+```go
+type AudioConfig struct {
+    FilePath string `yaml:"filepath,omitempty"`
+    Volume   int    `yaml:"volume,omitempty"`
+}
+```
+Represents an audio file configuration with file path and volume settings.
+
+### Key Functions
+
+#### Configuration Loading
+- **LoadAudioConfig()**: Loads audio configurations from `_datafiles/audio.yaml` file
+  - Clears existing configurations and reloads from file
+  - Uses YAML unmarshaling to populate the audioLookup map
+  - Logs loading time and count of loaded configurations
+  - Panics on file read or YAML parsing errors
+
+#### Audio Retrieval
+- **GetFile(identifier string) AudioConfig**: Retrieves audio configuration by identifier
+  - Returns AudioConfig if found, empty AudioConfig if not found
+  - Thread-safe lookup from the audioLookup map
+
+### Global State
+- **audioLookup**: `map[string]AudioConfig` - In-memory cache of all loaded audio configurations
+
+## Dependencies
+
+### Internal Dependencies
+- `internal/configs`: For accessing file path configurations
+- `internal/mudlog`: For logging audio loading operations
+
+### External Dependencies
+- `gopkg.in/yaml.v2`: For YAML configuration parsing
+- `github.com/pkg/errors`: For error wrapping
+- Standard library: `os`, `time`
+
+## Usage Patterns
+
+### Loading Audio Configurations
+```go
+// Load all audio configurations from file
+audio.LoadAudioConfig()
+```
+
+### Retrieving Audio Files
+```go
+// Get audio configuration for a specific sound
+audioConfig := audio.GetFile("sword_clang")
+if audioConfig.FilePath != "" {
+    // Use the audio file
+    playSound(audioConfig.FilePath, audioConfig.Volume)
+}
+```
+
+## Configuration File Format
+
+The system expects an `audio.yaml` file in the data files directory with the following structure:
+```yaml
+sound_identifier:
+  filepath: "path/to/audio/file.wav"
+  volume: 75
+another_sound:
+  filepath: "path/to/another/file.mp3"
+  volume: 50
+```
+
+## Error Handling
+
+- **File Loading Errors**: Panics if the audio.yaml file cannot be read or parsed
+- **Missing Configurations**: Returns empty AudioConfig for non-existent identifiers
+- **Thread Safety**: Uses map lookups which are safe for concurrent reads
+
+## Performance Considerations
+
+- **Memory Usage**: All audio configurations are loaded into memory at startup
+- **Lookup Performance**: O(1) map lookups for audio configuration retrieval
+- **Reload Strategy**: Complete replacement of configuration map on reload
+
+## Integration Points
+
+### Game Engine Integration
+- Used by sound effect systems to get audio file paths and volume settings
+- Integrated with MSP (MUD Sound Protocol) for client audio playback
+- Referenced by scripting system for dynamic audio playback
+
+### Configuration Management
+- Follows standard GoMud configuration loading patterns
+- Uses centralized file path configuration system
+- Supports hot-reloading of audio configurations
+
+## Future Considerations
+
+- Could be extended to support audio format validation
+- Potential for audio streaming or caching mechanisms
+- Integration with client-side audio capabilities
+- Support for audio playlists or sequences

internal/badinputtracker/context.md

@@ -0,0 +1,173 @@
+# Bad Input Tracker Context
+
+## Overview
+
+The `internal/badinputtracker` package provides a thread-safe system for tracking and analyzing invalid or unrecognized user commands in the GoMud game engine. This helps administrators identify common user input patterns that might indicate missing commands or user confusion.
+
+## Key Components
+
+### Core Files
+- **badinputtracker.go**: Main bad input tracking functionality
+- **badinputtracker_test.go**: Comprehensive unit tests for all tracking functions
+
+### Key Functions
+
+#### Command Tracking
+- **TrackBadCommand(cmd string, rest string)**: Records an invalid command attempt
+  - Thread-safe using mutex locking
+  - Tracks both the command and its arguments separately
+  - Increments counter for repeated identical bad commands
+  - Creates nested map structure: `badCommands[cmd][rest]`
+
+#### Data Retrieval
+- **GetBadCommands() map[string]int**: Returns flattened view of all tracked bad commands
+  - Thread-safe read operation
+  - Combines command and arguments into single string key format: `"cmd rest"`
+  - Returns copy of data with occurrence counts
+  - Safe for concurrent access
+
+#### Data Management
+- **Clear()**: Resets all tracked bad command data
+  - Thread-safe operation using mutex
+  - Completely reinitializes the badCommands map
+  - Used for periodic cleanup or testing
+
+### Global State
+- **badCommands**: `map[string]map[string]int` - Nested map tracking command failures
+  - First level key: command name
+  - Second level key: command arguments/rest
+  - Value: occurrence count
+- **lock**: `sync.Mutex` - Ensures thread-safe access to badCommands map
+
+## Data Structure Design
+
+### Nested Map Structure
+```go
+badCommands = map[string]map[string]int{
+    "unknowncmd": {
+        "arg1 arg2": 3,
+        "different args": 1,
+    },
+    "anotherbad": {
+        "some args": 2,
+    },
+}
+```
+
+### Flattened Output Format
+```go
+map[string]int{
+    "unknowncmd arg1 arg2": 3,
+    "unknowncmd different args": 1,
+    "anotherbad some args": 2,
+}
+```
+
+## Thread Safety
+
+### Concurrency Design
+- **Mutex Protection**: All operations protected by sync.Mutex
+- **Read/Write Safety**: Prevents data races between tracking and retrieval
+- **Lock Scope**: Minimal lock duration to reduce contention
+- **Safe Iteration**: GetBadCommands creates a copy to avoid holding locks during iteration
+
+## Usage Patterns
+
+### Tracking Bad Commands
+```go
+// Track a bad command attempt
+badinputtracker.TrackBadCommand("unknowncmd", "some arguments")
+
+// Track repeated attempts (increments counter)
+badinputtracker.TrackBadCommand("unknowncmd", "some arguments")
+```
+
+### Retrieving Analytics
+```go
+// Get all bad commands with counts
+badCommands := badinputtracker.GetBadCommands()
+for cmdWithArgs, count := range badCommands {
+    log.Printf("Bad command '%s' attempted %d times", cmdWithArgs, count)
+}
+```
+
+### Periodic Cleanup
+```go
+// Clear tracking data (e.g., daily reset)
+badinputtracker.Clear()
+```
+
+## Integration Points
+
+### Command Processing
+- Called when user input doesn't match any valid command
+- Integrated into main command parsing pipeline
+- Helps identify gaps in command coverage
+
+### Administrative Tools
+- Data accessible via admin commands for analysis
+- Used in web admin interface for usage statistics
+- Helps guide development of new commands
+
+### Logging and Monitoring
+- Provides data for system monitoring
+- Helps identify user experience issues
+- Supports usage pattern analysis
+
+## Testing Coverage
+
+### Comprehensive Test Suite
+- **Single Command Tracking**: Basic functionality verification
+- **Multiple Command Handling**: Different commands and arguments
+- **Counter Increment**: Repeated command tracking
+- **Complex Scenarios**: Mixed command patterns
+- **Clear Functionality**: Data reset verification
+- **Thread Safety**: Concurrent access patterns
+
+### Test Scenarios
+- Empty state handling
+- Single vs multiple command tracking
+- Increment behavior for identical commands
+- Mixed command and argument combinations
+- Clear operation verification
+
+## Performance Considerations
+
+### Memory Usage
+- **Bounded Growth**: Limited by unique command/argument combinations
+- **Efficient Storage**: Nested map structure minimizes memory overhead
+- **Cleanup Strategy**: Manual clearing prevents unbounded growth
+
+### Lookup Performance
+- **O(1) Access**: Map-based storage for fast lookups
+- **Minimal Locking**: Short critical sections for good concurrency
+- **Copy Strategy**: GetBadCommands creates copy to minimize lock time
+
+## Error Handling
+
+### Graceful Degradation
+- **No Panics**: All operations handle edge cases gracefully
+- **Empty State**: Safe handling of empty or uninitialized state
+- **Concurrent Safety**: No data corruption under concurrent access
+
+## Administrative Use Cases
+
+### Usage Analysis
+- Identify commonly mistyped commands
+- Discover missing command aliases
+- Analyze user behavior patterns
+- Guide user interface improvements
+
+### System Monitoring
+- Track system usage patterns
+- Identify potential bot or automated activity
+- Monitor user experience quality
+- Support capacity planning
+
+## Future Enhancements
+
+- Time-based tracking for temporal analysis
+- Integration with user session tracking
+- Automatic suggestion system for similar commands
+- Configurable retention policies
+- Export functionality for external analysis