first commit

api/app/data/abilities/README.md

@@ -0,0 +1,141 @@
+# Ability Configuration Files
+
+This directory contains YAML configuration files that define all abilities in the game.
+
+## Format
+
+Each ability is defined in a separate `.yaml` file with the following structure:
+
+```yaml
+ability_id: "unique_identifier"
+name: "Display Name"
+description: "What the ability does"
+ability_type: "attack|spell|skill|item_use|defend"
+base_power: 0                    # Base damage or healing
+damage_type: "physical|fire|ice|lightning|holy|shadow|poison"
+scaling_stat: "strength|dexterity|constitution|intelligence|wisdom|charisma"
+scaling_factor: 0.5              # Multiplier for scaling stat
+mana_cost: 0                     # MP required to use
+cooldown: 0                      # Turns before can be used again
+is_aoe: false                    # Whether it affects multiple targets
+target_count: 1                  # Number of targets (0 = all enemies)
+effects_applied: []              # List of effects to apply on hit
+```
+
+## Effect Format
+
+Effects applied by abilities use this structure:
+
+```yaml
+effects_applied:
+  - effect_id: "unique_id"
+    name: "Effect Name"
+    effect_type: "buff|debuff|dot|hot|stun|shield"
+    duration: 3                  # Turns before expiration
+    power: 5                     # Damage/healing/modifier per turn
+    stat_affected: "strength"    # For buffs/debuffs only (null otherwise)
+    stacks: 1                    # Initial stack count
+    max_stacks: 5                # Maximum stacks allowed
+    source: "ability_id"         # Which ability applied this
+```
+
+## Effect Types
+
+| Type | Power Usage | Example |
+|------|-------------|---------|
+| `buff` | Stat modifier (×stacks) | +5 strength per stack |
+| `debuff` | Stat modifier (×stacks) | -3 defense per stack |
+| `dot` | Damage per turn (×stacks) | 5 poison damage per turn |
+| `hot` | Healing per turn (×stacks) | 8 HP regeneration per turn |
+| `stun` | Not used | Prevents actions for duration |
+| `shield` | Shield strength (×stacks) | 50 damage absorption |
+
+## Damage Calculation
+
+Abilities calculate their final power using this formula:
+
+```
+Final Power = base_power + (scaling_stat × scaling_factor)
+Minimum power is always 1
+```
+
+**Examples:**
+- Fireball with 30 base_power, INT scaling 0.5, caster has 16 INT:
+  - 30 + (16 × 0.5) = 38 power
+- Shield Bash with 10 base_power, STR scaling 0.5, caster has 20 STR:
+  - 10 + (20 × 0.5) = 20 power
+
+## Loading Abilities
+
+Abilities are loaded via the `AbilityLoader` class:
+
+```python
+from app.models.abilities import AbilityLoader
+
+loader = AbilityLoader()
+fireball = loader.load_ability("fireball")
+power = fireball.calculate_power(caster_stats)
+```
+
+## Example Abilities
+
+### basic_attack.yaml
+- Simple physical attack
+- No mana cost or cooldown
+- Available to all characters
+
+### fireball.yaml
+- Offensive spell
+- Deals fire damage + applies burning DoT
+- Costs 15 MP, no cooldown
+
+### shield_bash.yaml
+- Vanguard class skill
+- Deals damage + stuns for 1 turn
+- Costs 5 MP, 2 turn cooldown
+
+### heal.yaml
+- Luminary class spell
+- Restores health + applies regeneration HoT
+- Costs 10 MP, no cooldown
+
+## Creating New Abilities
+
+1. Create a new `.yaml` file in this directory
+2. Follow the format above
+3. Set appropriate values for your ability
+4. Ability will be automatically available via `AbilityLoader`
+5. No code changes required!
+
+## Guidelines
+
+**Power Scaling:**
+- Basic attacks: 5-10 base power
+- Spells: 20-40 base power
+- Skills: 10-25 base power
+- Scaling factor typically 0.5 (50% of stat)
+
+**Mana Costs:**
+- Basic attacks: 0 MP
+- Low-tier spells: 5-10 MP
+- Mid-tier spells: 15-20 MP
+- High-tier spells: 25-30 MP
+- Ultimate abilities: 40-50 MP
+
+**Cooldowns:**
+- No cooldown (0): Most spells and basic attacks
+- Short (1-2 turns): Common skills
+- Medium (3-5 turns): Powerful skills
+- Long (5-10 turns): Ultimate abilities
+
+**Effect Duration:**
+- Instant effects (stun): 1 turn
+- Short DoT/HoT: 2-3 turns
+- Long DoT/HoT: 4-5 turns
+- Buffs/debuffs: 2-4 turns
+
+**Effect Power:**
+- Weak DoT: 3-5 damage per turn
+- Medium DoT: 8-12 damage per turn
+- Strong DoT: 15-20 damage per turn
+- Stat modifiers: 3-10 points per stack

api/app/data/abilities/basic_attack.yaml

@@ -0,0 +1,16 @@
+# Basic Attack - Default melee attack
+# Available to all characters, no mana cost, no cooldown
+
+ability_id: "basic_attack"
+name: "Basic Attack"
+description: "A standard melee attack with your equipped weapon"
+ability_type: "attack"
+base_power: 5
+damage_type: "physical"
+scaling_stat: "strength"
+scaling_factor: 0.5
+mana_cost: 0
+cooldown: 0
+is_aoe: false
+target_count: 1
+effects_applied: []

api/app/data/abilities/fireball.yaml

@@ -0,0 +1,25 @@
+# Fireball - Offensive spell for Arcanist class
+# Deals fire damage and applies burning DoT
+
+ability_id: "fireball"
+name: "Fireball"
+description: "Hurl a ball of fire at your enemies, dealing damage and burning them"
+ability_type: "spell"
+base_power: 30
+damage_type: "fire"
+scaling_stat: "intelligence"
+scaling_factor: 0.5
+mana_cost: 15
+cooldown: 0
+is_aoe: false
+target_count: 1
+effects_applied:
+  - effect_id: "burn"
+    name: "Burning"
+    effect_type: "dot"
+    duration: 3
+    power: 5
+    stat_affected: null
+    stacks: 1
+    max_stacks: 3
+    source: "fireball"

api/app/data/abilities/heal.yaml

@@ -0,0 +1,26 @@
+# Heal - Luminary class ability
+# Restores health to target ally
+
+ability_id: "heal"
+name: "Heal"
+description: "Channel divine energy to restore an ally's health"
+ability_type: "spell"
+base_power: 25
+damage_type: "holy"
+scaling_stat: "intelligence"
+scaling_factor: 0.5
+mana_cost: 10
+cooldown: 0
+is_aoe: false
+target_count: 1
+effects_applied:
+  # Healing is represented as negative DOT (HOT)
+  - effect_id: "regeneration"
+    name: "Regeneration"
+    effect_type: "hot"
+    duration: 2
+    power: 5
+    stat_affected: null
+    stacks: 1
+    max_stacks: 3
+    source: "heal"

api/app/data/abilities/shield_bash.yaml

@@ -0,0 +1,25 @@
+# Shield Bash - Vanguard class ability
+# Deals damage and stuns the target
+
+ability_id: "shield_bash"
+name: "Shield Bash"
+description: "Bash your enemy with your shield, dealing damage and stunning them briefly"
+ability_type: "skill"
+base_power: 10
+damage_type: "physical"
+scaling_stat: "strength"
+scaling_factor: 0.5
+mana_cost: 5
+cooldown: 2
+is_aoe: false
+target_count: 1
+effects_applied:
+  - effect_id: "stun"
+    name: "Stunned"
+    effect_type: "stun"
+    duration: 1
+    power: 0
+    stat_affected: null
+    stacks: 1
+    max_stacks: 1
+    source: "shield_bash"

api/app/data/action_prompts.yaml

@@ -0,0 +1,295 @@
+# Action Prompts Configuration
+#
+# Defines the predefined actions available to players during story progression.
+# Actions are filtered by user tier and location type.
+#
+# Tier hierarchy: FREE < BASIC < PREMIUM < ELITE
+# Location types: town, tavern, wilderness, dungeon, safe_area, library, any
+
+action_prompts:
+  # =============================================================================
+  # FREE TIER ACTIONS (4)
+  # Available to all players
+  # =============================================================================
+
+  - prompt_id: ask_locals
+    category: ask_question
+    display_text: Ask locals for information
+    description: Talk to NPCs to learn about quests, rumors, and local lore
+    tier_required: free
+    context_filter: [town, tavern]
+    icon: chat
+    cooldown_turns: 0
+    dm_prompt_template: |
+      The player approaches locals in {{ game_state.current_location }} and asks for information.
+
+      Character: {{ character.name }}, Level {{ character.level }} {{ character.player_class }}
+
+      Generate realistic NPC dialogue where locals share:
+      - Local rumors or gossip
+      - Information about nearby points of interest
+      - Hints about potential quests or dangers
+      - Useful tips for adventurers
+
+      The NPCs should have distinct personalities and speak naturally. Include 1-2 NPCs in the response.
+      End with a hook that encourages further exploration or action.
+
+  - prompt_id: explore_area
+    category: explore
+    display_text: Explore the area
+    description: Search your surroundings for points of interest, hidden paths, or useful items
+    tier_required: free
+    context_filter: [wilderness, dungeon]
+    icon: compass
+    cooldown_turns: 0
+    dm_prompt_template: |
+      The player explores the area around {{ game_state.current_location }}.
+
+      Character: {{ character.name }}, Level {{ character.level }} {{ character.player_class }}
+      Perception modifier: {{ character.stats.wisdom | default(10) }}
+
+      Describe what the player discovers:
+      - Environmental details and atmosphere
+      - Points of interest (paths, structures, natural features)
+      - Any items, tracks, or clues found
+      - Potential dangers or opportunities
+
+      Based on their Wisdom score, they may notice hidden details.
+
+      IMPORTANT: Do NOT automatically move the player to a new location.
+      Present 2-3 options of what they can investigate or where they can go.
+      Ask: "What would you like to investigate?" or "Which path do you take?"
+
+  - prompt_id: search_supplies
+    category: gather_info
+    display_text: Search for supplies
+    description: Look for useful items, herbs, or materials in the environment
+    tier_required: free
+    context_filter: [any]
+    icon: search
+    cooldown_turns: 2
+    requires_check:
+      check_type: search
+      difficulty: medium
+    dm_prompt_template: |
+      The player searches for supplies in {{ game_state.current_location }}.
+
+      Character: {{ character.name }}, Level {{ character.level }} {{ character.player_class }}
+
+      {% if check_outcome %}
+      DICE CHECK RESULT: {{ check_outcome.check_result.success | string | upper }}
+      - Roll: {{ check_outcome.check_result.roll }} + {{ check_outcome.check_result.modifier }} = {{ check_outcome.check_result.total }} vs DC {{ check_outcome.check_result.dc }}
+      {% if check_outcome.check_result.success %}
+      - Items found: {% for item in check_outcome.items_found %}{{ item.name }}{% if not loop.last %}, {% endif %}{% endfor %}
+      - Gold found: {{ check_outcome.gold_found }}
+
+      The player SUCCEEDED in their search. Narrate how they found these specific items.
+      The items will be automatically added to their inventory - describe the discovery.
+      {% else %}
+      The player FAILED their search. Narrate the unsuccessful search attempt.
+      They find nothing of value this time. Describe what they checked but came up empty.
+      {% endif %}
+      {% else %}
+      Describe what supply sources or items they find based on location.
+      {% endif %}
+
+      Keep the narration immersive and match the location type.
+
+  - prompt_id: rest_recover
+    category: rest
+    display_text: Rest and recover
+    description: Take a short rest to recover health and stamina in a safe location
+    tier_required: free
+    context_filter: [town, tavern, safe_area]
+    icon: bed
+    cooldown_turns: 3
+    dm_prompt_template: |
+      The player wants to rest in {{ game_state.current_location }}.
+
+      Character: {{ character.name }}, Level {{ character.level }} {{ character.player_class }}
+      Current HP: {{ character.current_hp }}/{{ character.max_hp }}
+
+      For PAID rest (taverns/inns):
+      - Describe the establishment and available rooms WITH PRICES
+      - Ask which option they want before resting
+      - DO NOT automatically spend their gold
+
+      For FREE rest (safe areas, campsites):
+      - Describe finding a suitable spot
+      - Describe the rest atmosphere and any ambient details
+      - Dreams, thoughts, or reflections the character has
+
+      After they choose to rest:
+      - The player recovers some health and feels refreshed
+      - End with them ready to continue their adventure
+
+  # =============================================================================
+  # PREMIUM TIER ACTIONS (+3)
+  # Available to Premium and Elite subscribers
+  # =============================================================================
+
+  - prompt_id: investigate_suspicious
+    category: gather_info
+    display_text: Investigate suspicious activity
+    description: Look deeper into something that seems out of place or dangerous
+    tier_required: premium
+    context_filter: [any]
+    icon: magnifying_glass
+    cooldown_turns: 0
+    dm_prompt_template: |
+      The player investigates suspicious activity in {{ game_state.current_location }}.
+
+      Character: {{ character.name }}, Level {{ character.level }} {{ character.player_class }}
+      Intelligence: {{ character.stats.intelligence | default(10) }}
+
+      Based on the location and recent events, describe:
+      - What draws their attention
+      - Clues or evidence they discover
+      - Connections to larger mysteries or threats
+      - Potential leads to follow
+
+      Higher Intelligence reveals more detailed observations.
+      This should advance the story or reveal hidden plot elements.
+      End with a clear lead or decision point.
+
+  - prompt_id: follow_lead
+    category: travel
+    display_text: Follow a lead
+    description: Pursue information or tracks that could lead to your goal
+    tier_required: premium
+    context_filter: [any]
+    icon: footprints
+    cooldown_turns: 0
+    dm_prompt_template: |
+      The player follows a lead from {{ game_state.current_location }}.
+
+      Character: {{ character.name }}, Level {{ character.level }} {{ character.player_class }}
+
+      Based on recent discoveries or conversations, describe:
+      - What lead they're following (information, tracks, rumors)
+      - The journey or investigation process
+      - What they find at the end of the trail
+      - New information or locations discovered
+
+      This should move the story forward significantly.
+      May lead to new areas, NPCs, or quest opportunities.
+      End with a meaningful discovery or encounter.
+
+  - prompt_id: make_camp
+    category: rest
+    display_text: Make camp
+    description: Set up a campsite in the wilderness for rest and preparation
+    tier_required: premium
+    context_filter: [wilderness]
+    icon: campfire
+    cooldown_turns: 5
+    dm_prompt_template: |
+      The player sets up camp in {{ game_state.current_location }}.
+
+      Character: {{ character.name }}, Level {{ character.level }} {{ character.player_class }}
+      Survival skill: {{ character.stats.wisdom | default(10) }}
+
+      Describe the camping experience:
+      - Finding a suitable spot and setting up
+      - Building a fire, preparing food
+      - The night watch and any nocturnal events
+      - Dreams or visions during sleep
+
+      Higher Wisdom means better campsite selection and awareness.
+      May include random encounters (friendly travelers, animals, or threats).
+      Player recovers health and is ready for the next day.
+
+  # =============================================================================
+  # ELITE TIER ACTIONS (+3)
+  # Available only to Elite subscribers
+  # =============================================================================
+
+  - prompt_id: consult_texts
+    category: special
+    display_text: Consult ancient texts
+    description: Study rare manuscripts and tomes for hidden knowledge and lore
+    tier_required: elite
+    context_filter: [library, town]
+    icon: book
+    cooldown_turns: 3
+    dm_prompt_template: |
+      The player consults ancient texts in {{ game_state.current_location }}.
+
+      Character: {{ character.name }}, Level {{ character.level }} {{ character.player_class }}
+      Intelligence: {{ character.stats.intelligence | default(10) }}
+
+      Describe the research session:
+      - The library or collection they access
+      - Specific tomes or scrolls they study
+      - Ancient knowledge they uncover
+      - Connections to current quests or mysteries
+
+      Higher Intelligence allows deeper understanding.
+      May reveal:
+      - Monster weaknesses or strategies
+      - Hidden location details
+      - Historical context for current events
+      - Magical item properties or crafting recipes
+
+      End with actionable knowledge that helps their quest.
+
+  - prompt_id: commune_nature
+    category: special
+    display_text: Commune with nature
+    description: Attune to the natural world to gain insights and guidance
+    tier_required: elite
+    context_filter: [wilderness]
+    icon: leaf
+    cooldown_turns: 4
+    dm_prompt_template: |
+      The player communes with nature in {{ game_state.current_location }}.
+
+      Character: {{ character.name }}, Level {{ character.level }} {{ character.player_class }}
+      Wisdom: {{ character.stats.wisdom | default(10) }}
+
+      Describe the mystical experience:
+      - The ritual or meditation performed
+      - Visions, sounds, or sensations received
+      - Messages from the natural world
+      - Animal messengers or nature spirits encountered
+
+      Higher Wisdom provides clearer visions.
+      May reveal:
+      - Danger ahead or safe paths
+      - Weather changes or natural disasters
+      - Animal behavior patterns
+      - Locations of rare herbs or resources
+      - Environmental quest hints
+
+      End with prophetic or practical guidance.
+
+  - prompt_id: seek_audience
+    category: special
+    display_text: Seek audience with authorities
+    description: Request a meeting with local leaders, nobles, or officials
+    tier_required: elite
+    context_filter: [town]
+    icon: crown
+    cooldown_turns: 5
+    dm_prompt_template: |
+      The player seeks an audience with authorities in {{ game_state.current_location }}.
+
+      Character: {{ character.name }}, Level {{ character.level }} {{ character.player_class }}
+      Charisma: {{ character.stats.charisma | default(10) }}
+      Reputation: {{ character.reputation | default('unknown') }}
+
+      Describe the audience:
+      - The authority figure (mayor, lord, guild master, etc.)
+      - The setting and formality of the meeting
+      - The conversation and requests made
+      - The authority's response and any tasks given
+
+      Higher Charisma and reputation improve reception.
+      May result in:
+      - Official quests with better rewards
+      - Access to restricted areas
+      - Political information or alliances
+      - Resources or equipment grants
+      - Letters of introduction
+
+      End with a clear outcome and next steps.

