# Les Héritiers FoundryVTT System - Documentation Index

## 📖 Available Documentation

### 1. **QUICK_REFERENCE.md** ⭐ START HERE
- **Length**: 250 lines
- **Purpose**: Fast lookup and common task guide
- **Best for**: Developers new to the system
- **Contains**:
  - Quick start setup commands
  - System overview & statistics
  - Project structure diagram
  - Key classes and exports
  - Step-by-step: Adding a new item type
  - Common edits (characteristics, packs, rolls, UI)
  - Testing and git workflow
  - Useful commands

### 2. **DEVELOPER_INSTRUCTIONS.md** 📚 COMPREHENSIVE GUIDE
- **Length**: 598 lines
- **Purpose**: Complete architectural reference
- **Best for**: Deep understanding and long-term development
- **Contains**:
  - Executive summary
  - Build/dev commands (package.json, gulpfile.js)
  - System architecture (metadata, data model, directories)
  - Directory structure with file descriptions
  - Template organization & conventions
  - Localization strategy
  - Styling (LESS, CSS)
  - Compendium packs reference
  - Detailed conventions:
    - Module/class structure
    - Data model conventions
    - Handlebars template patterns
    - Localization key naming
    - Dice & roll system
    - Socket message handling
    - Recent migration notes (v13)
  - Development workflow (setup, file organization, registration steps)
  - Debugging tips
  - Key statistics
  - External resources
  - Developer recommendations

### 3. **README.md** (ORIGINAL)
- **Length**: 29 lines
- **Purpose**: Project overview and credits
- **Contains**:
  - Project description (English & French)
  - Copyright & authorization notes
  - Developer credits

---

## 🎯 How to Use This Documentation

### For First-Time Setup (5-10 minutes)
1. Read **QUICK_REFERENCE.md** → "Quick Start" section
2. Run `npm install` and `npm run watch`
3. Skim the "Project Structure" section

### For Adding a New Feature (30 minutes)
1. Open **QUICK_REFERENCE.md** → "Adding a New Item Type" section
2. Follow the numbered steps
3. Reference **DEVELOPER_INSTRUCTIONS.md** for deeper understanding of each step
4. Test with `npm run watch`

### For Understanding the System (1-2 hours)
1. Start with **DEVELOPER_INSTRUCTIONS.md** → "Executive Summary"
2. Read section 2: "System Architecture"
3. Read section 3: "Key Conventions"
4. Review section 5: "Development Workflow"

### For Debugging a Bug (varies)
1. Check **QUICK_REFERENCE.md** → "Useful Commands" for search/analysis tools
2. Reference **DEVELOPER_INSTRUCTIONS.md** → Section 3 for patterns
3. Look at git history: `git log --oneline | head -20`
4. Check browser console (DevTools) at `http://localhost:30000`

### For Making Common Edits (5-15 minutes each)
Reference **QUICK_REFERENCE.md** → "Common Edits" section:
- Adding a new characteristic
- Adding a new compendium pack
- Adding a new roll type
- Changing UI layout

---

## 📊 Quick System Overview

| Aspect | Detail |
|--------|--------|
| **System ID** | `fvtt-les-heritiers` |
| **Version** | 13.0.7 |
| **Foundry** | v13+ (AppV2, DataModels) |
| **Language** | French (monolingual) |
| **Build Tool** | Gulp 4 + LESS |
| **Code** | 12,273 LOC total |
| **Actor Types** | 2 (personnage, pnj) |
| **Item Types** | 14 types |
| **Compendium Packs** | 11 LevelDB packs |
| **Sheets** | 16 AppV2 sheets |
| **Architecture** | ES6 modules, TypeDataModel |

---

## 🗂️ Repository Structure

