# 📚 Documentation Index

Welcome to TribeGen! Here's what to read based on your needs.

## 🚀 I Want to Start Playing Now
→ Read **[START.md](START.md)** (2 min)
- Quick startup instructions
- Troubleshooting
- How to play

## 🎮 I Want to Understand the Game
→ Read **[GETTING_STARTED.md](GETTING_STARTED.md)** (10 min)
- Complete overview
- Features explained
- Code examples
- Testing checklist

## 🛠️ I Want to Develop & Add Features
→ Read **[ARCHITECTURE.md](ARCHITECTURE.md)** (15 min)
- System architecture
- Database schema
- How to add events
- How to add stats
- How to add injuries

## 📖 I Want Complete Feature Documentation
→ Read **[README.md](README.md)** (10 min)
- Full feature list
- Game mechanics
- Tech stack
- Installation options

## 🎯 I Want to See What's Ready & What's Not
→ Read **[DESIGN.md](DESIGN.md)** (8 min)
- What's implemented
- What's scaffolded
- Next steps
- Quick reference

## 💻 I Want API Documentation
→ Read **[API_REFERENCE.md](API_REFERENCE.md)** (10 min)
- All endpoints
- Request/response formats
- Data types
- Error codes

## 📋 I Want a Development Roadmap
→ Read **[TODO.md](TODO.md)** (5 min)
- Priority tasks
- Known issues
- Future ideas
- Testing commands

## 📊 I Want Project Statistics
→ Read **[PROJECT_SUMMARY.md](PROJECT_SUMMARY.md)** (8 min)
- File structure
- Features checklist
- Metrics
- Design patterns

## ⚙️ I Want to Setup & Configure
→ Read **[QUICKSTART.md](QUICKSTART.md)** (3 min)
- Different setup options
- Configuration
- Troubleshooting

---

## Reading Order (Recommended)

### For Players
1. **START.md** - Run the game
2. **QUICKSTART.md** - Game mechanics
3. **README.md** - Features

### For Developers
1. **START.md** - Get it running
2. **GETTING_STARTED.md** - Understand structure
3. **DESIGN.md** - See what's ready
4. **ARCHITECTURE.md** - Deep dive
5. **API_REFERENCE.md** - API details
6. **TODO.md** - What to build next

### For Architects
1. **PROJECT_SUMMARY.md** - Overview
2. **ARCHITECTURE.md** - Design details
3. **Database schema** - Data structure
4. **DESIGN.md** - Implementation notes

---

## Quick Reference

### File Types

| Extension | What | Where |
|-----------|------|-------|
| .php | Game code | `src/`, `public/` |
| .html | Web interface | `public/` |
| .css | Styling | `public/css/` |
| .js | Frontend logic | `public/js/` |
| .md | Documentation | Root directory |
| .json | Configuration | `assets/`, project root |
| .db | Database | `data/` |

### Directories

| Directory | Purpose |
|-----------|---------|
| `public/` | Web-accessible files (index.php, HTML, CSS, JS) |
| `src/` | Application code (classes, database, API) |
| `src/Classes/` | Game logic classes |
| `src/Database/` | Database management |
| `src/Events/` | Event system |
| `src/Utilities/` | Helper functions |
| `src/api/` | API endpoints |
| `assets/` | Game assets (sprites, images) |
| `data/` | Game database and user saves |

### Classes

| Class | Purpose | File |
|-------|---------|------|
| `User` | Authentication | `src/Classes/User.php` |
| `Kobold` | Character system | `src/Classes/Kobold.php` |
| `Tribe` | Tribe management | `src/Classes/Tribe.php` |
| `Item` | Item system | `src/Classes/Item.php` |
| `Injury` | Injury tracking | `src/Classes/Injury.php` |
| `NPC` | NPC system | `src/Classes/NPC.php` |
| `Event` | Base event class | `src/Events/Event.php` |
| `EventManager` | Event management | `src/Events/EventManager.php` |
| `Database` | Database access | `src/Database/Database.php` |

---

## Key Concepts

### Stat System
- 7 stats: Vitality, Intelligence, Medicine, Crafting, Personality, Will
- Range: 0-100
- Display: Text (terrible → godlike)
- Scaling: Babies have reduced effective stats

### Age System
- Egg (age < 0)
- Baby (0-3, reduced stats)
- Adult (4-34, full stats)
- Old (35-59, reduced + injuries)
- Very Old (60+, many injuries)

### Game Flow
- User login → Create tribe → Generate kobolds → Select members → Play
- Each month: Initiate events → End month → Progression
- Game continues until all kobolds dead

### Event System
- Player-initiated: Hunting, Exploration, Farming
- Month events: Random based on season
- Events modify tribe state and generate story

---

## Getting Help

1. **Check TODO.md** - Known issues and solutions
2. **Check ARCHITECTURE.md** - How systems work
3. **Read code comments** - Every major function documented
4. **Check API_REFERENCE.md** - For endpoint issues

---

## Checklists

### First Time Setup ✓
- [ ] Read START.md
- [ ] Run `php -S localhost:8000 -t public/`
- [ ] Create account
- [ ] Create tribe
- [ ] Play the game

### Before Development ✓
- [ ] Read GETTING_STARTED.md
- [ ] Read ARCHITECTURE.md
- [ ] Understand project structure
- [ ] Know how events work
- [ ] Know stat system

### Adding New Feature ✓
- [ ] Check TODO.md for similar features
- [ ] Read ARCHITECTURE.md for system design
- [ ] Look at existing similar code
- [ ] Write and test
- [ ] Update documentation

---

## Links to Documentation Files

**Getting Started**
- [START.md](START.md) - Run the game (2 min read)
- [GETTING_STARTED.md](GETTING_STARTED.md) - Complete guide (10 min read)
- [QUICKSTART.md](QUICKSTART.md) - Setup options (3 min read)

**Understanding**
- [README.md](README.md) - Features (10 min read)
- [DESIGN.md](DESIGN.md) - Implementation (8 min read)
- [ARCHITECTURE.md](ARCHITECTURE.md) - Technical (15 min read)

**Development**
- [API_REFERENCE.md](API_REFERENCE.md) - API docs (10 min read)
- [TODO.md](TODO.md) - Roadmap (5 min read)
- [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) - Overview (8 min read)

---

## Quick Commands

### Run the game
```bash
php -S localhost:8000 -t public/
```

### Test database initialization
```php
php -r "require 'vendor/autoload.php'; \TribeGen\Database\Database::getInstance()->initializeTables(); echo 'OK';"
```

### View database tables
```bash
sqlite3 data/tribegen.db ".tables"
```

---

## Document Statistics

| Document | Length | Read Time | Topic |
|----------|--------|-----------|-------|
| START.md | 1 page | 2 min | Running the game |
| GETTING_STARTED.md | 3 pages | 10 min | Overview |
| QUICKSTART.md | 2 pages | 3 min | Setup |
| README.md | 3 pages | 10 min | Features |
| DESIGN.md | 5 pages | 8 min | Implementation |
| ARCHITECTURE.md | 6 pages | 15 min | Technical |
| API_REFERENCE.md | 5 pages | 10 min | API |
| TODO.md | 4 pages | 5 min | Roadmap |
| PROJECT_SUMMARY.md | 7 pages | 8 min | Summary |

**Total: ~36 pages of documentation**

---

## Next Steps

1. **Decide your path**: Player or Developer?
2. **Read the appropriate documents**: Based on your path
3. **Follow the instructions**: Start with START.md
4. **Enjoy!** 🎮

---

Last Updated: January 27, 2025  
Status: Ready for Use ✅