api/app/data/classes/arcanist.yaml

@@ -0,0 +1,264 @@
+# Arcanist - Magic Burst
+# Flexible hybrid class: Choose Pyromancy (fire AoE) or Cryomancy (ice control)
+
+class_id: arcanist
+name: Arcanist
+description: >
+  A master of elemental magic who bends the forces of fire and ice to their will. Arcanists
+  excel in devastating spell damage, capable of incinerating groups of foes or freezing
+  enemies in place. Choose your element: embrace the flames or command the frost.
+
+# Base stats (total: 65)
+base_stats:
+  strength: 8       # Low physical power
+  dexterity: 10     # Average agility
+  constitution: 9   # Below average endurance
+  intelligence: 15  # Exceptional magical power
+  wisdom: 12        # Above average perception
+  charisma: 11      # Above average social
+
+starting_equipment:
+  - worn_staff
+  - cloth_armor
+  - rusty_knife
+
+starting_abilities:
+  - basic_attack
+
+skill_trees:
+  # ==================== PYROMANCY (Fire AoE) ====================
+  - tree_id: pyromancy
+    name: Pyromancy
+    description: >
+      The path of flame. Master destructive fire magic to incinerate your enemies
+      with overwhelming area damage and burning DoTs.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: fireball
+        name: Fireball
+        description: Hurl a ball of flame at an enemy, dealing fire damage and igniting them.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - fireball
+
+      - skill_id: flame_attunement
+        name: Flame Attunement
+        description: Your affinity with fire magic increases your magical power.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            intelligence: 5
+
+      # --- TIER 2 ---
+      - skill_id: flame_burst
+        name: Flame Burst
+        description: Release a burst of fire around you, damaging all nearby enemies.
+        tier: 2
+        prerequisites:
+          - fireball
+        effects:
+          abilities:
+            - flame_burst
+
+      - skill_id: burning_soul
+        name: Burning Soul
+        description: Your inner fire burns brighter, increasing fire damage.
+        tier: 2
+        prerequisites:
+          - flame_attunement
+        effects:
+          stat_bonuses:
+            intelligence: 5
+          combat_bonuses:
+            fire_damage_bonus: 0.15  # +15% fire damage
+
+      # --- TIER 3 ---
+      - skill_id: inferno
+        name: Inferno
+        description: Summon a raging inferno that burns all enemies for 3 turns.
+        tier: 3
+        prerequisites:
+          - flame_burst
+        effects:
+          abilities:
+            - inferno
+
+      - skill_id: combustion
+        name: Combustion
+        description: Your fire spells can cause targets to explode on death, damaging nearby enemies.
+        tier: 3
+        prerequisites:
+          - burning_soul
+        effects:
+          passive_effects:
+            - burning_enemies_explode_on_death
+
+      # --- TIER 4 ---
+      - skill_id: firestorm
+        name: Firestorm
+        description: Call down a storm of meteors on all enemies, dealing massive fire damage.
+        tier: 4
+        prerequisites:
+          - inferno
+        effects:
+          abilities:
+            - firestorm
+
+      - skill_id: pyroclasm
+        name: Pyroclasm
+        description: Your mastery of flame makes all fire spells more devastating.
+        tier: 4
+        prerequisites:
+          - combustion
+        effects:
+          stat_bonuses:
+            intelligence: 10
+          combat_bonuses:
+            fire_damage_bonus: 0.25  # Additional +25% fire damage
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: sun_burst
+        name: Sun Burst
+        description: Channel the power of the sun itself, dealing catastrophic fire damage to all enemies.
+        tier: 5
+        prerequisites:
+          - firestorm
+        effects:
+          abilities:
+            - sun_burst
+
+      - skill_id: master_of_flame
+        name: Master of Flame
+        description: You are flame incarnate. Incredible fire magic bonuses.
+        tier: 5
+        prerequisites:
+          - pyroclasm
+        effects:
+          stat_bonuses:
+            intelligence: 20
+          combat_bonuses:
+            fire_damage_bonus: 0.50  # Additional +50% fire damage
+
+  # ==================== CRYOMANCY (Ice Control) ====================
+  - tree_id: cryomancy
+    name: Cryomancy
+    description: >
+      The path of frost. Master ice magic to freeze and slow enemies,
+      controlling the battlefield with chilling precision.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: ice_shard
+        name: Ice Shard
+        description: Launch a shard of ice at an enemy, dealing damage and slowing them.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - ice_shard
+
+      - skill_id: frost_attunement
+        name: Frost Attunement
+        description: Your affinity with ice magic increases your magical power.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            intelligence: 5
+
+      # --- TIER 2 ---
+      - skill_id: frozen_orb
+        name: Frozen Orb
+        description: Summon an orb of ice that explodes, freezing enemies in place for 1 turn.
+        tier: 2
+        prerequisites:
+          - ice_shard
+        effects:
+          abilities:
+            - frozen_orb
+
+      - skill_id: cold_embrace
+        name: Cold Embrace
+        description: The cold empowers you, increasing ice damage and mana.
+        tier: 2
+        prerequisites:
+          - frost_attunement
+        effects:
+          stat_bonuses:
+            intelligence: 5
+          combat_bonuses:
+            ice_damage_bonus: 0.15  # +15% ice damage
+
+      # --- TIER 3 ---
+      - skill_id: blizzard
+        name: Blizzard
+        description: Summon a raging blizzard that damages and slows all enemies.
+        tier: 3
+        prerequisites:
+          - frozen_orb
+        effects:
+          abilities:
+            - blizzard
+
+      - skill_id: permafrost
+        name: Permafrost
+        description: Your ice magic becomes more potent, with longer freeze durations.
+        tier: 3
+        prerequisites:
+          - cold_embrace
+        effects:
+          stat_bonuses:
+            wisdom: 5
+          combat_bonuses:
+            freeze_duration_bonus: 1  # +1 turn to freeze effects
+
+      # --- TIER 4 ---
+      - skill_id: glacial_spike
+        name: Glacial Spike
+        description: Impale an enemy with a massive ice spike, dealing heavy damage and freezing them.
+        tier: 4
+        prerequisites:
+          - blizzard
+        effects:
+          abilities:
+            - glacial_spike
+
+      - skill_id: ice_mastery
+        name: Ice Mastery
+        description: Your command of ice magic reaches new heights.
+        tier: 4
+        prerequisites:
+          - permafrost
+        effects:
+          stat_bonuses:
+            intelligence: 10
+          combat_bonuses:
+            ice_damage_bonus: 0.25  # Additional +25% ice damage
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: absolute_zero
+        name: Absolute Zero
+        description: Freeze all enemies solid for 2 turns while dealing massive damage over time.
+        tier: 5
+        prerequisites:
+          - glacial_spike
+        effects:
+          abilities:
+            - absolute_zero
+
+      - skill_id: winter_incarnate
+        name: Winter Incarnate
+        description: You become the embodiment of winter itself. Incredible ice magic bonuses.
+        tier: 5
+        prerequisites:
+          - ice_mastery
+        effects:
+          stat_bonuses:
+            intelligence: 20
+            wisdom: 10
+          combat_bonuses:
+            ice_damage_bonus: 0.50  # Additional +50% ice damage

api/app/data/classes/assassin.yaml

@@ -0,0 +1,265 @@
+# Assassin - Critical/Stealth
+# Flexible hybrid class: Choose Shadow Dancer (stealth/evasion) or Blade Specialist (critical damage)
+
+class_id: assassin
+name: Assassin
+description: >
+  A deadly operative who strikes from the shadows. Assassins excel in precise, devastating attacks,
+  capable of becoming an elusive phantom or a master of critical strikes. Choose your path: embrace
+  the shadows or perfect the killing blow.
+
+# Base stats (total: 65)
+base_stats:
+  strength: 11      # Above average physical power
+  dexterity: 15     # Exceptional agility
+  constitution: 10  # Average endurance
+  intelligence: 9   # Below average magic
+  wisdom: 10        # Average perception
+  charisma: 10      # Average social
+
+starting_equipment:
+  - rusty_dagger
+  - cloth_armor
+  - rusty_knife
+
+starting_abilities:
+  - basic_attack
+
+skill_trees:
+  # ==================== SHADOW DANCER (Stealth/Evasion) ====================
+  - tree_id: shadow_dancer
+    name: Shadow Dancer
+    description: >
+      The path of the phantom. Master stealth and evasion to become untouchable,
+      striking from darkness and vanishing before retaliation.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: shadowstep
+        name: Shadowstep
+        description: Teleport behind an enemy and strike, dealing bonus damage from behind.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - shadowstep
+
+      - skill_id: nimble
+        name: Nimble
+        description: Your natural agility is enhanced through training.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            dexterity: 5
+
+      # --- TIER 2 ---
+      - skill_id: smoke_bomb
+        name: Smoke Bomb
+        description: Throw a smoke bomb, becoming untargetable for 1 turn and gaining evasion bonus.
+        tier: 2
+        prerequisites:
+          - shadowstep
+        effects:
+          abilities:
+            - smoke_bomb
+
+      - skill_id: evasion_training
+        name: Evasion Training
+        description: Learn to anticipate and dodge incoming attacks.
+        tier: 2
+        prerequisites:
+          - nimble
+        effects:
+          combat_bonuses:
+            evasion_chance: 0.15  # +15% chance to evade attacks
+
+      # --- TIER 3 ---
+      - skill_id: vanish
+        name: Vanish
+        description: Disappear from the battlefield for 2 turns, removing all threat and repositioning.
+        tier: 3
+        prerequisites:
+          - smoke_bomb
+        effects:
+          abilities:
+            - vanish
+
+      - skill_id: shadow_form
+        name: Shadow Form
+        description: Your body becomes harder to hit, permanently increasing evasion.
+        tier: 3
+        prerequisites:
+          - evasion_training
+        effects:
+          combat_bonuses:
+            evasion_chance: 0.10  # Additional +10% evasion
+          stat_bonuses:
+            dexterity: 5
+
+      # --- TIER 4 ---
+      - skill_id: death_mark
+        name: Death Mark
+        description: Mark an enemy from stealth. Your next attack on them deals 200% damage.
+        tier: 4
+        prerequisites:
+          - vanish
+        effects:
+          abilities:
+            - death_mark
+
+      - skill_id: untouchable
+        name: Untouchable
+        description: Your mastery of evasion makes you extremely difficult to hit.
+        tier: 4
+        prerequisites:
+          - shadow_form
+        effects:
+          combat_bonuses:
+            evasion_chance: 0.15  # Additional +15% evasion
+          stat_bonuses:
+            dexterity: 10
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: shadow_assault
+        name: Shadow Assault
+        description: Strike all enemies in rapid succession from the shadows, guaranteed critical hits.
+        tier: 5
+        prerequisites:
+          - death_mark
+        effects:
+          abilities:
+            - shadow_assault
+
+      - skill_id: ghost
+        name: Ghost
+        description: Become one with the shadows. Massive evasion and dexterity bonuses.
+        tier: 5
+        prerequisites:
+          - untouchable
+        effects:
+          combat_bonuses:
+            evasion_chance: 0.20  # Additional +20% evasion (total can reach ~60%)
+          stat_bonuses:
+            dexterity: 15
+
+  # ==================== BLADE SPECIALIST (Critical Damage) ====================
+  - tree_id: blade_specialist
+    name: Blade Specialist
+    description: >
+      The path of precision. Master the art of the killing blow to deliver devastating
+      critical strikes that end fights in seconds.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: precise_strike
+        name: Precise Strike
+        description: A carefully aimed attack with increased critical hit chance.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - precise_strike
+
+      - skill_id: keen_edge
+        name: Keen Edge
+        description: Sharpen your weapons to a razor edge, increasing critical chance.
+        tier: 1
+        prerequisites: []
+        effects:
+          combat_bonuses:
+            crit_chance: 0.10  # +10% base crit
+
+      # --- TIER 2 ---
+      - skill_id: vital_strike
+        name: Vital Strike
+        description: Target vital points to deal massive critical damage.
+        tier: 2
+        prerequisites:
+          - precise_strike
+        effects:
+          abilities:
+            - vital_strike
+
+      - skill_id: deadly_precision
+        name: Deadly Precision
+        description: Your strikes become even more lethal.
+        tier: 2
+        prerequisites:
+          - keen_edge
+        effects:
+          combat_bonuses:
+            crit_chance: 0.10  # Additional +10% crit
+            crit_multiplier: 0.3  # +0.3 to crit multiplier
+
+      # --- TIER 3 ---
+      - skill_id: hemorrhage
+        name: Hemorrhage
+        description: Critical hits cause bleeding for 3 turns, dealing heavy damage over time.
+        tier: 3
+        prerequisites:
+          - vital_strike
+        effects:
+          passive_effects:
+            - crit_applies_bleed
+
+      - skill_id: surgical_strikes
+        name: Surgical Strikes
+        description: Every attack is a calculated execution.
+        tier: 3
+        prerequisites:
+          - deadly_precision
+        effects:
+          combat_bonuses:
+            crit_chance: 0.15  # Additional +15% crit
+          stat_bonuses:
+            dexterity: 5
+
+      # --- TIER 4 ---
+      - skill_id: coup_de_grace
+        name: Coup de Grace
+        description: Execute targets below 25% HP instantly with a guaranteed critical.
+        tier: 4
+        prerequisites:
+          - hemorrhage
+        effects:
+          abilities:
+            - coup_de_grace
+
+      - skill_id: master_assassin
+        name: Master Assassin
+        description: Your expertise with blades reaches perfection.
+        tier: 4
+        prerequisites:
+          - surgical_strikes
+        effects:
+          combat_bonuses:
+            crit_chance: 0.10  # Additional +10% crit
+            crit_multiplier: 0.5  # +0.5 to crit multiplier
+          stat_bonuses:
+            strength: 5
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: thousand_cuts
+        name: Thousand Cuts
+        description: Unleash a flurry of blade strikes on a single target, each hit has 50% crit chance.
+        tier: 5
+        prerequisites:
+          - coup_de_grace
+        effects:
+          abilities:
+            - thousand_cuts
+
+      - skill_id: perfect_assassination
+        name: Perfect Assassination
+        description: Your mastery of the blade is unmatched. Incredible critical bonuses.
+        tier: 5
+        prerequisites:
+          - master_assassin
+        effects:
+          combat_bonuses:
+            crit_chance: 0.20  # Additional +20% crit (total can reach ~75%)
+            crit_multiplier: 1.0  # +1.0 to crit multiplier
+          stat_bonuses:
+            dexterity: 10
+            strength: 10