```
fvtt-les-heritiers/
├── README.md                        # Original project readme
├── QUICK_REFERENCE.md               # ⭐ Start here (250 lines)
├── DEVELOPER_INSTRUCTIONS.md        # 📚 Deep dive (598 lines)
├── DOCUMENTATION_INDEX.md           # This file
├── package.json                     # npm config (build commands)
├── gulpfile.js                      # Gulp tasks (LESS → CSS)
├── system.json                      # FoundryVTT manifest
├── template.json.backup             # Data schema reference
├── LICENCE.txt                      # License
├── modules/                         # Source code (12,273 LOC)
│   ├── heritiers-main.js           # Foundry init & registration
│   ├── heritiers-actor.js          # HeritiersActor class
│   ├── heritiers-item.js           # HeritiersItem class
│   ├── heritiers-config.js         # Game constants (HERITIERS_CONFIG)
│   ├── heritiers-utility.js        # Static utilities & helpers
│   ├── heritiers-commands.js       # Chat commands
│   ├── heritiers-combat.js         # Combat handling
│   ├── models/                     # 16 TypeDataModels
│   │   └── personnage.mjs, arme.mjs, competence.mjs, ...
│   └── applications/sheets/        # 15 AppV2 Sheet classes
│       └── personnage-sheet.mjs, arme-sheet.mjs, ...
├── templates/                       # 27 Handlebars templates
│   ├── actor-sheet.hbs             # Character sheet
│   ├── actor-pnj-sheet.hbs         # NPC sheet
│   ├── item-[type]-sheet.hbs       # Item sheets (14)
│   ├── partial-*.hbs               # Reusable components
│   ├── chat-*-result.hbs           # Chat templates
│   └── editor-*.hbs                # Editor components
├── lang/
│   └── fr.json                      # Localization (24 lines, minimal)
├── less/
│   ├── heritiers.less              # Entry point
│   └── simple-converted.less       # Imported styles
├── styles/
│   ├── heritiers.css               # Compiled output (generated)
│   └── heritiers.css.map           # Source map (generated)
├── packs/                          # 11 Compendium packs (LevelDB)
├── srcdata/                        # Source data for compilation
├── assets/                         # UI assets (images, etc.)
└── .git/                           # Git history available
```

---

## 🚀 Common Tasks Quick Links

| Task | Guide | Time |
|------|-------|------|
| Initial setup | QUICK_REFERENCE.md → Quick Start | 5 min |
| Add item type | QUICK_REFERENCE.md → Adding a New Item Type | 30 min |
| Fix a bug | DEVELOPER_INSTRUCTIONS.md → Section 5 | 15-60 min |
| Understand architecture | DEVELOPER_INSTRUCTIONS.md → Section 2 | 30 min |
| Change UI layout | QUICK_REFERENCE.md → Change UI layout | 10 min |
| Add characteristic | QUICK_REFERENCE.md → Add a new characteristic | 20 min |
| Add new roll type | QUICK_REFERENCE.md → Add a new roll type | 25 min |
| Debug an issue | QUICK_REFERENCE.md → Testing Changes | 10-30 min |

---

## 📝 Documentation Standards

All documentation follows these principles:

1. **Clarity**: Written for developers unfamiliar with the system
2. **Completeness**: All information needed to perform tasks included
3. **Accuracy**: Based on actual code analysis, not assumptions
4. **Brevity**: Concise sections with clear headings
5. **Examples**: Code snippets and patterns provided
6. **Cross-references**: Links between guides for deeper understanding

---

## 🔄 Keeping Documentation Updated

When making significant changes:

1. **Update QUICK_REFERENCE.md** if:
   - Adding/removing item types
   - Changing build commands
   - Adding/removing features
   - Changing conventions

2. **Update DEVELOPER_INSTRUCTIONS.md** if:
   - Major architecture changes
   - New development patterns established
   - New statistics to report
   - New sections needed

3. **Update git history** (automatic):
   - Commit messages explain changes
   - Reference these in DEVELOPER_INSTRUCTIONS.md

---

## 📞 Questions?

Refer to:
- **FoundryVTT Docs**: https://foundryvtt.com/articles/
- **Game Rules**: https://titam-france.fr
- **Git History**: `git log --oneline` (see recent commits)
- **Code Comments**: Most functions have JSDoc-style comments

---

**Last Updated**: March 16, 2025  
**Documentation Version**: 1.0  
**System Version**: 13.0.7

---

## 🎓 Learning Path

**Day 1**: Quick understanding
1. Read QUICK_REFERENCE.md (20 min)
2. Run setup commands (5 min)
3. Explore directory structure (10 min)

**Week 1**: Basic development
1. Read DEVELOPER_INSTRUCTIONS.md sections 1-3 (45 min)
2. Add a simple new item type (1-2 hours)
3. Fix a small bug (30 min - 1 hour)

**Week 2+**: Deep expertise
1. Read full DEVELOPER_INSTRUCTIONS.md (1-2 hours)
2. Add complex feature (3-6 hours)
3. Understand DataModels & AppV2 sheets intimately
4. Review git history for patterns (1-2 hours)