fixing leveling xp reporting

api/docs/DATA_MODELS.md

@@ -936,7 +936,8 @@ power = fireball.calculate_power(caster_stats)
 | `name` | str | Character name |
 | `player_class` | PlayerClass | Character class |
 | `level` | int | Current level |
-| `experience` | int | XP points |
+| `experience` | int | Current XP progress toward next level (resets on level-up) |
+| `total_xp` | int | Cumulative XP earned across all levels (never decreases) |
 | `stats` | Stats | Current stats |
 | `unlocked_skills` | List[str] | Unlocked skill_ids |
 | `inventory` | List[Item] | All items |
@@ -945,10 +946,17 @@ power = fireball.calculate_power(caster_stats)
 | `active_quests` | List[str] | Quest IDs |
 | `discovered_locations` | List[str] | Location IDs |
 
+**Computed Properties:**
+- `xp_to_next_level` - XP remaining until next level (calculated: `required_xp - experience`)
+- `current_hp` / `max_hp` - Health points (calculated from constitution)
+- `defense` / `resistance` - Damage reduction (calculated from stats)
+
 **Methods:**
-- `to_dict()` - Serialize to dictionary for JSON storage
-- `from_dict(data)` - Deserialize from dictionary
+- `to_dict()` - Serialize to dictionary for JSON storage (includes computed fields)
+- `from_dict(data)` - Deserialize from dictionary (handles legacy data)
 - `get_effective_stats(active_effects)` - **THE CRITICAL METHOD** - Calculate final stats
+- `add_experience(xp)` - Add XP and check for level-up (updates both `experience` and `total_xp`)
+- `level_up()` - Level up character (resets `experience`, preserves `total_xp`)
 
 **get_effective_stats() Details:**