api/app/data/classes/lorekeeper.yaml

@@ -0,0 +1,273 @@
+# Lorekeeper - Support/Control
+# Flexible hybrid class: Choose Arcane Weaving (buffs/debuffs) or Illusionist (crowd control)
+
+class_id: lorekeeper
+name: Lorekeeper
+description: >
+  A master of arcane knowledge who manipulates reality through words and illusions. Lorekeepers
+  excel in supporting allies and controlling enemies through clever magic and mental manipulation.
+  Choose your art: weave arcane power or bend reality itself.
+
+# Base stats (total: 67)
+base_stats:
+  strength: 8       # Low physical power
+  dexterity: 11     # Above average agility
+  constitution: 10  # Average endurance
+  intelligence: 13  # Above average magical power
+  wisdom: 11        # Above average perception
+  charisma: 14      # High social/performance
+
+starting_equipment:
+  - tome
+  - cloth_armor
+  - rusty_knife
+
+starting_abilities:
+  - basic_attack
+
+skill_trees:
+  # ==================== ARCANE WEAVING (Buffs/Debuffs) ====================
+  - tree_id: arcane_weaving
+    name: Arcane Weaving
+    description: >
+      The path of the arcane weaver. Master supportive magic to enhance allies,
+      weaken enemies, and turn the tide of battle through clever enchantments.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: arcane_brilliance
+        name: Arcane Brilliance
+        description: Grant an ally increased intelligence and magical power for 5 turns.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - arcane_brilliance
+
+      - skill_id: scholarly_mind
+        name: Scholarly Mind
+        description: Your extensive study enhances your magical knowledge.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            intelligence: 5
+
+      # --- TIER 2 ---
+      - skill_id: haste
+        name: Haste
+        description: Speed up an ally, granting them an extra action this turn.
+        tier: 2
+        prerequisites:
+          - arcane_brilliance
+        effects:
+          abilities:
+            - haste
+
+      - skill_id: arcane_mastery
+        name: Arcane Mastery
+        description: Your mastery of arcane arts increases all buff effectiveness.
+        tier: 2
+        prerequisites:
+          - scholarly_mind
+        effects:
+          stat_bonuses:
+            intelligence: 5
+            charisma: 3
+          combat_bonuses:
+            buff_power: 0.20  # +20% buff effectiveness
+
+      # --- TIER 3 ---
+      - skill_id: mass_enhancement
+        name: Mass Enhancement
+        description: Enhance all allies at once, increasing their stats for 5 turns.
+        tier: 3
+        prerequisites:
+          - haste
+        effects:
+          abilities:
+            - mass_enhancement
+
+      - skill_id: arcane_weakness
+        name: Arcane Weakness
+        description: Curse an enemy with weakness, reducing their stats and damage.
+        tier: 3
+        prerequisites:
+          - arcane_mastery
+        effects:
+          abilities:
+            - arcane_weakness
+
+      # --- TIER 4 ---
+      - skill_id: time_warp
+        name: Time Warp
+        description: Manipulate time itself, granting all allies bonus actions.
+        tier: 4
+        prerequisites:
+          - mass_enhancement
+        effects:
+          abilities:
+            - time_warp
+
+      - skill_id: master_weaver
+        name: Master Weaver
+        description: Your weaving expertise makes all enchantments far more potent.
+        tier: 4
+        prerequisites:
+          - arcane_weakness
+        effects:
+          stat_bonuses:
+            intelligence: 15
+            charisma: 10
+          combat_bonuses:
+            buff_power: 0.35  # Additional +35% buff effectiveness
+            debuff_power: 0.35  # +35% debuff effectiveness
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: reality_shift
+        name: Reality Shift
+        description: Shift reality to massively empower all allies and weaken all enemies.
+        tier: 5
+        prerequisites:
+          - time_warp
+        effects:
+          abilities:
+            - reality_shift
+
+      - skill_id: archmage
+        name: Archmage
+        description: Achieve the rank of archmage. Incredible support magic bonuses.
+        tier: 5
+        prerequisites:
+          - master_weaver
+        effects:
+          stat_bonuses:
+            intelligence: 25
+            charisma: 20
+            wisdom: 10
+          combat_bonuses:
+            buff_power: 0.75  # Additional +75% buff effectiveness
+            debuff_power: 0.75  # Additional +75% debuff effectiveness
+
+  # ==================== ILLUSIONIST (Crowd Control) ====================
+  - tree_id: illusionist
+    name: Illusionist
+    description: >
+      The path of deception. Master illusion magic to confuse, disorient, and control
+      the minds of your enemies, rendering them helpless.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: confuse
+        name: Confuse
+        description: Confuse an enemy's mind, causing them to attack randomly for 2 turns.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - confuse
+
+      - skill_id: silver_tongue
+        name: Silver Tongue
+        description: Your persuasive abilities make mind magic more effective.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            charisma: 5
+
+      # --- TIER 2 ---
+      - skill_id: mesmerize
+        name: Mesmerize
+        description: Mesmerize an enemy, stunning them for 2 turns.
+        tier: 2
+        prerequisites:
+          - confuse
+        effects:
+          abilities:
+            - mesmerize
+
+      - skill_id: mental_fortress
+        name: Mental Fortress
+        description: Fortify your mind and those of your allies against mental attacks.
+        tier: 2
+        prerequisites:
+          - silver_tongue
+        effects:
+          stat_bonuses:
+            wisdom: 5
+          combat_bonuses:
+            mental_resistance: 0.25  # +25% resistance to mind effects
+
+      # --- TIER 3 ---
+      - skill_id: mass_confusion
+        name: Mass Confusion
+        description: Confuse all enemies, causing chaos on the battlefield.
+        tier: 3
+        prerequisites:
+          - mesmerize
+        effects:
+          abilities:
+            - mass_confusion
+
+      - skill_id: mirror_image
+        name: Mirror Image
+        description: Create illusory copies of yourself that absorb attacks.
+        tier: 3
+        prerequisites:
+          - mental_fortress
+        effects:
+          abilities:
+            - mirror_image
+
+      # --- TIER 4 ---
+      - skill_id: phantasmal_killer
+        name: Phantasmal Killer
+        description: Create a terrifying illusion that deals massive psychic damage and fears enemies.
+        tier: 4
+        prerequisites:
+          - mass_confusion
+        effects:
+          abilities:
+            - phantasmal_killer
+
+      - skill_id: master_illusionist
+        name: Master Illusionist
+        description: Your illusions become nearly indistinguishable from reality.
+        tier: 4
+        prerequisites:
+          - mirror_image
+        effects:
+          stat_bonuses:
+            charisma: 15
+            intelligence: 10
+          combat_bonuses:
+            illusion_duration: 2  # +2 turns to illusion effects
+            cc_effectiveness: 0.35  # +35% crowd control effectiveness
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: mass_domination
+        name: Mass Domination
+        description: Dominate the minds of all enemies, forcing them to fight for you briefly.
+        tier: 5
+        prerequisites:
+          - phantasmal_killer
+        effects:
+          abilities:
+            - mass_domination
+
+      - skill_id: grand_illusionist
+        name: Grand Illusionist
+        description: Become a grand illusionist. Reality bends to your will.
+        tier: 5
+        prerequisites:
+          - master_illusionist
+        effects:
+          stat_bonuses:
+            charisma: 30
+            intelligence: 15
+            wisdom: 10
+          combat_bonuses:
+            illusion_duration: 5  # Additional +5 turns to illusions
+            cc_effectiveness: 0.75  # Additional +75% crowd control effectiveness
+            mental_damage_bonus: 1.0  # +100% psychic damage

api/app/data/classes/luminary.yaml

@@ -0,0 +1,266 @@
+# Luminary - Holy Healer/DPS
+# Flexible hybrid class: Choose Divine Protection (healing/shields) or Radiant Judgment (holy damage)
+
+class_id: luminary
+name: Luminary
+description: >
+  A blessed warrior who channels divine power. Luminaries excel in healing and protection,
+  capable of becoming a guardian angel for their allies or a righteous crusader smiting evil.
+  Choose your calling: protect the innocent or judge the wicked.
+
+# Base stats (total: 68)
+base_stats:
+  strength: 9       # Below average physical power
+  dexterity: 9      # Below average agility
+  constitution: 11  # Above average endurance
+  intelligence: 12  # Above average magical power
+  wisdom: 14        # High perception/divine power
+  charisma: 13      # Above average social
+
+starting_equipment:
+  - rusty_mace
+  - cloth_armor
+  - rusty_knife
+
+starting_abilities:
+  - basic_attack
+
+skill_trees:
+  # ==================== DIVINE PROTECTION (Healing/Shields) ====================
+  - tree_id: divine_protection
+    name: Divine Protection
+    description: >
+      The path of the guardian. Channel divine energy to heal wounds, shield allies,
+      and protect the vulnerable from harm.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: heal
+        name: Heal
+        description: Channel divine energy to restore an ally's health.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - heal
+
+      - skill_id: divine_grace
+        name: Divine Grace
+        description: Your connection to the divine enhances your wisdom and healing power.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            wisdom: 5
+
+      # --- TIER 2 ---
+      - skill_id: holy_shield
+        name: Holy Shield
+        description: Grant an ally a protective barrier that absorbs damage.
+        tier: 2
+        prerequisites:
+          - heal
+        effects:
+          abilities:
+            - holy_shield
+
+      - skill_id: blessed_aura
+        name: Blessed Aura
+        description: Emit an aura that passively regenerates nearby allies' health each turn.
+        tier: 2
+        prerequisites:
+          - divine_grace
+        effects:
+          passive_effects:
+            - aura_healing  # 5% max HP per turn to allies
+
+      # --- TIER 3 ---
+      - skill_id: mass_heal
+        name: Mass Heal
+        description: Channel divine power to heal all allies at once.
+        tier: 3
+        prerequisites:
+          - holy_shield
+        effects:
+          abilities:
+            - mass_heal
+
+      - skill_id: guardian_angel
+        name: Guardian Angel
+        description: Place a protective blessing on an ally that prevents their next death.
+        tier: 3
+        prerequisites:
+          - blessed_aura
+        effects:
+          abilities:
+            - guardian_angel
+
+      # --- TIER 4 ---
+      - skill_id: divine_intervention
+        name: Divine Intervention
+        description: Call upon divine power to fully heal an ally and remove all debuffs.
+        tier: 4
+        prerequisites:
+          - mass_heal
+        effects:
+          abilities:
+            - divine_intervention
+
+      - skill_id: sanctified
+        name: Sanctified
+        description: Your divine power reaches new heights, improving all healing.
+        tier: 4
+        prerequisites:
+          - guardian_angel
+        effects:
+          stat_bonuses:
+            wisdom: 10
+          combat_bonuses:
+            healing_power: 0.25  # +25% healing
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: resurrection
+        name: Resurrection
+        description: Bring a fallen ally back to life with 50% health and mana.
+        tier: 5
+        prerequisites:
+          - divine_intervention
+        effects:
+          abilities:
+            - resurrection
+
+      - skill_id: beacon_of_hope
+        name: Beacon of Hope
+        description: You radiate divine energy. Massive wisdom and healing bonuses.
+        tier: 5
+        prerequisites:
+          - sanctified
+        effects:
+          stat_bonuses:
+            wisdom: 20
+            charisma: 10
+          combat_bonuses:
+            healing_power: 0.50  # Additional +50% healing
+
+  # ==================== RADIANT JUDGMENT (Holy Damage) ====================
+  - tree_id: radiant_judgment
+    name: Radiant Judgment
+    description: >
+      The path of the crusader. Wield holy power as a weapon, smiting the wicked
+      with radiant damage and divine wrath.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: smite
+        name: Smite
+        description: Strike an enemy with holy power, dealing radiant damage.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - smite
+
+      - skill_id: righteous_fury
+        name: Righteous Fury
+        description: Your righteous anger fuels your holy power.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            wisdom: 5
+
+      # --- TIER 2 ---
+      - skill_id: holy_fire
+        name: Holy Fire
+        description: Burn an enemy with holy flames, dealing damage and reducing their healing received.
+        tier: 2
+        prerequisites:
+          - smite
+        effects:
+          abilities:
+            - holy_fire
+
+      - skill_id: zealot
+        name: Zealot
+        description: Your devotion to righteousness increases your damage against evil.
+        tier: 2
+        prerequisites:
+          - righteous_fury
+        effects:
+          stat_bonuses:
+            wisdom: 5
+            strength: 3
+          combat_bonuses:
+            holy_damage_bonus: 0.15  # +15% holy damage
+
+      # --- TIER 3 ---
+      - skill_id: consecration
+        name: Consecration
+        description: Consecrate the ground, dealing holy damage to enemies standing in it each turn.
+        tier: 3
+        prerequisites:
+          - holy_fire
+        effects:
+          abilities:
+            - consecration
+
+      - skill_id: divine_wrath
+        name: Divine Wrath
+        description: Channel pure divine fury into your attacks.
+        tier: 3
+        prerequisites:
+          - zealot
+        effects:
+          stat_bonuses:
+            wisdom: 10
+          combat_bonuses:
+            holy_damage_bonus: 0.20  # Additional +20% holy damage
+
+      # --- TIER 4 ---
+      - skill_id: hammer_of_justice
+        name: Hammer of Justice
+        description: Summon a massive holy hammer to crush your foes, stunning and damaging them.
+        tier: 4
+        prerequisites:
+          - consecration
+        effects:
+          abilities:
+            - hammer_of_justice
+
+      - skill_id: crusader
+        name: Crusader
+        description: You become a true crusader, dealing devastating holy damage.
+        tier: 4
+        prerequisites:
+          - divine_wrath
+        effects:
+          stat_bonuses:
+            wisdom: 10
+            strength: 5
+          combat_bonuses:
+            holy_damage_bonus: 0.25  # Additional +25% holy damage
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: divine_storm
+        name: Divine Storm
+        description: Unleash a catastrophic storm of holy energy, damaging and stunning all enemies.
+        tier: 5
+        prerequisites:
+          - hammer_of_justice
+        effects:
+          abilities:
+            - divine_storm
+
+      - skill_id: avatar_of_light
+        name: Avatar of Light
+        description: Become an avatar of divine light itself. Incredible holy damage bonuses.
+        tier: 5
+        prerequisites:
+          - crusader
+        effects:
+          stat_bonuses:
+            wisdom: 20
+            strength: 10
+            charisma: 10
+          combat_bonuses:
+            holy_damage_bonus: 0.50  # Additional +50% holy damage

