Add visual progress bars and refactor handler modules

- Implement visual HP/Stamina/XP bars using Unicode characters (██░)
- Refactor handlers.py (1308 → 377 lines) into specialized modules:
  * action_handlers.py - World interaction and status display
  * inventory_handlers.py - Inventory management
  * combat_handlers.py - Combat actions
  * profile_handlers.py - Character stats with visual bars
  * corpse_handlers.py - Looting system
  * pickup_handlers.py - Item collection
- Add utility functions: create_progress_bar(), format_stat_bar()
- Organize all documentation into docs/ structure
- Create comprehensive documentation index with navigation
- Add UI examples showing before/after visual improvements

docs/development/REFACTORING_NOTES.md

@@ -0,0 +1,127 @@
+# Code Refactoring - Handler Organization
+
+## Overview
+The `bot/handlers.py` file has been refactored to improve code organization, readability, and maintainability. The massive `button_handler` function (previously 1000+ lines) has been broken down into logical, focused modules.
+
+## New Structure
+
+### Main Module: `bot/handlers.py`
+**Purpose:** Core routing and utility functions
+- `send_or_edit_with_image()` - Image handling utility
+- `start()` - /start command handler
+- `export_map()` - Admin command for map export
+- `spawn_stats()` - Admin command for spawn statistics
+- `button_handler()` - Main router that delegates to specific handlers
+
+### Action Handlers: `bot/action_handlers.py`
+**Purpose:** World interaction and inspection
+- `get_player_status_text()` - Generate player status display
+- `handle_inspect_area()` - Inspect current location
+- `handle_attack_wandering()` - Attack wandering enemies
+- `handle_inspect_interactable()` - Inspect objects
+- `handle_action()` - Perform actions on interactables
+- `handle_main_menu()` - Return to main menu
+- `handle_move_menu()` - Show movement options
+- `handle_move()` - Handle player movement
+
+### Inventory Handlers: `bot/inventory_handlers.py`
+**Purpose:** Inventory management
+- `handle_inventory_menu()` - Show inventory
+- `handle_inventory_item()` - Show item details
+- `handle_inventory_use()` - Use consumable items
+- `handle_inventory_drop()` - Drop items to world
+- `handle_inventory_equip()` - Equip items
+- `handle_inventory_unequip()` - Unequip items
+
+### Pickup Handlers: `bot/pickup_handlers.py`
+**Purpose:** Item collection from world
+- `handle_pickup_menu()` - Show pickup options
+- `handle_pickup()` - Pick up dropped items
+
+### Combat Handlers: `bot/combat_handlers.py`
+**Purpose:** Combat actions
+- `handle_combat_attack()` - Attack enemy
+- `handle_combat_flee()` - Attempt to flee
+- `handle_combat_use_item_menu()` - Show usable items in combat
+- `handle_combat_use_item()` - Use item during combat
+- `handle_combat_back()` - Return to combat menu
+
+### Profile Handlers: `bot/profile_handlers.py`
+**Purpose:** Character profile and stat management
+- `handle_profile()` - Show player profile
+- `handle_spend_points_menu()` - Show stat point menu
+- `handle_spend_point()` - Spend stat points
+
+### Corpse Handlers: `bot/corpse_handlers.py`
+**Purpose:** Looting corpses
+- `handle_loot_player_corpse()` - Show player corpse loot
+- `handle_take_corpse_item()` - Take item from player corpse
+- `handle_scavenge_npc_corpse()` - Show NPC corpse loot
+- `handle_scavenge_corpse_item()` - Scavenge from NPC corpse
+
+## Benefits
+
+### 1. **Improved Readability**
+- Each module focuses on a specific domain
+- Function names clearly describe their purpose
+- Easier to find and understand specific functionality
+
+### 2. **Better Maintainability**
+- Changes to one feature don't affect others
+- Easier to test individual components
+- Reduced risk of merge conflicts
+
+### 3. **Logical Organization**
+- Related functions grouped together
+- Clear separation of concerns
+- Follows Single Responsibility Principle
+
+### 4. **Easier Navigation**
+- Jump to specific functionality quickly
+- No need to scroll through 1000+ lines
+- Clear module imports show dependencies
+
+### 5. **Error Handling**
+- Centralized error handling in router
+- Consistent error messages
+- Better logging
+
+## Migration Notes
+
+### Old Structure
+```python
+async def button_handler():
+    # 1000+ lines of if/elif statements
+    if action_type == "inspect_area":
+        # 50 lines of code
+    elif action_type == "inventory_menu":
+        # 30 lines of code
+    # ... hundreds more lines
+```
+
+### New Structure
+```python
+async def button_handler():
+    # Clean router - delegates to specialized handlers
+    if action_type == "inspect_area":
+        await handle_inspect_area(query, user_id, player)
+    elif action_type == "inventory_menu":
+        await handle_inventory_menu(query, user_id, player)
+```
+
+## Future Improvements
+
+1. **Add unit tests** for each handler module
+2. **Create handler base class** for common functionality
+3. **Add type hints** for better IDE support
+4. **Document return types** and error conditions
+5. **Add handler decorators** for common validations
+
+## Backup Files
+
+Old versions have been preserved in `backups/`:
+- `handlers_original.py` - Last version before refactoring
+- `handlers.py.old` - Additional backup
+
+## Date
+Refactored: October 19, 2025