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/HANDLER_REFACTORING_SUMMARY.md

@@ -0,0 +1,180 @@
+# Handler Refactoring Summary
+
+## Code Metrics
+
+### Before Refactoring
+- **Single file:** `bot/handlers.py` (~1,308 lines)
+- **Giant function:** `button_handler()` with 1000+ lines of if/elif chains
+- **Maintainability:** Very difficult to navigate and modify
+
+### After Refactoring
+- **7 organized modules:** Total ~1,786 lines (well-structured)
+- **Main router:** `handlers.py` (377 lines) - clean routing logic
+- **6 specialized modules:**
+  - `action_handlers.py` (367 lines) - World interaction
+  - `inventory_handlers.py` (355 lines) - Inventory management
+  - `corpse_handlers.py` (234 lines) - Corpse looting
+  - `combat_handlers.py` (171 lines) - Combat actions
+  - `profile_handlers.py` (147 lines) - Profile & stats
+  - `pickup_handlers.py` (135 lines) - Item pickup
+
+## Architecture
+
+```
+bot/
+├── handlers.py              # Main router & utilities
+│   ├── send_or_edit_with_image()
+│   ├── start()
+│   ├── export_map()
+│   ├── spawn_stats()
+│   └── button_handler()     # Routes to specialized handlers
+│
+├── action_handlers.py       # World & Inspection
+│   ├── get_player_status_text()
+│   ├── handle_inspect_area()
+│   ├── handle_attack_wandering()
+│   ├── handle_inspect_interactable()
+│   ├── handle_action()
+│   ├── handle_main_menu()
+│   ├── handle_move_menu()
+│   └── handle_move()
+│
+├── inventory_handlers.py    # Inventory Management
+│   ├── handle_inventory_menu()
+│   ├── handle_inventory_item()
+│   ├── handle_inventory_use()
+│   ├── handle_inventory_drop()
+│   ├── handle_inventory_equip()
+│   └── handle_inventory_unequip()
+│
+├── pickup_handlers.py       # Item Collection
+│   ├── handle_pickup_menu()
+│   └── handle_pickup()
+│
+├── combat_handlers.py       # Combat System
+│   ├── handle_combat_attack()
+│   ├── handle_combat_flee()
+│   ├── handle_combat_use_item_menu()
+│   ├── handle_combat_use_item()
+│   └── handle_combat_back()
+│
+├── profile_handlers.py      # Character Stats
+│   ├── handle_profile()
+│   ├── handle_spend_points_menu()
+│   └── handle_spend_point()
+│
+└── corpse_handlers.py       # Looting System
+    ├── handle_loot_player_corpse()
+    ├── handle_take_corpse_item()
+    ├── handle_scavenge_npc_corpse()
+    └── handle_scavenge_corpse_item()
+```
+
+## Key Improvements
+
+### 1. Separation of Concerns
+Each module handles a specific domain of functionality:
+- **Action Handlers** → World exploration & interaction
+- **Inventory Handlers** → Item management
+- **Combat Handlers** → Battle mechanics
+- **Profile Handlers** → Character progression
+- **Corpse Handlers** → Looting system
+- **Pickup Handlers** → Item collection
+
+### 2. Single Responsibility Principle
+Each function has one clear purpose:
+- ✅ `handle_inventory_use()` - Use items
+- ✅ `handle_combat_attack()` - Attack in combat
+- ✅ `handle_pickup()` - Pick up items
+- ❌ ~~`button_handler()` - Do everything~~
+
+### 3. Improved Error Handling
+```python
+# Centralized error handling in router
+try:
+    if action_type == "inspect_area":
+        await handle_inspect_area(query, user_id, player)
+    # ... more routes
+except Exception as e:
+    logger.error(f"Error handling {action_type}: {e}", exc_info=True)
+    await query.answer("An error occurred.", show_alert=True)
+```
+
+### 4. Better Code Navigation
+- Jump to specific functionality in seconds
+- IDE autocomplete works better
+- Easier to review code changes
+- Reduced cognitive load
+
+### 5. Testability
+Each handler can now be tested independently:
+```python
+# Easy to test
+await handle_inventory_use(mock_query, user_id, player, data)
+
+# vs. testing 1000 lines of if/elif
+```
+
+## Migration Path
+
+All functionality has been preserved. The refactoring only changed the organization, not the behavior.
+
+### Verified Compatible
+- ✅ All action types still handled
+- ✅ Same function signatures
+- ✅ Same error handling behavior
+- ✅ No breaking changes to external code
+
+### Backup Files
+Original files saved in `backups/`:
+- `handlers_original.py`
+- `handlers.py.old`
+
+## Future Enhancements
+
+1. **Add Type Hints**
+   ```python
+   async def handle_inventory_use(
+       query: CallbackQuery,
+       user_id: int,
+       player: dict,
+       data: list[str]
+   ) -> None:
+   ```
+
+2. **Create Base Handler Class**
+   ```python
+   class BaseHandler:
+       def __init__(self, query, user_id, player):
+           self.query = query
+           self.user_id = user_id
+           self.player = player
+   ```
+
+3. **Add Unit Tests**
+   ```python
+   def test_handle_inventory_use():
+       # Test consumable usage
+       # Test inventory updates
+       # Test error cases
+   ```
+
+4. **Add Handler Decorators**
+   ```python
+   @requires_combat
+   async def handle_combat_attack(...):
+   
+   @requires_stamina(10)
+   async def handle_action(...):
+   ```
+
+## Conclusion
+
+This refactoring transforms a monolithic 1,308-line file with a 1000+ line function into a well-organized, modular architecture with:
+- ✅ Clear separation of concerns
+- ✅ Easy navigation and maintenance
+- ✅ Better error handling
+- ✅ Improved testability
+- ✅ No breaking changes
+
+**Result:** The codebase is now much easier to understand, modify, and extend.