api/app/data/classes/necromancer.yaml

@@ -0,0 +1,275 @@
+# Necromancer - DoT/Summoner
+# Flexible hybrid class: Choose Dark Affliction (DoTs/debuffs) or Raise Dead (summon undead)
+
+class_id: necromancer
+name: Necromancer
+description: >
+  A master of death magic who manipulates life force and commands the undead. Necromancers
+  excel in draining enemies over time or overwhelming foes with undead minions.
+  Choose your dark art: curse your enemies or raise an army of the dead.
+
+# Base stats (total: 65)
+base_stats:
+  strength: 8       # Low physical power
+  dexterity: 10     # Average agility
+  constitution: 10  # Average endurance
+  intelligence: 14  # High magical power
+  wisdom: 11        # Above average perception
+  charisma: 12      # Above average social (commands undead)
+
+starting_equipment:
+  - bone_wand
+  - cloth_armor
+  - rusty_knife
+
+starting_abilities:
+  - basic_attack
+
+skill_trees:
+  # ==================== DARK AFFLICTION (DoTs/Debuffs) ====================
+  - tree_id: dark_affliction
+    name: Dark Affliction
+    description: >
+      The path of the curseweaver. Master dark magic to drain life, inflict agonizing
+      curses, and watch enemies wither away over time.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: drain_life
+        name: Drain Life
+        description: Siphon life force from an enemy, damaging them and healing yourself.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - drain_life
+
+      - skill_id: dark_knowledge
+        name: Dark Knowledge
+        description: Study of forbidden arts enhances your dark magic power.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            intelligence: 5
+
+      # --- TIER 2 ---
+      - skill_id: plague
+        name: Plague
+        description: Infect an enemy with disease that spreads to nearby foes, dealing damage over time.
+        tier: 2
+        prerequisites:
+          - drain_life
+        effects:
+          abilities:
+            - plague
+
+      - skill_id: soul_harvest
+        name: Soul Harvest
+        description: Absorb the life essence of dying enemies, increasing your power.
+        tier: 2
+        prerequisites:
+          - dark_knowledge
+        effects:
+          stat_bonuses:
+            intelligence: 5
+          combat_bonuses:
+            lifesteal: 0.15  # Heal for 15% of damage dealt
+
+      # --- TIER 3 ---
+      - skill_id: curse_of_agony
+        name: Curse of Agony
+        description: Curse an enemy with excruciating pain, dealing heavy damage over 5 turns.
+        tier: 3
+        prerequisites:
+          - plague
+        effects:
+          abilities:
+            - curse_of_agony
+
+      - skill_id: dark_empowerment
+        name: Dark Empowerment
+        description: Channel dark energy to enhance all damage over time effects.
+        tier: 3
+        prerequisites:
+          - soul_harvest
+        effects:
+          stat_bonuses:
+            intelligence: 10
+          combat_bonuses:
+            dot_damage_bonus: 0.30  # +30% DoT damage
+
+      # --- TIER 4 ---
+      - skill_id: soul_rot
+        name: Soul Rot
+        description: Rot an enemy's soul, dealing massive damage over time and reducing their healing.
+        tier: 4
+        prerequisites:
+          - curse_of_agony
+        effects:
+          abilities:
+            - soul_rot
+
+      - skill_id: death_mastery
+        name: Death Mastery
+        description: Master the art of death magic, dramatically increasing curse potency.
+        tier: 4
+        prerequisites:
+          - dark_empowerment
+        effects:
+          stat_bonuses:
+            intelligence: 15
+          combat_bonuses:
+            dot_damage_bonus: 0.40  # Additional +40% DoT damage
+            lifesteal: 0.15  # Additional +15% lifesteal
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: epidemic
+        name: Epidemic
+        description: Unleash a deadly epidemic that afflicts all enemies with multiple DoTs.
+        tier: 5
+        prerequisites:
+          - soul_rot
+        effects:
+          abilities:
+            - epidemic
+
+      - skill_id: lord_of_decay
+        name: Lord of Decay
+        description: Become a lord of death and decay. Incredible DoT and drain bonuses.
+        tier: 5
+        prerequisites:
+          - death_mastery
+        effects:
+          stat_bonuses:
+            intelligence: 25
+            wisdom: 15
+          combat_bonuses:
+            dot_damage_bonus: 1.0  # Additional +100% DoT damage
+            lifesteal: 0.30  # Additional +30% lifesteal
+
+  # ==================== RAISE DEAD (Summon Undead) ====================
+  - tree_id: raise_dead
+    name: Raise Dead
+    description: >
+      The path of the necromancer. Command armies of the undead, raising fallen
+      enemies and empowering your minions with dark magic.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: summon_skeleton
+        name: Summon Skeleton
+        description: Raise a skeleton warrior from the ground to fight for you.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - summon_skeleton
+
+      - skill_id: dark_command
+        name: Dark Command
+        description: Your mastery over the undead makes your minions stronger.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            charisma: 5
+          combat_bonuses:
+            minion_damage_bonus: 0.15  # +15% minion damage
+
+      # --- TIER 2 ---
+      - skill_id: raise_ghoul
+        name: Raise Ghoul
+        description: Summon a ravenous ghoul that deals heavy melee damage.
+        tier: 2
+        prerequisites:
+          - summon_skeleton
+        effects:
+          abilities:
+            - raise_ghoul
+
+      - skill_id: unholy_bond
+        name: Unholy Bond
+        description: Strengthen your connection to the undead, empowering your minions.
+        tier: 2
+        prerequisites:
+          - dark_command
+        effects:
+          stat_bonuses:
+            charisma: 5
+          combat_bonuses:
+            minion_damage_bonus: 0.20  # Additional +20% minion damage
+            minion_health_bonus: 0.25  # +25% minion HP
+
+      # --- TIER 3 ---
+      - skill_id: corpse_explosion
+        name: Corpse Explosion
+        description: Detonate a corpse or minion, dealing massive AoE damage.
+        tier: 3
+        prerequisites:
+          - raise_ghoul
+        effects:
+          abilities:
+            - corpse_explosion
+
+      - skill_id: death_pact
+        name: Death Pact
+        description: Sacrifice a minion to restore your health and mana.
+        tier: 3
+        prerequisites:
+          - unholy_bond
+        effects:
+          abilities:
+            - death_pact
+
+      # --- TIER 4 ---
+      - skill_id: summon_abomination
+        name: Summon Abomination
+        description: Raise a massive undead abomination that dominates the battlefield.
+        tier: 4
+        prerequisites:
+          - corpse_explosion
+        effects:
+          abilities:
+            - summon_abomination
+
+      - skill_id: legion_master
+        name: Legion Master
+        description: Command larger armies of undead with increased effectiveness.
+        tier: 4
+        prerequisites:
+          - death_pact
+        effects:
+          stat_bonuses:
+            charisma: 15
+            intelligence: 5
+          combat_bonuses:
+            minion_damage_bonus: 0.35  # Additional +35% minion damage
+            minion_health_bonus: 0.50  # Additional +50% minion HP
+            max_minions: 2  # +2 max minions
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: army_of_the_dead
+        name: Army of the Dead
+        description: Summon a massive army of undead warriors to overwhelm your enemies.
+        tier: 5
+        prerequisites:
+          - summon_abomination
+        effects:
+          abilities:
+            - army_of_the_dead
+
+      - skill_id: lich_lord
+        name: Lich Lord
+        description: Transcend mortality to become a lich lord. Incredible minion bonuses.
+        tier: 5
+        prerequisites:
+          - legion_master
+        effects:
+          stat_bonuses:
+            charisma: 25
+            intelligence: 20
+          combat_bonuses:
+            minion_damage_bonus: 1.0  # Additional +100% minion damage
+            minion_health_bonus: 1.0  # Additional +100% minion HP
+            max_minions: 3  # Additional +3 max minions

api/app/data/classes/oathkeeper.yaml

@@ -0,0 +1,265 @@
+# Oathkeeper - Hybrid Tank/Healer
+# Flexible hybrid class: Choose Aegis of Light (protection/tanking) or Redemption (healing/support)
+
+class_id: oathkeeper
+name: Oathkeeper
+description: >
+  A sacred warrior bound by holy oaths. Oathkeepers excel as versatile protectors,
+  capable of becoming an unyielding shield for their allies or a beacon of healing light.
+  Choose your oath: defend the weak or redeem the fallen.
+
+# Base stats (total: 67)
+base_stats:
+  strength: 12      # Above average physical power
+  dexterity: 9      # Below average agility
+  constitution: 13  # High endurance
+  intelligence: 10  # Average magic
+  wisdom: 12        # Above average perception
+  charisma: 11      # Above average social
+
+starting_equipment:
+  - rusty_sword
+  - rusty_shield
+  - cloth_armor
+  - rusty_knife
+
+starting_abilities:
+  - basic_attack
+
+skill_trees:
+  # ==================== AEGIS OF LIGHT (Protection/Tanking) ====================
+  - tree_id: aegis_of_light
+    name: Aegis of Light
+    description: >
+      The path of the protector. Become an unyielding guardian who shields allies
+      from harm and draws enemy attention through divine resilience.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: taunt
+        name: Taunt
+        description: Challenge enemies to attack you instead of your allies.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - taunt
+
+      - skill_id: blessed_armor
+        name: Blessed Armor
+        description: Divine power enhances your natural toughness.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            constitution: 5
+
+      # --- TIER 2 ---
+      - skill_id: shield_of_faith
+        name: Shield of Faith
+        description: Conjure a holy shield that absorbs damage for you and nearby allies.
+        tier: 2
+        prerequisites:
+          - taunt
+        effects:
+          abilities:
+            - shield_of_faith
+
+      - skill_id: sacred_resilience
+        name: Sacred Resilience
+        description: Your oath grants you resistance to harm.
+        tier: 2
+        prerequisites:
+          - blessed_armor
+        effects:
+          stat_bonuses:
+            constitution: 5
+            resistance: 5
+
+      # --- TIER 3 ---
+      - skill_id: consecrated_ground
+        name: Consecrated Ground
+        description: Bless the ground beneath you, providing damage reduction to allies standing in it.
+        tier: 3
+        prerequisites:
+          - shield_of_faith
+        effects:
+          abilities:
+            - consecrated_ground
+
+      - skill_id: unbreakable_oath
+        name: Unbreakable Oath
+        description: Your oath makes you incredibly difficult to bring down.
+        tier: 3
+        prerequisites:
+          - sacred_resilience
+        effects:
+          stat_bonuses:
+            constitution: 10
+            defense: 10
+
+      # --- TIER 4 ---
+      - skill_id: divine_aegis
+        name: Divine Aegis
+        description: Summon a massive divine shield that protects all allies for 3 turns.
+        tier: 4
+        prerequisites:
+          - consecrated_ground
+        effects:
+          abilities:
+            - divine_aegis
+
+      - skill_id: indomitable
+        name: Indomitable
+        description: Nothing can break your will or body. Massive defensive bonuses.
+        tier: 4
+        prerequisites:
+          - unbreakable_oath
+        effects:
+          stat_bonuses:
+            constitution: 15
+            defense: 15
+          combat_bonuses:
+            damage_reduction: 0.15  # Reduce all damage by 15%
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: last_stand
+        name: Last Stand
+        description: Become invulnerable for 3 turns while taunting all enemies. Cannot be canceled.
+        tier: 5
+        prerequisites:
+          - divine_aegis
+        effects:
+          abilities:
+            - last_stand
+
+      - skill_id: eternal_guardian
+        name: Eternal Guardian
+        description: You are an eternal bastion of protection. Incredible defensive bonuses.
+        tier: 5
+        prerequisites:
+          - indomitable
+        effects:
+          stat_bonuses:
+            constitution: 25
+            defense: 20
+            resistance: 15
+          combat_bonuses:
+            damage_reduction: 0.30  # Additional 30% damage reduction
+
+  # ==================== REDEMPTION (Healing/Support) ====================
+  - tree_id: redemption
+    name: Redemption
+    description: >
+      The path of the redeemer. Channel divine power to heal wounds, cleanse corruption,
+      and grant your allies second chances through sacred intervention.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: lay_on_hands
+        name: Lay on Hands
+        description: Touch an ally to restore their health through divine power.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - lay_on_hands
+
+      - skill_id: divine_wisdom
+        name: Divine Wisdom
+        description: Your wisdom grows through devotion to your oath.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            wisdom: 5
+
+      # --- TIER 2 ---
+      - skill_id: cleanse
+        name: Cleanse
+        description: Remove all debuffs and negative effects from an ally.
+        tier: 2
+        prerequisites:
+          - lay_on_hands
+        effects:
+          abilities:
+            - cleanse
+
+      - skill_id: aura_of_mercy
+        name: Aura of Mercy
+        description: Emit a merciful aura that slowly heals all nearby allies each turn.
+        tier: 2
+        prerequisites:
+          - divine_wisdom
+        effects:
+          passive_effects:
+            - healing_aura  # 3% max HP per turn
+
+      # --- TIER 3 ---
+      - skill_id: word_of_healing
+        name: Word of Healing
+        description: Speak a divine word that heals all allies within range.
+        tier: 3
+        prerequisites:
+          - cleanse
+        effects:
+          abilities:
+            - word_of_healing
+
+      - skill_id: blessed_sacrifice
+        name: Blessed Sacrifice
+        description: Transfer an ally's wounds to yourself, healing them while you take damage.
+        tier: 3
+        prerequisites:
+          - aura_of_mercy
+        effects:
+          abilities:
+            - blessed_sacrifice
+
+      # --- TIER 4 ---
+      - skill_id: divine_blessing
+        name: Divine Blessing
+        description: Grant an ally a powerful blessing that increases their stats and regenerates health.
+        tier: 4
+        prerequisites:
+          - word_of_healing
+        effects:
+          abilities:
+            - divine_blessing
+
+      - skill_id: martyr
+        name: Martyr
+        description: Your willingness to sacrifice yourself empowers your healing abilities.
+        tier: 4
+        prerequisites:
+          - blessed_sacrifice
+        effects:
+          stat_bonuses:
+            wisdom: 15
+          combat_bonuses:
+            healing_power: 0.35  # +35% healing
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: miracle
+        name: Miracle
+        description: Perform a divine miracle, fully healing all allies and removing all debuffs.
+        tier: 5
+        prerequisites:
+          - divine_blessing
+        effects:
+          abilities:
+            - miracle
+
+      - skill_id: sainthood
+        name: Sainthood
+        description: Achieve sainthood through your devotion. Incredible healing and support bonuses.
+        tier: 5
+        prerequisites:
+          - martyr
+        effects:
+          stat_bonuses:
+            wisdom: 25
+            charisma: 15
+          combat_bonuses:
+            healing_power: 0.75  # Additional +75% healing
+            aura_radius: 2  # Increase aura range

