# Echoes of the Ashes - Documentation Index

## 📚 Documentation Overview

This directory contains all project documentation organized by category.

## 📁 Directory Structure

### `/docs/development/`
Technical documentation for developers

- **[BOT_MODULE.md](development/BOT_MODULE.md)** - Bot module architecture and handler system
- **[HANDLER_REFACTORING_SUMMARY.md](development/HANDLER_REFACTORING_SUMMARY.md)** - Code refactoring summary
- **[REFACTORING_NOTES.md](development/REFACTORING_NOTES.md)** - Detailed refactoring notes
- **[VISUAL_IMPROVEMENTS.md](development/VISUAL_IMPROVEMENTS.md)** - UI improvements and progress bars
- **[UI_EXAMPLES.md](development/UI_EXAMPLES.md)** - Before/after UI comparisons and visual mockups

### `/docs/game/`
Game design and mechanics documentation

- **[MECHANICS.md](game/MECHANICS.md)** - Complete game mechanics overview

### `/docs/api/`
API documentation and integration guides

- **Telegram Bot API** - Bot command reference
- **Database Schema** - Data models and relationships
- **Web Map Editor** - Map editor API and usage

## 🚀 Quick Links

### For Developers
- [Bot Module Documentation](development/BOT_MODULE.md) - Start here to understand the codebase
- [Handler System](development/HANDLER_REFACTORING_SUMMARY.md) - Handler architecture
- [Contributing Guide](../README.md#contributing) - How to contribute

### For Game Designers
- [Game Mechanics](game/) - Game systems and balance
- [World Editor](../web-map/README.md) - Map editing guide

### For Players
- [README](../README.md) - Project overview and setup
- [Game Guide](game/) - How to play

## 📝 Documentation Standards

### Markdown Guidelines
- Use clear, descriptive headings
- Include code examples where relevant
- Keep lines under 100 characters for readability
- Use emoji sparingly for visual organization

### File Naming
- Use `SCREAMING_SNAKE_CASE.md` for major documentation
- Use `PascalCase.md` for component-specific docs
- Use `kebab-case.md` for guides and tutorials

### Document Structure
```markdown
# Title

## Overview
Brief description

## Table of Contents
- [Section 1](#section-1)
- [Section 2](#section-2)

## Content
Detailed information

## See Also
Related documentation
```

## 🔄 Recent Updates

### October 19, 2025
- ✅ Reorganized documentation into structured folders
- ✅ Created documentation index (this file)
- ✅ Moved development docs from root to docs/development/
- ✅ **Added visual HP/Stamina bars** - Progress bars for better UI feedback
- ✅ Refactored handler system into modular architecture
- ✅ Created comprehensive bot module documentation
- ✅ Added utility functions for visual progress displays

### October 18, 2025
- ✅ Refactored handler system into modular architecture
- ✅ Created comprehensive bot module documentation
- ✅ Added refactoring notes and summaries

## 📖 Contributing to Documentation

When adding new documentation:

1. **Choose the right folder:**
   - `development/` - Technical/code documentation
   - `game/` - Game design and mechanics
   - `api/` - API references and integration

2. **Update this index** with links to new documents

3. **Follow naming conventions** as outlined above

4. **Include:**
   - Clear title and overview
   - Table of contents for longer docs
   - Code examples where applicable
   - Links to related documentation

5. **Keep it updated** - Documentation should match the code

## 🔍 Finding Documentation

### By Topic
- **Setup & Installation** → [README.md](../README.md)
- **Bot Development** → [development/BOT_MODULE.md](development/BOT_MODULE.md)
- **Code Architecture** → [development/](development/)
- **Game Mechanics** → [game/](game/)
- **Map Editor** → [../web-map/README.md](../web-map/README.md)
- **Database** → [api/](api/)

### By File Type
- **README files** - Quick overviews and getting started guides
- **Technical specs** - Detailed architecture and implementation
- **Guides** - Step-by-step tutorials
- **Reference** - API documentation and data schemas

## 📧 Questions?

If you can't find what you're looking for:
1. Check the [main README](../README.md)
2. Search through existing documentation
3. Look at code comments and docstrings
4. Create an issue for missing documentation

---

**Last Updated:** October 19, 2025  
**Maintained by:** Development Team