diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..46700e2
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,768 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+---
+
+# JailDoctor's Dilemma - Codebase Architecture Guide
+
+## Overview
+
+**JailDoctor's Dilemma** is a retro-style 2D puzzle platformer game built in C++20 using SDL3 for graphics and audio. The game features 60+ rooms, collectible items, enemies, and an achievement system. It targets multiple platforms (Windows, macOS, Linux) with a focus on retro aesthetics and precise collision detection.
+
+**Language:** C++20
+**Graphics:** SDL3, OpenGL
+**Audio:** SDL3 + custom jail_audio library
+**Build:** CMake 3.10+
+**Game Canvas:** 256x192 pixels (retro resolution)
+
+---
+
+## Build Commands
+
+### Initial Setup & Build
+```bash
+# From project root
+mkdir -p build
+cd build
+cmake ..
+cmake --build .
+```
+
+### Rebuild After Changes
+```bash
+# From build directory
+cmake --build .
+
+# Or from project root
+cmake --build build
+```
+
+### Clean Build
+```bash
+# From build directory
+cmake --build . --clean-first
+
+# Or from project root
+cmake --build build --clean-first
+```
+
+### Run the Game
+```bash
+# Executable is placed in project root
+./jaildoctors_dilemma
+```
+
+**Important:** The build directory is `/Users/sergio/Gitea/jaildoctors_dilemma/build` and the output executable is placed in the project root directory.
+
+---
+
+## 1. High-Level Architecture Overview
+
+The architecture follows a **layered, modular design** with clear separation of concerns:
+
+```
+┌─────────────────────────────────────┐
+│        Application Layer             │
+│  (Director, Scene Manager)           │
+└─────────────────────────────────────┘
+                  ↓
+┌─────────────────────────────────────┐
+│        Game Logic Layer              │
+│  (Game Scene, Entities, Gameplay)    │
+└─────────────────────────────────────┘
+                  ↓
+┌─────────────────────────────────────┐
+│        Core Systems Layer            │
+│  (Rendering, Audio, Input, Resources)│
+└─────────────────────────────────────┘
+                  ↓
+┌─────────────────────────────────────┐
+│     SDL3 & External Libraries        │
+│  (jail_audio, stb_image, stb_vorbis) │
+└─────────────────────────────────────┘
+```
+
+### Key Design Principles
+
+- **Singleton Pattern:** Core systems (Director, Screen, Audio, Input, Resource, Asset) use singleton pattern for global access
+- **Scene-Based Architecture:** Game flow managed through discrete scenes (Logo, Title, Loading, Game, Ending, etc.)
+- **Component-Based Entities:** Player, enemies, and items are discrete entities with render/update patterns
+- **Resource Management:** All assets (textures, sounds, animations, tilemaps) cached through Resource singleton
+- **Delta Time:** Frame-rate independent physics using DeltaTimer class
+
+---
+
+## 2. Directory Structure
+
+```
+source/
+├── core/                          # Core engine systems
+│   ├── audio/                     # Audio management
+│   │   └── audio.hpp/cpp          # Audio singleton (music, sounds, volumes)
+│   ├── input/                     # Input handling
+│   │   ├── input.hpp/cpp          # Input manager (keyboard, gamepad)
+│   │   ├── global_inputs.hpp      # Global input state
+│   │   └── mouse.hpp              # Mouse input
+│   ├── rendering/                 # Graphics rendering
+│   │   ├── screen.hpp/cpp         # Screen/window singleton, SDL renderer
+│   │   ├── surface.hpp/cpp        # 8-bit indexed color surface abstraction
+│   │   ├── surface_sprite.hpp     # Static sprite rendering
+│   │   ├── surface_animated_sprite.hpp # Animated sprite with frame data
+│   │   ├── surface_moving_sprite.hpp   # Moving sprite with velocity
+│   │   ├── texture.hpp/cpp        # SDL texture wrapper
+│   │   ├── text.hpp/cpp           # Text rendering system
+│   │   ├── gif.hpp/cpp            # GIF image loader
+│   │   ├── opengl/                # OpenGL shader backend
+│   │   │   └── opengl_shader.hpp/cpp  # CRT shader effects
+│   │   └── shader_backend.hpp     # Abstract shader interface
+│   ├── resources/                 # Asset & Resource management
+│   │   ├── asset.hpp/cpp          # Asset registry (file path mapping)
+│   │   └── resource.hpp/cpp       # Resource singleton (loads/caches assets)
+│   └── system/                    # System management
+│       ├── director.hpp/cpp       # Main application controller
+│       ├── debug.hpp/cpp          # Debug info overlay
+│       └── global_events.hpp/cpp  # Global event broadcasting
+├── game/                          # Game-specific logic
+│   ├── entities/                  # Game objects
+│   │   ├── player.hpp/cpp         # Player entity with physics
+│   │   ├── enemy.hpp/cpp          # Enemy entities
+│   │   └── item.hpp/cpp           # Collectible items
+│   ├── gameplay/                  # Core gameplay systems
+│   │   ├── room.hpp/cpp           # Room/level logic, tilemap, collision
+│   │   ├── room_tracker.hpp/cpp   # Tracks visited rooms
+│   │   ├── scoreboard.hpp/cpp     # Score display & data
+│   │   ├── item_tracker.hpp/cpp   # Tracks collected items
+│   │   ├── stats.hpp/cpp          # Game statistics
+│   │   └── cheevos.hpp/cpp        # Achievement system
+│   ├── scenes/                    # Game scenes (flow states)
+│   │   ├── logo.hpp/cpp           # JailGames logo screen
+│   │   ├── loading_screen.hpp/cpp # Resource loading progress
+│   │   ├── title.hpp/cpp          # Title screen & menus
+│   │   ├── game.hpp/cpp           # Main gameplay loop
+│   │   ├── game_over.hpp/cpp      # Game over screen
+│   │   ├── ending.hpp/cpp         # Ending sequence 1
+│   │   ├── ending2.hpp/cpp        # Ending sequence 2
+│   │   └── credits.hpp/cpp        # Credits screen
+│   ├── ui/                        # User interface
+│   │   └── notifier.hpp/cpp       # Achievement/notification display
+│   ├── options.hpp/cpp            # Game configuration/options
+│   ├── scene_manager.hpp          # Scene flow state machine
+│   ├── defaults.hpp               # Game defaults constants
+│   └── gameplay.hpp               # Gameplay constants
+├── external/                      # Third-party libraries
+│   ├── jail_audio.hpp/cpp         # Custom audio library
+│   ├── jail_audio.h               # C interface for jail_audio
+│   ├── stb_image.h                # Image loading library
+│   └── stb_vorbis.h               # OGG Vorbis audio decoding
+├── utils/                         # Utility code
+│   ├── delta_timer.hpp/cpp        # Frame-rate independent timing
+│   ├── defines.hpp                # Game constants (resolutions, block sizes)
+│   └── utils.hpp/cpp              # Helper functions (colors, math)
+└── main.cpp                       # Application entry point
+
+data/                              # Game assets
+├── font/                          # Bitmap fonts + descriptors
+├── palette/                       # Color palettes (.pal files)
+├── shaders/                       # GLSL vertex/fragment shaders
+├── room/                          # Tilemaps & room definitions (01.tmx-60.tmx)
+├── tilesets/                      # Tileset graphics
+├── enemies/                       # Enemy sprites & animations
+├── player/                        # Player sprites & animations
+├── items/                         # Item sprite sheets
+├── music/                         # Background music (OGG)
+├── sound/                         # Sound effects (WAV)
+├── logo/                          # Logo images
+├── loading/                       # Loading screen graphics
+├── title/                         # Title screen graphics
+├── ending/                        # Ending sequence images
+└── credits/                       # Credits screen assets
+```
+
+---
+
+## 3. Key Architectural Patterns
+
+### 3.1 Singleton Pattern (Core Systems)
+
+Most core systems use thread-safe singleton pattern:
+
+```cpp
+class Screen {
+    private:
+        static Screen* screen_;  // Singleton instance
+        Screen();                // Private constructor
+        ~Screen();
+    public:
+        static void init();      // Creates singleton
+        static void destroy();   // Destroys singleton
+        static Screen* get();    // Accesses singleton
+};
+```
+
+**Singleton Systems:**
+- `Screen` - Rendering, window management, palette/shader effects
+- `Input` - Keyboard & gamepad input binding and checking
+- `Audio` - Music and sound effect playback
+- `Resource` - Asset loading, caching, streaming
+- `Asset` - Asset path registry and verification
+- `Director` - Main application controller
+- `Cheevos` - Achievement state management
+- `Debug` - Debug information overlay
+
+### 3.2 Scene-Based State Machine
+
+The game uses a scene manager to control application flow:
+
+```cpp
+// namespace SceneManager
+enum class Scene {
+    LOGO, LOADING_SCREEN, TITLE, CREDITS, GAME, DEMO, 
+    GAME_OVER, ENDING, ENDING2, QUIT
+};
+
+inline Scene current = Scene::LOGO;  // Global scene state
+inline Options options = ...;        // Transition options
+```
+
+**Scene Hierarchy:**
+- Each scene runs its own update/render loop
+- `Director` switches between scenes based on `SceneManager::current`
+- Scenes can request transitions via `SceneManager::current` assignment
+
+### 3.3 Entity-Component Pattern (Simplified)
+
+Entities (Player, Enemies, Items) have:
+- **Update** - Logic, physics, animation
+- **Render** - Draw to screen surface
+- **Collision** - Hit detection (player collides with room, enemies, items)
+
+### 3.4 Surface-Based Rendering Pipeline
+
+The rendering system uses a **8-bit indexed color** pipeline:
+
+```
+SurfaceData (pixel buffer)
+     ↓
+Surface (palette + rendering operations)
+     ↓
+SDL_Texture (GPU texture)
+     ↓
+SDL_Renderer (to SDL_Window)
+     ↓
+Display
+```
+
+**Key Components:**
+- `Surface` - 8-bit indexed pixel buffer with palette support
+- `SurfaceSprite` - Renders a fixed region of a surface
+- `SurfaceAnimatedSprite` - Frame-based animation on top of sprite
+- `SurfaceMovingSprite` - Adds velocity/position to animated sprite
+- Supports color replacement, palette swapping, and shader effects (CRT)
+
+### 3.5 Tile-Based Collision System
+
+Rooms use a sophisticated collision detection system:
+
+```cpp
+class Room {
+    std::vector<LineHorizontal> bottom_floors_;   // Ground surfaces
+    std::vector<LineHorizontal> top_floors_;      // Ceiling surfaces
+    std::vector<LineVertical> left_walls_;        // Left walls
+    std::vector<LineVertical> right_walls_;       // Right walls
+    std::vector<LineDiagonal> left_slopes_;       // Ramps going left
+    std::vector<LineDiagonal> right_slopes_;      // Ramps going right
+    std::vector<LineHorizontal> conveyor_belt_floors_; // Moving platforms
+};
+```
+
+**Collision Detection:**
+- Player has collision points and "feet" points for fine-grained detection
+- Room provides `check*Surfaces()` methods for collision resolution
+- Supports ramps, slopes, conveyor belts, and auto-surfaces
+- Enemies have axis-aligned bounding boxes
+
+### 3.6 Sprite Animation System
+
+Animation is data-driven:
+
+```cpp
+struct AnimationData {
+    std::string name;
+    std::vector<SDL_FRect> frames;  // Frame rectangles
+    int speed;                       // Milliseconds per frame
+    int loop;                        // Frame to return to (-1 = no loop)
+    bool completed;
+    int current_frame;
+    int counter;
+};
+
+// Loaded from .ani files (list of animation names)
+// Rendered with SurfaceAnimatedSprite
+```
+
+---
+
+## 4. System Interactions & Data Flow
+
+### 4.1 Application Lifecycle
+
+```
+main()
+  ↓
+Director::Director()  [Initialization]
+  ├─ Options::init()         - Load game configuration
+  ├─ Asset::init()           - Register asset paths
+  ├─ Screen::init()          - Create window, SDL renderer
+  ├─ Audio::init()           - Initialize SDL audio
+  ├─ Input::init()           - Bind keyboard/gamepad controls
+  ├─ Resource::init()        - Load all game resources
+  └─ Cheevos::init()         - Load achievement state
+
+Director::run()        [Main loop]
+  ├─ while (SceneManager::current != QUIT)
+  │   ├─ Logo::run()
+  │   ├─ LoadingScreen::run()
+  │   ├─ Title::run()
+  │   ├─ Game::run()
+  │   ├─ Ending::run()
+  │   └─ ...
+  └─ return 0
+
+Director::~Director() [Cleanup]
+  ├─ Options::saveToFile()   - Save game settings
+  ├─ Resource::destroy()
+  ├─ Audio::destroy()
+  ├─ Input::destroy()
+  ├─ Screen::destroy()
+  └─ Asset::destroy()
+```
+
+### 4.2 Game Scene Flow (Core Gameplay Loop)
+
+```cpp
+Game::run() {
+    while (game is running) {
+        // Update
+        Input::checkInput()          - Get player commands
+        Player::update()             - Physics, animation, collision
+        Room::update()               - Enemy AI, animated tiles
+        checkCollisions()            - Player vs enemies, items, room
+        checkGameOver()              - Win/lose conditions
+        
+        // Render
+        Screen::start()              - Prepare for drawing
+        Room::renderMap()            - Draw tilemap
+        Room::renderEnemies()        - Draw enemy sprites
+        Room::renderItems()          - Draw item sprites
+        Player::render()             - Draw player sprite
+        renderScoreboard()           - Draw HUD
+        Screen::render()             - Flush to GPU
+    }
+}
+```
+
+### 4.3 Resource Loading & Caching
+
+```
+Director::setFileList()
+  ├─ Asset::add(file, type)  - Register all assets
+  └─ Asset::check()          - Verify files exist
+
+Game Scene initialization
+  └─ Resource::init()        - Loads all resources
+      ├─ loadSounds()        - WAV files
+      ├─ loadMusics()        - OGG files  
+      ├─ loadSurfaces()      - GIF/PNG images
+      ├─ loadAnimations()    - .ani animation definitions
+      ├─ loadTileMaps()      - .room tilemap data
+      └─ loadRooms()         - Room metadata
+
+During gameplay
+  └─ Resource::get*(name)    - Return cached resource
+```
+
+### 4.4 Input Flow
+
+```
+SDL_Event (from OS)
+  ↓
+Input::checkInput(action)
+  ├─ Check keyboard bindings      - SDL_Scancode → InputAction
+  ├─ Check gamepad bindings       - SDL_GamepadButton → InputAction
+  └─ Return true if action active
+
+Game logic uses checked inputs
+  └─ Player responds to actions
+```
+
+### 4.5 Audio Control Flow
+
+```
+Game code
+  ├─ Audio::playMusic(name, loop)
+  ├─ Audio::playSound(name, group)
+  └─ Audio::stopMusic()
+      ↓
+    Audio [wrapper/manager]
+      ├─ Resource::getMusic(name)
+      ├─ Resource::getSound(name)
+      └─ jail_audio C library
+          └─ SDL3 Audio device
+```
+
+---
+
+## 5. Important Design Patterns & Conventions
+
+### 5.1 Naming Conventions
+
+**Classes:**
+- `PascalCase` for classes: `Player`, `Room`, `Screen`, `Director`
+- Suffix `Sprite` for sprite classes: `SurfaceSprite`, `SurfaceAnimatedSprite`
+
+**Methods:**
+- `get*()` for getters: `getWidth()`, `getRect()`
+- `set*()` for setters: `setColor()`, `setPos()`
+- `check*()` for boolean checks: `checkInput()`, `checkCollision()`
+- `update()` for game logic updates
+- `render()` for drawing
+
+**Variables:**
+- `snake_case` for member variables with `_` suffix: `x_`, `y_`, `sprite_`
+- `UPPER_CASE` for constants: `BLOCK`, `MAX_VY_`, `WIDTH_`
+- Private members: `private_member_`
+
+**Structs for Data:**
+- `XxxData` suffix: `PlayerData`, `RoomData`, `AnimationData`
+- Used as initialization structures passed to constructors
+
+### 5.2 Memory Management
+
+- **Smart Pointers:** Uses `std::shared_ptr` for shared ownership (Surfaces, Sprites, Rooms)
+- **Unique Pointers:** Uses `std::unique_ptr` for sole ownership (Director, local objects)
+- **Raw Pointers:** Minimal use, mainly for singleton access or SDL objects
+- **Static Allocation:** Singletons use static pointer pattern for RAII
+
+### 5.3 Frame-Independent Physics
+
+Uses `DeltaTimer` for delta time calculation:
+
+```cpp
+// In game loop
+float delta = deltaTimer.tick();  // Get seconds since last frame
+
+// Apply to physics
+player.vy_ += gravity * delta;
+player.y_ += player.vy_ * delta;
+```
+
+Provides **time scaling** for slow-motion effects.
+
+### 5.4 Palette System
+
+- 8-bit indexed color (256 colors per palette)
+- Multiple palettes can be loaded and swapped
+- `Surface::setPalette()` changes rendering colors
+- Supports color replacement per-render: `renderWithColorReplace()`
+- CRT shader effects can modify colors in real-time
+
+### 5.5 Configuration System
+
+Game settings stored in configuration file:
+
+```cpp
+namespace Options {
+    inline Video video{};           // Screen resolution, fullscreen, etc.
+    inline Audio audio{};           // Music/sound volumes
+    inline Notification notifications{};
+    inline Cheat cheats{};          // Cheat codes
+    inline ControlScheme keys{};    // Control mapping
+    inline Stats stats{};           // Game statistics
+}
+
+Options::loadFromFile(path);  // Load from config.txt
+Options::saveToFile(path);    // Save on exit
+```
+
+### 5.6 Achievement System
+
+```cpp
+struct Achievement {
+    int id;
+    std::string caption;
+    std::string description;
+    int icon;
+    bool completed;
+    bool obtainable;
+};
+
+Cheevos::unlock(id);           // Unlock achievement
+Cheevos::setUnobtainable(id);  // Lock achievement
+Cheevos::saveToFile();         // Persist state
+```
+
+Achievements trigger notifications on unlock.
+
+---
+
+## 6. Technology Stack
+
+### Core Technologies
+
+| Component | Technology | Version | Role |
+|-----------|-----------|---------|------|
+| **Graphics** | SDL3 | Latest | Window, rendering, input |
+| **GPU Rendering** | OpenGL | 3.2+ | Shader effects (CRT) |
+| **Audio** | SDL3 Audio | Latest | Audio device, mixing |
+| **Audio Decoding** | jail_audio (custom) | 1.x | OGG/WAV playback |
+| **Image Loading** | stb_image | v2.x | PNG/GIF image loading |
+| **Audio Decoding** | stb_vorbis | v1.x | OGG Vorbis support |
+| **Language** | C++ | C++20 | Standard library features |
+| **Build System** | CMake | 3.10+ | Cross-platform building |
+
+### C++ Features Used
+
+- **Smart Pointers:** `std::shared_ptr`, `std::unique_ptr`
+- **Standard Containers:** `std::vector`, `std::array`
+- **Modern Features:** `std::move`, lambda functions, constexpr
+- **Namespaces:** Extensive use for organization
+- **Inline Variables:** C++17 `inline` for global game state
+
+### Platform Support
+
+- **Windows:** MinGW/MSVC with SDL3
+- **macOS:** Apple Clang, arm64 architecture, OpenGL
+- **Linux:** GCC with SDL3 and OpenGL
+
+---
+
+## 7. Key Classes & Their Responsibilities
+
+### Core System Classes
+
+| Class | Purpose | Pattern |
+|-------|---------|---------|
+| `Director` | Main application controller, scene manager | Singleton |
+| `Screen` | Rendering, window, palette management | Singleton |
+| `Input` | Keyboard & gamepad input | Singleton |
+| `Audio` | Music and SFX playback | Singleton |
+| `Resource` | Asset caching and loading | Singleton |
+| `Asset` | Asset path registry | Singleton |
+| `Debug` | Debug overlay information | Singleton |
+| `globalEvents` | Global SDL event handling (quit, device reset, mouse) | Namespace |
+
+### Game Logic Classes
+
+| Class | Purpose |
+|-------|---------|
+| `Game` | Main gameplay scene, orchestrates update/render |
+| `Player` | Player entity with physics and animation |
+| `Room` | Level data, collision detection, tilemap rendering |
+| `Enemy` | Enemy entity behavior and rendering |
+| `Item` | Collectible items |
+| `Scoreboard` | HUD display data |
+| `Cheevos` | Achievement unlock and state |
+| `ItemTracker` | Tracks collected items |
+| `RoomTracker` | Tracks visited rooms |
+
+### Rendering Classes
+
+| Class | Purpose |
+|-------|---------|
+| `Surface` | 8-bit indexed color pixel buffer with palette |
+| `SurfaceSprite` | Renders a sprite region |
+| `SurfaceAnimatedSprite` | Frame-based animation rendering |
+| `SurfaceMovingSprite` | Sprite with velocity/position |
+| `Text` | Text rendering system |
+| `OpenGLShader` | Shader compilation and effects |
+
+### Utility Classes
+
+| Class | Purpose |
+|-------|---------|
+| `DeltaTimer` | Frame-rate independent timing |
+
+---
+
+## 8. Common Development Workflows
+
+### Adding a New Input Action
+
+1. Add to `InputAction` enum in `core/input/input.hpp`
+2. Bind in `Director::initInput()`:
+   ```cpp
+   Input::get()->bindKey(InputAction::NEW_ACTION, SDL_SCANCODE_X);
+   ```
+3. Check in game code:
+   ```cpp
+   if (Input::get()->checkInput(InputAction::NEW_ACTION)) {
+       // Handle action
+   }
+   ```
+
+### Adding a New Scene
+
+1. Create class inheriting appropriate base (usually standalone `run()` method)
+2. Add to `SceneManager::Scene` enum
+3. Implement in `Director::run()` switch statement
+4. Set `SceneManager::current` to transition
+
+### Adding Game Assets
+
+1. Place file in `data/` directory
+2. Register in `Director::setFileList()`:
+   ```cpp
+   Asset::get()->add("/data/path/file.ext", AssetType::TYPE);
+   ```
+3. Resource loads automatically during `Resource::init()`
+4. Access via: `Resource::get()->getSurface("name")`
+
+### Modifying Collision Detection
+
+1. Update `Room::setBottomSurfaces()`, `setLeftSlopes()`, etc.
+2. Modify Player collision point generation in `Player::updateColliderPoints()`
+3. Adjust tile classification in `TileType` enum
+4. Test with debug visualization (F12 key)
+
+---
+
+## 9. Debug Features
+
+### Available at Runtime
+
+- **F12** - Toggle debug info overlay (FPS, player position, collision points)
+- **F1/F2** - Decrease/increase window zoom
+- **F3** - Toggle fullscreen mode
+- **F4** - Toggle shader effects
+- **F5/F6** - Next/previous palette
+- **F7** - Toggle integer scaling
+- **M** - Toggle music
+- **B** - Toggle border display
+- **P** - Pause game
+
+### Debug Mode Compilation
+
+In debug builds (`#ifdef DEBUG`), renders:
+- Player collision boxes
+- Collision point visualization
+- Debug information overlay
+- Special debug event handling
+
+---
+
+## 10. Performance Considerations
+
+### Optimization Points
+
+1. **Rendering:** Uses indexed color (8-bit) to reduce memory bandwidth
+2. **Surfaces:** Shared smart pointers reduce copying
+3. **Collision:** Pre-computed tile surface lists avoid per-frame searches
+4. **Animation:** Frame-based animation reduces computation vs. bone systems
+5. **Audio:** Cached music and sound effects, no runtime decoding
+6. **Delta Time:** Frame-rate independent logic for smooth gameplay
+
+### Known Limitations
+
+- Single-threaded architecture (SDL3 requires single-thread rendering)
+- Surfaces stored entirely in CPU memory (not GPU-side textures)
+- Palette system requires full surface redraw when changing colors
+
+---
+
+## 11. File Format Reference
+
+### Animation Files (.ani)
+List of animation names, one per line:
+```
+default
+jump
+run
+fall
+```
+
+### Room Data Files (.room)
+Key-value pairs defining room properties:
+```
+number=01
+name=Starting Room
+bg_color=0x000000
+border_color=0xFF00FF
+...
+```
+
+### Tilemap Files (.tmx)
+Tiled map format with tileset and collision data.
+
+### Palette Files (.pal)
+Binary 256-color palette format (256 × 4 bytes RGBA).
+
+---
+
+## 12. Quick Reference: Main Entry Points
+
+### For Graphics Issues
+- `Screen::render()` - Main rendering method
+- `Screen::setPalete()` - Palette application
+- `Surface` class - Pixel buffer operations
+
+### For Input Issues
+- `Input::checkInput()` - Input state checking
+- `Director::initInput()` - Binding configuration
+
+### For Audio Issues
+- `Audio::playMusic()` - Music playback
+- `Audio::playSound()` - SFX playback
+- `jail_audio` library - Low-level audio operations
+
+### For Game Logic
+- `Game::run()` - Main game loop
+- `Room` class - Collision and level logic
+- `Player::update()` - Physics and movement
+
+### For Asset Management
+- `Asset::add()` - Asset registration
+- `Resource::load()` - Asset loading
+- `Director::setFileList()` - Complete asset registry
+
+---
+
+## 13. Future Enhancement Points
+
+### Identified Areas for Expansion
+
+1. **Network Play:** Stats upload to online service
+2. **More Scenes:** Additional game modes
+3. **Custom Rooms:** Level editor integration
+4. **Audio Streaming:** Background music without loading entire file
+5. **Particle System:** Visual effects for pickups/collisions
+6. **Controller Feedback:** Haptic feedback for game events
+7. **Accessibility:** Font scaling, color-blind modes, key remapping UI
+
+---
+
+## Development Notes
+
+- **Language:** All code comments and some variable names are in Spanish (maintaining original author style)
+- **Compilation:** Use CMake - automatically handles platform differences
+- **Performance Profiling:** Use debug overlay (F12) for basic metrics; consider external profilers for deeper analysis
+- **Common Warnings:** The codebase has been cleaned of the `struct`/`class` forward declaration inconsistency warnings that previously appeared
+
+### Important Code Consistency Rules
+
+1. **Forward Declarations:** Always use `class` for forward declarations of classes defined with `class` (not `struct`). The `Surface` class is defined as `class Surface` in `surface.hpp:57`, so all forward declarations must use `class Surface;`
+
+2. **Singleton Pattern:** When creating new singletons, follow the existing pattern:
+   - Private static instance pointer
+   - Private constructor/destructor
+   - Public `init()`, `destroy()`, and `get()` methods
+
+3. **Delta Time:** Always use `DeltaTimer` for frame-rate independent physics calculations
+
+4. **Memory Management:** Prefer `std::shared_ptr` for shared resources (Surfaces, Sprites) and `std::unique_ptr` for sole ownership
+
+---
+
+**Last Updated:** November 2022 (per README)
+**Original Author:** JailDesigner
+**Repository:** Gitea (internal)
diff --git a/CMakeLists.txt b/CMakeLists.txt
index d346a26..e64f5b1 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -58,6 +58,7 @@ set(APP_SOURCES
     # Core - System
     source/core/system/debug.cpp
     source/core/system/director.cpp
+    source/core/system/global_events.cpp
 
     # Game - Entities
     source/game/entities/enemy.cpp
@@ -90,7 +91,6 @@ set(APP_SOURCES
 
     # Utils
     source/utils/delta_timer.cpp
-    source/utils/global_events.cpp
     source/utils/utils.cpp
 
     # Main
diff --git a/source/core/rendering/screen.hpp b/source/core/rendering/screen.hpp
index e3fdc6e..c73f89d 100644
--- a/source/core/rendering/screen.hpp
+++ b/source/core/rendering/screen.hpp
@@ -8,7 +8,7 @@
 #include <vector>  // Para vector
 
 #include "utils/utils.hpp"  // Para Color
-struct Surface;
+class Surface;
 namespace Rendering {
 class ShaderBackend;
 }
diff --git a/source/utils/global_events.cpp b/source/core/system/global_events.cpp
similarity index 94%
rename from source/utils/global_events.cpp
rename to source/core/system/global_events.cpp
index 49e3984..8e2b754 100644
--- a/source/utils/global_events.cpp
+++ b/source/core/system/global_events.cpp
@@ -1,6 +1,6 @@
 #include "game/scene_manager.hpp"  // Para SceneManager
 
-#include "utils/global_events.hpp"
+#include "core/system/global_events.hpp"
 
 #include "core/input/mouse.hpp"
 #include "game/options.hpp"  // Para Options, options, OptionsGame, OptionsAudio
diff --git a/source/utils/global_events.hpp b/source/core/system/global_events.hpp
similarity index 100%
rename from source/utils/global_events.hpp
rename to source/core/system/global_events.hpp
diff --git a/source/game/scenes/credits.cpp b/source/game/scenes/credits.cpp
index d225f3e..c90cff1 100644
--- a/source/game/scenes/credits.cpp
+++ b/source/game/scenes/credits.cpp
@@ -13,7 +13,7 @@
 #include "game/options.hpp"                            // Para Options, options, OptionsGame, Sectio...
 #include "game/scene_manager.hpp"                      // Para SceneManager
 #include "utils/defines.hpp"                           // Para GAME_SPEED, PLAY_AREA_CENTER_X, PLAY_...
-#include "utils/global_events.hpp"                     // Para check
+#include "core/system/global_events.hpp"               // Para check
 #include "utils/utils.hpp"                             // Para PaletteColor
 
 // Constructor
diff --git a/source/game/scenes/ending.cpp b/source/game/scenes/ending.cpp
index 5a9d249..9676b4f 100644
--- a/source/game/scenes/ending.cpp
+++ b/source/game/scenes/ending.cpp
@@ -14,7 +14,7 @@
 #include "game/options.hpp"                   // Para Options, options, OptionsGame, SectionS...
 #include "game/scene_manager.hpp"             // Para SceneManager
 #include "utils/defines.hpp"                  // Para GAME_SPEED
-#include "utils/global_events.hpp"            // Para check
+#include "core/system/global_events.hpp"      // Para check
 #include "utils/utils.hpp"                    // Para PaletteColor
 
 // Constructor
diff --git a/source/game/scenes/ending2.cpp b/source/game/scenes/ending2.cpp
index 27826a1..33a3f38 100644
--- a/source/game/scenes/ending2.cpp
+++ b/source/game/scenes/ending2.cpp
@@ -15,7 +15,7 @@
 #include "game/options.hpp"                            // Para Options, options, OptionsGame, Sectio...
 #include "game/scene_manager.hpp"                      // Para SceneManager
 #include "utils/defines.hpp"                           // Para GAMECANVAS_CENTER_X, GAMECANVAS_CENTER_Y
-#include "utils/global_events.hpp"                     // Para check
+#include "core/system/global_events.hpp"               // Para check
 #include "utils/utils.hpp"                             // Para PaletteColor, stringToColor
 
 // Constructor
diff --git a/source/game/scenes/game.cpp b/source/game/scenes/game.cpp
index 8a62560..f5cff2f 100644
--- a/source/game/scenes/game.cpp
+++ b/source/game/scenes/game.cpp
@@ -24,7 +24,7 @@
 #include "game/gameplay/stats.hpp"         // Para Stats
 #include "game/ui/notifier.hpp"            // Para Notifier, NotificationText, CHEEVO_NO...
 #include "utils/defines.hpp"               // Para BLOCK, PLAY_AREA_HEIGHT, RoomBorder::BOTTOM
-#include "utils/global_events.hpp"         // Para check
+#include "core/system/global_events.hpp"   // Para check
 #include "utils/utils.hpp"                 // Para PaletteColor, stringToColor
 
 // Constructor
diff --git a/source/game/scenes/game_over.cpp b/source/game/scenes/game_over.cpp
index a4748f5..f1fd069 100644
--- a/source/game/scenes/game_over.cpp
+++ b/source/game/scenes/game_over.cpp
@@ -14,7 +14,7 @@
 #include "game/options.hpp"                            // Para Options, options, OptionsStats, Secti...
 #include "game/scene_manager.hpp"                      // Para SceneManager
 #include "utils/defines.hpp"                           // Para GAMECANVAS_CENTER_X, GAME_SPEED
-#include "utils/global_events.hpp"                     // Para check
+#include "core/system/global_events.hpp"               // Para check
 #include "utils/utils.hpp"                             // Para PaletteColor, stringToColor
 
 // Constructor
diff --git a/source/game/scenes/loading_screen.cpp b/source/game/scenes/loading_screen.cpp
index 4010674..24c8479 100644
--- a/source/game/scenes/loading_screen.cpp
+++ b/source/game/scenes/loading_screen.cpp
@@ -12,7 +12,7 @@
 #include "game/options.hpp"                   // Para Options, options, SectionState, Options...
 #include "game/scene_manager.hpp"             // Para SceneManager
 #include "utils/defines.hpp"                  // Para GAME_SPEED
-#include "utils/global_events.hpp"            // Para check
+#include "core/system/global_events.hpp"      // Para check
 #include "utils/utils.hpp"                    // Para stringToColor, PaletteColor
 
 // Constructor
diff --git a/source/game/scenes/logo.cpp b/source/game/scenes/logo.cpp
index 303c781..234babb 100644
--- a/source/game/scenes/logo.cpp
+++ b/source/game/scenes/logo.cpp
@@ -12,7 +12,7 @@
 #include "game/options.hpp"                   // Para Options, SectionState, options, Section
 #include "game/scene_manager.hpp"             // Para SceneManager
 #include "utils/delta_timer.hpp"              // Para DeltaTimer
-#include "utils/global_events.hpp"            // Para check
+#include "core/system/global_events.hpp"      // Para check
 #include "utils/utils.hpp"                    // Para PaletteColor
 
 // Constructor
diff --git a/source/game/scenes/title.cpp b/source/game/scenes/title.cpp
index 425a3e5..5a76662 100644
--- a/source/game/scenes/title.cpp
+++ b/source/game/scenes/title.cpp
@@ -15,7 +15,7 @@
 #include "game/options.hpp"                   // Para Options, options, SectionState, Section
 #include "game/scene_manager.hpp"             // Para SceneManager
 #include "utils/defines.hpp"                  // Para PLAY_AREA_CENTER_X, GAMECANVAS_WIDTH
-#include "utils/global_events.hpp"            // Para check
+#include "core/system/global_events.hpp"      // Para check
 #include "utils/utils.hpp"                    // Para stringToColor, PaletteColor, playMusic
 
 // Constructor