api/app/data/classes/vanguard.yaml

@@ -0,0 +1,264 @@
+# Vanguard - Melee Tank/DPS
+# Flexible hybrid class: Choose Shield Bearer (tank) or Weapon Master (DPS)
+
+class_id: vanguard
+name: Vanguard
+description: >
+  A seasoned warrior who stands at the front lines of battle. Vanguards excel in melee combat,
+  capable of becoming an unbreakable shield for their allies or a relentless damage dealer.
+  Choose your path: become a stalwart defender or a devastating weapon master.
+
+# Base stats (total: 65, average: 10.83)
+base_stats:
+  strength: 14      # High physical power
+  dexterity: 10     # Average agility
+  constitution: 14  # High endurance for tanking
+  intelligence: 8   # Low magic
+  wisdom: 10        # Average perception
+  charisma: 9       # Below average social
+
+# Starting equipment (minimal)
+starting_equipment:
+  - rusty_sword
+  - cloth_armor
+  - rusty_knife  # Everyone gets pocket knife
+
+# Starting abilities
+starting_abilities:
+  - basic_attack
+
+# Skill trees (mutually exclusive playstyles)
+skill_trees:
+  # ==================== SHIELD BEARER (Tank) ====================
+  - tree_id: shield_bearer
+    name: Shield Bearer
+    description: >
+      The path of the defender. Master the shield to become an impenetrable fortress,
+      protecting your allies and controlling the battlefield.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: shield_bash
+        name: Shield Bash
+        description: Strike an enemy with your shield, dealing minor damage and stunning them for 1 turn.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - shield_bash  # References ability YAML
+
+      - skill_id: fortify
+        name: Fortify
+        description: Your defensive training grants you enhanced protection.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            defense: 5
+
+      # --- TIER 2 ---
+      - skill_id: shield_wall
+        name: Shield Wall
+        description: Raise your shield to block incoming attacks, reducing damage by 50% for 3 turns.
+        tier: 2
+        prerequisites:
+          - shield_bash
+        effects:
+          abilities:
+            - shield_wall
+
+      - skill_id: iron_skin
+        name: Iron Skin
+        description: Your body becomes hardened through relentless training.
+        tier: 2
+        prerequisites:
+          - fortify
+        effects:
+          stat_bonuses:
+            constitution: 5
+
+      # --- TIER 3 ---
+      - skill_id: guardians_resolve
+        name: Guardian's Resolve
+        description: Your unwavering determination makes you nearly impossible to break.
+        tier: 3
+        prerequisites:
+          - shield_wall
+        effects:
+          stat_bonuses:
+            defense: 10
+          passive_effects:
+            - stun_resistance  # Immune to stun when shield wall active
+
+      - skill_id: riposte
+        name: Riposte
+        description: After blocking an attack, counter with a swift strike.
+        tier: 3
+        prerequisites:
+          - iron_skin
+        effects:
+          abilities:
+            - riposte
+
+      # --- TIER 4 ---
+      - skill_id: bulwark
+        name: Bulwark
+        description: You are a living fortress, shrugging off blows that would fell lesser warriors.
+        tier: 4
+        prerequisites:
+          - guardians_resolve
+        effects:
+          stat_bonuses:
+            constitution: 10
+            resistance: 5
+
+      - skill_id: counter_strike
+        name: Counter Strike
+        description: Enhance your Riposte ability to deal critical damage when countering.
+        tier: 4
+        prerequisites:
+          - riposte
+        effects:
+          ability_enhancements:
+            riposte:
+              crit_chance_bonus: 0.3  # +30% crit on riposte
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: unbreakable
+        name: Unbreakable
+        description: Channel your inner strength to become invulnerable, reducing all damage by 75% for 5 turns.
+        tier: 5
+        prerequisites:
+          - bulwark
+        effects:
+          abilities:
+            - unbreakable  # Ultimate defensive ability
+
+      - skill_id: fortress
+        name: Fortress
+        description: Your defensive mastery reaches its peak. Permanently gain massive defensive bonuses.
+        tier: 5
+        prerequisites:
+          - counter_strike
+        effects:
+          stat_bonuses:
+            defense: 20
+            constitution: 10
+            resistance: 10
+
+  # ==================== WEAPON MASTER (DPS) ====================
+  - tree_id: weapon_master
+    name: Weapon Master
+    description: >
+      The path of destruction. Master devastating melee techniques to cut through enemies
+      with overwhelming physical power.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: power_strike
+        name: Power Strike
+        description: A heavy attack that deals 150% weapon damage.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - power_strike
+
+      - skill_id: weapon_proficiency
+        name: Weapon Proficiency
+        description: Your training with weapons grants increased physical power.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            strength: 5
+
+      # --- TIER 2 ---
+      - skill_id: cleave
+        name: Cleave
+        description: Swing your weapon in a wide arc, hitting all enemies in front of you.
+        tier: 2
+        prerequisites:
+          - power_strike
+        effects:
+          abilities:
+            - cleave  # AoE attack
+
+      - skill_id: battle_frenzy
+        name: Battle Frenzy
+        description: The heat of battle fuels your strength.
+        tier: 2
+        prerequisites:
+          - weapon_proficiency
+        effects:
+          stat_bonuses:
+            strength: 5
+
+      # --- TIER 3 ---
+      - skill_id: rending_blow
+        name: Rending Blow
+        description: Strike with such force that your enemy bleeds for 3 turns.
+        tier: 3
+        prerequisites:
+          - cleave
+        effects:
+          abilities:
+            - rending_blow  # Applies bleed DoT
+
+      - skill_id: brutal_force
+        name: Brutal Force
+        description: Your attacks become devastatingly powerful.
+        tier: 3
+        prerequisites:
+          - battle_frenzy
+        effects:
+          stat_bonuses:
+            strength: 10
+
+      # --- TIER 4 ---
+      - skill_id: execute
+        name: Execute
+        description: Finish off weakened enemies. Deals bonus damage to targets below 30% HP.
+        tier: 4
+        prerequisites:
+          - rending_blow
+        effects:
+          abilities:
+            - execute
+
+      - skill_id: weapon_mastery
+        name: Weapon Mastery
+        description: Your expertise with weapons allows you to find weak points more easily.
+        tier: 4
+        prerequisites:
+          - brutal_force
+        effects:
+          stat_bonuses:
+            strength: 5
+          combat_bonuses:
+            crit_chance: 0.15  # +15% crit chance
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: titans_wrath
+        name: Titan's Wrath
+        description: Unleash a devastating attack that deals 300% weapon damage and stuns all enemies hit.
+        tier: 5
+        prerequisites:
+          - execute
+        effects:
+          abilities:
+            - titans_wrath  # Ultimate offensive ability
+
+      - skill_id: perfect_form
+        name: Perfect Form
+        description: Your combat technique reaches perfection. Massive offensive bonuses.
+        tier: 5
+        prerequisites:
+          - weapon_mastery
+        effects:
+          stat_bonuses:
+            strength: 20
+            dexterity: 10
+          combat_bonuses:
+            crit_chance: 0.1   # Additional +10% crit
+            crit_multiplier: 0.5  # +0.5 to crit multiplier

api/app/data/classes/wildstrider.yaml

@@ -0,0 +1,275 @@
+# Wildstrider - Ranged Physical
+# Flexible hybrid class: Choose Marksmanship (precision ranged) or Beast Companion (pet damage)
+
+class_id: wildstrider
+name: Wildstrider
+description: >
+  A master of the wilds who excels at ranged combat and bonds with nature. Wildstriders
+  can become elite marksmen with unmatched accuracy or beast masters commanding powerful
+  animal companions. Choose your path: perfect your aim or unleash the wild.
+
+# Base stats (total: 66)
+base_stats:
+  strength: 10      # Average physical power
+  dexterity: 14     # High agility
+  constitution: 11  # Above average endurance
+  intelligence: 9   # Below average magic
+  wisdom: 13        # Above average perception
+  charisma: 9       # Below average social
+
+starting_equipment:
+  - rusty_bow
+  - cloth_armor
+  - rusty_knife
+
+starting_abilities:
+  - basic_attack
+
+skill_trees:
+  # ==================== MARKSMANSHIP (Precision Ranged) ====================
+  - tree_id: marksmanship
+    name: Marksmanship
+    description: >
+      The path of the sharpshooter. Master the bow to deliver devastating precision
+      strikes from afar, never missing your mark.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: aimed_shot
+        name: Aimed Shot
+        description: Take careful aim before firing, dealing increased damage with high accuracy.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - aimed_shot
+
+      - skill_id: steady_hand
+        name: Steady Hand
+        description: Your ranged accuracy improves through training.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            dexterity: 5
+
+      # --- TIER 2 ---
+      - skill_id: multishot
+        name: Multishot
+        description: Fire multiple arrows at once, hitting up to 3 targets.
+        tier: 2
+        prerequisites:
+          - aimed_shot
+        effects:
+          abilities:
+            - multishot
+
+      - skill_id: eagle_eye
+        name: Eagle Eye
+        description: Your perception sharpens, increasing critical hit chance with ranged weapons.
+        tier: 2
+        prerequisites:
+          - steady_hand
+        effects:
+          stat_bonuses:
+            wisdom: 5
+          combat_bonuses:
+            ranged_crit_chance: 0.15  # +15% crit with ranged
+
+      # --- TIER 3 ---
+      - skill_id: piercing_shot
+        name: Piercing Shot
+        description: Fire an arrow that pierces through enemies, hitting all in a line.
+        tier: 3
+        prerequisites:
+          - multishot
+        effects:
+          abilities:
+            - piercing_shot
+
+      - skill_id: deadly_aim
+        name: Deadly Aim
+        description: Your arrows find vital spots with deadly precision.
+        tier: 3
+        prerequisites:
+          - eagle_eye
+        effects:
+          stat_bonuses:
+            dexterity: 10
+          combat_bonuses:
+            ranged_crit_chance: 0.10  # Additional +10% crit
+            ranged_crit_multiplier: 0.5  # +0.5 to crit damage
+
+      # --- TIER 4 ---
+      - skill_id: explosive_shot
+        name: Explosive Shot
+        description: Fire an explosive arrow that detonates on impact, damaging nearby enemies.
+        tier: 4
+        prerequisites:
+          - piercing_shot
+        effects:
+          abilities:
+            - explosive_shot
+
+      - skill_id: master_archer
+        name: Master Archer
+        description: Your archery skills reach legendary status.
+        tier: 4
+        prerequisites:
+          - deadly_aim
+        effects:
+          stat_bonuses:
+            dexterity: 15
+          combat_bonuses:
+            ranged_damage_bonus: 0.25  # +25% ranged damage
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: rain_of_arrows
+        name: Rain of Arrows
+        description: Fire countless arrows into the sky that rain down on all enemies.
+        tier: 5
+        prerequisites:
+          - explosive_shot
+        effects:
+          abilities:
+            - rain_of_arrows
+
+      - skill_id: true_shot
+        name: True Shot
+        description: Every arrow finds its mark. Massive ranged combat bonuses.
+        tier: 5
+        prerequisites:
+          - master_archer
+        effects:
+          stat_bonuses:
+            dexterity: 20
+            wisdom: 10
+          combat_bonuses:
+            ranged_damage_bonus: 0.50  # Additional +50% ranged damage
+            ranged_crit_chance: 0.20   # Additional +20% crit
+
+  # ==================== BEAST COMPANION (Pet Damage) ====================
+  - tree_id: beast_companion
+    name: Beast Companion
+    description: >
+      The path of the beast master. Bond with a wild animal companion that fights
+      alongside you, growing stronger as your connection deepens.
+
+    nodes:
+      # --- TIER 1 ---
+      - skill_id: summon_companion
+        name: Summon Companion
+        description: Call a loyal animal companion to fight by your side.
+        tier: 1
+        prerequisites: []
+        effects:
+          abilities:
+            - summon_companion
+
+      - skill_id: animal_bond
+        name: Animal Bond
+        description: Your connection with nature strengthens your companion.
+        tier: 1
+        prerequisites: []
+        effects:
+          stat_bonuses:
+            wisdom: 5
+          combat_bonuses:
+            pet_damage_bonus: 0.15  # +15% pet damage
+
+      # --- TIER 2 ---
+      - skill_id: coordinated_attack
+        name: Coordinated Attack
+        description: Command your companion to attack with you for combined damage.
+        tier: 2
+        prerequisites:
+          - summon_companion
+        effects:
+          abilities:
+            - coordinated_attack
+
+      - skill_id: feral_instinct
+        name: Feral Instinct
+        description: Your companion becomes more ferocious and resilient.
+        tier: 2
+        prerequisites:
+          - animal_bond
+        effects:
+          stat_bonuses:
+            wisdom: 5
+          combat_bonuses:
+            pet_damage_bonus: 0.20  # Additional +20% pet damage
+            pet_health_bonus: 0.25  # +25% pet HP
+
+      # --- TIER 3 ---
+      - skill_id: bestial_wrath
+        name: Bestial Wrath
+        description: Enrage your companion, drastically increasing its damage for 3 turns.
+        tier: 3
+        prerequisites:
+          - coordinated_attack
+        effects:
+          abilities:
+            - bestial_wrath
+
+      - skill_id: wild_empathy
+        name: Wild Empathy
+        description: Your bond with beasts allows your companion to grow stronger.
+        tier: 3
+        prerequisites:
+          - feral_instinct
+        effects:
+          stat_bonuses:
+            wisdom: 10
+          combat_bonuses:
+            pet_damage_bonus: 0.25  # Additional +25% pet damage
+
+      # --- TIER 4 ---
+      - skill_id: primal_fury
+        name: Primal Fury
+        description: Your companion enters a primal rage, dealing massive damage to all enemies.
+        tier: 4
+        prerequisites:
+          - bestial_wrath
+        effects:
+          abilities:
+            - primal_fury
+
+      - skill_id: apex_predator
+        name: Apex Predator
+        description: Your companion becomes an apex predator, feared by all.
+        tier: 4
+        prerequisites:
+          - wild_empathy
+        effects:
+          stat_bonuses:
+            wisdom: 10
+          combat_bonuses:
+            pet_damage_bonus: 0.35  # Additional +35% pet damage
+            pet_health_bonus: 0.50  # Additional +50% pet HP
+            pet_crit_chance: 0.20   # +20% pet crit
+
+      # --- TIER 5 (Ultimate) ---
+      - skill_id: stampede
+        name: Stampede
+        description: Summon a stampede of beasts that trample all enemies, dealing catastrophic damage.
+        tier: 5
+        prerequisites:
+          - primal_fury
+        effects:
+          abilities:
+            - stampede
+
+      - skill_id: one_with_the_wild
+        name: One with the Wild
+        description: You and your companion become one with nature. Incredible bonuses.
+        tier: 5
+        prerequisites:
+          - apex_predator
+        effects:
+          stat_bonuses:
+            wisdom: 20
+            dexterity: 10
+          combat_bonuses:
+            pet_damage_bonus: 1.0  # Additional +100% pet damage (double damage!)
+            pet_health_bonus: 1.0  # Additional +100% pet HP

api/app/data/generic_items.yaml

@@ -0,0 +1,269 @@
+# Generic Item Templates
+# These are common mundane items that the AI can give to players during gameplay.
+# They serve as templates for AI-generated items, providing consistent values
+# for simple items like torches, food, rope, etc.
+#
+# When the AI creates a generic item, the validator will look for a matching
+# template to use as defaults. Items not matching a template will be created
+# with the AI-provided values only.
+
+templates:
+  # Light sources
+  torch:
+    name: "Torch"
+    description: "A wooden torch that provides light in dark places."
+    value: 1
+    is_tradeable: true
+    required_level: 1
+
+  lantern:
+    name: "Lantern"
+    description: "An oil lantern that provides steady light."
+    value: 10
+    is_tradeable: true
+    required_level: 1
+
+  candle:
+    name: "Candle"
+    description: "A simple wax candle."
+    value: 1
+    is_tradeable: true
+    required_level: 1
+
+  # Food and drink
+  bread:
+    name: "Bread"
+    description: "A loaf of bread, possibly stale but still edible."
+    value: 1
+    is_tradeable: true
+    required_level: 1
+
+  apple:
+    name: "Apple"
+    description: "A fresh red apple."
+    value: 1
+    is_tradeable: true
+    required_level: 1
+
+  cheese:
+    name: "Cheese"
+    description: "A wedge of aged cheese."
+    value: 2
+    is_tradeable: true
+    required_level: 1
+
+  rations:
+    name: "Rations"
+    description: "A day's worth of preserved food."
+    value: 5
+    is_tradeable: true
+    required_level: 1
+
+  water:
+    name: "Waterskin"
+    description: "A leather waterskin filled with clean water."
+    value: 2
+    is_tradeable: true
+    required_level: 1
+
+  ale:
+    name: "Ale"
+    description: "A mug of common tavern ale."
+    value: 1
+    is_tradeable: true
+    required_level: 1
+
+  wine:
+    name: "Wine"
+    description: "A bottle of wine."
+    value: 5
+    is_tradeable: true
+    required_level: 1
+
+  # Tools and supplies
+  rope:
+    name: "Rope"
+    description: "A sturdy length of hempen rope, about 50 feet."
+    value: 5
+    is_tradeable: true
+    required_level: 1
+
+  flint:
+    name: "Flint and Steel"
+    description: "A flint and steel for starting fires."
+    value: 3
+    is_tradeable: true
+    required_level: 1
+
+  bedroll:
+    name: "Bedroll"
+    description: "A simple bedroll for sleeping outdoors."
+    value: 5
+    is_tradeable: true
+    required_level: 1
+
+  backpack:
+    name: "Backpack"
+    description: "A sturdy canvas backpack."
+    value: 10
+    is_tradeable: true
+    required_level: 1
+
+  crowbar:
+    name: "Crowbar"
+    description: "An iron crowbar for prying things open."
+    value: 8
+    is_tradeable: true
+    required_level: 1
+
+  hammer:
+    name: "Hammer"
+    description: "A simple hammer."
+    value: 5
+    is_tradeable: true
+    required_level: 1
+
+  pitons:
+    name: "Pitons"
+    description: "A set of iron pitons for climbing."
+    value: 5
+    is_tradeable: true
+    required_level: 1
+
+  grappling_hook:
+    name: "Grappling Hook"
+    description: "A three-pronged iron grappling hook."
+    value: 10
+    is_tradeable: true
+    required_level: 1
+
+  # Writing supplies
+  ink:
+    name: "Ink"
+    description: "A small vial of black ink."
+    value: 5
+    is_tradeable: true
+    required_level: 1
+
+  parchment:
+    name: "Parchment"
+    description: "A sheet of parchment for writing."
+    value: 1
+    is_tradeable: true
+    required_level: 1
+
+  quill:
+    name: "Quill"
+    description: "A feather quill for writing."
+    value: 1
+    is_tradeable: true
+    required_level: 1
+
+  # Containers
+  pouch:
+    name: "Pouch"
+    description: "A small leather pouch."
+    value: 2
+    is_tradeable: true
+    required_level: 1
+
+  sack:
+    name: "Sack"
+    description: "A burlap sack for carrying goods."
+    value: 1
+    is_tradeable: true
+    required_level: 1
+
+  vial:
+    name: "Empty Vial"
+    description: "A small glass vial."
+    value: 1
+    is_tradeable: true
+    required_level: 1
+
+  # Clothing
+  cloak:
+    name: "Cloak"
+    description: "A simple traveler's cloak."
+    value: 5
+    is_tradeable: true
+    required_level: 1
+
+  boots:
+    name: "Boots"
+    description: "A sturdy pair of leather boots."
+    value: 8
+    is_tradeable: true
+    required_level: 1
+
+  gloves:
+    name: "Gloves"
+    description: "A pair of leather gloves."
+    value: 3
+    is_tradeable: true
+    required_level: 1
+
+  # Miscellaneous
+  mirror:
+    name: "Mirror"
+    description: "A small steel mirror."
+    value: 10
+    is_tradeable: true
+    required_level: 1
+
+  bell:
+    name: "Bell"
+    description: "A small brass bell."
+    value: 2
+    is_tradeable: true
+    required_level: 1
+
+  whistle:
+    name: "Whistle"
+    description: "A simple wooden whistle."
+    value: 1
+    is_tradeable: true
+    required_level: 1
+
+  key:
+    name: "Key"
+    description: "A simple iron key."
+    value: 5
+    is_tradeable: true
+    required_level: 1
+
+  map:
+    name: "Map"
+    description: "A rough map of the local area."
+    value: 15
+    is_tradeable: true
+    required_level: 1
+
+  compass:
+    name: "Compass"
+    description: "A magnetic compass for navigation."
+    value: 20
+    is_tradeable: true
+    required_level: 1
+
+  # Simple consumables
+  bandage:
+    name: "Bandage"
+    description: "A clean cloth bandage for basic wound care."
+    value: 2
+    is_tradeable: true
+    required_level: 1
+
+  antidote:
+    name: "Antidote"
+    description: "A basic herbal remedy for common poisons."
+    value: 15
+    is_tradeable: true
+    required_level: 1
+
+  herbs:
+    name: "Herbs"
+    description: "A bundle of useful herbs."
+    value: 3
+    is_tradeable: true
+    required_level: 1

api/app/data/locations/crossville/crossville_crypt.yaml

@@ -0,0 +1,46 @@
+# The Forgotten Crypt - Ancient burial site
+location_id: crossville_crypt
+name: The Forgotten Crypt
+location_type: ruins
+region_id: crossville
+
+description: |
+  Hidden beneath a collapsed stone circle deep in Thornwood Forest lies an
+  ancient crypt. The entrance, half-buried by centuries of accumulated earth
+  and roots, leads down into darkness. Faded carvings on the weathered stones
+  depict figures in robes performing unknown rituals around what appears to be
+  a great black sun.
+
+lore: |
+  Long before Crossville was founded, before even the elves came to these lands,
+  another civilization built monuments to their strange gods. The Forgotten Crypt
+  is one of their burial sites - a place where priest-kings were interred with
+  their servants and treasures. Local legends warn that the dead here do not
+  rest peacefully, and that disturbing their tombs invites a terrible curse.
+
+ambient_description: |
+  The air in the crypt is stale and cold, carrying the musty scent of ancient
+  decay. What little light enters through the broken ceiling reveals dust motes
+  floating in perfectly still air. Stone sarcophagi line the walls, their lids
+  carved with the faces of the long-dead. Some lids have been displaced,
+  revealing empty darkness within. The silence is absolute - even footsteps
+  seem muffled, as if the crypt itself absorbs sound.
+
+available_quests:
+  - quest_undead_menace
+  - quest_ancient_relic
+  - quest_necromancer_lair
+
+npc_ids: []
+
+discoverable_locations: []
+
+is_starting_location: false
+
+tags:
+  - ruins
+  - dangerous
+  - undead
+  - treasure
+  - mystery
+  - boss

api/app/data/locations/crossville/crossville_dungeon.yaml

@@ -0,0 +1,47 @@
+# The Old Mines - Abandoned dungeon beneath the hills
+location_id: crossville_dungeon
+name: The Old Mines
+location_type: dungeon
+region_id: crossville
+
+description: |
+  A network of abandoned mine tunnels carved into the hills north of Crossville.
+  The mines were sealed decades ago after a cave-in killed a dozen workers, but
+  the entrance has recently been found open. Strange sounds echo from the depths,
+  and the few who have ventured inside speak of unnatural creatures lurking in
+  the darkness.
+
+lore: |
+  The mines were originally dug by dwarven prospectors seeking iron ore. They
+  found more than iron - ancient carvings deep in the tunnels suggest something
+  else was buried here long ago. The cave-in that sealed the mines was blamed
+  on unstable rock, but survivors whispered of something awakening in the deep.
+  The mine was sealed and the entrance forbidden, until recent earthquakes
+  reopened the way.
+
+ambient_description: |
+  The mine entrance yawns like a mouth in the hillside, exhaling cold air that
+  smells of wet stone and something older. Rotting timber supports the first
+  few feet of tunnel, beyond which darkness swallows everything. Somewhere
+  in the depths, water drips with metronomic regularity. Occasionally, other
+  sounds echo up from below - scraping, shuffling, or what might be whispered
+  voices.
+
+available_quests:
+  - quest_mine_exploration
+  - quest_lost_miners
+  - quest_ancient_artifact
+
+npc_ids: []
+
+discoverable_locations:
+  - crossville_crypt
+
+is_starting_location: false
+
+tags:
+  - dungeon
+  - dangerous
+  - combat
+  - treasure
+  - mystery

api/app/data/locations/crossville/crossville_forest.yaml

@@ -0,0 +1,45 @@
+# Thornwood Forest - Wilderness area east of village
+location_id: crossville_forest
+name: Thornwood Forest
+location_type: wilderness
+region_id: crossville
+
+description: |
+  A dense woodland stretching east from Crossville, named for the thorny
+  undergrowth that makes travel off the main path treacherous. Ancient oaks
+  and twisted pines block much of the sunlight, creating an perpetual twilight
+  beneath the canopy. The eastern trade road cuts through here, though bandits
+  have made it increasingly dangerous.
+
+lore: |
+  The Thornwood is said to be as old as the mountains themselves. Local legend
+  speaks of an ancient elven settlement deep within the forest, though no one
+  has found it in living memory. What is certain is that the forest hides many
+  secrets - ancient ruins, hidden caves, and creatures that prefer darkness
+  to light. Hunters know to return before nightfall.
+
+ambient_description: |
+  Shafts of pale light filter through the canopy, illuminating swirling motes
+  of dust and pollen. The forest floor is carpeted with fallen leaves and
+  treacherous roots. Birds call from the branches above, falling silent
+  whenever something large moves through the underbrush. The air is thick
+  with the scent of damp earth and decaying vegetation.
+
+available_quests:
+  - quest_bandit_camp
+  - quest_herb_gathering
+  - quest_lost_traveler
+
+npc_ids: []
+
+discoverable_locations:
+  - crossville_dungeon
+  - crossville_crypt
+
+is_starting_location: false
+
+tags:
+  - wilderness
+  - dangerous
+  - exploration
+  - hunting

api/app/data/locations/crossville/crossville_tavern.yaml

@@ -0,0 +1,47 @@
+# The Rusty Anchor Tavern - Social hub of Crossville
+location_id: crossville_tavern
+name: The Rusty Anchor Tavern
+location_type: tavern
+region_id: crossville
+
+description: |
+  A weathered two-story establishment at the heart of Crossville Village.
+  The wooden sign creaks in the wind, depicting a rusted ship's anchor - an
+  odd choice for a landlocked village. Inside, travelers and locals alike
+  gather around rough-hewn tables to share drinks, stories, and rumors.
+
+lore: |
+  Founded eighty years ago by a retired sailor named Captain Morgath, the
+  Rusty Anchor has served as Crossville's social hub for generations.
+  The captain's old anchor hangs above the fireplace, supposedly recovered
+  from a shipwreck that cost him his crew. Many adventurers have planned
+  expeditions over tankards of the house special - a dark ale brewed from
+  a secret recipe the captain brought from the coast.
+
+ambient_description: |
+  The tavern interior is warm and dimly lit by oil lamps and the glow of
+  the stone hearth. Pipe smoke hangs in lazy clouds above the regulars'
+  corner. The air smells of ale, roasted meat, and wood polish. A bard
+  occasionally plucks at a lute in the corner, though tonight the only
+  music is the murmur of conversation and the crackle of the fire.
+
+available_quests:
+  - quest_cellar_rats
+  - quest_missing_shipment
+
+npc_ids:
+  - npc_grom_ironbeard
+  - npc_mira_swiftfoot
+
+discoverable_locations:
+  - crossville_dungeon
+  - crossville_forest
+
+is_starting_location: false
+
+tags:
+  - social
+  - rest
+  - rumors
+  - merchant
+  - information

api/app/data/locations/crossville/crossville_village.yaml

@@ -0,0 +1,44 @@
+# Crossville Village - The main settlement
+location_id: crossville_village
+name: Crossville Village
+location_type: town
+region_id: crossville
+
+description: |
+  A modest farming village built around a central square where several roads
+  meet. Stone and timber buildings line the main street, with the mayor's
+  manor overlooking the square from a small hill. Farmers sell produce at
+  market stalls while merchants hawk wares from distant lands.
+
+lore: |
+  Founded two centuries ago by settlers from the eastern kingdoms, Crossville
+  grew from a simple waystation into a thriving village. The original stone
+  well in the center of the square is said to have been blessed by a traveling
+  cleric, and the village has never suffered drought since.
+
+ambient_description: |
+  The village square bustles with activity - farmers haggling over prices,
+  children running between market stalls, and the rhythmic clang of the
+  blacksmith's hammer echoing from his forge. The smell of fresh bread
+  drifts from the bakery, mixing with the earthier scents of livestock
+  and hay.
+
+available_quests:
+  - quest_mayors_request
+  - quest_missing_merchant
+
+npc_ids:
+  - npc_mayor_aldric
+  - npc_blacksmith_hilda
+
+discoverable_locations:
+  - crossville_tavern
+  - crossville_forest
+
+is_starting_location: true
+
+tags:
+  - town
+  - social
+  - merchant
+  - safe

api/app/data/locations/regions/crossville.yaml

@@ -0,0 +1,16 @@
+# Crossville Region - Starting area for new adventurers
+region_id: crossville
+name: Crossville Province
+description: |
+  A quiet farming province on the frontier of the kingdom. Crossville sits at
+  the crossroads of several trade routes, making it a natural gathering point
+  for travelers, merchants, and those seeking adventure. The village has
+  prospered from this trade, though recent bandit activity has made the roads
+  less safe than they once were.
+
+location_ids:
+  - crossville_village
+  - crossville_tavern
+  - crossville_forest
+  - crossville_dungeon
+  - crossville_crypt

api/app/data/loot_tables.yaml

@@ -0,0 +1,281 @@
+# Loot Tables
+# Defines what items can be found when searching in different locations.
+# Items are referenced by their template key from generic_items.yaml.
+#
+# Rarity tiers determine selection based on check margin:
+#   - common: margin < 5 (just barely passed)
+#   - uncommon: margin 5-9 (solid success)
+#   - rare: margin >= 10 (excellent roll)
+#
+# Gold ranges are also determined by margin.
+
+# Default loot for unspecified locations
+default:
+  common:
+    - torch
+    - flint
+    - rope
+    - rations
+  uncommon:
+    - lantern
+    - crowbar
+    - bandage
+    - herbs
+  rare:
+    - compass
+    - map
+    - antidote
+  gold:
+    min: 1
+    max: 10
+    bonus_per_margin: 1  # Extra gold per margin point
+
+# Forest/wilderness locations
+forest:
+  common:
+    - herbs
+    - apple
+    - flint
+    - rope
+  uncommon:
+    - rations
+    - antidote
+    - bandage
+    - water
+  rare:
+    - map
+    - compass
+    - grappling_hook
+  gold:
+    min: 0
+    max: 5
+    bonus_per_margin: 0
+
+# Cave/dungeon locations
+cave:
+  common:
+    - torch
+    - flint
+    - rope
+    - pitons
+  uncommon:
+    - lantern
+    - crowbar
+    - grappling_hook
+    - bandage
+  rare:
+    - map
+    - compass
+    - key
+  gold:
+    min: 5
+    max: 25
+    bonus_per_margin: 2
+
+dungeon:
+  common:
+    - torch
+    - key
+    - rope
+    - bandage
+  uncommon:
+    - lantern
+    - crowbar
+    - antidote
+    - map
+  rare:
+    - compass
+    - grappling_hook
+    - mirror
+  gold:
+    min: 10
+    max: 50
+    bonus_per_margin: 3
+
+# Town/city locations
+town:
+  common:
+    - bread
+    - apple
+    - ale
+    - candle
+  uncommon:
+    - cheese
+    - wine
+    - rations
+    - parchment
+  rare:
+    - map
+    - ink
+    - quill
+  gold:
+    min: 2
+    max: 15
+    bonus_per_margin: 1
+
+tavern:
+  common:
+    - bread
+    - cheese
+    - ale
+    - candle
+  uncommon:
+    - wine
+    - rations
+    - water
+    - key
+  rare:
+    - map
+    - pouch
+    - mirror
+  gold:
+    min: 3
+    max: 20
+    bonus_per_margin: 2
+
+# Ruins/ancient locations
+ruins:
+  common:
+    - torch
+    - parchment
+    - vial
+    - rope
+  uncommon:
+    - ink
+    - quill
+    - mirror
+    - key
+  rare:
+    - map
+    - compass
+    - antidote
+  gold:
+    min: 10
+    max: 40
+    bonus_per_margin: 3
+
+# Camp/outdoor locations
+camp:
+  common:
+    - rations
+    - water
+    - bedroll
+    - flint
+  uncommon:
+    - rope
+    - torch
+    - bandage
+    - sack
+  rare:
+    - lantern
+    - backpack
+    - map
+  gold:
+    min: 1
+    max: 10
+    bonus_per_margin: 1
+
+# Merchant/shop locations
+shop:
+  common:
+    - pouch
+    - sack
+    - candle
+    - parchment
+  uncommon:
+    - ink
+    - quill
+    - vial
+    - key
+  rare:
+    - map
+    - mirror
+    - compass
+  gold:
+    min: 5
+    max: 30
+    bonus_per_margin: 2
+
+# Road/path locations
+road:
+  common:
+    - rope
+    - flint
+    - water
+    - bread
+  uncommon:
+    - bandage
+    - rations
+    - torch
+    - boots
+  rare:
+    - map
+    - compass
+    - cloak
+  gold:
+    min: 1
+    max: 15
+    bonus_per_margin: 1
+
+# Castle/fortress locations
+castle:
+  common:
+    - torch
+    - candle
+    - key
+    - parchment
+  uncommon:
+    - lantern
+    - ink
+    - quill
+    - mirror
+  rare:
+    - map
+    - compass
+    - crowbar
+  gold:
+    min: 15
+    max: 60
+    bonus_per_margin: 4
+
+# Dock/port locations
+dock:
+  common:
+    - rope
+    - water
+    - rations
+    - sack
+  uncommon:
+    - grappling_hook
+    - lantern
+    - map
+    - flint
+  rare:
+    - compass
+    - backpack
+    - cloak
+  gold:
+    min: 5
+    max: 25
+    bonus_per_margin: 2
+
+# Mine locations
+mine:
+  common:
+    - torch
+    - pitons
+    - rope
+    - hammer
+  uncommon:
+    - lantern
+    - crowbar
+    - flint
+    - bandage
+  rare:
+    - grappling_hook
+    - map
+    - key
+  gold:
+    min: 15
+    max: 50
+    bonus_per_margin: 3

api/app/data/npcs/crossville/npc_blacksmith_hilda.yaml

@@ -0,0 +1,93 @@
+# Hilda Ironforge - Village Blacksmith
+npc_id: npc_blacksmith_hilda
+name: Hilda Ironforge
+role: blacksmith
+location_id: crossville_village
+
+personality:
+  traits:
+    - straightforward
+    - hardworking
+    - proud of her craft
+    - protective of the village
+    - stubborn as iron
+  speech_style: |
+    Blunt and direct - says what she means without flourish. Her voice
+    carries the confidence of someone who knows their worth. Uses
+    smithing metaphors often ("hammer out the details," "strike while
+    hot"). Speaks slowly and deliberately, each word carrying weight.
+  quirks:
+    - Absent-mindedly hammers on things when thinking
+    - Inspects every weapon she sees for quality
+    - Refuses to sell poorly-made goods even at high prices
+    - Hums dwarven work songs while forging
+
+appearance:
+  brief: Muscular dwarven woman with soot-streaked red hair, burn-scarred forearms, and an appraising gaze
+  detailed: |
+    Hilda is built like a forge - solid, hot-tempered, and productive.
+    Her red hair is pulled back in a practical braid, streaked with
+    grey and permanently dusted with soot. Her forearms are a map of
+    old burns and calluses, badges of honor in her trade. She wears a
+    leather apron over practical clothes, and her hands are never far
+    from a hammer. Her eyes assess everything with the critical gaze of
+    a master craftsman, always noting quality - or its lack.
+
+knowledge:
+  public:
+    - The best iron ore came from the Old Mines before they were sealed
+    - She can repair almost anything made of metal
+    - Bandit attacks have increased demand for weapons
+    - Her family has been smithing in Crossville for four generations
+  secret:
+    - Her grandfather forged something for the previous mayor - something that was buried
+    - She has the original designs for that artifact
+    - The ore in the mines had unusual properties - made metal stronger
+    - She suspects the bandits are looking for her grandfather's work
+  will_share_if:
+    - condition: "interaction_count >= 4"
+      reveals: "Mentions her grandfather worked on a special project for the mayor's family"
+    - condition: "custom_flags.brought_quality_ore == true"
+      reveals: "Shares that the mine ore was special - almost magical"
+    - condition: "relationship_level >= 75"
+      reveals: "Shows them her grandfather's old designs"
+    - condition: "custom_flags.proved_worthy_warrior == true"
+      reveals: "Offers to forge them something special if they find the right materials"
+
+relationships:
+  - npc_id: npc_grom_ironbeard
+    attitude: friendly
+    reason: Old drinking companions and fellow dwarves
+  - npc_id: npc_mayor_aldric
+    attitude: respectful but curious
+    reason: The Thornwood family has secrets connected to her own
+
+inventory_for_sale:
+  - item: sword_iron
+    price: 50
+  - item: shield_iron
+    price: 40
+  - item: armor_chainmail
+    price: 150
+  - item: dagger_steel
+    price: 25
+  - item: repair_service
+    price: 20
+
+dialogue_hooks:
+  greeting: "*sets down hammer* Something you need forged, or just looking?"
+  farewell: "May your blade stay sharp and your armor hold."
+  busy: "*keeps hammering* Talk while I work. Time is iron."
+  quest_complete: "*nods approvingly* Fine work. You've got the heart of a warrior."
+
+quest_giver_for:
+  - quest_ore_delivery
+  - quest_equipment_repair
+
+reveals_locations: []
+
+tags:
+  - merchant
+  - quest_giver
+  - craftsman
+  - dwarf

api/app/data/npcs/crossville/npc_grom_ironbeard.yaml

@@ -0,0 +1,95 @@
+# Grom Ironbeard - Tavern Bartender
+npc_id: npc_grom_ironbeard
+name: Grom Ironbeard
+role: bartender
+location_id: crossville_tavern
+
+personality:
+  traits:
+    - gruff
+    - secretly kind
+    - protective of regulars
+    - distrustful of strangers
+    - nostalgic about his adventuring days
+  speech_style: |
+    Short, clipped sentences. Heavy dwarvish accent - often drops articles
+    ("Need a drink?" becomes "Need drink?"). Speaks in a gravelly baritone.
+    Uses "lad" and "lass" frequently. Never raises his voice unless truly angry.
+  quirks:
+    - Polishes the same glass when nervous or thinking
+    - Tugs his beard when considering something seriously
+    - Refuses to serve anyone who insults his ale
+    - Hums old mining songs when the tavern is quiet
+
+appearance:
+  brief: Stocky dwarf with a braided grey beard, one clouded eye, and arms like tree trunks
+  detailed: |
+    Standing barely four feet tall, Grom's broad shoulders and thick arms
+    speak to decades of barrel-lifting and troublemaker-throwing. His grey
+    beard is immaculately braided with copper rings passed down from his
+    grandfather. A milky cataract clouds his left eye - a souvenir from his
+    adventuring days - but his right eye misses nothing that happens in his
+    tavern. His apron is always clean, though his hands bear the calluses
+    of hard work.
+
+knowledge:
+  public:
+    - Local gossip about Mayor Aldric raising taxes again
+    - The road east through Thornwood has been plagued by bandits
+    - A traveling merchant was asking about ancient ruins last week
+    - The blacksmith Hilda needs more iron ore but the mines are sealed
+  secret:
+    - Hidden passage behind the wine barrels leads to old smuggling tunnels
+    - The mayor is being blackmailed by someone - he's seen the letters
+    - Knows the location of a legendary dwarven forge in the mountains
+    - The cave-in in the mines wasn't natural - something broke through from below
+  will_share_if:
+    - condition: "interaction_count >= 3"
+      reveals: "Mentions he used to be an adventurer who explored the Old Mines"
+    - condition: "custom_flags.helped_with_rowdy_patrons == true"
+      reveals: "Shows them the hidden passage behind the wine barrels"
+    - condition: "relationship_level >= 70"
+      reveals: "Confides about the mayor's blackmail situation"
+    - condition: "relationship_level >= 85"
+      reveals: "Shares the location of the dwarven forge"
+
+relationships:
+  - npc_id: npc_mayor_aldric
+    attitude: distrustful
+    reason: Mayor raised tavern taxes unfairly and seems nervous lately
+  - npc_id: npc_mira_swiftfoot
+    attitude: protective
+    reason: She reminds him of his daughter who died young
+  - npc_id: npc_blacksmith_hilda
+    attitude: friendly
+    reason: Fellow dwarf and drinking companion for decades
+
+inventory_for_sale:
+  - item: ale
+    price: 2
+  - item: dwarven_stout
+    price: 5
+  - item: meal_hearty
+    price: 8
+  - item: room_night
+    price: 15
+  - item: information_local
+    price: 10
+
+dialogue_hooks:
+  greeting: "*grunts* What'll it be? And don't waste my time."
+  farewell: "*nods* Don't cause trouble out there."
+  busy: "Got thirsty folk to serve. Make it quick."
+  quest_complete: "*actually smiles* Well done, lad. Drink's on the house."
+
+quest_giver_for:
+  - quest_cellar_rats
+
+reveals_locations:
+  - crossville_dungeon
+
+tags:
+  - merchant
+  - quest_giver
+  - information_source
+  - dwarf

api/app/data/npcs/crossville/npc_mayor_aldric.yaml

@@ -0,0 +1,83 @@
+# Mayor Aldric Thornwood - Village Leader
+npc_id: npc_mayor_aldric
+name: Mayor Aldric Thornwood
+role: mayor
+location_id: crossville_village
+
+personality:
+  traits:
+    - outwardly confident
+    - secretly terrified
+    - genuinely cares about the village
+    - increasingly desperate
+    - hiding something significant
+  speech_style: |
+    Speaks with the practiced cadence of a politician - measured words,
+    careful pauses for effect. His voice wavers slightly when stressed,
+    and he has a habit of clearing his throat before difficult topics.
+    Uses formal address even in casual conversation.
+  quirks:
+    - Constantly adjusts his mayoral chain of office
+    - Glances at his manor when the Old Mines are mentioned
+    - Keeps touching a ring on his left hand
+    - Offers wine to guests but never drinks himself
+
+appearance:
+  brief: Tall, thin man with receding grey hair, worry lines, and expensive but slightly disheveled clothing
+  detailed: |
+    Mayor Aldric carries himself with the posture of authority, though
+    lately that posture has developed a slight stoop. His grey hair,
+    once meticulously combed, shows signs of distracted neglect. His
+    clothes are fine but wrinkled, and dark circles under his eyes
+    suggest many sleepless nights. The heavy gold chain of his office
+    seems to weigh on him more than it should. His hands tremble
+    slightly when he thinks no one is watching.
+
+knowledge:
+  public:
+    - The village has prospered under his ten-year leadership
+    - Taxes were raised to fund road repairs and militia expansion
+    - He's offering a reward for clearing the bandit threat
+    - The Old Mines are sealed for safety reasons
+  secret:
+    - He's being blackmailed by someone who knows about the mines
+    - His grandfather found something in the mines that should stay buried
+    - The blackmailer wants access to the crypt
+    - He knows the earthquake that reopened the mines wasn't natural
+  will_share_if:
+    - condition: "relationship_level >= 60"
+      reveals: "Admits the tax increase was forced by external pressure"
+    - condition: "custom_flags.proved_trustworthy == true"
+      reveals: "Confesses he's being blackmailed but won't say by whom"
+    - condition: "relationship_level >= 80"
+      reveals: "Shares his grandfather's journal about the mines"
+    - condition: "custom_flags.defeated_blackmailer == true"
+      reveals: "Reveals everything about what's buried in the crypt"
+
+relationships:
+  - npc_id: npc_grom_ironbeard
+    attitude: guilty
+    reason: Knows the tax increase hurt the tavern unfairly
+  - npc_id: npc_blacksmith_hilda
+    attitude: respectful
+    reason: Her family has served the village for generations
+
+inventory_for_sale: []
+
+dialogue_hooks:
+  greeting: "*straightens his chain* Ah, welcome to Crossville. How may I be of service?"
+  farewell: "The village thanks you. May your roads be safe."
+  busy: "*distracted* I have urgent matters to attend. Perhaps later?"
+  quest_complete: "*genuine relief* You have done Crossville a great service."
+
+quest_giver_for:
+  - quest_mayors_request
+  - quest_bandit_threat
+
+reveals_locations:
+  - crossville_dungeon
+
+tags:
+  - quest_giver
+  - authority
+  - human

api/app/data/npcs/crossville/npc_mira_swiftfoot.yaml

@@ -0,0 +1,90 @@
+# Mira Swiftfoot - Rogue and Information Broker
+npc_id: npc_mira_swiftfoot
+name: Mira Swiftfoot
+role: rogue
+location_id: crossville_tavern
+
+personality:
+  traits:
+    - curious
+    - street-smart
+    - morally flexible
+    - loyal once trust is earned
+    - haunted by her past
+  speech_style: |
+    Quick and clever, often speaking in half-sentences as if her mouth
+    can't keep up with her racing thoughts. Uses thieves' cant occasionally.
+    Tends to deflect personal questions with humor or questions of her own.
+    Her voice drops to a whisper when sharing secrets.
+  quirks:
+    - Always sits with her back to the wall, facing the door
+    - Fidgets with a coin, rolling it across her knuckles
+    - Sizes up everyone who enters the tavern
+    - Never drinks anything she didn't pour herself
+
+appearance:
+  brief: Slender half-elf with sharp green eyes, dark hair cut short, and fingers that never stop moving
+  detailed: |
+    Mira moves with the easy grace of someone used to slipping through
+    shadows unnoticed. Her dark hair is cut practically short, framing
+    an angular face with sharp green eyes that seem to catalog everything
+    they see. She dresses in muted colors - browns and greys that blend
+    into any crowd. A thin scar runs from her left ear to her jaw, and
+    she wears leather bracers that probably hide more than calluses.
+
+knowledge:
+  public:
+    - The bandits in Thornwood are more organized than simple thieves
+    - There's a fence in the city who buys no-questions-asked
+    - The mayor's been receiving mysterious visitors at night
+    - Several people have gone missing in the forest lately
+  secret:
+    - The bandit leader is a former soldier named Kael
+    - She knows a secret entrance to the crypt through the forest
+    - The missing people were all asking about the Old Mines
+    - She's actually running from a thieves' guild she betrayed
+  will_share_if:
+    - condition: "interaction_count >= 2"
+      reveals: "Mentions the bandits seem to be searching for something specific"
+    - condition: "custom_flags.shared_drink == true"
+      reveals: "Admits she knows more about the forest than most"
+    - condition: "relationship_level >= 65"
+      reveals: "Reveals she knows a secret path to the crypt"
+    - condition: "relationship_level >= 80"
+      reveals: "Tells them about Kael and offers to help infiltrate the bandits"
+
+relationships:
+  - npc_id: npc_grom_ironbeard
+    attitude: affectionate
+    reason: He's the closest thing to family she has
+  - npc_id: npc_mayor_aldric
+    attitude: suspicious
+    reason: Something about him doesn't add up
+
+inventory_for_sale:
+  - item: lockpick_set
+    price: 25
+  - item: rope_silk
+    price: 15
+  - item: map_local
+    price: 20
+
+dialogue_hooks:
+  greeting: "*looks you over* New face. What brings you to our little crossroads?"
+  farewell: "Watch your back out there. Trust me on that."
+  busy: "*glances at the door* Not now. Later."
+  quest_complete: "*grins* You've got potential. Stick around."
+
+quest_giver_for:
+  - quest_bandit_camp
+
+reveals_locations:
+  - crossville_forest
+  - crossville_crypt
+
+tags:
+  - information_source
+  - merchant
+  - quest_giver
+  - rogue
+  - half-elf

api/app/data/origins.yaml

@@ -0,0 +1,158 @@
+# Character Origin Stories
+# These are saved to the character and referenced by the AI DM throughout the game
+# to create personalized narrative experiences and quest hooks.
+
+origins:
+  soul_revenant:
+    id: soul_revenant
+    name: Soul Revenant
+    description: |
+      You died centuries ago, but death was not the end. Through dark magic, divine
+      intervention, or a cosmic mistake, you have been returned to the world of the
+      living. Your memories are fragmented—flashes of a life long past, faces you once
+      knew now turned to dust, and deeds both noble and terrible that weigh upon your soul.
+
+      The world has changed beyond recognition. The kingdom you served no longer exists,
+      the people you loved are gone, and the wrongs you committed—or suffered—can never
+      be undone. Yet here you stand, given a second chance you never asked for.
+
+      You awaken in an ancient crypt, your body restored but your purpose unclear.
+      Are you here to atone? To finish unfinished business? Or simply to understand
+      why you were brought back?
+
+    starting_location:
+      id: forgotten_crypt
+      name: The Forgotten Crypt
+      region: Shadowmere Necropolis
+      description: Ancient burial grounds beneath twisted trees, where the veil between life and death grows thin
+
+    narrative_hooks:
+      - Past lives and forgotten memories that surface during gameplay
+      - NPCs or descendants related to your previous life
+      - Unfinished business from centuries ago
+      - Haunted by spectral visions or voices from the past
+      - Divine or dark entities interested in your return
+      - Questions about identity and purpose across lifetimes
+
+    starting_bonus:
+      trait: Deathless Resolve
+      description: You have walked through death itself. Fear holds less power over you.
+      effect: +2 WIS, resistance to fear effects
+
+  memory_thief:
+    id: memory_thief
+    name: Memory Thief
+    description: |
+      You opened your eyes in an open field with no memory of who you are, where you
+      came from, or how you got here. Your mind is a blank slate—no name, no past,
+      no identity. Even your own face in a reflection seems like a stranger's.
+
+      The only thing you possess is an overwhelming sense that something was taken
+      from you. Your memories weren't simply lost—they were stolen. By whom? Why?
+      You don't know. But deep in your gut, you feel that discovering the truth might
+      be more terrifying than living in ignorance.
+
+      As you wander the world, fragments occasionally surface—a fleeting image, a
+      half-remembered name, a skill you didn't know you had. Are these clues to your
+      real identity, or false memories planted by whoever stole your past?
+
+      One thing is certain: you must piece together who you were, even if you discover
+      you were someone you'd rather not remember.
+
+    starting_location:
+      id: thornfield_plains
+      name: Thornfield Plains
+      region: The Midlands
+      description: Vast open grasslands where merchant roads cross, a place of new beginnings for the lost
+
+    narrative_hooks:
+      - Gradual memory fragments revealed during key story moments
+      - NPCs who seem to recognize you but you don't remember them
+      - Clues to your stolen past hidden in the world
+      - A mysterious organization or individual who took your memories
+      - Skills or knowledge you possess without knowing why
+      - Identity crisis as you discover who you might have been
+
+    starting_bonus:
+      trait: Blank Slate
+      description: Without a past to define you, you adapt quickly to new situations.
+      effect: +1 to all stats, faster skill learning
+
+  shadow_apprentice:
+    id: shadow_apprentice
+    name: Shadow Apprentice
+    description: |
+      You were raised in darkness—literally and figuratively. From childhood, you were
+      trained by a mysterious master who taught you the arts of stealth, deception,
+      and survival in the underworld. You learned to move unseen, to read people's
+      secrets in their eyes, and to trust no one.
+
+      Your master never revealed why they chose you, only that you had "potential."
+      For years, you honed your skills in the shadows, taking on jobs that required
+      discretion and ruthlessness. You became a weapon in your master's hands.
+
+      But recently, everything changed. Your master disappeared without a word, leaving
+      you with only your training and a single cryptic message: "Trust no one. Not even me."
+
+      Now you walk alone, unsure if your master abandoned you, was captured, or is
+      testing you one final time. The underworld you once navigated so confidently
+      suddenly feels hostile and full of eyes watching from the darkness.
+
+    starting_location:
+      id: shadowfen
+      name: Shadowfen
+      region: The Murkvale
+      description: A misty swamp settlement where outlaws and exiles gather, hidden from the world's judging eyes
+
+    narrative_hooks:
+      - The mysterious master and their true motivations
+      - Dark organizations or guilds from your past
+      - Moral dilemmas between loyalty and self-preservation
+      - Rivals or enemies from your apprenticeship
+      - Secrets your master never told you
+      - The true reason you were chosen and trained
+
+    starting_bonus:
+      trait: Trained in Shadows
+      description: Your master taught you well. The darkness is your ally.
+      effect: +2 DEX, +1 CHA, advantage on stealth checks in darkness
+
+  escaped_captive:
+    id: escaped_captive
+    name: The Escaped Captive
+    description: |
+      You were a prisoner at Ironpeak Pass, one of the most notorious holding facilities
+      in the realm. How you ended up there, you remember all too well—whether you were
+      guilty or innocent, the iron bars didn't care. Days blurred into weeks, weeks into
+      months, and you felt yourself becoming just another forgotten soul.
+
+      But you refused to accept that fate. Through cunning, luck, or sheer desperation,
+      you escaped. Now you stand on the other side of those mountain walls, breathing
+      free air for the first time in what feels like forever.
+
+      Freedom tastes sweet, but it comes with a price. The authorities will be searching
+      for you. Your face might be on wanted posters. Anyone who learns of your past might
+      turn you in for a reward. You must build a new life while constantly looking over
+      your shoulder.
+
+      Can you truly start fresh, or will your past always define you? That depends on
+      the choices you make from here.
+
+    starting_location:
+      id: ironpeak_pass
+      name: Ironpeak Pass
+      region: The Frost Peaks
+      description: A treacherous mountain passage near the prison you escaped, where few travelers venture
+
+    narrative_hooks:
+      - Bounty hunters or guards searching for you
+      - NPCs who recognize you from your past
+      - The crime you were imprisoned for (guilty or framed)
+      - Fellow prisoners or guards from Ironpeak
+      - Building a new identity while hiding your past
+      - Redemption arc or embracing your criminal nature
+
+    starting_bonus:
+      trait: Hardened Survivor
+      description: Prison taught you to endure hardship and seize opportunities.
+      effect: +2 CON, +1 STR, bonus to survival and escape checks