feat(api): implement combat loot integration with hybrid static/procedural system

Add CombatLootService that orchestrates loot generation from combat,
supporting both static item drops (consumables, materials) and procedural
equipment generation (weapons, armor with affixes).

Key changes:
- Extend LootEntry model with LootType enum (STATIC/PROCEDURAL)
- Create StaticItemLoader service for consumables/materials from YAML
- Create CombatLootService with full rarity formula incorporating:
  - Party average level
  - Enemy difficulty tier (EASY: +0%, MEDIUM: +5%, HARD: +15%, BOSS: +30%)
  - Character luck stat
  - Per-entry rarity bonus
- Integrate with CombatService._calculate_rewards() for automatic loot gen
- Add boss guaranteed drops via generate_boss_loot()

New enemy variants (goblin family proof-of-concept):
- goblin_scout (Easy) - static drops only
- goblin_warrior (Medium) - static + procedural weapon drops
- goblin_chieftain (Hard) - static + procedural weapon/armor drops

Static items added:
- consumables.yaml: health/mana potions, elixirs, food
- materials.yaml: trophy items, crafting materials

Tests: 59 new tests across 3 test files (all passing)

.gitignore

@@ -35,3 +35,4 @@ Thumbs.db
 logs/
 app/logs/
 *.log
+CLAUDE.md

api/app/__init__.py

@@ -164,8 +164,22 @@ def register_blueprints(app: Flask) -> None:
     app.register_blueprint(npcs_bp)
     logger.info("NPCs API blueprint registered")
 
+    # Import and register Chat API blueprint
+    from app.api.chat import chat_bp
+    app.register_blueprint(chat_bp)
+    logger.info("Chat API blueprint registered")
+
+    # Import and register Combat API blueprint
+    from app.api.combat import combat_bp
+    app.register_blueprint(combat_bp)
+    logger.info("Combat API blueprint registered")
+
+    # Import and register Inventory API blueprint
+    from app.api.inventory import inventory_bp
+    app.register_blueprint(inventory_bp)
+    logger.info("Inventory API blueprint registered")
+
     # TODO: Register additional blueprints as they are created
-    # from app.api import combat, marketplace, shop
-    # app.register_blueprint(combat.bp, url_prefix='/api/v1/combat')
+    # from app.api import marketplace, shop
     # app.register_blueprint(marketplace.bp, url_prefix='/api/v1/marketplace')
     # app.register_blueprint(shop.bp, url_prefix='/api/v1/shop')

api/app/api/auth.py

@@ -15,6 +15,7 @@ from flask import Blueprint, request, make_response, render_template, redirect,
 from appwrite.exception import AppwriteException
 
 from app.services.appwrite_service import AppwriteService
+from app.services.session_cache_service import SessionCacheService
 from app.utils.response import (
     success_response,
     created_response,
@@ -305,7 +306,11 @@ def api_logout():
         if not token:
             return unauthorized_response(message="No active session")
 
-        # Logout user
+        # Invalidate session cache before Appwrite logout
+        cache = SessionCacheService()
+        cache.invalidate_token(token)
+
+        # Logout user from Appwrite
         appwrite = AppwriteService()
         appwrite.logout_user(session_id=token)
 
@@ -340,6 +345,36 @@ def api_logout():
         return error_response(message="An unexpected error occurred", code="INTERNAL_ERROR")
 
 
+@auth_bp.route('/api/v1/auth/me', methods=['GET'])
+@require_auth
+def api_get_current_user():
+    """
+    Get the currently authenticated user's data.
+
+    This endpoint is lightweight and uses cached session data when available,
+    making it suitable for frequent use (e.g., checking user tier, verifying
+    session is still valid).
+
+    Returns:
+        200: User data
+        401: Not authenticated
+    """
+    user = get_current_user()
+
+    if not user:
+        return unauthorized_response(message="Not authenticated")
+
+    return success_response(
+        result={
+            "id": user.id,
+            "email": user.email,
+            "name": user.name,
+            "email_verified": user.email_verified,
+            "tier": user.tier
+        }
+    )
+
+
 @auth_bp.route('/api/v1/auth/verify-email', methods=['GET'])
 def api_verify_email():
     """
@@ -480,6 +515,10 @@ def api_reset_password():
         appwrite = AppwriteService()
         appwrite.confirm_password_reset(user_id=user_id, secret=secret, password=password)
 
+        # Invalidate all cached sessions for this user (security: password changed)
+        cache = SessionCacheService()
+        cache.invalidate_user(user_id)
+
         logger.info("Password reset successfully", user_id=user_id)
 
         return success_response(

api/app/api/chat.py

@@ -0,0 +1,320 @@
+"""
+Chat API Endpoints.
+
+Provides REST API for accessing player-NPC conversation history,
+searching messages, and managing chat data.
+"""
+
+from flask import Blueprint, request
+from datetime import datetime, timezone
+
+from app.utils.auth import require_auth, get_current_user
+from app.services.chat_message_service import (
+    get_chat_message_service,
+    ChatMessageNotFound,
+    ChatMessagePermissionDenied
+)
+from app.services.npc_loader import get_npc_loader
+from app.models.chat_message import MessageContext
+from app.utils.response import (
+    success_response,
+    error_response,
+    not_found_response,
+    validation_error_response
+)
+from app.utils.logging import get_logger
+
+logger = get_logger(__file__)
+
+chat_bp = Blueprint('chat', __name__)
+
+
+@chat_bp.route('/api/v1/characters/<character_id>/chats', methods=['GET'])
+@require_auth
+def get_conversations_summary(character_id: str):
+    """
+    Get summary of all NPC conversations for a character.
+
+    Returns list of NPCs the character has talked to, with message counts,
+    last message timestamp, and preview of most recent exchange.
+
+    Path params:
+        character_id: Character ID
+
+    Query params:
+        None
+
+    Returns:
+        JSON response with list of conversation summaries
+    """
+    try:
+        user = get_current_user()
+
+        # Get conversation summaries
+        chat_service = get_chat_message_service()
+        summaries = chat_service.get_all_conversations_summary(character_id, user.id)
+
+        # Convert to dict for JSON response
+        conversations = [summary.to_dict() for summary in summaries]
+
+        logger.info("Retrieved conversation summaries",
+                   user_id=user.id,
+                   character_id=character_id,
+                   count=len(conversations))
+
+        return success_response({"conversations": conversations})
+
+    except ChatMessagePermissionDenied as e:
+        logger.warning("Permission denied getting conversations",
+                      user_id=user.id if 'user' in locals() else None,
+                      character_id=character_id)
+        return error_response(str(e), 403)
+    except Exception as e:
+        logger.error("Failed to get conversations summary",
+                    character_id=character_id,
+                    error=str(e))
+        return error_response(f"Failed to retrieve conversations: {str(e)}", 500)
+
+
+@chat_bp.route('/api/v1/characters/<character_id>/chats/<npc_id>', methods=['GET'])
+@require_auth
+def get_conversation_history(character_id: str, npc_id: str):
+    """
+    Get full conversation history between character and specific NPC.
+
+    Returns paginated list of messages ordered by timestamp DESC (most recent first).
+
+    Path params:
+        character_id: Character ID
+        npc_id: NPC ID
+
+    Query params:
+        limit: Maximum messages to return (default 50, max 100)
+        offset: Number of messages to skip (default 0)
+
+    Returns:
+        JSON response with messages and pagination info
+    """
+    try:
+        user = get_current_user()
+
+        # Get query parameters
+        limit = request.args.get('limit', 50, type=int)
+        offset = request.args.get('offset', 0, type=int)
+
+        # Validate parameters
+        if limit < 1:
+            return validation_error_response("limit must be at least 1")
+        if offset < 0:
+            return validation_error_response("offset must be at least 0")
+
+        # Get conversation history
+        chat_service = get_chat_message_service()
+        messages = chat_service.get_conversation_history(
+            character_id=character_id,
+            user_id=user.id,
+            npc_id=npc_id,
+            limit=limit,
+            offset=offset
+        )
+
+        # Get NPC name if available
+        npc_loader = get_npc_loader()
+        npc = npc_loader.load_npc(npc_id)
+        npc_name = npc.name if npc else npc_id.replace('_', ' ').title()
+
+        # Convert messages to dict
+        message_dicts = [msg.to_dict() for msg in messages]
+
+        result = {
+            "npc_id": npc_id,
+            "npc_name": npc_name,
+            "total_messages": len(messages),  # Count in this batch
+            "messages": message_dicts,
+            "pagination": {
+                "limit": limit,
+                "offset": offset,
+                "has_more": len(messages) == limit  # If we got a full batch, there might be more
+            }
+        }
+
+        logger.info("Retrieved conversation history",
+                   user_id=user.id,
+                   character_id=character_id,
+                   npc_id=npc_id,
+                   count=len(messages))
+
+        return success_response(result)
+
+    except ChatMessagePermissionDenied as e:
+        logger.warning("Permission denied getting conversation",
+                      user_id=user.id if 'user' in locals() else None,
+                      character_id=character_id,
+                      npc_id=npc_id)
+        return error_response(str(e), 403)
+    except Exception as e:
+        logger.error("Failed to get conversation history",
+                    character_id=character_id,
+                    npc_id=npc_id,
+                    error=str(e))
+        return error_response(f"Failed to retrieve conversation: {str(e)}", 500)
+
+
+@chat_bp.route('/api/v1/characters/<character_id>/chats/search', methods=['GET'])
+@require_auth
+def search_messages(character_id: str):
+    """
+    Search messages by text with optional filters.
+
+    Query params:
+        q (required): Search text to find in player_message and npc_response
+        npc_id (optional): Filter by specific NPC
+        context (optional): Filter by message context (dialogue, quest_offered, shop, etc.)
+        date_from (optional): Start date ISO format (e.g., 2025-11-25T00:00:00Z)
+        date_to (optional): End date ISO format
+        limit (optional): Maximum messages to return (default 50, max 100)
+        offset (optional): Number of messages to skip (default 0)
+
+    Returns:
+        JSON response with matching messages
+    """
+    try:
+        user = get_current_user()
+
+        # Get query parameters
+        search_text = request.args.get('q')
+        npc_id = request.args.get('npc_id')
+        context_str = request.args.get('context')
+        date_from = request.args.get('date_from')
+        date_to = request.args.get('date_to')
+        limit = request.args.get('limit', 50, type=int)
+        offset = request.args.get('offset', 0, type=int)
+
+        # Validate required parameters
+        if not search_text:
+            return validation_error_response("q (search text) is required")
+
+        # Validate optional parameters
+        if limit < 1:
+            return validation_error_response("limit must be at least 1")
+        if offset < 0:
+            return validation_error_response("offset must be at least 0")
+
+        # Parse context enum if provided
+        context = None
+        if context_str:
+            try:
+                context = MessageContext(context_str)
+            except ValueError:
+                valid_contexts = [c.value for c in MessageContext]
+                return validation_error_response(
+                    f"Invalid context. Must be one of: {', '.join(valid_contexts)}"
+                )
+
+        # Search messages
+        chat_service = get_chat_message_service()
+        messages = chat_service.search_messages(
+            character_id=character_id,
+            user_id=user.id,
+            search_text=search_text,
+            npc_id=npc_id,
+            context=context,
+            date_from=date_from,
+            date_to=date_to,
+            limit=limit,
+            offset=offset
+        )
+
+        # Convert messages to dict
+        message_dicts = [msg.to_dict() for msg in messages]
+
+        result = {
+            "search_text": search_text,
+            "filters": {
+                "npc_id": npc_id,
+                "context": context_str,
+                "date_from": date_from,
+                "date_to": date_to
+            },
+            "total_results": len(messages),
+            "messages": message_dicts,
+            "pagination": {
+                "limit": limit,
+                "offset": offset,
+                "has_more": len(messages) == limit
+            }
+        }
+
+        logger.info("Search completed",
+                   user_id=user.id,
+                   character_id=character_id,
+                   search_text=search_text,
+                   results=len(messages))
+
+        return success_response(result)
+
+    except ChatMessagePermissionDenied as e:
+        logger.warning("Permission denied searching messages",
+                      user_id=user.id if 'user' in locals() else None,
+                      character_id=character_id)
+        return error_response(str(e), 403)
+    except Exception as e:
+        logger.error("Failed to search messages",
+                    character_id=character_id,
+                    error=str(e))
+        return error_response(f"Search failed: {str(e)}", 500)
+
+
+@chat_bp.route('/api/v1/characters/<character_id>/chats/<message_id>', methods=['DELETE'])
+@require_auth
+def delete_message(character_id: str, message_id: str):
+    """
+    Soft delete a message (sets is_deleted=True).
+
+    Used for privacy/moderation. Message remains in database but filtered from queries.
+
+    Path params:
+        character_id: Character ID (for ownership validation)
+        message_id: Message ID to delete
+
+    Returns:
+        JSON response with success confirmation
+    """
+    try:
+        user = get_current_user()
+
+        # Soft delete message
+        chat_service = get_chat_message_service()
+        success = chat_service.soft_delete_message(
+            message_id=message_id,
+            character_id=character_id,
+            user_id=user.id
+        )
+
+        logger.info("Message deleted",
+                   user_id=user.id,
+                   character_id=character_id,
+                   message_id=message_id)
+
+        return success_response({
+            "message_id": message_id,
+            "deleted": success
+        })
+
+    except ChatMessageNotFound as e:
+        logger.warning("Message not found for deletion",
+                      message_id=message_id,
+                      character_id=character_id)
+        return not_found_response(str(e))
+    except ChatMessagePermissionDenied as e:
+        logger.warning("Permission denied deleting message",
+                      user_id=user.id if 'user' in locals() else None,
+                      character_id=character_id,
+                      message_id=message_id)
+        return error_response(str(e), 403)
+    except Exception as e:
+        logger.error("Failed to delete message",
+                    message_id=message_id,
+                    character_id=character_id,
+                    error=str(e))
+        return error_response(f"Delete failed: {str(e)}", 500)

api/app/api/combat.py

@@ -0,0 +1,729 @@
+"""
+Combat API Blueprint
+
+This module provides API endpoints for turn-based combat:
+- Starting combat encounters
+- Executing combat actions (attack, ability, defend, flee)
+- Getting combat state
+- Processing enemy turns
+"""
+
+from flask import Blueprint, request
+
+from app.services.combat_service import (
+    get_combat_service,
+    CombatAction,
+    CombatError,
+    NotInCombatError,
+    AlreadyInCombatError,
+    InvalidActionError,
+    InsufficientResourceError,
+)
+from app.models.enums import CombatStatus
+from app.utils.response import (
+    success_response,
+    error_response,
+    not_found_response,
+    validation_error_response
+)
+from app.utils.auth import require_auth, get_current_user
+from app.utils.logging import get_logger
+
+
+# Initialize logger
+logger = get_logger(__file__)
+
+# Create blueprint
+combat_bp = Blueprint('combat', __name__, url_prefix='/api/v1/combat')
+
+
+# =============================================================================
+# Combat Lifecycle Endpoints
+# =============================================================================
+
+@combat_bp.route('/start', methods=['POST'])
+@require_auth
+def start_combat():
+    """
+    Start a new combat encounter.
+
+    Creates a combat encounter with the session's character(s) vs specified enemies.
+    Rolls initiative and sets up turn order.
+
+    Request JSON:
+        {
+            "session_id": "sess_123",
+            "enemy_ids": ["goblin", "goblin", "goblin_shaman"]
+        }
+
+    Returns:
+        {
+            "encounter_id": "enc_abc123",
+            "combatants": [...],
+            "turn_order": [...],
+            "current_turn": "char_456",
+            "round_number": 1,
+            "status": "active"
+        }
+
+    Errors:
+        400: Missing required fields
+        400: Already in combat
+        404: Enemy template not found
+    """
+    user = get_current_user()
+    data = request.get_json()
+
+    if not data:
+        return validation_error_response(
+            message="Request body is required",
+            details={"field": "body", "issue": "Missing JSON body"}
+        )
+
+    # Validate required fields
+    session_id = data.get("session_id")
+    enemy_ids = data.get("enemy_ids", [])
+
+    if not session_id:
+        return validation_error_response(
+            message="session_id is required",
+            details={"field": "session_id", "issue": "Missing required field"}
+        )
+
+    if not enemy_ids:
+        return validation_error_response(
+            message="enemy_ids is required and must not be empty",
+            details={"field": "enemy_ids", "issue": "Missing or empty list"}
+        )
+
+    try:
+        combat_service = get_combat_service()
+        encounter = combat_service.start_combat(
+            session_id=session_id,
+            user_id=user["user_id"],
+            enemy_ids=enemy_ids,
+        )
+
+        # Format response
+        current = encounter.get_current_combatant()
+        response_data = {
+            "encounter_id": encounter.encounter_id,
+            "combatants": [
+                {
+                    "combatant_id": c.combatant_id,
+                    "name": c.name,
+                    "is_player": c.is_player,
+                    "current_hp": c.current_hp,
+                    "max_hp": c.max_hp,
+                    "current_mp": c.current_mp,
+                    "max_mp": c.max_mp,
+                    "initiative": c.initiative,
+                    "abilities": c.abilities,
+                }
+                for c in encounter.combatants
+            ],
+            "turn_order": encounter.turn_order,
+            "current_turn": current.combatant_id if current else None,
+            "round_number": encounter.round_number,
+            "status": encounter.status.value,
+        }
+
+        logger.info("Combat started via API",
+                   session_id=session_id,
+                   encounter_id=encounter.encounter_id,
+                   enemy_count=len(enemy_ids))
+
+        return success_response(response_data)
+
+    except AlreadyInCombatError as e:
+        logger.warning("Attempt to start combat while already in combat",
+                      session_id=session_id)
+        return error_response(
+            status_code=400,
+            message=str(e),
+            error_code="ALREADY_IN_COMBAT"
+        )
+    except ValueError as e:
+        logger.warning("Invalid enemy ID",
+                      session_id=session_id,
+                      error=str(e))
+        return not_found_response(message=str(e))
+    except Exception as e:
+        logger.error("Failed to start combat",
+                    session_id=session_id,
+                    error=str(e),
+                    exc_info=True)
+        return error_response(
+            status_code=500,
+            message="Failed to start combat",
+            error_code="COMBAT_START_ERROR"
+        )
+
+
+@combat_bp.route('/<session_id>/state', methods=['GET'])
+@require_auth
+def get_combat_state(session_id: str):
+    """
+    Get current combat state for a session.
+
+    Returns the full combat encounter state including all combatants,
+    turn order, combat log, and current status.
+
+    Path Parameters:
+        session_id: Game session ID
+
+    Returns:
+        {
+            "in_combat": true,
+            "encounter": {
+                "encounter_id": "...",
+                "combatants": [...],
+                "turn_order": [...],
+                "current_turn": "...",
+                "round_number": 1,
+                "status": "active",
+                "combat_log": [...]
+            }
+        }
+
+        or if not in combat:
+        {
+            "in_combat": false,
+            "encounter": null
+        }
+    """
+    user = get_current_user()
+
+    try:
+        combat_service = get_combat_service()
+        encounter = combat_service.get_combat_state(session_id, user["user_id"])
+
+        if not encounter:
+            return success_response({
+                "in_combat": False,
+                "encounter": None
+            })
+
+        current = encounter.get_current_combatant()
+        response_data = {
+            "in_combat": True,
+            "encounter": {
+                "encounter_id": encounter.encounter_id,
+                "combatants": [
+                    {
+                        "combatant_id": c.combatant_id,
+                        "name": c.name,
+                        "is_player": c.is_player,
+                        "current_hp": c.current_hp,
+                        "max_hp": c.max_hp,
+                        "current_mp": c.current_mp,
+                        "max_mp": c.max_mp,
+                        "is_alive": c.is_alive(),
+                        "is_stunned": c.is_stunned(),
+                        "active_effects": [
+                            {"name": e.name, "duration": e.duration}
+                            for e in c.active_effects
+                        ],
+                        "abilities": c.abilities,
+                        "cooldowns": c.cooldowns,
+                    }
+                    for c in encounter.combatants
+                ],
+                "turn_order": encounter.turn_order,
+                "current_turn": current.combatant_id if current else None,
+                "round_number": encounter.round_number,
+                "status": encounter.status.value,
+                "combat_log": encounter.combat_log[-10:],  # Last 10 entries
+            }
+        }
+
+        return success_response(response_data)
+
+    except Exception as e:
+        logger.error("Failed to get combat state",
+                    session_id=session_id,
+                    error=str(e),
+                    exc_info=True)
+        return error_response(
+            status_code=500,
+            message="Failed to get combat state",
+            error_code="COMBAT_STATE_ERROR"
+        )
+
+
+# =============================================================================
+# Action Execution Endpoints
+# =============================================================================
+
+@combat_bp.route('/<session_id>/action', methods=['POST'])
+@require_auth
+def execute_action(session_id: str):
+    """
+    Execute a combat action for a combatant.
+
+    Processes the specified action (attack, ability, defend, flee, item)
+    for the given combatant. Must be that combatant's turn.
+
+    Path Parameters:
+        session_id: Game session ID
+
+    Request JSON:
+        {
+            "combatant_id": "char_456",
+            "action_type": "attack" | "ability" | "defend" | "flee" | "item",
+            "target_ids": ["enemy_1"],  // Optional, auto-targets if omitted
+            "ability_id": "fireball",   // Required for ability actions
+            "item_id": "health_potion"  // Required for item actions
+        }
+
+    Returns:
+        {
+            "success": true,
+            "message": "Attack hits for 15 damage!",
+            "damage_results": [...],
+            "effects_applied": [...],
+            "combat_ended": false,
+            "combat_status": null,
+            "next_combatant_id": "goblin_0"
+        }
+
+    Errors:
+        400: Missing required fields
+        400: Not this combatant's turn
+        400: Invalid action
+        404: Session not in combat
+    """
+    user = get_current_user()
+    data = request.get_json()
+
+    if not data:
+        return validation_error_response(
+            message="Request body is required",
+            details={"field": "body", "issue": "Missing JSON body"}
+        )
+
+    # Validate required fields
+    combatant_id = data.get("combatant_id")
+    action_type = data.get("action_type")
+
+    if not combatant_id:
+        return validation_error_response(
+            message="combatant_id is required",
+            details={"field": "combatant_id", "issue": "Missing required field"}
+        )
+
+    if not action_type:
+        return validation_error_response(
+            message="action_type is required",
+            details={"field": "action_type", "issue": "Missing required field"}
+        )
+
+    valid_actions = ["attack", "ability", "defend", "flee", "item"]
+    if action_type not in valid_actions:
+        return validation_error_response(
+            message=f"Invalid action_type. Must be one of: {valid_actions}",
+            details={"field": "action_type", "issue": "Invalid value"}
+        )
+
+    # Validate ability_id for ability actions
+    if action_type == "ability" and not data.get("ability_id"):
+        return validation_error_response(
+            message="ability_id is required for ability actions",
+            details={"field": "ability_id", "issue": "Missing required field"}
+        )
+
+    try:
+        combat_service = get_combat_service()
+
+        action = CombatAction(
+            action_type=action_type,
+            target_ids=data.get("target_ids", []),
+            ability_id=data.get("ability_id"),
+            item_id=data.get("item_id"),
+        )
+
+        result = combat_service.execute_action(
+            session_id=session_id,
+            user_id=user["user_id"],
+            combatant_id=combatant_id,
+            action=action,
+        )
+
+        logger.info("Combat action executed",
+                   session_id=session_id,
+                   combatant_id=combatant_id,
+                   action_type=action_type,
+                   success=result.success)
+
+        return success_response(result.to_dict())
+
+    except NotInCombatError as e:
+        logger.warning("Action attempted while not in combat",
+                      session_id=session_id)
+        return not_found_response(message="Session is not in combat")
+    except InvalidActionError as e:
+        logger.warning("Invalid combat action",
+                      session_id=session_id,
+                      combatant_id=combatant_id,
+                      error=str(e))
+        return error_response(
+            status_code=400,
+            message=str(e),
+            error_code="INVALID_ACTION"
+        )
+    except InsufficientResourceError as e:
+        logger.warning("Insufficient resources for action",
+                      session_id=session_id,
+                      combatant_id=combatant_id,
+                      error=str(e))
+        return error_response(
+            status_code=400,
+            message=str(e),
+            error_code="INSUFFICIENT_RESOURCES"
+        )
+    except Exception as e:
+        logger.error("Failed to execute combat action",
+                    session_id=session_id,
+                    combatant_id=combatant_id,
+                    action_type=action_type,
+                    error=str(e),
+                    exc_info=True)
+        return error_response(
+            status_code=500,
+            message="Failed to execute action",
+            error_code="ACTION_EXECUTION_ERROR"
+        )
+
+
+@combat_bp.route('/<session_id>/enemy-turn', methods=['POST'])
+@require_auth
+def execute_enemy_turn(session_id: str):
+    """
+    Execute the current enemy's turn using AI logic.
+
+    Called when it's an enemy combatant's turn. The enemy AI will
+    automatically choose and execute an appropriate action.
+
+    Path Parameters:
+        session_id: Game session ID
+
+    Returns:
+        {
+            "success": true,
+            "message": "Goblin attacks Hero for 8 damage!",
+            "damage_results": [...],
+            "effects_applied": [...],
+            "combat_ended": false,
+            "combat_status": null,
+            "next_combatant_id": "char_456"
+        }
+
+    Errors:
+        400: Current combatant is not an enemy
+        404: Session not in combat
+    """
+    user = get_current_user()
+
+    try:
+        combat_service = get_combat_service()
+        result = combat_service.execute_enemy_turn(
+            session_id=session_id,
+            user_id=user["user_id"],
+        )
+
+        logger.info("Enemy turn executed",
+                   session_id=session_id,
+                   success=result.success)
+
+        return success_response(result.to_dict())
+
+    except NotInCombatError as e:
+        return not_found_response(message="Session is not in combat")
+    except InvalidActionError as e:
+        return error_response(
+            status_code=400,
+            message=str(e),
+            error_code="INVALID_ACTION"
+        )
+    except Exception as e:
+        logger.error("Failed to execute enemy turn",
+                    session_id=session_id,
+                    error=str(e),
+                    exc_info=True)
+        return error_response(
+            status_code=500,
+            message="Failed to execute enemy turn",
+            error_code="ENEMY_TURN_ERROR"
+        )
+
+
+@combat_bp.route('/<session_id>/flee', methods=['POST'])
+@require_auth
+def attempt_flee(session_id: str):
+    """
+    Attempt to flee from combat.
+
+    The current combatant attempts to flee. Success is based on
+    DEX comparison with enemies. Failed flee attempts consume the turn.
+
+    Path Parameters:
+        session_id: Game session ID
+
+    Request JSON:
+        {
+            "combatant_id": "char_456"
+        }
+
+    Returns:
+        {
+            "success": true,
+            "message": "Successfully fled from combat!",
+            "combat_ended": true,
+            "combat_status": "fled"
+        }
+
+        or on failure:
+        {
+            "success": false,
+            "message": "Failed to flee! (Roll: 0.35, Needed: 0.50)",
+            "combat_ended": false
+        }
+    """
+    user = get_current_user()
+    data = request.get_json() or {}
+
+    combatant_id = data.get("combatant_id")
+
+    try:
+        combat_service = get_combat_service()
+
+        action = CombatAction(
+            action_type="flee",
+            target_ids=[],
+        )
+
+        result = combat_service.execute_action(
+            session_id=session_id,
+            user_id=user["user_id"],
+            combatant_id=combatant_id,
+            action=action,
+        )
+
+        return success_response(result.to_dict())
+
+    except NotInCombatError:
+        return not_found_response(message="Session is not in combat")
+    except InvalidActionError as e:
+        return error_response(
+            status_code=400,
+            message=str(e),
+            error_code="INVALID_ACTION"
+        )
+    except Exception as e:
+        logger.error("Failed flee attempt",
+                    session_id=session_id,
+                    error=str(e),
+                    exc_info=True)
+        return error_response(
+            status_code=500,
+            message="Failed to attempt flee",
+            error_code="FLEE_ERROR"
+        )
+
+
+@combat_bp.route('/<session_id>/end', methods=['POST'])
+@require_auth
+def end_combat(session_id: str):
+    """
+    Force end the current combat (debug/admin endpoint).
+
+    Ends combat with the specified outcome. Should normally only be used
+    for debugging or admin purposes - combat usually ends automatically.
+
+    Path Parameters:
+        session_id: Game session ID
+
+    Request JSON:
+        {
+            "outcome": "victory" | "defeat" | "fled"
+        }
+
+    Returns:
+        {
+            "outcome": "victory",
+            "rewards": {
+                "experience": 100,
+                "gold": 50,
+                "items": [...],
+                "level_ups": []
+            }
+        }
+    """
+    user = get_current_user()
+    data = request.get_json() or {}
+
+    outcome_str = data.get("outcome", "fled")
+
+    # Parse outcome
+    try:
+        outcome = CombatStatus(outcome_str)
+    except ValueError:
+        return validation_error_response(
+            message="Invalid outcome. Must be: victory, defeat, or fled",
+            details={"field": "outcome", "issue": "Invalid value"}
+        )
+
+    try:
+        combat_service = get_combat_service()
+        rewards = combat_service.end_combat(
+            session_id=session_id,
+            user_id=user["user_id"],
+            outcome=outcome,
+        )
+
+        logger.info("Combat force-ended",
+                   session_id=session_id,
+                   outcome=outcome_str)
+
+        return success_response({
+            "outcome": outcome_str,
+            "rewards": rewards.to_dict() if outcome == CombatStatus.VICTORY else None,
+        })
+
+    except NotInCombatError:
+        return not_found_response(message="Session is not in combat")
+    except Exception as e:
+        logger.error("Failed to end combat",
+                    session_id=session_id,
+                    error=str(e),
+                    exc_info=True)
+        return error_response(
+            status_code=500,
+            message="Failed to end combat",
+            error_code="COMBAT_END_ERROR"
+        )
+
+
+# =============================================================================
+# Utility Endpoints
+# =============================================================================
+
+@combat_bp.route('/enemies', methods=['GET'])
+def list_enemies():
+    """
+    List all available enemy templates.
+
+    Returns a list of all enemy templates that can be used in combat.
+    Useful for encounter building and testing.
+
+    Query Parameters:
+        difficulty: Filter by difficulty (easy, medium, hard, boss)
+        tag: Filter by tag (undead, beast, humanoid, etc.)
+
+    Returns:
+        {
+            "enemies": [
+                {
+                    "enemy_id": "goblin",
+                    "name": "Goblin Scout",
+                    "difficulty": "easy",
+                    "tags": ["humanoid", "goblinoid"],
+                    "experience_reward": 15
+                },
+                ...
+            ]
+        }
+    """
+    from app.services.enemy_loader import get_enemy_loader
+    from app.models.enemy import EnemyDifficulty
+
+    difficulty = request.args.get("difficulty")
+    tag = request.args.get("tag")
+
+    try:
+        enemy_loader = get_enemy_loader()
+        enemy_loader.load_all_enemies()
+
+        if difficulty:
+            try:
+                diff = EnemyDifficulty(difficulty)
+                enemies = enemy_loader.get_enemies_by_difficulty(diff)
+            except ValueError:
+                return validation_error_response(
+                    message="Invalid difficulty",
+                    details={"field": "difficulty", "issue": "Must be: easy, medium, hard, boss"}
+                )
+        elif tag:
+            enemies = enemy_loader.get_enemies_by_tag(tag)
+        else:
+            enemies = list(enemy_loader.get_all_cached().values())
+
+        response_data = {
+            "enemies": [
+                {
+                    "enemy_id": e.enemy_id,
+                    "name": e.name,
+                    "description": e.description[:100] + "..." if len(e.description) > 100 else e.description,
+                    "difficulty": e.difficulty.value,
+                    "tags": e.tags,
+                    "experience_reward": e.experience_reward,
+                    "gold_reward_range": [e.gold_reward_min, e.gold_reward_max],
+                }
+                for e in enemies
+            ]
+        }
+
+        return success_response(response_data)
+
+    except Exception as e:
+        logger.error("Failed to list enemies",
+                    error=str(e),
+                    exc_info=True)
+        return error_response(
+            status_code=500,
+            message="Failed to list enemies",
+            error_code="ENEMY_LIST_ERROR"
+        )
+
+
+@combat_bp.route('/enemies/<enemy_id>', methods=['GET'])
+def get_enemy_details(enemy_id: str):
+    """
+    Get detailed information about a specific enemy template.
+
+    Path Parameters:
+        enemy_id: Enemy template ID
+
+    Returns:
+        {
+            "enemy_id": "goblin",
+            "name": "Goblin Scout",
+            "description": "...",
+            "base_stats": {...},
+            "abilities": [...],
+            "loot_table": [...],
+            "difficulty": "easy",
+            ...
+        }
+    """
+    from app.services.enemy_loader import get_enemy_loader
+
+    try:
+        enemy_loader = get_enemy_loader()
+        enemy = enemy_loader.load_enemy(enemy_id)
+
+        if not enemy:
+            return not_found_response(message=f"Enemy not found: {enemy_id}")
+
+        return success_response(enemy.to_dict())
+
+    except Exception as e:
+        logger.error("Failed to get enemy details",
+                    enemy_id=enemy_id,
+                    error=str(e),
+                    exc_info=True)
+        return error_response(
+            status_code=500,
+            message="Failed to get enemy details",
+            error_code="ENEMY_DETAILS_ERROR"
+        )

api/app/api/inventory.py

@@ -0,0 +1,639 @@
+"""
+Inventory API Blueprint
+
+Endpoints for managing character inventory and equipment.
+All endpoints require authentication and enforce ownership validation.
+
+Endpoints:
+- GET /api/v1/characters/<id>/inventory - Get character inventory and equipped items
+- POST /api/v1/characters/<id>/inventory/equip - Equip an item
+- POST /api/v1/characters/<id>/inventory/unequip - Unequip an item
+- POST /api/v1/characters/<id>/inventory/use - Use a consumable item
+- DELETE /api/v1/characters/<id>/inventory/<item_id> - Drop an item
+"""
+
+from flask import Blueprint, request
+
+from app.services.inventory_service import (
+    get_inventory_service,
+    ItemNotFoundError,
+    CannotEquipError,
+    InvalidSlotError,
+    CannotUseItemError,
+    InventoryFullError,
+    VALID_SLOTS,
+    MAX_INVENTORY_SIZE,
+)
+from app.services.character_service import (
+    get_character_service,
+    CharacterNotFound,
+)
+from app.utils.response import (
+    success_response,
+    error_response,
+    not_found_response,
+    validation_error_response,
+)
+from app.utils.auth import require_auth, get_current_user
+from app.utils.logging import get_logger
+
+
+# Initialize logger
+logger = get_logger(__file__)
+
+# Create blueprint
+inventory_bp = Blueprint('inventory', __name__)
+
+
+# =============================================================================
+# API Endpoints
+# =============================================================================
+
+@inventory_bp.route('/api/v1/characters/<character_id>/inventory', methods=['GET'])
+@require_auth
+def get_inventory(character_id: str):
+    """
+    Get character inventory and equipped items.
+
+    Args:
+        character_id: Character ID
+
+    Returns:
+        200: Inventory and equipment data
+        401: Not authenticated
+        404: Character not found or not owned by user
+        500: Internal server error
+
+    Example Response:
+        {
+            "result": {
+                "inventory": [
+                    {
+                        "item_id": "gen_abc123",
+                        "name": "Flaming Dagger",
+                        "item_type": "weapon",
+                        "rarity": "rare",
+                        ...
+                    }
+                ],
+                "equipped": {
+                    "weapon": {...},
+                    "helmet": null,
+                    ...
+                },
+                "inventory_count": 5,
+                "max_inventory": 100
+            }
+        }
+    """
+    try:
+        user = get_current_user()
+        logger.info("Getting inventory",
+                   user_id=user.id,
+                   character_id=character_id)
+
+        # Get character (validates ownership)
+        char_service = get_character_service()
+        character = char_service.get_character(character_id, user.id)
+
+        # Get inventory service
+        inventory_service = get_inventory_service()
+
+        # Get inventory items
+        inventory_items = inventory_service.get_inventory(character)
+
+        # Get equipped items
+        equipped_items = inventory_service.get_equipped_items(character)
+
+        # Build equipped dict with all slots (None for empty slots)
+        equipped_response = {}
+        for slot in VALID_SLOTS:
+            item = equipped_items.get(slot)
+            equipped_response[slot] = item.to_dict() if item else None
+
+        logger.info("Inventory retrieved successfully",
+                   user_id=user.id,
+                   character_id=character_id,
+                   item_count=len(inventory_items))
+
+        return success_response(
+            result={
+                "inventory": [item.to_dict() for item in inventory_items],
+                "equipped": equipped_response,
+                "inventory_count": len(inventory_items),
+                "max_inventory": MAX_INVENTORY_SIZE,
+            }
+        )
+
+    except CharacterNotFound as e:
+        logger.warning("Character not found",
+                      user_id=user.id if 'user' in locals() else 'unknown',
+                      character_id=character_id,
+                      error=str(e))
+        return not_found_response(message=str(e))
+
+    except Exception as e:
+        logger.error("Failed to get inventory",
+                    user_id=user.id if 'user' in locals() else 'unknown',
+                    character_id=character_id,
+                    error=str(e))
+        return error_response(
+            code="INVENTORY_GET_ERROR",
+            message="Failed to retrieve inventory",
+            status=500
+        )
+
+
+@inventory_bp.route('/api/v1/characters/<character_id>/inventory/equip', methods=['POST'])
+@require_auth
+def equip_item(character_id: str):
+    """
+    Equip an item from inventory to a specified slot.
+
+    Args:
+        character_id: Character ID
+
+    Request Body:
+        {
+            "item_id": "gen_abc123",
+            "slot": "weapon"
+        }
+
+    Returns:
+        200: Item equipped successfully
+        400: Cannot equip item (wrong type, level requirement, etc.)
+        401: Not authenticated
+        404: Character or item not found
+        422: Validation error (invalid slot)
+        500: Internal server error
+
+    Example Response:
+        {
+            "result": {
+                "message": "Equipped Flaming Dagger to weapon slot",
+                "equipped": {...},
+                "unequipped_item": null
+            }
+        }
+    """
+    try:
+        user = get_current_user()
+
+        # Get request data
+        data = request.get_json()
+
+        if not data:
+            return validation_error_response(
+                message="Request body is required",
+                details={"error": "Request body is required"}
+            )
+
+        item_id = data.get('item_id', '').strip()
+        slot = data.get('slot', '').strip().lower()
+
+        # Validate required fields
+        validation_errors = {}
+
+        if not item_id:
+            validation_errors['item_id'] = "item_id is required"
+
+        if not slot:
+            validation_errors['slot'] = "slot is required"
+
+        if validation_errors:
+            return validation_error_response(
+                message="Validation failed",
+                details=validation_errors
+            )
+
+        logger.info("Equipping item",
+                   user_id=user.id,
+                   character_id=character_id,
+                   item_id=item_id,
+                   slot=slot)
+
+        # Get character (validates ownership)
+        char_service = get_character_service()
+        character = char_service.get_character(character_id, user.id)
+
+        # Get inventory service
+        inventory_service = get_inventory_service()
+
+        # Equip item
+        previous_item = inventory_service.equip_item(
+            character, item_id, slot, user.id
+        )
+
+        # Get item name for message
+        equipped_item = character.equipped.get(slot)
+        item_name = equipped_item.get_display_name() if equipped_item else item_id
+
+        # Build equipped response
+        equipped_response = {}
+        for s in VALID_SLOTS:
+            item = character.equipped.get(s)
+            equipped_response[s] = item.to_dict() if item else None
+
+        logger.info("Item equipped successfully",
+                   user_id=user.id,
+                   character_id=character_id,
+                   item_id=item_id,
+                   slot=slot,
+                   previous_item=previous_item.item_id if previous_item else None)
+
+        return success_response(
+            result={
+                "message": f"Equipped {item_name} to {slot} slot",
+                "equipped": equipped_response,
+                "unequipped_item": previous_item.to_dict() if previous_item else None,
+            }
+        )
+
+    except CharacterNotFound as e:
+        logger.warning("Character not found for equip",
+                      user_id=user.id if 'user' in locals() else 'unknown',
+                      character_id=character_id,
+                      error=str(e))
+        return not_found_response(message=str(e))
+
+    except ItemNotFoundError as e:
+        logger.warning("Item not found for equip",
+                      user_id=user.id if 'user' in locals() else 'unknown',
+                      character_id=character_id,
+                      item_id=item_id if 'item_id' in locals() else 'unknown',
+                      error=str(e))
+        return not_found_response(message=str(e))
+
+    except InvalidSlotError as e:
+        logger.warning("Invalid slot for equip",
+                      user_id=user.id if 'user' in locals() else 'unknown',
+                      character_id=character_id,
+                      slot=slot if 'slot' in locals() else 'unknown',
+                      error=str(e))
+        return validation_error_response(
+            message=str(e),
+            details={"slot": str(e)}
+        )
+
+    except CannotEquipError as e:
+        logger.warning("Cannot equip item",
+                      user_id=user.id if 'user' in locals() else 'unknown',
+                      character_id=character_id,
+                      item_id=item_id if 'item_id' in locals() else 'unknown',
+                      error=str(e))
+        return error_response(
+            code="CANNOT_EQUIP",
+            message=str(e),
+            status=400
+        )
+
+    except Exception as e:
+        logger.error("Failed to equip item",
+                    user_id=user.id if 'user' in locals() else 'unknown',
+                    character_id=character_id,
+                    error=str(e))
+        return error_response(
+            code="EQUIP_ERROR",
+            message="Failed to equip item",
+            status=500
+        )
+
+
+@inventory_bp.route('/api/v1/characters/<character_id>/inventory/unequip', methods=['POST'])
+@require_auth
+def unequip_item(character_id: str):
+    """
+    Unequip an item from a specified slot (returns to inventory).
+
+    Args:
+        character_id: Character ID
+
+    Request Body:
+        {
+            "slot": "weapon"
+        }
+
+    Returns:
+        200: Item unequipped successfully (or slot was empty)
+        400: Inventory full, cannot unequip
+        401: Not authenticated
+        404: Character not found
+        422: Validation error (invalid slot)
+        500: Internal server error
+
+    Example Response:
+        {
+            "result": {
+                "message": "Unequipped Flaming Dagger from weapon slot",
+                "unequipped_item": {...},
+                "equipped": {...}
+            }
+        }
+    """
+    try:
+        user = get_current_user()
+
+        # Get request data
+        data = request.get_json()
+
+        if not data:
+            return validation_error_response(
+                message="Request body is required",
+                details={"error": "Request body is required"}
+            )
+
+        slot = data.get('slot', '').strip().lower()
+
+        if not slot:
+            return validation_error_response(
+                message="Validation failed",
+                details={"slot": "slot is required"}
+            )
+
+        logger.info("Unequipping item",
+                   user_id=user.id,
+                   character_id=character_id,
+                   slot=slot)
+
+        # Get character (validates ownership)
+        char_service = get_character_service()
+        character = char_service.get_character(character_id, user.id)
+
+        # Get inventory service
+        inventory_service = get_inventory_service()
+
+        # Unequip item
+        unequipped_item = inventory_service.unequip_item(character, slot, user.id)
+
+        # Build equipped response
+        equipped_response = {}
+        for s in VALID_SLOTS:
+            item = character.equipped.get(s)
+            equipped_response[s] = item.to_dict() if item else None
+
+        # Build message
+        if unequipped_item:
+            message = f"Unequipped {unequipped_item.get_display_name()} from {slot} slot"
+        else:
+            message = f"Slot '{slot}' was already empty"
+
+        logger.info("Item unequipped",
+                   user_id=user.id,
+                   character_id=character_id,
+                   slot=slot,
+                   unequipped_item=unequipped_item.item_id if unequipped_item else None)
+
+        return success_response(
+            result={
+                "message": message,
+                "unequipped_item": unequipped_item.to_dict() if unequipped_item else None,
+                "equipped": equipped_response,
+            }
+        )
+
+    except CharacterNotFound as e:
+        logger.warning("Character not found for unequip",
+                      user_id=user.id if 'user' in locals() else 'unknown',
+                      character_id=character_id,
+                      error=str(e))
+        return not_found_response(message=str(e))
+
+    except InvalidSlotError as e:
+        logger.warning("Invalid slot for unequip",
+                      user_id=user.id if 'user' in locals() else 'unknown',
+                      character_id=character_id,
+                      slot=slot if 'slot' in locals() else 'unknown',
+                      error=str(e))
+        return validation_error_response(
+            message=str(e),
+            details={"slot": str(e)}
+        )
+
+    except InventoryFullError as e:
+        logger.warning("Inventory full, cannot unequip",
+                      user_id=user.id if 'user' in locals() else 'unknown',
+                      character_id=character_id,
+                      error=str(e))
+        return error_response(
+            code="INVENTORY_FULL",
+            message=str(e),
+            status=400
+        )
+
+    except Exception as e:
+        logger.error("Failed to unequip item",
+                    user_id=user.id if 'user' in locals() else 'unknown',
+                    character_id=character_id,
+                    error=str(e))
+        return error_response(
+            code="UNEQUIP_ERROR",
+            message="Failed to unequip item",
+            status=500
+        )
+
+
+@inventory_bp.route('/api/v1/characters/<character_id>/inventory/use', methods=['POST'])
+@require_auth
+def use_item(character_id: str):
+    """
+    Use a consumable item from inventory.
+
+    Args:
+        character_id: Character ID
+
+    Request Body:
+        {
+            "item_id": "health_potion_small"
+        }
+
+    Returns:
+        200: Item used successfully
+        400: Cannot use item (not consumable)
+        401: Not authenticated
+        404: Character or item not found
+        500: Internal server error
+
+    Example Response:
+        {
+            "result": {
+                "item_used": "Small Health Potion",
+                "effects_applied": [
+                    {
+                        "effect_name": "Healing",
+                        "effect_type": "hot",
+                        "value": 25,
+                        "message": "Restored 25 HP"
+                    }
+                ],
+                "hp_restored": 25,
+                "mp_restored": 0,
+                "message": "Used Small Health Potion: Restored 25 HP"
+            }
+        }
+    """
+    try:
+        user = get_current_user()
+
+        # Get request data
+        data = request.get_json()
+
+        if not data:
+            return validation_error_response(
+                message="Request body is required",
+                details={"error": "Request body is required"}
+            )
+
+        item_id = data.get('item_id', '').strip()
+
+        if not item_id:
+            return validation_error_response(
+                message="Validation failed",
+                details={"item_id": "item_id is required"}
+            )
+
+        logger.info("Using item",
+                   user_id=user.id,
+                   character_id=character_id,
+                   item_id=item_id)
+
+        # Get character (validates ownership)
+        char_service = get_character_service()
+        character = char_service.get_character(character_id, user.id)
+
+        # Get inventory service
+        inventory_service = get_inventory_service()
+
+        # Use consumable
+        result = inventory_service.use_consumable(character, item_id, user.id)
+
+        logger.info("Item used successfully",
+                   user_id=user.id,
+                   character_id=character_id,
+                   item_id=item_id,
+                   hp_restored=result.hp_restored,
+                   mp_restored=result.mp_restored)
+
+        return success_response(result=result.to_dict())
+
+    except CharacterNotFound as e:
+        logger.warning("Character not found for use item",
+                      user_id=user.id if 'user' in locals() else 'unknown',
+                      character_id=character_id,
+                      error=str(e))
+        return not_found_response(message=str(e))
+
+    except ItemNotFoundError as e:
+        logger.warning("Item not found for use",
+                      user_id=user.id if 'user' in locals() else 'unknown',
+                      character_id=character_id,
+                      item_id=item_id if 'item_id' in locals() else 'unknown',
+                      error=str(e))
+        return not_found_response(message=str(e))
+
+    except CannotUseItemError as e:
+        logger.warning("Cannot use item",
+                      user_id=user.id if 'user' in locals() else 'unknown',
+                      character_id=character_id,
+                      item_id=item_id if 'item_id' in locals() else 'unknown',
+                      error=str(e))
+        return error_response(
+            code="CANNOT_USE_ITEM",
+            message=str(e),
+            status=400
+        )
+
+    except Exception as e:
+        logger.error("Failed to use item",
+                    user_id=user.id if 'user' in locals() else 'unknown',
+                    character_id=character_id,
+                    error=str(e))
+        return error_response(
+            code="USE_ITEM_ERROR",
+            message="Failed to use item",
+            status=500
+        )
+
+
+@inventory_bp.route('/api/v1/characters/<character_id>/inventory/<item_id>', methods=['DELETE'])
+@require_auth
+def drop_item(character_id: str, item_id: str):
+    """
+    Drop (remove) an item from inventory.
+
+    Args:
+        character_id: Character ID
+        item_id: Item ID to drop
+
+    Returns:
+        200: Item dropped successfully
+        401: Not authenticated
+        404: Character or item not found
+        500: Internal server error
+
+    Example Response:
+        {
+            "result": {
+                "message": "Dropped Rusty Sword",
+                "dropped_item": {...},
+                "inventory_count": 4
+            }
+        }
+    """
+    try:
+        user = get_current_user()
+
+        logger.info("Dropping item",
+                   user_id=user.id,
+                   character_id=character_id,
+                   item_id=item_id)
+
+        # Get character (validates ownership)
+        char_service = get_character_service()
+        character = char_service.get_character(character_id, user.id)
+
+        # Get inventory service
+        inventory_service = get_inventory_service()
+
+        # Drop item
+        dropped_item = inventory_service.drop_item(character, item_id, user.id)
+
+        logger.info("Item dropped successfully",
+                   user_id=user.id,
+                   character_id=character_id,
+                   item_id=item_id,
+                   item_name=dropped_item.get_display_name())
+
+        return success_response(
+            result={
+                "message": f"Dropped {dropped_item.get_display_name()}",
+                "dropped_item": dropped_item.to_dict(),
+                "inventory_count": len(character.inventory),
+            }
+        )
+
+    except CharacterNotFound as e:
+        logger.warning("Character not found for drop",
+                      user_id=user.id if 'user' in locals() else 'unknown',
+                      character_id=character_id,
+                      error=str(e))
+        return not_found_response(message=str(e))
+
+    except ItemNotFoundError as e:
+        logger.warning("Item not found for drop",
+                      user_id=user.id if 'user' in locals() else 'unknown',
+                      character_id=character_id,
+                      item_id=item_id,
+                      error=str(e))
+        return not_found_response(message=str(e))
+
+    except Exception as e:
+        logger.error("Failed to drop item",
+                    user_id=user.id if 'user' in locals() else 'unknown',
+                    character_id=character_id,
+                    item_id=item_id,
+                    error=str(e))
+        return error_response(
+            code="DROP_ITEM_ERROR",
+            message="Failed to drop item",
+            status=500
+        )

api/app/api/npcs.py

@@ -281,6 +281,7 @@ def get_npcs_at_location(location_id: str):
                 "role": npc.role,
                 "appearance": npc.appearance.brief,
                 "tags": npc.tags,
+                "image_url": npc.image_url,
             })
 
         return success_response({

api/app/api/sessions.py

@@ -235,7 +235,7 @@ def create_session():
         return error_response(
             status=409,
             code="SESSION_LIMIT_EXCEEDED",
-            message="Maximum active sessions limit reached (5). Please end an existing session first."
+            message=str(e)
         )
 
     except Exception as e:
@@ -602,3 +602,111 @@ def get_history(session_id: str):
             code="HISTORY_ERROR",
             message="Failed to get conversation history"
         )
+
+
+@sessions_bp.route('/api/v1/sessions/<session_id>', methods=['DELETE'])
+@require_auth
+def delete_session(session_id: str):
+    """
+    Permanently delete a game session.
+
+    This removes the session from the database entirely. The session cannot be
+    recovered after deletion. Use this to free up session slots for users who
+    have reached their tier limit.
+
+    Returns:
+        200: Session deleted successfully
+        401: Not authenticated
+        404: Session not found or not owned by user
+        500: Internal server error
+    """
+    logger.info("Deleting session", session_id=session_id)
+
+    try:
+        # Get current user
+        user = get_current_user()
+        user_id = user.id
+
+        # Delete session (validates ownership internally)
+        session_service = get_session_service()
+        session_service.delete_session(session_id, user_id)
+
+        logger.info("Session deleted successfully",
+                   session_id=session_id,
+                   user_id=user_id)
+
+        return success_response({
+            "message": "Session deleted successfully",
+            "session_id": session_id
+        })
+
+    except SessionNotFound as e:
+        logger.warning("Session not found for deletion",
+                      session_id=session_id,
+                      error=str(e))
+        return not_found_response("Session not found")
+
+    except Exception as e:
+        logger.error("Failed to delete session",
+                    session_id=session_id,
+                    error=str(e),
+                    exc_info=True)
+        return error_response(
+            status=500,
+            code="SESSION_DELETE_ERROR",
+            message="Failed to delete session"
+        )
+
+
+@sessions_bp.route('/api/v1/usage', methods=['GET'])
+@require_auth
+def get_usage():
+    """
+    Get user's daily usage information.
+
+    Returns the current daily turn usage, limit, remaining turns,
+    and reset time. Limits are based on user's subscription tier.
+
+    Returns:
+        200: Usage information
+            {
+                "user_id": "user_123",
+                "user_tier": "free",
+                "current_usage": 15,
+                "daily_limit": 50,
+                "remaining": 35,
+                "reset_time": "2025-11-27T00:00:00+00:00",
+                "is_limited": false,
+                "is_unlimited": false
+            }
+        401: Not authenticated
+        500: Internal server error
+    """
+    logger.info("Getting usage info")
+
+    try:
+        # Get current user and tier
+        user = get_current_user()
+        user_id = user.id
+        user_tier = get_user_tier_from_user(user)
+
+        # Get usage info from rate limiter
+        rate_limiter = RateLimiterService()
+        usage_info = rate_limiter.get_usage_info(user_id, user_tier)
+
+        logger.debug("Usage info retrieved",
+                    user_id=user_id,
+                    current_usage=usage_info.get('current_usage'),
+                    remaining=usage_info.get('remaining'))
+
+        return success_response(usage_info)
+
+    except Exception as e:
+        logger.error("Failed to get usage info",
+                    error=str(e),
+                    exc_info=True)
+        return error_response(
+            status=500,
+            code="USAGE_ERROR",
+            message="Failed to get usage information"
+        )

api/app/config.py

@@ -76,6 +76,7 @@ class RateLimitTier:
     ai_calls_per_day: int
     custom_actions_per_day: int  # -1 for unlimited
     custom_action_char_limit: int
+    max_sessions: int = 1  # Maximum active game sessions allowed
 
 
 @dataclass
@@ -86,6 +87,14 @@ class RateLimitingConfig:
     tiers: Dict[str, RateLimitTier] = field(default_factory=dict)
 
 
+@dataclass
+class SessionCacheConfig:
+    """Session cache configuration for reducing Appwrite API calls."""
+    enabled: bool = True
+    ttl_seconds: int = 300  # 5 minutes
+    redis_db: int = 2  # Separate from RQ (db 0) and rate limiting (db 1)
+
+
 @dataclass
 class AuthConfig:
     """Authentication configuration."""
@@ -104,6 +113,7 @@ class AuthConfig:
     name_min_length: int
     name_max_length: int
     email_max_length: int
+    session_cache: SessionCacheConfig = field(default_factory=SessionCacheConfig)
 
 
 @dataclass
@@ -229,7 +239,11 @@ class Config:
             tiers=rate_limit_tiers
         )
 
-        auth_config = AuthConfig(**config_data['auth'])
+        # Parse auth config with nested session_cache
+        auth_data = config_data['auth'].copy()
+        session_cache_data = auth_data.pop('session_cache', {})
+        session_cache_config = SessionCacheConfig(**session_cache_data) if session_cache_data else SessionCacheConfig()
+        auth_config = AuthConfig(**auth_data, session_cache=session_cache_config)
         session_config = SessionConfig(**config_data['session'])
         marketplace_config = MarketplaceConfig(**config_data['marketplace'])
         cors_config = CORSConfig(**config_data['cors'])

api/app/data/affixes/prefixes.yaml

@@ -0,0 +1,177 @@
+# Item Prefix Affixes
+# Prefixes appear before the item name: "Flaming Dagger"
+#
+# Affix Structure:
+#   affix_id: Unique identifier
+#   name: Display name (what appears in the item name)
+#   affix_type: "prefix"
+#   tier: "minor" (RARE), "major" (EPIC), "legendary" (LEGENDARY only)
+#   description: Flavor text describing the effect
+#   stat_bonuses: Dict of stat_name -> bonus value
+#   defense_bonus: Direct defense bonus
+#   resistance_bonus: Direct resistance bonus
+#   damage_bonus: Flat damage bonus (weapons)
+#   damage_type: Elemental damage type
+#   elemental_ratio: Portion converted to elemental (0.0-1.0)
+#   crit_chance_bonus: Added to crit chance
+#   crit_multiplier_bonus: Added to crit multiplier
+#   allowed_item_types: [] = all types, or ["weapon", "armor"]
+#   required_rarity: null = any, or "legendary"
+
+prefixes:
+  # ==================== ELEMENTAL PREFIXES (FIRE) ====================
+  flaming:
+    affix_id: "flaming"
+    name: "Flaming"
+    affix_type: "prefix"
+    tier: "minor"
+    description: "Imbued with fire magic, dealing bonus fire damage"
+    damage_type: "fire"
+    elemental_ratio: 0.25
+    damage_bonus: 3
+    allowed_item_types: ["weapon"]
+
+  blazing:
+    affix_id: "blazing"
+    name: "Blazing"
+    affix_type: "prefix"
+    tier: "major"
+    description: "Wreathed in intense flames"
+    damage_type: "fire"
+    elemental_ratio: 0.35
+    damage_bonus: 6
+    allowed_item_types: ["weapon"]
+
+  # ==================== ELEMENTAL PREFIXES (ICE) ====================
+  frozen:
+    affix_id: "frozen"
+    name: "Frozen"
+    affix_type: "prefix"
+    tier: "minor"
+    description: "Enchanted with frost magic"
+    damage_type: "ice"
+    elemental_ratio: 0.25
+    damage_bonus: 3
+    allowed_item_types: ["weapon"]
+
+  glacial:
+    affix_id: "glacial"
+    name: "Glacial"
+    affix_type: "prefix"
+    tier: "major"
+    description: "Encased in eternal ice"
+    damage_type: "ice"
+    elemental_ratio: 0.35
+    damage_bonus: 6
+    allowed_item_types: ["weapon"]
+
+  # ==================== ELEMENTAL PREFIXES (LIGHTNING) ====================
+  shocking:
+    affix_id: "shocking"
+    name: "Shocking"
+    affix_type: "prefix"
+    tier: "minor"
+    description: "Crackles with electrical energy"
+    damage_type: "lightning"
+    elemental_ratio: 0.25
+    damage_bonus: 3
+    allowed_item_types: ["weapon"]
+
+  thundering:
+    affix_id: "thundering"
+    name: "Thundering"
+    affix_type: "prefix"
+    tier: "major"
+    description: "Charged with the power of storms"
+    damage_type: "lightning"
+    elemental_ratio: 0.35
+    damage_bonus: 6
+    allowed_item_types: ["weapon"]
+
+  # ==================== MATERIAL PREFIXES ====================
+  iron:
+    affix_id: "iron"
+    name: "Iron"
+    affix_type: "prefix"
+    tier: "minor"
+    description: "Reinforced with sturdy iron"
+    stat_bonuses:
+      constitution: 1
+    defense_bonus: 2
+
+  steel:
+    affix_id: "steel"
+    name: "Steel"
+    affix_type: "prefix"
+    tier: "major"
+    description: "Forged from fine steel"
+    stat_bonuses:
+      constitution: 2
+      strength: 1
+    defense_bonus: 4
+
+  # ==================== QUALITY PREFIXES ====================
+  sharp:
+    affix_id: "sharp"
+    name: "Sharp"
+    affix_type: "prefix"
+    tier: "minor"
+    description: "Honed to a fine edge"
+    damage_bonus: 3
+    crit_chance_bonus: 0.02
+    allowed_item_types: ["weapon"]
+
+  keen:
+    affix_id: "keen"
+    name: "Keen"
+    affix_type: "prefix"
+    tier: "major"
+    description: "Razor-sharp edge that finds weak points"
+    damage_bonus: 5
+    crit_chance_bonus: 0.04
+    allowed_item_types: ["weapon"]
+
+  # ==================== DEFENSIVE PREFIXES ====================
+  sturdy:
+    affix_id: "sturdy"
+    name: "Sturdy"
+    affix_type: "prefix"
+    tier: "minor"
+    description: "Built to withstand punishment"
+    defense_bonus: 3
+    allowed_item_types: ["armor"]
+
+  reinforced:
+    affix_id: "reinforced"
+    name: "Reinforced"
+    affix_type: "prefix"
+    tier: "major"
+    description: "Heavily reinforced for maximum protection"
+    defense_bonus: 5
+    resistance_bonus: 2
+    allowed_item_types: ["armor"]
+
+  # ==================== LEGENDARY PREFIXES ====================
+  infernal:
+    affix_id: "infernal"
+    name: "Infernal"
+    affix_type: "prefix"
+    tier: "legendary"
+    description: "Burns with hellfire"
+    damage_type: "fire"
+    elemental_ratio: 0.45
+    damage_bonus: 12
+    allowed_item_types: ["weapon"]
+    required_rarity: "legendary"
+
+  vorpal:
+    affix_id: "vorpal"
+    name: "Vorpal"
+    affix_type: "prefix"
+    tier: "legendary"
+    description: "Cuts through anything with supernatural precision"
+    damage_bonus: 10
+    crit_chance_bonus: 0.08
+    crit_multiplier_bonus: 0.5
+    allowed_item_types: ["weapon"]
+    required_rarity: "legendary"

api/app/data/affixes/suffixes.yaml

@@ -0,0 +1,155 @@
+# Item Suffix Affixes
+# Suffixes appear after the item name: "Dagger of Strength"
+#
+# Suffix naming convention:
+#   - Minor tier: "of [Stat]" (e.g., "of Strength")
+#   - Major tier: "of the [Animal/Element]" (e.g., "of the Bear")
+#   - Legendary tier: "of the [Mythical]" (e.g., "of the Titan")
+
+suffixes:
+  # ==================== STAT SUFFIXES (MINOR) ====================
+  of_strength:
+    affix_id: "of_strength"
+    name: "of Strength"
+    affix_type: "suffix"
+    tier: "minor"
+    description: "Grants physical power"
+    stat_bonuses:
+      strength: 2
+
+  of_dexterity:
+    affix_id: "of_dexterity"
+    name: "of Dexterity"
+    affix_type: "suffix"
+    tier: "minor"
+    description: "Grants agility and precision"
+    stat_bonuses:
+      dexterity: 2
+
+  of_constitution:
+    affix_id: "of_constitution"
+    name: "of Fortitude"
+    affix_type: "suffix"
+    tier: "minor"
+    description: "Grants endurance"
+    stat_bonuses:
+      constitution: 2
+
+  of_intelligence:
+    affix_id: "of_intelligence"
+    name: "of Intelligence"
+    affix_type: "suffix"
+    tier: "minor"
+    description: "Grants magical aptitude"
+    stat_bonuses:
+      intelligence: 2
+
+  of_wisdom:
+    affix_id: "of_wisdom"
+    name: "of Wisdom"
+    affix_type: "suffix"
+    tier: "minor"
+    description: "Grants insight and perception"
+    stat_bonuses:
+      wisdom: 2
+
+  of_charisma:
+    affix_id: "of_charisma"
+    name: "of Charm"
+    affix_type: "suffix"
+    tier: "minor"
+    description: "Grants social influence"
+    stat_bonuses:
+      charisma: 2
+
+  of_luck:
+    affix_id: "of_luck"
+    name: "of Fortune"
+    affix_type: "suffix"
+    tier: "minor"
+    description: "Grants favor from fate"
+    stat_bonuses:
+      luck: 2
+
+  # ==================== ENHANCED STAT SUFFIXES (MAJOR) ====================
+  of_the_bear:
+    affix_id: "of_the_bear"
+    name: "of the Bear"
+    affix_type: "suffix"
+    tier: "major"
+    description: "Grants the might and endurance of a bear"
+    stat_bonuses:
+      strength: 4
+      constitution: 2
+
+  of_the_fox:
+    affix_id: "of_the_fox"
+    name: "of the Fox"
+    affix_type: "suffix"
+    tier: "major"
+    description: "Grants the cunning and agility of a fox"
+    stat_bonuses:
+      dexterity: 4
+      luck: 2
+
+  of_the_owl:
+    affix_id: "of_the_owl"
+    name: "of the Owl"
+    affix_type: "suffix"
+    tier: "major"
+    description: "Grants the wisdom and insight of an owl"
+    stat_bonuses:
+      intelligence: 3
+      wisdom: 3
+
+  # ==================== DEFENSIVE SUFFIXES ====================
+  of_protection:
+    affix_id: "of_protection"
+    name: "of Protection"
+    affix_type: "suffix"
+    tier: "minor"
+    description: "Offers physical protection"
+    defense_bonus: 3
+
+  of_warding:
+    affix_id: "of_warding"
+    name: "of Warding"
+    affix_type: "suffix"
+    tier: "major"
+    description: "Wards against physical and magical harm"
+    defense_bonus: 5
+    resistance_bonus: 3
+
+  # ==================== LEGENDARY SUFFIXES ====================
+  of_the_titan:
+    affix_id: "of_the_titan"
+    name: "of the Titan"
+    affix_type: "suffix"
+    tier: "legendary"
+    description: "Grants titanic strength and endurance"
+    stat_bonuses:
+      strength: 8
+      constitution: 4
+    required_rarity: "legendary"
+
+  of_the_wind:
+    affix_id: "of_the_wind"
+    name: "of the Wind"
+    affix_type: "suffix"
+    tier: "legendary"
+    description: "Swift as the wind itself"
+    stat_bonuses:
+      dexterity: 8
+      luck: 4
+    crit_chance_bonus: 0.05
+    required_rarity: "legendary"
+
+  of_invincibility:
+    affix_id: "of_invincibility"
+    name: "of Invincibility"
+    affix_type: "suffix"
+    tier: "legendary"
+    description: "Grants supreme protection"
+    defense_bonus: 10
+    resistance_bonus: 8
+    required_rarity: "legendary"

api/app/data/base_items/armor.yaml

@@ -0,0 +1,152 @@
+# Base Armor Templates for Procedural Generation
+#
+# These templates define the foundation that affixes attach to.
+# Example: "Leather Vest" + "Sturdy" prefix = "Sturdy Leather Vest"
+#
+# Armor categories:
+# - Cloth: Low defense, high resistance (mages)
+# - Leather: Balanced defense/resistance (rogues)
+# - Chain: Medium defense, low resistance (versatile)
+# - Plate: High defense, low resistance (warriors)
+
+armor:
+  # ==================== CLOTH (MAGE ARMOR) ====================
+  cloth_robe:
+    template_id: "cloth_robe"
+    name: "Cloth Robe"
+    item_type: "armor"
+    description: "Simple cloth robes favored by spellcasters"
+    base_defense: 2
+    base_resistance: 5
+    base_value: 15
+    required_level: 1
+    drop_weight: 1.3
+
+  silk_robe:
+    template_id: "silk_robe"
+    name: "Silk Robe"
+    item_type: "armor"
+    description: "Fine silk robes that channel magical energy"
+    base_defense: 3
+    base_resistance: 8
+    base_value: 40
+    required_level: 3
+    drop_weight: 0.9
+
+  arcane_vestments:
+    template_id: "arcane_vestments"
+    name: "Arcane Vestments"
+    item_type: "armor"
+    description: "Robes woven with magical threads"
+    base_defense: 5
+    base_resistance: 12
+    base_value: 80
+    required_level: 5
+    drop_weight: 0.6
+    min_rarity: "uncommon"
+
+  # ==================== LEATHER (ROGUE ARMOR) ====================
+  leather_vest:
+    template_id: "leather_vest"
+    name: "Leather Vest"
+    item_type: "armor"
+    description: "Basic leather protection for agile fighters"
+    base_defense: 5
+    base_resistance: 2
+    base_value: 20
+    required_level: 1
+    drop_weight: 1.3
+
+  studded_leather:
+    template_id: "studded_leather"
+    name: "Studded Leather"
+    item_type: "armor"
+    description: "Leather armor reinforced with metal studs"
+    base_defense: 8
+    base_resistance: 3
+    base_value: 45
+    required_level: 3
+    drop_weight: 1.0
+
+  hardened_leather:
+    template_id: "hardened_leather"
+    name: "Hardened Leather"
+    item_type: "armor"
+    description: "Boiled and hardened leather for superior protection"
+    base_defense: 12
+    base_resistance: 5
+    base_value: 75
+    required_level: 5
+    drop_weight: 0.7
+    min_rarity: "uncommon"
+
+  # ==================== CHAIN (VERSATILE) ====================
+  chain_shirt:
+    template_id: "chain_shirt"
+    name: "Chain Shirt"
+    item_type: "armor"
+    description: "A shirt of interlocking metal rings"
+    base_defense: 7
+    base_resistance: 2
+    base_value: 35
+    required_level: 2
+    drop_weight: 1.0
+
+  chainmail:
+    template_id: "chainmail"
+    name: "Chainmail"
+    item_type: "armor"
+    description: "Full chainmail armor covering torso and arms"
+    base_defense: 10
+    base_resistance: 3
+    base_value: 50
+    required_level: 3
+    drop_weight: 1.0
+
+  heavy_chainmail:
+    template_id: "heavy_chainmail"
+    name: "Heavy Chainmail"
+    item_type: "armor"
+    description: "Thick chainmail with reinforced rings"
+    base_defense: 14
+    base_resistance: 4
+    base_value: 85
+    required_level: 5
+    drop_weight: 0.7
+    min_rarity: "uncommon"
+
+  # ==================== PLATE (WARRIOR ARMOR) ====================
+  scale_mail:
+    template_id: "scale_mail"
+    name: "Scale Mail"
+    item_type: "armor"
+    description: "Overlapping metal scales on leather backing"
+    base_defense: 12
+    base_resistance: 2
+    base_value: 60
+    required_level: 4
+    drop_weight: 0.8
+
+  half_plate:
+    template_id: "half_plate"
+    name: "Half Plate"
+    item_type: "armor"
+    description: "Plate armor protecting vital areas"
+    base_defense: 16
+    base_resistance: 2
+    base_value: 120
+    required_level: 6
+    drop_weight: 0.5
+    min_rarity: "rare"
+
+  plate_armor:
+    template_id: "plate_armor"
+    name: "Plate Armor"
+    item_type: "armor"
+    description: "Full metal plate protection"
+    base_defense: 22
+    base_resistance: 3
+    base_value: 200
+    required_level: 7
+    drop_weight: 0.4
+    min_rarity: "rare"

api/app/data/base_items/weapons.yaml

@@ -0,0 +1,227 @@
+# Base Weapon Templates for Procedural Generation
+#
+# These templates define the foundation that affixes attach to.
+# Example: "Dagger" + "Flaming" prefix = "Flaming Dagger"
+#
+# Template Structure:
+#   template_id: Unique identifier
+#   name: Base item name
+#   item_type: "weapon"
+#   description: Flavor text
+#   base_damage: Weapon damage
+#   base_value: Gold value
+#   damage_type: "physical" (default)
+#   crit_chance: Critical hit chance (0.0-1.0)
+#   crit_multiplier: Crit damage multiplier
+#   required_level: Min level to use/drop
+#   drop_weight: Higher = more common (1.0 = standard)
+#   min_rarity: Minimum rarity for this template
+
+weapons:
+  # ==================== ONE-HANDED SWORDS ====================
+  dagger:
+    template_id: "dagger"
+    name: "Dagger"
+    item_type: "weapon"
+    description: "A small, quick blade for close combat"
+    base_damage: 6
+    base_value: 15
+    damage_type: "physical"
+    crit_chance: 0.08
+    crit_multiplier: 2.0
+    required_level: 1
+    drop_weight: 1.5
+
+  short_sword:
+    template_id: "short_sword"
+    name: "Short Sword"
+    item_type: "weapon"
+    description: "A versatile one-handed blade"
+    base_damage: 10
+    base_value: 30
+    damage_type: "physical"
+    crit_chance: 0.06
+    crit_multiplier: 2.0
+    required_level: 1
+    drop_weight: 1.3
+
+  longsword:
+    template_id: "longsword"
+    name: "Longsword"
+    item_type: "weapon"
+    description: "A standard warrior's blade"
+    base_damage: 14
+    base_value: 50
+    damage_type: "physical"
+    crit_chance: 0.05
+    crit_multiplier: 2.0
+    required_level: 3
+    drop_weight: 1.0
+
+  # ==================== TWO-HANDED WEAPONS ====================
+  greatsword:
+    template_id: "greatsword"
+    name: "Greatsword"
+    item_type: "weapon"
+    description: "A massive two-handed blade"
+    base_damage: 22
+    base_value: 100
+    damage_type: "physical"
+    crit_chance: 0.04
+    crit_multiplier: 2.5
+    required_level: 5
+    drop_weight: 0.7
+    min_rarity: "uncommon"
+
+  # ==================== AXES ====================
+  hatchet:
+    template_id: "hatchet"
+    name: "Hatchet"
+    item_type: "weapon"
+    description: "A small throwing axe"
+    base_damage: 8
+    base_value: 20
+    damage_type: "physical"
+    crit_chance: 0.06
+    crit_multiplier: 2.2
+    required_level: 1
+    drop_weight: 1.2
+
+  battle_axe:
+    template_id: "battle_axe"
+    name: "Battle Axe"
+    item_type: "weapon"
+    description: "A heavy axe designed for combat"
+    base_damage: 16
+    base_value: 60
+    damage_type: "physical"
+    crit_chance: 0.05
+    crit_multiplier: 2.3
+    required_level: 4
+    drop_weight: 0.9
+
+  # ==================== BLUNT WEAPONS ====================
+  club:
+    template_id: "club"
+    name: "Club"
+    item_type: "weapon"
+    description: "A simple wooden club"
+    base_damage: 7
+    base_value: 10
+    damage_type: "physical"
+    crit_chance: 0.04
+    crit_multiplier: 2.0
+    required_level: 1
+    drop_weight: 1.5
+
+  mace:
+    template_id: "mace"
+    name: "Mace"
+    item_type: "weapon"
+    description: "A flanged mace for crushing armor"
+    base_damage: 12
+    base_value: 40
+    damage_type: "physical"
+    crit_chance: 0.05
+    crit_multiplier: 2.0
+    required_level: 2
+    drop_weight: 1.0
+
+  # ==================== STAVES ====================
+  quarterstaff:
+    template_id: "quarterstaff"
+    name: "Quarterstaff"
+    item_type: "weapon"
+    description: "A simple wooden staff"
+    base_damage: 6
+    base_value: 10
+    damage_type: "physical"
+    crit_chance: 0.05
+    crit_multiplier: 2.0
+    required_level: 1
+    drop_weight: 1.2
+
+  wizard_staff:
+    template_id: "wizard_staff"
+    name: "Wizard Staff"
+    item_type: "weapon"
+    description: "A staff attuned to magical energy"
+    base_damage: 4
+    base_spell_power: 12
+    base_value: 45
+    damage_type: "arcane"
+    crit_chance: 0.05
+    crit_multiplier: 2.0
+    required_level: 3
+    drop_weight: 0.8
+
+  arcane_staff:
+    template_id: "arcane_staff"
+    name: "Arcane Staff"
+    item_type: "weapon"
+    description: "A powerful staff pulsing with arcane power"
+    base_damage: 6
+    base_spell_power: 18
+    base_value: 90
+    damage_type: "arcane"
+    crit_chance: 0.06
+    crit_multiplier: 2.0
+    required_level: 5
+    drop_weight: 0.6
+    min_rarity: "uncommon"
+
+  # ==================== WANDS ====================
+  wand:
+    template_id: "wand"
+    name: "Wand"
+    item_type: "weapon"
+    description: "A simple magical focus"
+    base_damage: 2
+    base_spell_power: 8
+    base_value: 30
+    damage_type: "arcane"
+    crit_chance: 0.06
+    crit_multiplier: 2.0
+    required_level: 1
+    drop_weight: 1.0
+
+  crystal_wand:
+    template_id: "crystal_wand"
+    name: "Crystal Wand"
+    item_type: "weapon"
+    description: "A wand topped with a magical crystal"
+    base_damage: 3
+    base_spell_power: 14
+    base_value: 60
+    damage_type: "arcane"
+    crit_chance: 0.07
+    crit_multiplier: 2.2
+    required_level: 4
+    drop_weight: 0.8
+
+  # ==================== RANGED ====================
+  shortbow:
+    template_id: "shortbow"
+    name: "Shortbow"
+    item_type: "weapon"
+    description: "A compact bow for quick shots"
+    base_damage: 8
+    base_value: 25
+    damage_type: "physical"
+    crit_chance: 0.07
+    crit_multiplier: 2.0
+    required_level: 1
+    drop_weight: 1.1
+
+  longbow:
+    template_id: "longbow"
+    name: "Longbow"
+    item_type: "weapon"
+    description: "A powerful bow with excellent range"
+    base_damage: 14
+    base_value: 55
+    damage_type: "physical"
+    crit_chance: 0.08
+    crit_multiplier: 2.2
+    required_level: 4
+    drop_weight: 0.9

api/app/data/classes/arcanist.yaml

@@ -8,7 +8,7 @@ description: >
   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 (total: 65 + luck)
 base_stats:
   strength: 8       # Low physical power
   dexterity: 10     # Average agility
@@ -16,6 +16,7 @@ base_stats:
   intelligence: 15  # Exceptional magical power
   wisdom: 12        # Above average perception
   charisma: 11      # Above average social
+  luck: 9           # Slight chaos magic boost
 
 starting_equipment:
   - worn_staff

api/app/data/classes/assassin.yaml

@@ -8,7 +8,7 @@ description: >
   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 (total: 65 + luck)
 base_stats:
   strength: 11      # Above average physical power
   dexterity: 15     # Exceptional agility
@@ -16,6 +16,7 @@ base_stats:
   intelligence: 9   # Below average magic
   wisdom: 10        # Average perception
   charisma: 10      # Average social
+  luck: 12          # High luck for crits and precision
 
 starting_equipment:
   - rusty_dagger

api/app/data/classes/lorekeeper.yaml

@@ -8,7 +8,7 @@ description: >
   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 (total: 67 + luck)
 base_stats:
   strength: 8       # Low physical power
   dexterity: 11     # Above average agility
@@ -16,6 +16,7 @@ base_stats:
   intelligence: 13  # Above average magical power
   wisdom: 11        # Above average perception
   charisma: 14      # High social/performance
+  luck: 10          # Knowledge is its own luck
 
 starting_equipment:
   - tome

api/app/data/classes/luminary.yaml

@@ -8,7 +8,7 @@ description: >
   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 (total: 68 + luck)
 base_stats:
   strength: 9       # Below average physical power
   dexterity: 9      # Below average agility
@@ -16,6 +16,7 @@ base_stats:
   intelligence: 12  # Above average magical power
   wisdom: 14        # High perception/divine power
   charisma: 13      # Above average social
+  luck: 11          # Divine favor grants fortune
 
 starting_equipment:
   - rusty_mace

api/app/data/classes/necromancer.yaml

@@ -8,7 +8,7 @@ description: >
   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 (total: 65 + luck)
 base_stats:
   strength: 8       # Low physical power
   dexterity: 10     # Average agility
@@ -16,6 +16,7 @@ base_stats:
   intelligence: 14  # High magical power
   wisdom: 11        # Above average perception
   charisma: 12      # Above average social (commands undead)
+  luck: 7           # Dark arts come with a cost
 
 starting_equipment:
   - bone_wand

api/app/data/classes/oathkeeper.yaml

@@ -8,7 +8,7 @@ description: >
   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 (total: 67 + luck)
 base_stats:
   strength: 12      # Above average physical power
   dexterity: 9      # Below average agility
@@ -16,6 +16,7 @@ base_stats:
   intelligence: 10  # Average magic
   wisdom: 12        # Above average perception
   charisma: 11      # Above average social
+  luck: 9           # Honorable, modest fortune
 
 starting_equipment:
   - rusty_sword

api/app/data/classes/vanguard.yaml

@@ -8,7 +8,7 @@ description: >
   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 (total: 65 + luck)
 base_stats:
   strength: 14      # High physical power
   dexterity: 10     # Average agility
@@ -16,6 +16,7 @@ base_stats:
   intelligence: 8   # Low magic
   wisdom: 10        # Average perception
   charisma: 9       # Below average social
+  luck: 8           # Low luck, relies on strength
 
 # Starting equipment (minimal)
 starting_equipment:

api/app/data/classes/wildstrider.yaml

@@ -8,7 +8,7 @@ description: >
   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 (total: 66 + luck)
 base_stats:
   strength: 10      # Average physical power
   dexterity: 14     # High agility
@@ -16,6 +16,7 @@ base_stats:
   intelligence: 9   # Below average magic
   wisdom: 13        # Above average perception
   charisma: 9       # Below average social
+  luck: 10          # Average luck, self-reliant
 
 starting_equipment:
   - rusty_bow

api/app/data/enemies/bandit.yaml

@@ -0,0 +1,55 @@
+# Bandit - Medium humanoid with weapon
+# A highway robber armed with sword and dagger
+
+enemy_id: bandit
+name: Bandit Rogue
+description: >
+  A rough-looking human in worn leather armor, their face partially hidden
+  by a tattered hood. They fight with a chipped sword and keep a dagger
+  ready for backstabs. Desperation has made them dangerous.
+
+base_stats:
+  strength: 12
+  dexterity: 14
+  constitution: 10
+  intelligence: 10
+  wisdom: 8
+  charisma: 8
+  luck: 10
+
+abilities:
+  - basic_attack
+  - quick_strike
+  - dirty_trick
+
+loot_table:
+  - item_id: bandit_sword
+    drop_chance: 0.20
+    quantity_min: 1
+    quantity_max: 1
+  - item_id: leather_armor
+    drop_chance: 0.15
+    quantity_min: 1
+    quantity_max: 1
+  - item_id: lockpick
+    drop_chance: 0.25
+    quantity_min: 1
+    quantity_max: 3
+  - item_id: gold_coin
+    drop_chance: 0.80
+    quantity_min: 5
+    quantity_max: 20
+
+experience_reward: 35
+gold_reward_min: 10
+gold_reward_max: 30
+difficulty: medium
+
+tags:
+  - humanoid
+  - rogue
+  - armed
+
+base_damage: 8
+crit_chance: 0.12
+flee_chance: 0.45

api/app/data/enemies/dire_wolf.yaml

@@ -0,0 +1,52 @@
+# Dire Wolf - Medium beast enemy
+# A large, ferocious predator
+
+enemy_id: dire_wolf
+name: Dire Wolf
+description: >
+  A massive wolf the size of a horse, with matted black fur and eyes
+  that glow with predatory intelligence. Its fangs are as long as daggers,
+  and its growl rumbles like distant thunder.
+
+base_stats:
+  strength: 14
+  dexterity: 14
+  constitution: 12
+  intelligence: 4
+  wisdom: 10
+  charisma: 6
+  luck: 8
+
+abilities:
+  - basic_attack
+  - savage_bite
+  - pack_howl
+
+loot_table:
+  - item_id: wolf_pelt
+    drop_chance: 0.60
+    quantity_min: 1
+    quantity_max: 1
+  - item_id: wolf_fang
+    drop_chance: 0.40
+    quantity_min: 1
+    quantity_max: 2
+  - item_id: beast_meat
+    drop_chance: 0.70
+    quantity_min: 1
+    quantity_max: 3
+
+experience_reward: 40
+gold_reward_min: 0
+gold_reward_max: 5
+difficulty: medium
+
+tags:
+  - beast
+  - wolf
+  - large
+  - pack
+
+base_damage: 10
+crit_chance: 0.10
+flee_chance: 0.40

api/app/data/enemies/goblin.yaml

@@ -0,0 +1,45 @@
+# Goblin - Easy melee enemy (STR-focused)
+# A small, cunning creature that attacks in groups
+
+enemy_id: goblin
+name: Goblin Scout
+description: >
+  A small, green-skinned creature with pointed ears and sharp teeth.
+  Goblins are cowardly alone but dangerous in groups, using crude weapons
+  and dirty tactics to overwhelm their prey.
+
+base_stats:
+  strength: 8
+  dexterity: 12
+  constitution: 6
+  intelligence: 6
+  wisdom: 6
+  charisma: 4
+  luck: 8
+
+abilities:
+  - basic_attack
+
+loot_table:
+  - item_id: rusty_dagger
+    drop_chance: 0.15
+    quantity_min: 1
+    quantity_max: 1
+  - item_id: gold_coin
+    drop_chance: 0.50
+    quantity_min: 1
+    quantity_max: 3
+
+experience_reward: 15
+gold_reward_min: 2
+gold_reward_max: 8
+difficulty: easy
+
+tags:
+  - humanoid
+  - goblinoid
+  - small
+
+base_damage: 4
+crit_chance: 0.05
+flee_chance: 0.60

api/app/data/enemies/goblin_chieftain.yaml

@@ -0,0 +1,85 @@
+# Goblin Chieftain - Hard variant, elite tribe leader
+# A cunning and powerful goblin leader, adorned with trophies.
+# Commands respect through fear and violence, drops quality loot.
+
+enemy_id: goblin_chieftain
+name: Goblin Chieftain
+description: >
+  A large, scarred goblin wearing a crown of teeth and bones.
+  The chieftain has clawed its way to leadership through countless
+  battles and betrayals. It wields a well-maintained weapon stolen
+  from a fallen adventurer and commands its tribe with an iron fist.
+
+base_stats:
+  strength: 16
+  dexterity: 12
+  constitution: 14
+  intelligence: 10
+  wisdom: 10
+  charisma: 12
+  luck: 12
+
+abilities:
+  - basic_attack
+  - shield_bash
+  - intimidating_shout
+
+loot_table:
+  # Static drops - guaranteed materials
+  - loot_type: static
+    item_id: goblin_ear
+    drop_chance: 1.0
+    quantity_min: 2
+    quantity_max: 3
+  - loot_type: static
+    item_id: goblin_chieftain_token
+    drop_chance: 0.80
+    quantity_min: 1
+    quantity_max: 1
+  - loot_type: static
+    item_id: goblin_war_paint
+    drop_chance: 0.50
+    quantity_min: 1
+    quantity_max: 2
+
+  # Consumable drops
+  - loot_type: static
+    item_id: health_potion_medium
+    drop_chance: 0.40
+    quantity_min: 1
+    quantity_max: 1
+  - loot_type: static
+    item_id: elixir_of_strength
+    drop_chance: 0.10
+    quantity_min: 1
+    quantity_max: 1
+
+  # Procedural equipment drops - higher chance and rarity bonus
+  - loot_type: procedural
+    item_type: weapon
+    drop_chance: 0.25
+    rarity_bonus: 0.10
+    quantity_min: 1
+    quantity_max: 1
+  - loot_type: procedural
+    item_type: armor
+    drop_chance: 0.15
+    rarity_bonus: 0.05
+    quantity_min: 1
+    quantity_max: 1
+
+experience_reward: 75
+gold_reward_min: 20
+gold_reward_max: 50
+difficulty: hard
+
+tags:
+  - humanoid
+  - goblinoid
+  - leader
+  - elite
+  - armed
+
+base_damage: 14
+crit_chance: 0.15
+flee_chance: 0.25

api/app/data/enemies/goblin_scout.yaml

@@ -0,0 +1,56 @@
+# Goblin Scout - Easy variant, agile but fragile
+# A fast, cowardly goblin that serves as a lookout for its tribe.
+# Quick to flee, drops minor loot and the occasional small potion.
+
+enemy_id: goblin_scout
+name: Goblin Scout
+description: >
+  A small, wiry goblin with oversized ears and beady yellow eyes.
+  Goblin scouts are the first line of awareness for their tribes,
+  often found lurking in shadows or perched in trees. They prefer
+  to run rather than fight, but will attack if cornered.
+
+base_stats:
+  strength: 6
+  dexterity: 14
+  constitution: 5
+  intelligence: 6
+  wisdom: 10
+  charisma: 4
+  luck: 10
+
+abilities:
+  - basic_attack
+
+loot_table:
+  # Static drops - materials and consumables
+  - loot_type: static
+    item_id: goblin_ear
+    drop_chance: 0.60
+    quantity_min: 1
+    quantity_max: 1
+  - loot_type: static
+    item_id: goblin_trinket
+    drop_chance: 0.20
+    quantity_min: 1
+    quantity_max: 1
+  - loot_type: static
+    item_id: health_potion_small
+    drop_chance: 0.08
+    quantity_min: 1
+    quantity_max: 1
+
+experience_reward: 10
+gold_reward_min: 1
+gold_reward_max: 4
+difficulty: easy
+
+tags:
+  - humanoid
+  - goblinoid
+  - small
+  - scout
+
+base_damage: 3
+crit_chance: 0.08
+flee_chance: 0.70

api/app/data/enemies/goblin_shaman.yaml

@@ -0,0 +1,52 @@
+# Goblin Shaman - Easy caster enemy (INT-focused)
+# A goblin spellcaster that provides magical support
+
+enemy_id: goblin_shaman
+name: Goblin Shaman
+description: >
+  A hunched goblin wrapped in tattered robes, clutching a staff adorned
+  with bones and feathers. It mutters dark incantations and hurls bolts
+  of sickly green fire at its enemies.
+
+base_stats:
+  strength: 4
+  dexterity: 10
+  constitution: 6
+  intelligence: 12
+  wisdom: 10
+  charisma: 6
+  luck: 10
+
+abilities:
+  - basic_attack
+  - fire_bolt
+  - minor_heal
+
+loot_table:
+  - item_id: shaman_staff
+    drop_chance: 0.10
+    quantity_min: 1
+    quantity_max: 1
+  - item_id: mana_potion_small
+    drop_chance: 0.20
+    quantity_min: 1
+    quantity_max: 1
+  - item_id: gold_coin
+    drop_chance: 0.60
+    quantity_min: 3
+    quantity_max: 8
+
+experience_reward: 25
+gold_reward_min: 5
+gold_reward_max: 15
+difficulty: easy
+
+tags:
+  - humanoid
+  - goblinoid
+  - caster
+  - small
+
+base_damage: 3
+crit_chance: 0.08
+flee_chance: 0.55

api/app/data/enemies/goblin_warrior.yaml

@@ -0,0 +1,70 @@
+# Goblin Warrior - Medium variant, trained fighter
+# A battle-hardened goblin wielding crude but effective weapons.
+# More dangerous than scouts, fights in organized groups.
+
+enemy_id: goblin_warrior
+name: Goblin Warrior
+description: >
+  A muscular goblin clad in scavenged armor and wielding a crude
+  but deadly weapon. Goblin warriors are the backbone of any goblin
+  warband, trained to fight rather than flee. They attack with
+  surprising ferocity and coordination.
+
+base_stats:
+  strength: 12
+  dexterity: 10
+  constitution: 10
+  intelligence: 6
+  wisdom: 6
+  charisma: 4
+  luck: 8
+
+abilities:
+  - basic_attack
+  - shield_bash
+
+loot_table:
+  # Static drops - materials and consumables
+  - loot_type: static
+    item_id: goblin_ear
+    drop_chance: 0.80
+    quantity_min: 1
+    quantity_max: 1
+  - loot_type: static
+    item_id: goblin_war_paint
+    drop_chance: 0.15
+    quantity_min: 1
+    quantity_max: 1
+  - loot_type: static
+    item_id: health_potion_small
+    drop_chance: 0.15
+    quantity_min: 1
+    quantity_max: 1
+  - loot_type: static
+    item_id: iron_ore
+    drop_chance: 0.10
+    quantity_min: 1
+    quantity_max: 2
+
+  # Procedural equipment drops
+  - loot_type: procedural
+    item_type: weapon
+    drop_chance: 0.08
+    rarity_bonus: 0.0
+    quantity_min: 1
+    quantity_max: 1
+
+experience_reward: 25
+gold_reward_min: 5
+gold_reward_max: 15
+difficulty: medium
+
+tags:
+  - humanoid
+  - goblinoid
+  - warrior
+  - armed
+
+base_damage: 8
+crit_chance: 0.10
+flee_chance: 0.45

api/app/data/enemies/orc_berserker.yaml

@@ -0,0 +1,58 @@
+# Orc Berserker - Hard heavy hitter
+# A fearsome orc warrior in a battle rage
+
+enemy_id: orc_berserker
+name: Orc Berserker
+description: >
+  A towering mass of green muscle and fury, covered in tribal war paint
+  and scars from countless battles. Foam flecks at the corners of its
+  mouth as it swings a massive greataxe with terrifying speed. In its
+  battle rage, it feels no pain and shows no mercy.
+
+base_stats:
+  strength: 18
+  dexterity: 10
+  constitution: 16
+  intelligence: 6
+  wisdom: 6
+  charisma: 4
+  luck: 8
+
+abilities:
+  - basic_attack
+  - cleave
+  - berserker_rage
+  - intimidating_shout
+
+loot_table:
+  - item_id: orc_greataxe
+    drop_chance: 0.20
+    quantity_min: 1
+    quantity_max: 1
+  - item_id: orc_war_paint
+    drop_chance: 0.35
+    quantity_min: 1
+    quantity_max: 2
+  - item_id: beast_hide_armor
+    drop_chance: 0.15
+    quantity_min: 1
+    quantity_max: 1
+  - item_id: gold_coin
+    drop_chance: 0.70
+    quantity_min: 15
+    quantity_max: 40
+
+experience_reward: 80
+gold_reward_min: 20
+gold_reward_max: 50
+difficulty: hard
+
+tags:
+  - humanoid
+  - orc
+  - berserker
+  - large
+
+base_damage: 15
+crit_chance: 0.15
+flee_chance: 0.30

api/app/data/enemies/skeleton_warrior.yaml

@@ -0,0 +1,52 @@
+# Skeleton Warrior - Medium undead melee
+# An animated skeleton wielding ancient weapons
+
+enemy_id: skeleton_warrior
+name: Skeleton Warrior
+description: >
+  The animated remains of a long-dead soldier, held together by dark magic.
+  Its empty eye sockets glow with pale blue fire, and it wields a rusted
+  but deadly sword with unnatural precision. It knows no fear and feels no pain.
+
+base_stats:
+  strength: 12
+  dexterity: 10
+  constitution: 10
+  intelligence: 4
+  wisdom: 6
+  charisma: 2
+  luck: 6
+
+abilities:
+  - basic_attack
+  - shield_bash
+  - bone_rattle
+
+loot_table:
+  - item_id: ancient_sword
+    drop_chance: 0.15
+    quantity_min: 1
+    quantity_max: 1
+  - item_id: bone_fragment
+    drop_chance: 0.80
+    quantity_min: 2
+    quantity_max: 5
+  - item_id: soul_essence
+    drop_chance: 0.10
+    quantity_min: 1
+    quantity_max: 1
+
+experience_reward: 45
+gold_reward_min: 0
+gold_reward_max: 10
+difficulty: medium
+
+tags:
+  - undead
+  - skeleton
+  - armed
+  - fearless
+
+base_damage: 9
+crit_chance: 0.08
+flee_chance: 0.50

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

@@ -3,6 +3,7 @@ npc_id: npc_blacksmith_hilda
 name: Hilda Ironforge
 role: blacksmith
 location_id: crossville_village
+image_url: /static/images/npcs/crossville/blacksmith_hilda.png
 
 personality:
   traits:

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

@@ -3,6 +3,7 @@ npc_id: npc_grom_ironbeard
 name: Grom Ironbeard
 role: bartender
 location_id: crossville_tavern
+image_url: /static/images/npcs/crossville/grom_ironbeard.png
 
 personality:
   traits:

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

@@ -3,6 +3,7 @@ npc_id: npc_mayor_aldric
 name: Mayor Aldric Thornwood
 role: mayor
 location_id: crossville_village
+image_url: /static/images/npcs/crossville/mayor_aldric.png
 
 personality:
   traits:

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

@@ -3,6 +3,7 @@ npc_id: npc_mira_swiftfoot
 name: Mira Swiftfoot
 role: rogue
 location_id: crossville_tavern
+image_url: /static/images/npcs/crossville/mira_swiftfoot.png
 
 personality:
   traits:

api/app/data/static_items/consumables.yaml

@@ -0,0 +1,161 @@
+# Consumable items that drop from enemies or are purchased from vendors
+# These items have effects_on_use that trigger when consumed
+
+items:
+  # ==========================================================================
+  # Health Potions
+  # ==========================================================================
+
+  health_potion_small:
+    name: "Small Health Potion"
+    item_type: consumable
+    rarity: common
+    description: "A small vial of red liquid that restores a modest amount of health."
+    value: 25
+    is_tradeable: true
+    effects_on_use:
+      - effect_id: heal_small
+        name: "Minor Healing"
+        effect_type: hot
+        power: 30
+        duration: 1
+        stacks: 1
+
+  health_potion_medium:
+    name: "Health Potion"
+    item_type: consumable
+    rarity: uncommon
+    description: "A standard healing potion used by adventurers across the realm."
+    value: 75
+    is_tradeable: true
+    effects_on_use:
+      - effect_id: heal_medium
+        name: "Healing"
+        effect_type: hot
+        power: 75
+        duration: 1
+        stacks: 1
+
+  health_potion_large:
+    name: "Large Health Potion"
+    item_type: consumable
+    rarity: rare
+    description: "A potent healing draught that restores significant health."
+    value: 150
+    is_tradeable: true
+    effects_on_use:
+      - effect_id: heal_large
+        name: "Major Healing"
+        effect_type: hot
+        power: 150
+        duration: 1
+        stacks: 1
+
+  # ==========================================================================
+  # Mana Potions
+  # ==========================================================================
+
+  mana_potion_small:
+    name: "Small Mana Potion"
+    item_type: consumable
+    rarity: common
+    description: "A small vial of blue liquid that restores mana."
+    value: 25
+    is_tradeable: true
+    # Note: MP restoration would need custom effect type or game logic
+
+  mana_potion_medium:
+    name: "Mana Potion"
+    item_type: consumable
+    rarity: uncommon
+    description: "A standard mana potion favored by spellcasters."
+    value: 75
+    is_tradeable: true
+
+  # ==========================================================================
+  # Status Effect Cures
+  # ==========================================================================
+
+  antidote:
+    name: "Antidote"
+    item_type: consumable
+    rarity: common
+    description: "A bitter herbal remedy that cures poison effects."
+    value: 30
+    is_tradeable: true
+
+  smelling_salts:
+    name: "Smelling Salts"
+    item_type: consumable
+    rarity: uncommon
+    description: "Pungent salts that can revive unconscious allies or cure stun."
+    value: 40
+    is_tradeable: true
+
+  # ==========================================================================
+  # Combat Buffs
+  # ==========================================================================
+
+  elixir_of_strength:
+    name: "Elixir of Strength"
+    item_type: consumable
+    rarity: rare
+    description: "A powerful elixir that temporarily increases strength."
+    value: 100
+    is_tradeable: true
+    effects_on_use:
+      - effect_id: str_buff
+        name: "Strength Boost"
+        effect_type: buff
+        power: 5
+        duration: 5
+        stacks: 1
+
+  elixir_of_agility:
+    name: "Elixir of Agility"
+    item_type: consumable
+    rarity: rare
+    description: "A shimmering elixir that enhances reflexes and speed."
+    value: 100
+    is_tradeable: true
+    effects_on_use:
+      - effect_id: dex_buff
+        name: "Agility Boost"
+        effect_type: buff
+        power: 5
+        duration: 5
+        stacks: 1
+
+  # ==========================================================================
+  # Food Items (simple healing, no combat use)
+  # ==========================================================================
+
+  ration:
+    name: "Trail Ration"
+    item_type: consumable
+    rarity: common
+    description: "Dried meat, hardtack, and nuts. Sustains an adventurer on long journeys."
+    value: 5
+    is_tradeable: true
+    effects_on_use:
+      - effect_id: ration_heal
+        name: "Nourishment"
+        effect_type: hot
+        power: 10
+        duration: 1
+        stacks: 1
+
+  cooked_meat:
+    name: "Cooked Meat"
+    item_type: consumable
+    rarity: common
+    description: "Freshly cooked meat that restores health."
+    value: 15
+    is_tradeable: true
+    effects_on_use:
+      - effect_id: meat_heal
+        name: "Hearty Meal"
+        effect_type: hot
+        power: 20
+        duration: 1
+        stacks: 1

api/app/data/static_items/materials.yaml

@@ -0,0 +1,207 @@
+# Trophy items, crafting materials, and quest items dropped by enemies
+# These items don't have combat effects but are used for quests, crafting, or selling
+
+items:
+  # ==========================================================================
+  # Goblin Drops
+  # ==========================================================================
+
+  goblin_ear:
+    name: "Goblin Ear"
+    item_type: quest_item
+    rarity: common
+    description: "A severed goblin ear. Proof of a kill, sometimes collected for bounties."
+    value: 2
+    is_tradeable: true
+
+  goblin_trinket:
+    name: "Goblin Trinket"
+    item_type: quest_item
+    rarity: common
+    description: "A crude piece of jewelry stolen by a goblin. Worth a few coins."
+    value: 8
+    is_tradeable: true
+
+  goblin_war_paint:
+    name: "Goblin War Paint"
+    item_type: quest_item
+    rarity: uncommon
+    description: "Pungent red and black paint used by goblin warriors before battle."
+    value: 15
+    is_tradeable: true
+
+  goblin_chieftain_token:
+    name: "Chieftain's Token"
+    item_type: quest_item
+    rarity: rare
+    description: "A carved bone token marking the authority of a goblin chieftain."
+    value: 50
+    is_tradeable: true
+
+  # ==========================================================================
+  # Wolf/Beast Drops
+  # ==========================================================================
+
+  wolf_pelt:
+    name: "Wolf Pelt"
+    item_type: quest_item
+    rarity: common
+    description: "A fur pelt from a wolf. Useful for crafting or selling to tanners."
+    value: 10
+    is_tradeable: true
+
+  dire_wolf_fang:
+    name: "Dire Wolf Fang"
+    item_type: quest_item
+    rarity: uncommon
+    description: "A large fang from a dire wolf. Prized by craftsmen for weapon making."
+    value: 25
+    is_tradeable: true
+
+  beast_hide:
+    name: "Beast Hide"
+    item_type: quest_item
+    rarity: common
+    description: "Thick hide from a large beast. Can be tanned into leather."
+    value: 12
+    is_tradeable: true
+
+  # ==========================================================================
+  # Undead Drops
+  # ==========================================================================
+
+  skeleton_bone:
+    name: "Skeleton Bone"
+    item_type: quest_item
+    rarity: common
+    description: "A bone from an animated skeleton. Retains faint magical energy."
+    value: 5
+    is_tradeable: true
+
+  bone_dust:
+    name: "Bone Dust"
+    item_type: quest_item
+    rarity: common
+    description: "Powdered bone from undead remains. Used in alchemy and rituals."
+    value: 8
+    is_tradeable: true
+
+  skull_fragment:
+    name: "Skull Fragment"
+    item_type: quest_item
+    rarity: uncommon
+    description: "A piece of an undead skull, still crackling with dark energy."
+    value: 20
+    is_tradeable: true
+
+  # ==========================================================================
+  # Orc Drops
+  # ==========================================================================
+
+  orc_tusk:
+    name: "Orc Tusk"
+    item_type: quest_item
+    rarity: uncommon
+    description: "A large tusk from an orc warrior. A trophy prized by collectors."
+    value: 25
+    is_tradeable: true
+
+  orc_war_banner:
+    name: "Orc War Banner"
+    item_type: quest_item
+    rarity: rare
+    description: "A bloodstained banner torn from an orc warband. Proof of a hard fight."
+    value: 45
+    is_tradeable: true
+
+  berserker_charm:
+    name: "Berserker Charm"
+    item_type: quest_item
+    rarity: rare
+    description: "A crude charm worn by orc berserkers. Said to enhance rage."
+    value: 60
+    is_tradeable: true
+
+  # ==========================================================================
+  # Bandit Drops
+  # ==========================================================================
+
+  bandit_mask:
+    name: "Bandit Mask"
+    item_type: quest_item
+    rarity: common
+    description: "A cloth mask worn by bandits to conceal their identity."
+    value: 8
+    is_tradeable: true
+
+  stolen_coin_pouch:
+    name: "Stolen Coin Pouch"
+    item_type: quest_item
+    rarity: common
+    description: "A small pouch of coins stolen by bandits. Should be returned."
+    value: 15
+    is_tradeable: true
+
+  wanted_poster:
+    name: "Wanted Poster"
+    item_type: quest_item
+    rarity: uncommon
+    description: "A crumpled wanted poster. May lead to bounty opportunities."
+    value: 5
+    is_tradeable: true
+
+  # ==========================================================================
+  # Generic/Currency Items
+  # ==========================================================================
+
+  gold_coin:
+    name: "Gold Coin"
+    item_type: quest_item
+    rarity: common
+    description: "A single gold coin. Standard currency across the realm."
+    value: 1
+    is_tradeable: true
+
+  silver_coin:
+    name: "Silver Coin"
+    item_type: quest_item
+    rarity: common
+    description: "A silver coin worth less than gold but still useful."
+    value: 1
+    is_tradeable: true
+
+  # ==========================================================================
+  # Crafting Materials (Generic)
+  # ==========================================================================
+
+  iron_ore:
+    name: "Iron Ore"
+    item_type: quest_item
+    rarity: common
+    description: "Raw iron ore that can be smelted into ingots."
+    value: 10
+    is_tradeable: true
+
+  leather_scraps:
+    name: "Leather Scraps"
+    item_type: quest_item
+    rarity: common
+    description: "Scraps of leather useful for crafting and repairs."
+    value: 5
+    is_tradeable: true
+
+  cloth_scraps:
+    name: "Cloth Scraps"
+    item_type: quest_item
+    rarity: common
+    description: "Torn cloth that can be sewn into bandages or used for crafting."
+    value: 3
+    is_tradeable: true
+
+  magic_essence:
+    name: "Magic Essence"
+    item_type: quest_item
+    rarity: uncommon
+    description: "Crystallized magical energy. Used in enchanting and alchemy."
+    value: 30
+    is_tradeable: true

api/app/models/__init__.py

@@ -9,6 +9,7 @@ from app.models.enums import (
     EffectType,
     DamageType,
     ItemType,
+    ItemRarity,
     StatType,
     AbilityType,
     CombatStatus,
@@ -53,6 +54,7 @@ __all__ = [
     "EffectType",
     "DamageType",
     "ItemType",
+    "ItemRarity",
     "StatType",
     "AbilityType",
     "CombatStatus",

api/app/models/affixes.py

@@ -0,0 +1,305 @@
+"""
+Item affix system for procedural item generation.
+
+This module defines affixes (prefixes and suffixes) that can be attached to items
+to provide stat bonuses and generate Diablo-style names like "Flaming Dagger of Strength".
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import Dict, Any, List, Optional
+
+from app.models.enums import AffixType, AffixTier, DamageType, ItemRarity
+
+
+@dataclass
+class Affix:
+    """
+    Represents a single item affix (prefix or suffix).
+
+    Affixes provide stat bonuses and contribute to item naming.
+    Prefixes appear before the item name: "Flaming Dagger"
+    Suffixes appear after the item name: "Dagger of Strength"
+
+    Attributes:
+        affix_id: Unique identifier (e.g., "flaming", "of_strength")
+        name: Display name for the affix (e.g., "Flaming", "of Strength")
+        affix_type: PREFIX or SUFFIX
+        tier: MINOR, MAJOR, or LEGENDARY (determines bonus magnitude)
+        description: Human-readable description of the affix effect
+
+        Stat Bonuses:
+        stat_bonuses: Dict mapping stat name to bonus value
+                     Example: {"strength": 2, "constitution": 1}
+        defense_bonus: Direct defense bonus
+        resistance_bonus: Direct resistance bonus
+
+        Weapon Properties (PREFIX only, elemental):
+        damage_bonus: Flat damage bonus added to weapon
+        damage_type: Elemental damage type (fire, ice, etc.)
+        elemental_ratio: Portion of damage converted to elemental (0.0-1.0)
+        crit_chance_bonus: Added to weapon crit chance
+        crit_multiplier_bonus: Added to crit damage multiplier
+
+        Restrictions:
+        allowed_item_types: Empty list = all types allowed
+        required_rarity: Minimum rarity to roll this affix (for legendary-only)
+    """
+
+    affix_id: str
+    name: str
+    affix_type: AffixType
+    tier: AffixTier
+    description: str = ""
+
+    # Stat bonuses (applies to any item)
+    stat_bonuses: Dict[str, int] = field(default_factory=dict)
+    defense_bonus: int = 0
+    resistance_bonus: int = 0
+
+    # Weapon-specific bonuses
+    damage_bonus: int = 0
+    damage_type: Optional[DamageType] = None
+    elemental_ratio: float = 0.0
+    crit_chance_bonus: float = 0.0
+    crit_multiplier_bonus: float = 0.0
+
+    # Restrictions
+    allowed_item_types: List[str] = field(default_factory=list)
+    required_rarity: Optional[str] = None
+
+    def applies_elemental_damage(self) -> bool:
+        """
+        Check if this affix converts damage to elemental.
+
+        Returns:
+            True if affix adds elemental damage component
+        """
+        return self.damage_type is not None and self.elemental_ratio > 0.0
+
+    def is_legendary_only(self) -> bool:
+        """
+        Check if this affix only rolls on legendary items.
+
+        Returns:
+            True if affix requires legendary rarity
+        """
+        return self.required_rarity == "legendary"
+
+    def can_apply_to(self, item_type: str, rarity: str) -> bool:
+        """
+        Check if this affix can be applied to an item.
+
+        Args:
+            item_type: Type of item ("weapon", "armor", etc.)
+            rarity: Item rarity ("common", "rare", "epic", "legendary")
+
+        Returns:
+            True if affix can be applied, False otherwise
+        """
+        # Check rarity requirement
+        if self.required_rarity and rarity != self.required_rarity:
+            return False
+
+        # Check item type restriction
+        if self.allowed_item_types and item_type not in self.allowed_item_types:
+            return False
+
+        return True
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Serialize affix to dictionary.
+
+        Returns:
+            Dictionary containing all affix data
+        """
+        data = asdict(self)
+        data["affix_type"] = self.affix_type.value
+        data["tier"] = self.tier.value
+        if self.damage_type:
+            data["damage_type"] = self.damage_type.value
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'Affix':
+        """
+        Deserialize affix from dictionary.
+
+        Args:
+            data: Dictionary containing affix data
+
+        Returns:
+            Affix instance
+        """
+        affix_type = AffixType(data["affix_type"])
+        tier = AffixTier(data["tier"])
+        damage_type = DamageType(data["damage_type"]) if data.get("damage_type") else None
+
+        return cls(
+            affix_id=data["affix_id"],
+            name=data["name"],
+            affix_type=affix_type,
+            tier=tier,
+            description=data.get("description", ""),
+            stat_bonuses=data.get("stat_bonuses", {}),
+            defense_bonus=data.get("defense_bonus", 0),
+            resistance_bonus=data.get("resistance_bonus", 0),
+            damage_bonus=data.get("damage_bonus", 0),
+            damage_type=damage_type,
+            elemental_ratio=data.get("elemental_ratio", 0.0),
+            crit_chance_bonus=data.get("crit_chance_bonus", 0.0),
+            crit_multiplier_bonus=data.get("crit_multiplier_bonus", 0.0),
+            allowed_item_types=data.get("allowed_item_types", []),
+            required_rarity=data.get("required_rarity"),
+        )
+
+    def __repr__(self) -> str:
+        """String representation of the affix."""
+        bonuses = []
+        if self.stat_bonuses:
+            bonuses.append(f"stats={self.stat_bonuses}")
+        if self.damage_bonus:
+            bonuses.append(f"dmg+{self.damage_bonus}")
+        if self.defense_bonus:
+            bonuses.append(f"def+{self.defense_bonus}")
+        if self.applies_elemental_damage():
+            bonuses.append(f"{self.damage_type.value}={self.elemental_ratio:.0%}")
+
+        bonus_str = ", ".join(bonuses) if bonuses else "no bonuses"
+        return f"Affix({self.name}, {self.affix_type.value}, {self.tier.value}, {bonus_str})"
+
+
+@dataclass
+class BaseItemTemplate:
+    """
+    Template for base items used in procedural generation.
+
+    Base items define the foundation (e.g., "Dagger", "Longsword", "Chainmail")
+    that affixes attach to during item generation.
+
+    Attributes:
+        template_id: Unique identifier (e.g., "dagger", "longsword")
+        name: Display name (e.g., "Dagger", "Longsword")
+        item_type: Category ("weapon", "armor")
+        description: Flavor text for the base item
+
+        Base Stats:
+        base_damage: Base weapon damage (weapons only)
+        base_defense: Base armor defense (armor only)
+        base_resistance: Base magic resistance (armor only)
+        base_value: Base gold value before rarity/affix modifiers
+
+        Weapon Properties:
+        damage_type: Primary damage type (usually "physical")
+        crit_chance: Base critical hit chance
+        crit_multiplier: Base critical damage multiplier
+
+        Generation:
+        required_level: Minimum character level for this template
+        drop_weight: Weighting for random selection (higher = more common)
+        min_rarity: Minimum rarity this template can generate at
+    """
+
+    template_id: str
+    name: str
+    item_type: str  # "weapon" or "armor"
+    description: str = ""
+
+    # Base stats
+    base_damage: int = 0
+    base_spell_power: int = 0  # For magical weapons (staves, wands)
+    base_defense: int = 0
+    base_resistance: int = 0
+    base_value: int = 10
+
+    # Weapon properties
+    damage_type: str = "physical"
+    crit_chance: float = 0.05
+    crit_multiplier: float = 2.0
+
+    # Generation settings
+    required_level: int = 1
+    drop_weight: float = 1.0
+    min_rarity: str = "common"
+
+    def can_generate_at_rarity(self, rarity: str) -> bool:
+        """
+        Check if this template can generate at a given rarity.
+
+        Some templates (like greatswords) may only drop at rare+.
+
+        Args:
+            rarity: Target rarity to check
+
+        Returns:
+            True if template can generate at this rarity
+        """
+        rarity_order = ["common", "uncommon", "rare", "epic", "legendary"]
+        min_index = rarity_order.index(self.min_rarity)
+        target_index = rarity_order.index(rarity)
+        return target_index >= min_index
+
+    def can_drop_for_level(self, character_level: int) -> bool:
+        """
+        Check if this template can drop for a character level.
+
+        Args:
+            character_level: Character's current level
+
+        Returns:
+            True if template can drop for this level
+        """
+        return character_level >= self.required_level
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Serialize template to dictionary.
+
+        Returns:
+            Dictionary containing all template data
+        """
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'BaseItemTemplate':
+        """
+        Deserialize template from dictionary.
+
+        Args:
+            data: Dictionary containing template data
+
+        Returns:
+            BaseItemTemplate instance
+        """
+        return cls(
+            template_id=data["template_id"],
+            name=data["name"],
+            item_type=data["item_type"],
+            description=data.get("description", ""),
+            base_damage=data.get("base_damage", 0),
+            base_spell_power=data.get("base_spell_power", 0),
+            base_defense=data.get("base_defense", 0),
+            base_resistance=data.get("base_resistance", 0),
+            base_value=data.get("base_value", 10),
+            damage_type=data.get("damage_type", "physical"),
+            crit_chance=data.get("crit_chance", 0.05),
+            crit_multiplier=data.get("crit_multiplier", 2.0),
+            required_level=data.get("required_level", 1),
+            drop_weight=data.get("drop_weight", 1.0),
+            min_rarity=data.get("min_rarity", "common"),
+        )
+
+    def __repr__(self) -> str:
+        """String representation of the template."""
+        if self.item_type == "weapon":
+            return (
+                f"BaseItemTemplate({self.name}, weapon, dmg={self.base_damage}, "
+                f"crit={self.crit_chance*100:.0f}%, lvl={self.required_level})"
+            )
+        elif self.item_type == "armor":
+            return (
+                f"BaseItemTemplate({self.name}, armor, def={self.base_defense}, "
+                f"res={self.base_resistance}, lvl={self.required_level})"
+            )
+        else:
+            return f"BaseItemTemplate({self.name}, {self.item_type})"

api/app/models/character.py

@@ -13,7 +13,7 @@ from app.models.stats import Stats
 from app.models.items import Item
 from app.models.skills import PlayerClass, SkillNode
 from app.models.effects import Effect
-from app.models.enums import EffectType, StatType
+from app.models.enums import EffectType, StatType, ItemType
 from app.models.origins import Origin
 
 
@@ -70,8 +70,20 @@ class Character:
     current_location: Optional[str] = None  # Set to origin starting location on creation
 
     # NPC interaction tracking (persists across sessions)
-    # Each entry: {npc_id: {interaction_count, relationship_level, dialogue_history, ...}}
-    # dialogue_history: List[{player_line: str, npc_response: str}]
+    # Each entry: {
+    #     npc_id: str,
+    #     first_met: str (ISO timestamp),
+    #     last_interaction: str (ISO timestamp),
+    #     interaction_count: int,
+    #     revealed_secrets: List[int],
+    #     relationship_level: int (0-100, 50=neutral),
+    #     custom_flags: Dict[str, Any],
+    #     recent_messages: List[Dict] (last 3 messages for AI context),
+    #         format: [{player_message: str, npc_response: str, timestamp: str}, ...],
+    #     total_messages: int (total conversation message count),
+    #     dialogue_history: List[Dict] (DEPRECATED, use ChatMessageService for full history)
+    # }
+    # Full conversation history stored in chat_messages collection (unlimited)
     npc_interactions: Dict[str, Dict] = field(default_factory=dict)
 
     def get_effective_stats(self, active_effects: Optional[List[Effect]] = None) -> Stats:
@@ -80,7 +92,11 @@ class Character:
 
         This is the CRITICAL METHOD that combines:
         1. Base stats (from character)
-        2. Equipment bonuses (from equipped items)
+        2. Equipment bonuses (from equipped items):
+           - stat_bonuses dict applied to corresponding stats
+           - Weapon damage added to damage_bonus
+           - Weapon spell_power added to spell_power_bonus
+           - Armor defense/resistance added to defense_bonus/resistance_bonus
         3. Skill tree bonuses (from unlocked skills)
         4. Active effect modifiers (buffs/debuffs)
 
@@ -88,18 +104,30 @@ class Character:
             active_effects: Currently active effects on this character (from combat)
 
         Returns:
-            Stats instance with all modifiers applied
+            Stats instance with all modifiers applied (including computed
+            damage, defense, resistance properties that incorporate bonuses)
         """
         # Start with a copy of base stats
         effective = self.base_stats.copy()
 
         # Apply equipment bonuses
         for item in self.equipped.values():
+            # Apply stat bonuses from item (e.g., +3 strength)
             for stat_name, bonus in item.stat_bonuses.items():
                 if hasattr(effective, stat_name):
                     current_value = getattr(effective, stat_name)
                     setattr(effective, stat_name, current_value + bonus)
 
+            # Add weapon damage and spell_power to bonus fields
+            if item.item_type == ItemType.WEAPON:
+                effective.damage_bonus += item.damage
+                effective.spell_power_bonus += item.spell_power
+
+            # Add armor defense and resistance to bonus fields
+            if item.item_type == ItemType.ARMOR:
+                effective.defense_bonus += item.defense
+                effective.resistance_bonus += item.resistance
+
         # Apply skill tree bonuses
         skill_bonuses = self._get_skill_bonuses()
         for stat_name, bonus in skill_bonuses.items():

api/app/models/chat_message.py

@@ -0,0 +1,172 @@
+"""
+Chat Message Data Models.
+
+This module defines the data structures for player-NPC chat messages,
+stored in the Appwrite chat_messages collection for unlimited conversation history.
+"""
+
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from enum import Enum
+from typing import Dict, Any, Optional
+import uuid
+
+
+class MessageContext(Enum):
+    """
+    Context type for chat messages.
+
+    Indicates the type of interaction that generated this message,
+    useful for filtering and quest/faction tracking.
+    """
+    DIALOGUE = "dialogue"  # General conversation
+    QUEST_OFFERED = "quest_offered"  # Quest offering dialogue
+    QUEST_COMPLETED = "quest_completed"  # Quest completion dialogue
+    SHOP = "shop"  # Merchant transaction
+    LOCATION_REVEALED = "location_revealed"  # New location discovered through chat
+    LORE = "lore"  # Lore/backstory reveals
+
+
+@dataclass
+class ChatMessage:
+    """
+    Represents a single message exchange between a player and an NPC.
+
+    This is the core data model for the chat log system. Each message
+    represents a complete exchange: what the player said and how the NPC responded.
+
+    Stored in: Appwrite chat_messages collection
+    Indexed by: character_id, npc_id, timestamp, session_id, context
+
+    Attributes:
+        message_id: Unique identifier (UUID)
+        character_id: Player's character ID
+        npc_id: NPC identifier
+        player_message: What the player said to the NPC
+        npc_response: NPC's reply
+        timestamp: When the message was created (ISO 8601)
+        session_id: Game session reference (optional, for session-based queries)
+        location_id: Where conversation happened (optional)
+        context: Type of interaction (dialogue, quest, shop, etc.)
+        metadata: Extensible JSON field for quest_id, faction_id, item_id, etc.
+        is_deleted: Soft delete flag (for privacy/moderation)
+    """
+    message_id: str
+    character_id: str
+    npc_id: str
+    player_message: str
+    npc_response: str
+    timestamp: str  # ISO 8601 format
+    context: MessageContext
+    session_id: Optional[str] = None
+    location_id: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    is_deleted: bool = False
+
+    @staticmethod
+    def create(
+        character_id: str,
+        npc_id: str,
+        player_message: str,
+        npc_response: str,
+        context: MessageContext = MessageContext.DIALOGUE,
+        session_id: Optional[str] = None,
+        location_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> "ChatMessage":
+        """
+        Factory method to create a new ChatMessage with auto-generated ID and timestamp.
+
+        Args:
+            character_id: Player's character ID
+            npc_id: NPC identifier
+            player_message: What the player said
+            npc_response: NPC's reply
+            context: Type of interaction (default: DIALOGUE)
+            session_id: Optional game session reference
+            location_id: Optional location where conversation happened
+            metadata: Optional extensible metadata (quest_id, faction_id, etc.)
+
+        Returns:
+            New ChatMessage instance with generated ID and current timestamp
+        """
+        return ChatMessage(
+            message_id=str(uuid.uuid4()),
+            character_id=character_id,
+            npc_id=npc_id,
+            player_message=player_message,
+            npc_response=npc_response,
+            timestamp=datetime.utcnow().isoformat() + "Z",
+            context=context,
+            session_id=session_id,
+            location_id=location_id,
+            metadata=metadata or {},
+            is_deleted=False
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert ChatMessage to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary representation with MessageContext converted to string
+        """
+        data = asdict(self)
+        data["context"] = self.context.value  # Convert enum to string
+        return data
+
+    @staticmethod
+    def from_dict(data: Dict[str, Any]) -> "ChatMessage":
+        """
+        Create ChatMessage from dictionary (Appwrite document).
+
+        Args:
+            data: Dictionary from Appwrite document
+
+        Returns:
+            ChatMessage instance
+        """
+        # Convert context string to enum
+        if isinstance(data.get("context"), str):
+            data["context"] = MessageContext(data["context"])
+
+        return ChatMessage(**data)
+
+    def to_preview(self) -> Dict[str, str]:
+        """
+        Convert to lightweight preview format for character.npc_interactions.recent_messages.
+
+        Returns:
+            Dictionary with only player_message, npc_response, timestamp
+        """
+        return {
+            "player_message": self.player_message,
+            "npc_response": self.npc_response,
+            "timestamp": self.timestamp
+        }
+
+
+@dataclass
+class ConversationSummary:
+    """
+    Summary of all messages with a specific NPC.
+
+    Used for the "conversations list" UI to show all NPCs
+    the character has talked to.
+
+    Attributes:
+        npc_id: NPC identifier
+        npc_name: NPC display name (fetched from NPC data)
+        last_message_timestamp: When the last message was sent
+        message_count: Total number of messages exchanged
+        recent_preview: Short preview of most recent NPC response
+    """
+    npc_id: str
+    npc_name: str
+    last_message_timestamp: str
+    message_count: int
+    recent_preview: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return asdict(self)

api/app/models/combat.py

@@ -12,7 +12,7 @@ import random
 from app.models.stats import Stats
 from app.models.effects import Effect
 from app.models.abilities import Ability
-from app.models.enums import CombatStatus, EffectType
+from app.models.enums import CombatStatus, EffectType, DamageType
 
 
 @dataclass
@@ -36,6 +36,12 @@ class Combatant:
         abilities: Available abilities for this combatant
         cooldowns: Map of ability_id to turns remaining
         initiative: Turn order value (rolled at combat start)
+        weapon_crit_chance: Critical hit chance from equipped weapon
+        weapon_crit_multiplier: Critical hit damage multiplier
+        weapon_damage_type: Primary damage type of weapon
+        elemental_damage_type: Secondary damage type for elemental weapons
+        physical_ratio: Portion of damage that is physical (0.0-1.0)
+        elemental_ratio: Portion of damage that is elemental (0.0-1.0)
     """
 
     combatant_id: str
@@ -51,6 +57,16 @@ class Combatant:
     cooldowns: Dict[str, int] = field(default_factory=dict)
     initiative: int = 0
 
+    # Weapon properties (for combat calculations)
+    weapon_crit_chance: float = 0.05
+    weapon_crit_multiplier: float = 2.0
+    weapon_damage_type: Optional[DamageType] = None
+
+    # Elemental weapon properties (for split damage)
+    elemental_damage_type: Optional[DamageType] = None
+    physical_ratio: float = 1.0
+    elemental_ratio: float = 0.0
+
     def is_alive(self) -> bool:
         """Check if combatant is still alive."""
         return self.current_hp > 0
@@ -228,6 +244,12 @@ class Combatant:
             "abilities": self.abilities,
             "cooldowns": self.cooldowns,
             "initiative": self.initiative,
+            "weapon_crit_chance": self.weapon_crit_chance,
+            "weapon_crit_multiplier": self.weapon_crit_multiplier,
+            "weapon_damage_type": self.weapon_damage_type.value if self.weapon_damage_type else None,
+            "elemental_damage_type": self.elemental_damage_type.value if self.elemental_damage_type else None,
+            "physical_ratio": self.physical_ratio,
+            "elemental_ratio": self.elemental_ratio,
         }
 
     @classmethod
@@ -236,6 +258,15 @@ class Combatant:
         stats = Stats.from_dict(data["stats"])
         active_effects = [Effect.from_dict(e) for e in data.get("active_effects", [])]
 
+        # Parse damage types
+        weapon_damage_type = None
+        if data.get("weapon_damage_type"):
+            weapon_damage_type = DamageType(data["weapon_damage_type"])
+
+        elemental_damage_type = None
+        if data.get("elemental_damage_type"):
+            elemental_damage_type = DamageType(data["elemental_damage_type"])
+
         return cls(
             combatant_id=data["combatant_id"],
             name=data["name"],
@@ -249,6 +280,12 @@ class Combatant:
             abilities=data.get("abilities", []),
             cooldowns=data.get("cooldowns", {}),
             initiative=data.get("initiative", 0),
+            weapon_crit_chance=data.get("weapon_crit_chance", 0.05),
+            weapon_crit_multiplier=data.get("weapon_crit_multiplier", 2.0),
+            weapon_damage_type=weapon_damage_type,
+            elemental_damage_type=elemental_damage_type,
+            physical_ratio=data.get("physical_ratio", 1.0),
+            elemental_ratio=data.get("elemental_ratio", 0.0),
         )
 
 

api/app/models/enemy.py

@@ -0,0 +1,274 @@
+"""
+Enemy data models for combat encounters.
+
+This module defines the EnemyTemplate dataclass representing enemies/monsters
+that can be encountered in combat. Enemy definitions are loaded from YAML files
+for data-driven game design.
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import Dict, Any, List, Optional, Tuple
+from enum import Enum
+
+from app.models.stats import Stats
+
+
+class EnemyDifficulty(Enum):
+    """Enemy difficulty levels for scaling and encounter building."""
+    EASY = "easy"
+    MEDIUM = "medium"
+    HARD = "hard"
+    BOSS = "boss"
+
+
+class LootType(Enum):
+    """
+    Types of loot drops in enemy loot tables.
+
+    STATIC: Fixed item_id reference (consumables, quest items, materials)
+    PROCEDURAL: Procedurally generated equipment (weapons, armor with affixes)
+    """
+    STATIC = "static"
+    PROCEDURAL = "procedural"
+
+
+@dataclass
+class LootEntry:
+    """
+    Single entry in an enemy's loot table.
+
+    Supports two types of loot:
+
+    STATIC loot (default):
+        - item_id references a predefined item (health_potion, gold_coin, etc.)
+        - quantity_min/max define stack size
+
+    PROCEDURAL loot:
+        - item_type specifies "weapon" or "armor"
+        - rarity_bonus adds to rarity roll (difficulty contribution)
+        - Generated equipment uses the ItemGenerator system
+
+    Attributes:
+        loot_type: Type of loot (static or procedural)
+        drop_chance: Probability of dropping (0.0 to 1.0)
+        quantity_min: Minimum quantity if dropped
+        quantity_max: Maximum quantity if dropped
+        item_id: Reference to item definition (for STATIC loot)
+        item_type: Type of equipment to generate (for PROCEDURAL loot)
+        rarity_bonus: Added to rarity roll (0.0 to 0.5, for PROCEDURAL)
+    """
+
+    # Common fields
+    loot_type: LootType = LootType.STATIC
+    drop_chance: float = 0.1
+    quantity_min: int = 1
+    quantity_max: int = 1
+
+    # Static loot fields
+    item_id: Optional[str] = None
+
+    # Procedural loot fields
+    item_type: Optional[str] = None  # "weapon" or "armor"
+    rarity_bonus: float = 0.0  # Added to rarity roll (0.0 to 0.5)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize loot entry to dictionary."""
+        data = {
+            "loot_type": self.loot_type.value,
+            "drop_chance": self.drop_chance,
+            "quantity_min": self.quantity_min,
+            "quantity_max": self.quantity_max,
+        }
+        # Only include relevant fields based on loot type
+        if self.item_id is not None:
+            data["item_id"] = self.item_id
+        if self.item_type is not None:
+            data["item_type"] = self.item_type
+            data["rarity_bonus"] = self.rarity_bonus
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'LootEntry':
+        """
+        Deserialize loot entry from dictionary.
+
+        Backward compatible: entries without loot_type default to STATIC,
+        and item_id is required for STATIC entries (for backward compat).
+        """
+        # Parse loot type with backward compatibility
+        loot_type_str = data.get("loot_type", "static")
+        loot_type = LootType(loot_type_str)
+
+        return cls(
+            loot_type=loot_type,
+            drop_chance=data.get("drop_chance", 0.1),
+            quantity_min=data.get("quantity_min", 1),
+            quantity_max=data.get("quantity_max", 1),
+            item_id=data.get("item_id"),
+            item_type=data.get("item_type"),
+            rarity_bonus=data.get("rarity_bonus", 0.0),
+        )
+
+
+@dataclass
+class EnemyTemplate:
+    """
+    Template definition for an enemy type.
+
+    EnemyTemplates define the base characteristics of enemy types. When combat
+    starts, instances are created from templates with randomized variations.
+
+    Attributes:
+        enemy_id: Unique identifier (e.g., "goblin", "dire_wolf")
+        name: Display name (e.g., "Goblin Scout")
+        description: Flavor text about the enemy
+        base_stats: Base stat block for this enemy
+        abilities: List of ability_ids this enemy can use
+        loot_table: Potential drops on defeat
+        experience_reward: Base XP granted on defeat
+        gold_reward_min: Minimum gold dropped
+        gold_reward_max: Maximum gold dropped
+        difficulty: Difficulty classification for encounter building
+        tags: Classification tags (e.g., ["humanoid", "goblinoid"])
+        image_url: Optional image reference for UI
+
+    Combat-specific attributes:
+        base_damage: Base damage for basic attack (no weapon)
+        crit_chance: Critical hit chance (0.0 to 1.0)
+        flee_chance: Chance to successfully flee from this enemy
+    """
+
+    enemy_id: str
+    name: str
+    description: str
+    base_stats: Stats
+    abilities: List[str] = field(default_factory=list)
+    loot_table: List[LootEntry] = field(default_factory=list)
+    experience_reward: int = 10
+    gold_reward_min: int = 1
+    gold_reward_max: int = 5
+    difficulty: EnemyDifficulty = EnemyDifficulty.EASY
+    tags: List[str] = field(default_factory=list)
+    image_url: Optional[str] = None
+
+    # Combat attributes
+    base_damage: int = 5
+    crit_chance: float = 0.05
+    flee_chance: float = 0.5
+
+    def get_gold_reward(self) -> int:
+        """
+        Roll random gold reward within range.
+
+        Returns:
+            Random gold amount between min and max
+        """
+        import random
+        return random.randint(self.gold_reward_min, self.gold_reward_max)
+
+    def roll_loot(self) -> List[Dict[str, Any]]:
+        """
+        Roll for loot drops based on loot table.
+
+        Returns:
+            List of dropped items with quantities
+        """
+        import random
+        drops = []
+
+        for entry in self.loot_table:
+            if random.random() < entry.drop_chance:
+                quantity = random.randint(entry.quantity_min, entry.quantity_max)
+                drops.append({
+                    "item_id": entry.item_id,
+                    "quantity": quantity,
+                })
+
+        return drops
+
+    def is_boss(self) -> bool:
+        """Check if this enemy is a boss."""
+        return self.difficulty == EnemyDifficulty.BOSS
+
+    def has_tag(self, tag: str) -> bool:
+        """Check if enemy has a specific tag."""
+        return tag.lower() in [t.lower() for t in self.tags]
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Serialize enemy template to dictionary.
+
+        Returns:
+            Dictionary containing all enemy data
+        """
+        return {
+            "enemy_id": self.enemy_id,
+            "name": self.name,
+            "description": self.description,
+            "base_stats": self.base_stats.to_dict(),
+            "abilities": self.abilities,
+            "loot_table": [entry.to_dict() for entry in self.loot_table],
+            "experience_reward": self.experience_reward,
+            "gold_reward_min": self.gold_reward_min,
+            "gold_reward_max": self.gold_reward_max,
+            "difficulty": self.difficulty.value,
+            "tags": self.tags,
+            "image_url": self.image_url,
+            "base_damage": self.base_damage,
+            "crit_chance": self.crit_chance,
+            "flee_chance": self.flee_chance,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'EnemyTemplate':
+        """
+        Deserialize enemy template from dictionary.
+
+        Args:
+            data: Dictionary containing enemy data (from YAML or JSON)
+
+        Returns:
+            EnemyTemplate instance
+        """
+        # Parse base stats
+        stats_data = data.get("base_stats", {})
+        base_stats = Stats.from_dict(stats_data)
+
+        # Parse loot table
+        loot_table = [
+            LootEntry.from_dict(entry)
+            for entry in data.get("loot_table", [])
+        ]
+
+        # Parse difficulty
+        difficulty_value = data.get("difficulty", "easy")
+        if isinstance(difficulty_value, str):
+            difficulty = EnemyDifficulty(difficulty_value)
+        else:
+            difficulty = difficulty_value
+
+        return cls(
+            enemy_id=data["enemy_id"],
+            name=data["name"],
+            description=data.get("description", ""),
+            base_stats=base_stats,
+            abilities=data.get("abilities", []),
+            loot_table=loot_table,
+            experience_reward=data.get("experience_reward", 10),
+            gold_reward_min=data.get("gold_reward_min", 1),
+            gold_reward_max=data.get("gold_reward_max", 5),
+            difficulty=difficulty,
+            tags=data.get("tags", []),
+            image_url=data.get("image_url"),
+            base_damage=data.get("base_damage", 5),
+            crit_chance=data.get("crit_chance", 0.05),
+            flee_chance=data.get("flee_chance", 0.5),
+        )
+
+    def __repr__(self) -> str:
+        """String representation of the enemy template."""
+        return (
+            f"EnemyTemplate({self.enemy_id}, {self.name}, "
+            f"difficulty={self.difficulty.value}, "
+            f"xp={self.experience_reward})"
+        )

api/app/models/enums.py

@@ -29,6 +29,7 @@ class DamageType(Enum):
     HOLY = "holy"           # Holy/divine damage
     SHADOW = "shadow"       # Dark/shadow magic damage
     POISON = "poison"       # Poison damage (usually DoT)
+    ARCANE = "arcane"       # Pure magical damage (staves, wands)
 
 
 class ItemType(Enum):
@@ -40,6 +41,31 @@ class ItemType(Enum):
     QUEST_ITEM = "quest_item"   # Story-related, non-tradeable
 
 
+class ItemRarity(Enum):
+    """Item rarity tiers affecting drop rates, value, and visual styling."""
+
+    COMMON = "common"           # White/gray - basic items
+    UNCOMMON = "uncommon"       # Green - slightly better
+    RARE = "rare"               # Blue - noticeably better
+    EPIC = "epic"               # Purple - powerful items
+    LEGENDARY = "legendary"     # Orange/gold - best items
+
+
+class AffixType(Enum):
+    """Types of item affixes for procedural item generation."""
+
+    PREFIX = "prefix"   # Appears before item name: "Flaming Dagger"
+    SUFFIX = "suffix"   # Appears after item name: "Dagger of Strength"
+
+
+class AffixTier(Enum):
+    """Affix power tiers determining bonus magnitudes."""
+
+    MINOR = "minor"           # Weaker bonuses, rolls on RARE items
+    MAJOR = "major"           # Medium bonuses, rolls on EPIC items
+    LEGENDARY = "legendary"   # Strongest bonuses, LEGENDARY only
+
+
 class StatType(Enum):
     """Character attribute types."""
 
@@ -49,6 +75,7 @@ class StatType(Enum):
     INTELLIGENCE = "intelligence"   # Magical power
     WISDOM = "wisdom"               # Perception and insight
     CHARISMA = "charisma"           # Social influence
+    LUCK = "luck"                   # Fortune and fate
 
 
 class AbilityType(Enum):

api/app/models/items.py

@@ -8,7 +8,7 @@ including weapons, armor, consumables, and quest items.
 from dataclasses import dataclass, field, asdict
 from typing import Dict, Any, List, Optional
 
-from app.models.enums import ItemType, DamageType
+from app.models.enums import ItemType, ItemRarity, DamageType
 from app.models.effects import Effect
 
 
@@ -24,6 +24,7 @@ class Item:
         item_id: Unique identifier
         name: Display name
         item_type: Category (weapon, armor, consumable, quest_item)
+        rarity: Rarity tier (common, uncommon, rare, epic, legendary)
         description: Item lore and information
         value: Gold value for buying/selling
         is_tradeable: Whether item can be sold on marketplace
@@ -32,7 +33,8 @@ class Item:
         effects_on_use: Effects applied when consumed (consumables only)
 
         Weapon-specific attributes:
-        damage: Base weapon damage
+        damage: Base weapon damage (physical/melee/ranged)
+        spell_power: Spell power for staves/wands (boosts spell damage)
         damage_type: Type of damage (physical, fire, etc.)
         crit_chance: Probability of critical hit (0.0 to 1.0)
         crit_multiplier: Damage multiplier on critical hit
@@ -49,7 +51,8 @@ class Item:
     item_id: str
     name: str
     item_type: ItemType
-    description: str
+    rarity: ItemRarity = ItemRarity.COMMON
+    description: str = ""
     value: int = 0
     is_tradeable: bool = True
 
@@ -60,11 +63,18 @@ class Item:
     effects_on_use: List[Effect] = field(default_factory=list)
 
     # Weapon-specific
-    damage: int = 0
+    damage: int = 0  # Physical damage for melee/ranged weapons
+    spell_power: int = 0  # Spell power for staves/wands (boosts spell damage)
     damage_type: Optional[DamageType] = None
     crit_chance: float = 0.05  # 5% default critical hit chance
     crit_multiplier: float = 2.0  # 2x damage on critical hit
 
+    # Elemental weapon properties (for split damage like Fire Sword)
+    # These enable weapons to deal both physical AND elemental damage
+    elemental_damage_type: Optional[DamageType] = None  # Secondary damage type (fire, ice, etc.)
+    physical_ratio: float = 1.0  # Portion of damage that is physical (0.0-1.0)
+    elemental_ratio: float = 0.0  # Portion of damage that is elemental (0.0-1.0)
+
     # Armor-specific
     defense: int = 0
     resistance: int = 0
@@ -73,6 +83,24 @@ class Item:
     required_level: int = 1
     required_class: Optional[str] = None
 
+    # Affix tracking (for procedurally generated items)
+    applied_affixes: List[str] = field(default_factory=list)  # List of affix_ids
+    base_template_id: Optional[str] = None  # ID of base item template used
+    generated_name: Optional[str] = None  # Full generated name with affixes
+    is_generated: bool = False  # True if created by item generator
+
+    def get_display_name(self) -> str:
+        """
+        Get the item's display name.
+
+        For generated items, returns the affix-enhanced name.
+        For static items, returns the base name.
+
+        Returns:
+            Display name string
+        """
+        return self.generated_name or self.name
+
     def is_weapon(self) -> bool:
         """Check if this item is a weapon."""
         return self.item_type == ItemType.WEAPON
@@ -89,6 +117,39 @@ class Item:
         """Check if this item is a quest item."""
         return self.item_type == ItemType.QUEST_ITEM
 
+    def is_elemental_weapon(self) -> bool:
+        """
+        Check if this weapon deals elemental damage (split damage).
+
+        Elemental weapons deal both physical AND elemental damage,
+        calculated separately against DEF and RES.
+
+        Examples:
+            Fire Sword: 70% physical / 30% fire
+            Frost Blade: 60% physical / 40% ice
+            Lightning Spear: 50% physical / 50% lightning
+
+        Returns:
+            True if weapon has elemental damage component
+        """
+        return (
+            self.is_weapon() and
+            self.elemental_ratio > 0.0 and
+            self.elemental_damage_type is not None
+        )
+
+    def is_magical_weapon(self) -> bool:
+        """
+        Check if this weapon is a spell-casting weapon (staff, wand, tome).
+
+        Magical weapons provide spell_power which boosts spell damage,
+        rather than physical damage for melee/ranged attacks.
+
+        Returns:
+            True if weapon has spell_power (staves, wands, etc.)
+        """
+        return self.is_weapon() and self.spell_power > 0
+
     def can_equip(self, character_level: int, character_class: Optional[str] = None) -> bool:
         """
         Check if a character can equip this item.
@@ -131,9 +192,14 @@ class Item:
         """
         data = asdict(self)
         data["item_type"] = self.item_type.value
+        data["rarity"] = self.rarity.value
         if self.damage_type:
             data["damage_type"] = self.damage_type.value
+        if self.elemental_damage_type:
+            data["elemental_damage_type"] = self.elemental_damage_type.value
         data["effects_on_use"] = [effect.to_dict() for effect in self.effects_on_use]
+        # Include display_name for convenience
+        data["display_name"] = self.get_display_name()
         return data
 
     @classmethod
@@ -149,7 +215,13 @@ class Item:
         """
         # Convert string values back to enums
         item_type = ItemType(data["item_type"])
+        rarity = ItemRarity(data.get("rarity", "common"))
         damage_type = DamageType(data["damage_type"]) if data.get("damage_type") else None
+        elemental_damage_type = (
+            DamageType(data["elemental_damage_type"])
+            if data.get("elemental_damage_type")
+            else None
+        )
 
         # Deserialize effects
         effects = []
@@ -160,7 +232,8 @@ class Item:
             item_id=data["item_id"],
             name=data["name"],
             item_type=item_type,
-            description=data["description"],
+            rarity=rarity,
+            description=data.get("description", ""),
             value=data.get("value", 0),
             is_tradeable=data.get("is_tradeable", True),
             stat_bonuses=data.get("stat_bonuses", {}),
@@ -169,15 +242,29 @@ class Item:
             damage_type=damage_type,
             crit_chance=data.get("crit_chance", 0.05),
             crit_multiplier=data.get("crit_multiplier", 2.0),
+            elemental_damage_type=elemental_damage_type,
+            physical_ratio=data.get("physical_ratio", 1.0),
+            elemental_ratio=data.get("elemental_ratio", 0.0),
             defense=data.get("defense", 0),
             resistance=data.get("resistance", 0),
             required_level=data.get("required_level", 1),
             required_class=data.get("required_class"),
+            # Affix tracking fields
+            applied_affixes=data.get("applied_affixes", []),
+            base_template_id=data.get("base_template_id"),
+            generated_name=data.get("generated_name"),
+            is_generated=data.get("is_generated", False),
         )
 
     def __repr__(self) -> str:
         """String representation of the item."""
         if self.is_weapon():
+            if self.is_elemental_weapon():
+                return (
+                    f"Item({self.name}, elemental_weapon, dmg={self.damage}, "
+                    f"phys={self.physical_ratio:.0%}/{self.elemental_damage_type.value}={self.elemental_ratio:.0%}, "
+                    f"crit={self.crit_chance*100:.0f}%, value={self.value}g)"
+                )
             return (
                 f"Item({self.name}, weapon, dmg={self.damage}, "
                 f"crit={self.crit_chance*100:.0f}%, value={self.value}g)"

api/app/models/npc.py

@@ -296,6 +296,7 @@ class NPC:
     location_id: str
     personality: NPCPersonality
     appearance: NPCAppearance
+    image_url: Optional[str] = None
     knowledge: Optional[NPCKnowledge] = None
     relationships: List[NPCRelationship] = field(default_factory=list)
     inventory_for_sale: List[NPCInventoryItem] = field(default_factory=list)
@@ -316,6 +317,7 @@ class NPC:
             "name": self.name,
             "role": self.role,
             "location_id": self.location_id,
+            "image_url": self.image_url,
             "personality": self.personality.to_dict(),
             "appearance": self.appearance.to_dict(),
             "knowledge": self.knowledge.to_dict() if self.knowledge else None,
@@ -400,6 +402,7 @@ class NPC:
             name=data["name"],
             role=data["role"],
             location_id=data["location_id"],
+            image_url=data.get("image_url"),
             personality=personality,
             appearance=appearance,
             knowledge=knowledge,

api/app/models/stats.py

@@ -21,12 +21,19 @@ class Stats:
         intelligence: Magical power, affects spell damage and MP
         wisdom: Perception and insight, affects magical resistance
         charisma: Social influence, affects NPC interactions
+        luck: Fortune and fate, affects critical hits, loot, and random outcomes
+        damage_bonus: Flat damage bonus from equipped weapons (default 0)
+        spell_power_bonus: Flat spell power bonus from staves/wands (default 0)
+        defense_bonus: Flat defense bonus from equipped armor (default 0)
+        resistance_bonus: Flat resistance bonus from equipped armor (default 0)
 
     Computed Properties:
         hit_points: Maximum HP = 10 + (constitution × 2)
         mana_points: Maximum MP = 10 + (intelligence × 2)
-        defense: Physical defense = constitution // 2
-        resistance: Magical resistance = wisdom // 2
+        damage: Physical damage = int(strength × 0.75) + damage_bonus
+        spell_power: Spell power = int(intelligence × 0.75) + spell_power_bonus
+        defense: Physical defense = (constitution // 2) + defense_bonus
+        resistance: Magical resistance = (wisdom // 2) + resistance_bonus
     """
 
     strength: int = 10
@@ -35,6 +42,13 @@ class Stats:
     intelligence: int = 10
     wisdom: int = 10
     charisma: int = 10
+    luck: int = 8
+
+    # Equipment bonus fields (populated by get_effective_stats())
+    damage_bonus: int = 0         # From weapons (physical damage)
+    spell_power_bonus: int = 0    # From staves/wands (magical damage)
+    defense_bonus: int = 0        # From armor
+    resistance_bonus: int = 0     # From armor
 
     @property
     def hit_points(self) -> int:
@@ -60,29 +74,122 @@ class Stats:
         """
         return 10 + (self.intelligence * 2)
 
+    @property
+    def damage(self) -> int:
+        """
+        Calculate total physical damage from strength and equipment.
+
+        Formula: int(strength * 0.75) + damage_bonus
+
+        The damage_bonus comes from equipped weapons and is populated
+        by Character.get_effective_stats().
+
+        Returns:
+            Total physical damage value
+        """
+        return int(self.strength * 0.75) + self.damage_bonus
+
+    @property
+    def spell_power(self) -> int:
+        """
+        Calculate spell power from intelligence and equipment.
+
+        Formula: int(intelligence * 0.75) + spell_power_bonus
+
+        The spell_power_bonus comes from equipped staves/wands and is
+        populated by Character.get_effective_stats().
+
+        Returns:
+            Total spell power value
+        """
+        return int(self.intelligence * 0.75) + self.spell_power_bonus
+
     @property
     def defense(self) -> int:
         """
-        Calculate physical defense from constitution.
+        Calculate physical defense from constitution and equipment.
 
-        Formula: constitution // 2
+        Formula: (constitution // 2) + defense_bonus
+
+        The defense_bonus comes from equipped armor and is populated
+        by Character.get_effective_stats().
 
         Returns:
             Physical defense value (damage reduction)
         """
-        return self.constitution // 2
+        return (self.constitution // 2) + self.defense_bonus
 
     @property
     def resistance(self) -> int:
         """
-        Calculate magical resistance from wisdom.
+        Calculate magical resistance from wisdom and equipment.
 
-        Formula: wisdom // 2
+        Formula: (wisdom // 2) + resistance_bonus
+
+        The resistance_bonus comes from equipped armor and is populated
+        by Character.get_effective_stats().
 
         Returns:
             Magical resistance value (spell damage reduction)
         """
-        return self.wisdom // 2
+        return (self.wisdom // 2) + self.resistance_bonus
+
+    @property
+    def crit_bonus(self) -> float:
+        """
+        Calculate critical hit chance bonus from luck.
+
+        Formula: luck * 0.5% (0.005)
+
+        This bonus is added to the weapon's base crit chance.
+        The total crit chance is capped at 25% in the DamageCalculator.
+
+        Returns:
+            Crit chance bonus as a decimal (e.g., 0.04 for LUK 8)
+
+        Examples:
+            LUK 8: 0.04 (4% bonus)
+            LUK 12: 0.06 (6% bonus)
+        """
+        return self.luck * 0.005
+
+    @property
+    def hit_bonus(self) -> float:
+        """
+        Calculate hit chance bonus (miss reduction) from luck.
+
+        Formula: luck * 0.5% (0.005)
+
+        This reduces the base 10% miss chance. The minimum miss
+        chance is hard capped at 5% to prevent frustration.
+
+        Returns:
+            Miss reduction as a decimal (e.g., 0.04 for LUK 8)
+
+        Examples:
+            LUK 8: 0.04 (reduces miss from 10% to 6%)
+            LUK 12: 0.06 (reduces miss from 10% to 4%, capped at 5%)
+        """
+        return self.luck * 0.005
+
+    @property
+    def lucky_roll_chance(self) -> float:
+        """
+        Calculate chance for a "lucky" high damage variance roll.
+
+        Formula: 5% + (luck * 0.25%)
+
+        When triggered, damage variance uses 100%-110% instead of 95%-105%.
+        This gives LUK characters more frequent high damage rolls.
+
+        Returns:
+            Lucky roll chance as a decimal
+
+        Examples:
+            LUK 8: 0.07 (7% chance for lucky roll)
+            LUK 12: 0.08 (8% chance for lucky roll)
+        """
+        return 0.05 + (self.luck * 0.0025)
 
     def to_dict(self) -> Dict[str, Any]:
         """
@@ -111,6 +218,11 @@ class Stats:
             intelligence=data.get("intelligence", 10),
             wisdom=data.get("wisdom", 10),
             charisma=data.get("charisma", 10),
+            luck=data.get("luck", 8),
+            damage_bonus=data.get("damage_bonus", 0),
+            spell_power_bonus=data.get("spell_power_bonus", 0),
+            defense_bonus=data.get("defense_bonus", 0),
+            resistance_bonus=data.get("resistance_bonus", 0),
         )
 
     def copy(self) -> 'Stats':
@@ -127,6 +239,11 @@ class Stats:
             intelligence=self.intelligence,
             wisdom=self.wisdom,
             charisma=self.charisma,
+            luck=self.luck,
+            damage_bonus=self.damage_bonus,
+            spell_power_bonus=self.spell_power_bonus,
+            defense_bonus=self.defense_bonus,
+            resistance_bonus=self.resistance_bonus,
         )
 
     def __repr__(self) -> str:
@@ -134,7 +251,9 @@ class Stats:
         return (
             f"Stats(STR={self.strength}, DEX={self.dexterity}, "
             f"CON={self.constitution}, INT={self.intelligence}, "
-            f"WIS={self.wisdom}, CHA={self.charisma}, "
+            f"WIS={self.wisdom}, CHA={self.charisma}, LUK={self.luck}, "
             f"HP={self.hit_points}, MP={self.mana_points}, "
-            f"DEF={self.defense}, RES={self.resistance})"
+            f"DMG={self.damage}, SP={self.spell_power}, "
+            f"DEF={self.defense}, RES={self.resistance}, "
+            f"CRIT_BONUS={self.crit_bonus:.1%}, HIT_BONUS={self.hit_bonus:.1%})"
         )

api/app/services/affix_loader.py

@@ -0,0 +1,315 @@
+"""
+Affix Loader Service - YAML-based affix pool loading.
+
+This service loads prefix and suffix affix definitions from YAML files,
+providing a data-driven approach to item generation.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+import random
+import yaml
+
+from app.models.affixes import Affix
+from app.models.enums import AffixType, AffixTier
+from app.utils.logging import get_logger
+
+logger = get_logger(__file__)
+
+
+class AffixLoader:
+    """
+    Loads and manages item affixes from YAML configuration files.
+
+    This allows game designers to define affixes without touching code.
+    Affixes are organized into prefixes.yaml and suffixes.yaml files.
+    """
+
+    def __init__(self, data_dir: Optional[str] = None):
+        """
+        Initialize the affix loader.
+
+        Args:
+            data_dir: Path to directory containing affix YAML files
+                     Defaults to /app/data/affixes/
+        """
+        if data_dir is None:
+            # Default to app/data/affixes relative to this file
+            current_file = Path(__file__)
+            app_dir = current_file.parent.parent  # Go up to /app
+            data_dir = str(app_dir / "data" / "affixes")
+
+        self.data_dir = Path(data_dir)
+        self._prefix_cache: Dict[str, Affix] = {}
+        self._suffix_cache: Dict[str, Affix] = {}
+        self._loaded = False
+
+        logger.info("AffixLoader initialized", data_dir=str(self.data_dir))
+
+    def _ensure_loaded(self) -> None:
+        """Ensure affixes are loaded before any operation."""
+        if not self._loaded:
+            self.load_all()
+
+    def load_all(self) -> None:
+        """Load all affixes from YAML files."""
+        if not self.data_dir.exists():
+            logger.warning("Affix data directory not found", path=str(self.data_dir))
+            return
+
+        # Load prefixes
+        prefixes_file = self.data_dir / "prefixes.yaml"
+        if prefixes_file.exists():
+            self._load_affixes_from_file(prefixes_file, self._prefix_cache)
+
+        # Load suffixes
+        suffixes_file = self.data_dir / "suffixes.yaml"
+        if suffixes_file.exists():
+            self._load_affixes_from_file(suffixes_file, self._suffix_cache)
+
+        self._loaded = True
+        logger.info(
+            "Affixes loaded",
+            prefix_count=len(self._prefix_cache),
+            suffix_count=len(self._suffix_cache)
+        )
+
+    def _load_affixes_from_file(
+        self,
+        yaml_file: Path,
+        cache: Dict[str, Affix]
+    ) -> None:
+        """
+        Load affixes from a YAML file into the cache.
+
+        Args:
+            yaml_file: Path to the YAML file
+            cache: Cache dictionary to populate
+        """
+        try:
+            with open(yaml_file, 'r') as f:
+                data = yaml.safe_load(f)
+
+            # Get the top-level key (prefixes or suffixes)
+            affix_key = "prefixes" if "prefixes" in data else "suffixes"
+            affixes_data = data.get(affix_key, {})
+
+            for affix_id, affix_data in affixes_data.items():
+                # Ensure affix_id is set
+                affix_data["affix_id"] = affix_id
+
+                # Set defaults for missing optional fields
+                affix_data.setdefault("stat_bonuses", {})
+                affix_data.setdefault("defense_bonus", 0)
+                affix_data.setdefault("resistance_bonus", 0)
+                affix_data.setdefault("damage_bonus", 0)
+                affix_data.setdefault("elemental_ratio", 0.0)
+                affix_data.setdefault("crit_chance_bonus", 0.0)
+                affix_data.setdefault("crit_multiplier_bonus", 0.0)
+                affix_data.setdefault("allowed_item_types", [])
+                affix_data.setdefault("required_rarity", None)
+
+                affix = Affix.from_dict(affix_data)
+                cache[affix.affix_id] = affix
+
+            logger.debug(
+                "Affixes loaded from file",
+                file=str(yaml_file),
+                count=len(affixes_data)
+            )
+
+        except Exception as e:
+            logger.error(
+                "Failed to load affix file",
+                file=str(yaml_file),
+                error=str(e)
+            )
+
+    def get_affix(self, affix_id: str) -> Optional[Affix]:
+        """
+        Get a specific affix by ID.
+
+        Args:
+            affix_id: Unique affix identifier
+
+        Returns:
+            Affix instance or None if not found
+        """
+        self._ensure_loaded()
+
+        if affix_id in self._prefix_cache:
+            return self._prefix_cache[affix_id]
+        if affix_id in self._suffix_cache:
+            return self._suffix_cache[affix_id]
+
+        return None
+
+    def get_eligible_prefixes(
+        self,
+        item_type: str,
+        rarity: str,
+        tier: Optional[AffixTier] = None
+    ) -> List[Affix]:
+        """
+        Get all prefixes eligible for an item.
+
+        Args:
+            item_type: Type of item ("weapon", "armor")
+            rarity: Item rarity ("rare", "epic", "legendary")
+            tier: Optional tier filter
+
+        Returns:
+            List of eligible Affix instances
+        """
+        self._ensure_loaded()
+
+        eligible = []
+        for affix in self._prefix_cache.values():
+            # Check if affix can apply to this item
+            if not affix.can_apply_to(item_type, rarity):
+                continue
+
+            # Apply tier filter if specified
+            if tier and affix.tier != tier:
+                continue
+
+            eligible.append(affix)
+
+        return eligible
+
+    def get_eligible_suffixes(
+        self,
+        item_type: str,
+        rarity: str,
+        tier: Optional[AffixTier] = None
+    ) -> List[Affix]:
+        """
+        Get all suffixes eligible for an item.
+
+        Args:
+            item_type: Type of item ("weapon", "armor")
+            rarity: Item rarity ("rare", "epic", "legendary")
+            tier: Optional tier filter
+
+        Returns:
+            List of eligible Affix instances
+        """
+        self._ensure_loaded()
+
+        eligible = []
+        for affix in self._suffix_cache.values():
+            # Check if affix can apply to this item
+            if not affix.can_apply_to(item_type, rarity):
+                continue
+
+            # Apply tier filter if specified
+            if tier and affix.tier != tier:
+                continue
+
+            eligible.append(affix)
+
+        return eligible
+
+    def get_random_prefix(
+        self,
+        item_type: str,
+        rarity: str,
+        tier: Optional[AffixTier] = None,
+        exclude_ids: Optional[List[str]] = None
+    ) -> Optional[Affix]:
+        """
+        Get a random eligible prefix.
+
+        Args:
+            item_type: Type of item ("weapon", "armor")
+            rarity: Item rarity
+            tier: Optional tier filter
+            exclude_ids: Affix IDs to exclude (for avoiding duplicates)
+
+        Returns:
+            Random eligible Affix or None if none available
+        """
+        eligible = self.get_eligible_prefixes(item_type, rarity, tier)
+
+        # Filter out excluded IDs
+        if exclude_ids:
+            eligible = [a for a in eligible if a.affix_id not in exclude_ids]
+
+        if not eligible:
+            return None
+
+        return random.choice(eligible)
+
+    def get_random_suffix(
+        self,
+        item_type: str,
+        rarity: str,
+        tier: Optional[AffixTier] = None,
+        exclude_ids: Optional[List[str]] = None
+    ) -> Optional[Affix]:
+        """
+        Get a random eligible suffix.
+
+        Args:
+            item_type: Type of item ("weapon", "armor")
+            rarity: Item rarity
+            tier: Optional tier filter
+            exclude_ids: Affix IDs to exclude (for avoiding duplicates)
+
+        Returns:
+            Random eligible Affix or None if none available
+        """
+        eligible = self.get_eligible_suffixes(item_type, rarity, tier)
+
+        # Filter out excluded IDs
+        if exclude_ids:
+            eligible = [a for a in eligible if a.affix_id not in exclude_ids]
+
+        if not eligible:
+            return None
+
+        return random.choice(eligible)
+
+    def get_all_prefixes(self) -> Dict[str, Affix]:
+        """
+        Get all cached prefixes.
+
+        Returns:
+            Dictionary of prefix affixes
+        """
+        self._ensure_loaded()
+        return self._prefix_cache.copy()
+
+    def get_all_suffixes(self) -> Dict[str, Affix]:
+        """
+        Get all cached suffixes.
+
+        Returns:
+            Dictionary of suffix affixes
+        """
+        self._ensure_loaded()
+        return self._suffix_cache.copy()
+
+    def clear_cache(self) -> None:
+        """Clear the affix cache, forcing reload on next access."""
+        self._prefix_cache.clear()
+        self._suffix_cache.clear()
+        self._loaded = False
+        logger.debug("Affix cache cleared")
+
+
+# Global instance for convenience
+_loader_instance: Optional[AffixLoader] = None
+
+
+def get_affix_loader() -> AffixLoader:
+    """
+    Get the global AffixLoader instance.
+
+    Returns:
+        Singleton AffixLoader instance
+    """
+    global _loader_instance
+    if _loader_instance is None:
+        _loader_instance = AffixLoader()
+    return _loader_instance

api/app/services/base_item_loader.py

@@ -0,0 +1,274 @@
+"""
+Base Item Loader Service - YAML-based base item template loading.
+
+This service loads base item templates (weapons, armor) from YAML files,
+providing the foundation for procedural item generation.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+import random
+import yaml
+
+from app.models.affixes import BaseItemTemplate
+from app.utils.logging import get_logger
+
+logger = get_logger(__file__)
+
+# Rarity order for comparison
+RARITY_ORDER = {
+    "common": 0,
+    "uncommon": 1,
+    "rare": 2,
+    "epic": 3,
+    "legendary": 4
+}
+
+
+class BaseItemLoader:
+    """
+    Loads and manages base item templates from YAML configuration files.
+
+    This allows game designers to define base items without touching code.
+    Templates are organized into weapons.yaml and armor.yaml files.
+    """
+
+    def __init__(self, data_dir: Optional[str] = None):
+        """
+        Initialize the base item loader.
+
+        Args:
+            data_dir: Path to directory containing base item YAML files
+                     Defaults to /app/data/base_items/
+        """
+        if data_dir is None:
+            # Default to app/data/base_items relative to this file
+            current_file = Path(__file__)
+            app_dir = current_file.parent.parent  # Go up to /app
+            data_dir = str(app_dir / "data" / "base_items")
+
+        self.data_dir = Path(data_dir)
+        self._weapon_cache: Dict[str, BaseItemTemplate] = {}
+        self._armor_cache: Dict[str, BaseItemTemplate] = {}
+        self._loaded = False
+
+        logger.info("BaseItemLoader initialized", data_dir=str(self.data_dir))
+
+    def _ensure_loaded(self) -> None:
+        """Ensure templates are loaded before any operation."""
+        if not self._loaded:
+            self.load_all()
+
+    def load_all(self) -> None:
+        """Load all base item templates from YAML files."""
+        if not self.data_dir.exists():
+            logger.warning("Base item data directory not found", path=str(self.data_dir))
+            return
+
+        # Load weapons
+        weapons_file = self.data_dir / "weapons.yaml"
+        if weapons_file.exists():
+            self._load_templates_from_file(weapons_file, "weapons", self._weapon_cache)
+
+        # Load armor
+        armor_file = self.data_dir / "armor.yaml"
+        if armor_file.exists():
+            self._load_templates_from_file(armor_file, "armor", self._armor_cache)
+
+        self._loaded = True
+        logger.info(
+            "Base item templates loaded",
+            weapon_count=len(self._weapon_cache),
+            armor_count=len(self._armor_cache)
+        )
+
+    def _load_templates_from_file(
+        self,
+        yaml_file: Path,
+        key: str,
+        cache: Dict[str, BaseItemTemplate]
+    ) -> None:
+        """
+        Load templates from a YAML file into the cache.
+
+        Args:
+            yaml_file: Path to the YAML file
+            key: Top-level key in YAML (e.g., "weapons", "armor")
+            cache: Cache dictionary to populate
+        """
+        try:
+            with open(yaml_file, 'r') as f:
+                data = yaml.safe_load(f)
+
+            templates_data = data.get(key, {})
+
+            for template_id, template_data in templates_data.items():
+                # Ensure template_id is set
+                template_data["template_id"] = template_id
+
+                # Set defaults for missing optional fields
+                template_data.setdefault("description", "")
+                template_data.setdefault("base_damage", 0)
+                template_data.setdefault("base_spell_power", 0)
+                template_data.setdefault("base_defense", 0)
+                template_data.setdefault("base_resistance", 0)
+                template_data.setdefault("base_value", 10)
+                template_data.setdefault("damage_type", "physical")
+                template_data.setdefault("crit_chance", 0.05)
+                template_data.setdefault("crit_multiplier", 2.0)
+                template_data.setdefault("required_level", 1)
+                template_data.setdefault("drop_weight", 1.0)
+                template_data.setdefault("min_rarity", "common")
+
+                template = BaseItemTemplate.from_dict(template_data)
+                cache[template.template_id] = template
+
+            logger.debug(
+                "Templates loaded from file",
+                file=str(yaml_file),
+                count=len(templates_data)
+            )
+
+        except Exception as e:
+            logger.error(
+                "Failed to load base item file",
+                file=str(yaml_file),
+                error=str(e)
+            )
+
+    def get_template(self, template_id: str) -> Optional[BaseItemTemplate]:
+        """
+        Get a specific template by ID.
+
+        Args:
+            template_id: Unique template identifier
+
+        Returns:
+            BaseItemTemplate instance or None if not found
+        """
+        self._ensure_loaded()
+
+        if template_id in self._weapon_cache:
+            return self._weapon_cache[template_id]
+        if template_id in self._armor_cache:
+            return self._armor_cache[template_id]
+
+        return None
+
+    def get_eligible_templates(
+        self,
+        item_type: str,
+        rarity: str,
+        character_level: int = 1
+    ) -> List[BaseItemTemplate]:
+        """
+        Get all templates eligible for generation.
+
+        Args:
+            item_type: Type of item ("weapon", "armor")
+            rarity: Target rarity
+            character_level: Player level for eligibility
+
+        Returns:
+            List of eligible BaseItemTemplate instances
+        """
+        self._ensure_loaded()
+
+        # Select the appropriate cache
+        if item_type == "weapon":
+            cache = self._weapon_cache
+        elif item_type == "armor":
+            cache = self._armor_cache
+        else:
+            logger.warning("Unknown item type", item_type=item_type)
+            return []
+
+        eligible = []
+        for template in cache.values():
+            # Check level requirement
+            if not template.can_drop_for_level(character_level):
+                continue
+
+            # Check rarity requirement
+            if not template.can_generate_at_rarity(rarity):
+                continue
+
+            eligible.append(template)
+
+        return eligible
+
+    def get_random_template(
+        self,
+        item_type: str,
+        rarity: str,
+        character_level: int = 1
+    ) -> Optional[BaseItemTemplate]:
+        """
+        Get a random eligible template, weighted by drop_weight.
+
+        Args:
+            item_type: Type of item ("weapon", "armor")
+            rarity: Target rarity
+            character_level: Player level for eligibility
+
+        Returns:
+            Random eligible BaseItemTemplate or None if none available
+        """
+        eligible = self.get_eligible_templates(item_type, rarity, character_level)
+
+        if not eligible:
+            logger.warning(
+                "No templates match criteria",
+                item_type=item_type,
+                rarity=rarity,
+                level=character_level
+            )
+            return None
+
+        # Weighted random selection based on drop_weight
+        weights = [t.drop_weight for t in eligible]
+        return random.choices(eligible, weights=weights, k=1)[0]
+
+    def get_all_weapons(self) -> Dict[str, BaseItemTemplate]:
+        """
+        Get all cached weapon templates.
+
+        Returns:
+            Dictionary of weapon templates
+        """
+        self._ensure_loaded()
+        return self._weapon_cache.copy()
+
+    def get_all_armor(self) -> Dict[str, BaseItemTemplate]:
+        """
+        Get all cached armor templates.
+
+        Returns:
+            Dictionary of armor templates
+        """
+        self._ensure_loaded()
+        return self._armor_cache.copy()
+
+    def clear_cache(self) -> None:
+        """Clear the template cache, forcing reload on next access."""
+        self._weapon_cache.clear()
+        self._armor_cache.clear()
+        self._loaded = False
+        logger.debug("Base item template cache cleared")
+
+
+# Global instance for convenience
+_loader_instance: Optional[BaseItemLoader] = None
+
+
+def get_base_item_loader() -> BaseItemLoader:
+    """
+    Get the global BaseItemLoader instance.
+
+    Returns:
+        Singleton BaseItemLoader instance
+    """
+    global _loader_instance
+    if _loader_instance is None:
+        _loader_instance = BaseItemLoader()
+    return _loader_instance

api/app/services/character_service.py

@@ -334,7 +334,10 @@ class CharacterService:
 
     def delete_character(self, character_id: str, user_id: str) -> bool:
         """
-        Delete a character (soft delete by marking inactive).
+        Permanently delete a character from the database.
+
+        Also cleans up any game sessions associated with the character
+        to prevent orphaned sessions.
 
         Args:
             character_id: Character ID
@@ -354,11 +357,20 @@ class CharacterService:
             if not character:
                 raise CharacterNotFound(f"Character not found: {character_id}")
 
-            # Soft delete by marking inactive
-            self.db.update_document(
+            # Clean up associated sessions before deleting the character
+            # Local import to avoid circular dependency (session_service imports character_service)
+            from app.services.session_service import get_session_service
+            session_service = get_session_service()
+            deleted_sessions = session_service.delete_sessions_by_character(character_id)
+            if deleted_sessions > 0:
+                logger.info("Cleaned up sessions for deleted character",
+                           character_id=character_id,
+                           sessions_deleted=deleted_sessions)
+
+            # Hard delete - permanently remove from database
+            self.db.delete_document(
                 collection_id=self.collection_id,
-                document_id=character_id,
-                data={'is_active': False}
+                document_id=character_id
             )
 
             logger.info("Character deleted successfully", character_id=character_id)
@@ -982,7 +994,14 @@ class CharacterService:
         limit: int = 5
     ) -> List[Dict[str, str]]:
         """
-        Get recent dialogue history with an NPC.
+        Get recent dialogue history with an NPC from recent_messages cache.
+
+        This method reads from character.npc_interactions[npc_id].recent_messages
+        which contains the last 3 messages for quick AI context. For full conversation
+        history, use ChatMessageService.get_conversation_history().
+
+        Backward Compatibility: Falls back to dialogue_history if recent_messages
+        doesn't exist (for characters created before chat_messages system).
 
         Args:
             character_id: Character ID
@@ -991,16 +1010,46 @@ class CharacterService:
             limit: Maximum number of recent exchanges to return (default 5)
 
         Returns:
-            List of dialogue exchanges [{player_line: str, npc_response: str}, ...]
+            List of dialogue exchanges [{player_message: str, npc_response: str, timestamp: str}, ...]
+            OR legacy format [{player_line: str, npc_response: str}, ...]
         """
         try:
             character = self.get_character(character_id, user_id)
 
             interaction = character.npc_interactions.get(npc_id, {})
-            dialogue_history = interaction.get("dialogue_history", [])
 
-            # Return most recent exchanges (up to limit)
-            return dialogue_history[-limit:] if dialogue_history else []
+            # NEW: Try recent_messages first (last 3 messages cache)
+            recent_messages = interaction.get("recent_messages")
+            if recent_messages is not None:
+                # Return most recent exchanges (up to limit, but recent_messages is already capped at 3)
+                return recent_messages[-limit:] if recent_messages else []
+
+            # DEPRECATED: Fall back to dialogue_history for backward compatibility
+            # This field will be removed after full migration to chat_messages system
+            dialogue_history = interaction.get("dialogue_history", [])
+            if dialogue_history:
+                logger.debug("Using deprecated dialogue_history field",
+                           character_id=character_id,
+                           npc_id=npc_id)
+                # Convert old format to new format if needed
+                # Old format: {player_line, npc_response}
+                # New format: {player_message, npc_response, timestamp}
+                converted = []
+                for entry in dialogue_history[-limit:]:
+                    if "player_message" in entry:
+                        # Already new format
+                        converted.append(entry)
+                    else:
+                        # Old format, convert
+                        converted.append({
+                            "player_message": entry.get("player_line", ""),
+                            "npc_response": entry.get("npc_response", ""),
+                            "timestamp": ""  # No timestamp available in old format
+                        })
+                return converted
+
+            # No dialogue history at all
+            return []
 
         except CharacterNotFound:
             raise

api/app/services/chat_message_service.py

@@ -0,0 +1,617 @@
+"""
+Chat Message Service.
+
+This service handles all business logic for player-NPC conversation history,
+including saving messages, retrieving conversations, searching, and managing
+the recent_messages cache in character documents.
+"""
+
+import json
+from typing import List, Dict, Any, Optional
+from datetime import datetime
+
+from appwrite.query import Query
+from appwrite.exception import AppwriteException
+from appwrite.id import ID
+
+from app.models.chat_message import ChatMessage, MessageContext, ConversationSummary
+from app.services.database_service import get_database_service
+from app.services.character_service import CharacterService
+from app.utils.logging import get_logger
+
+logger = get_logger(__file__)
+
+
+# Custom Exceptions
+class ChatMessageNotFound(Exception):
+    """Raised when a chat message is not found."""
+    pass
+
+
+class ChatMessagePermissionDenied(Exception):
+    """Raised when user doesn't have permission to access/modify a chat message."""
+    pass
+
+
+class ChatMessageService:
+    """
+    Service for managing player-NPC chat messages.
+
+    This service provides:
+    - Saving dialogue exchanges to chat_messages collection
+    - Updating recent_messages cache in character documents
+    - Retrieving conversation history with pagination
+    - Searching messages by text, NPC, context, date range
+    - Getting conversation summaries for UI
+    - Soft deleting messages for privacy/moderation
+    """
+
+    def __init__(self):
+        """Initialize the chat message service with database and character service."""
+        self.db = get_database_service()
+        self.character_service = CharacterService()
+        logger.info("ChatMessageService initialized")
+
+    def save_dialogue_exchange(
+        self,
+        character_id: str,
+        user_id: str,
+        npc_id: str,
+        player_message: str,
+        npc_response: str,
+        context: MessageContext = MessageContext.DIALOGUE,
+        metadata: Optional[Dict[str, Any]] = None,
+        session_id: Optional[str] = None,
+        location_id: Optional[str] = None
+    ) -> ChatMessage:
+        """
+        Save a dialogue exchange to chat_messages collection and update character's recent_messages cache.
+
+        This method:
+        1. Creates a ChatMessage document in the chat_messages collection
+        2. Updates character.npc_interactions[npc_id].recent_messages with the last 3 messages
+        3. Updates character.npc_interactions[npc_id].total_messages counter
+
+        Args:
+            character_id: Player's character ID
+            user_id: User ID (for ownership validation)
+            npc_id: NPC identifier
+            player_message: What the player said
+            npc_response: NPC's reply
+            context: Type of interaction (default: DIALOGUE)
+            metadata: Optional extensible metadata (quest_id, faction_id, etc.)
+            session_id: Optional game session reference
+            location_id: Optional location where conversation happened
+
+        Returns:
+            Saved ChatMessage instance
+
+        Raises:
+            ChatMessagePermissionDenied: If user doesn't own the character
+            AppwriteException: If database operation fails
+        """
+        try:
+            # Validate ownership
+            self._validate_ownership(character_id, user_id)
+
+            # Create chat message
+            chat_message = ChatMessage.create(
+                character_id=character_id,
+                npc_id=npc_id,
+                player_message=player_message,
+                npc_response=npc_response,
+                context=context,
+                session_id=session_id,
+                location_id=location_id,
+                metadata=metadata
+            )
+
+            # Save to database
+            message_data = chat_message.to_dict()
+            # Convert metadata dict to JSON string for storage (Appwrite requires string type)
+            # Always convert, even if empty dict (empty dict {} is falsy in Python!)
+            message_data['metadata'] = json.dumps(message_data.get('metadata') or {})
+
+            self.db.create_row(
+                table_id='chat_messages',
+                data=message_data,
+                row_id=chat_message.message_id
+            )
+
+            logger.info("Chat message saved",
+                       message_id=chat_message.message_id,
+                       character_id=character_id,
+                       npc_id=npc_id,
+                       context=context.value)
+
+            # Update character's recent_messages cache
+            self._update_recent_messages_preview(character_id, user_id, npc_id, chat_message)
+
+            return chat_message
+
+        except ChatMessagePermissionDenied:
+            raise
+        except Exception as e:
+            logger.error("Failed to save dialogue exchange",
+                        character_id=character_id,
+                        npc_id=npc_id,
+                        error=str(e))
+            raise
+
+    def get_conversation_history(
+        self,
+        character_id: str,
+        user_id: str,
+        npc_id: str,
+        limit: int = 50,
+        offset: int = 0
+    ) -> List[ChatMessage]:
+        """
+        Get paginated conversation history between character and specific NPC.
+
+        Args:
+            character_id: Player's character ID
+            user_id: User ID (for ownership validation)
+            npc_id: NPC identifier
+            limit: Maximum messages to return (default 50, max 100)
+            offset: Number of messages to skip for pagination
+
+        Returns:
+            List of ChatMessage instances ordered by timestamp DESC (most recent first)
+
+        Raises:
+            ChatMessagePermissionDenied: If user doesn't own the character
+            AppwriteException: If database query fails
+        """
+        try:
+            # Validate ownership
+            self._validate_ownership(character_id, user_id)
+
+            # Clamp limit to max 100
+            limit = min(limit, 100)
+
+            # Build query
+            queries = [
+                Query.equal('character_id', character_id),
+                Query.equal('npc_id', npc_id),
+                Query.equal('is_deleted', False),
+                Query.order_desc('timestamp'),
+                Query.limit(limit),
+                Query.offset(offset)
+            ]
+
+            # Fetch messages
+            rows = self.db.list_rows(
+                table_id='chat_messages',
+                queries=queries
+            )
+
+            # Convert to ChatMessage objects
+            messages = []
+            for row in rows:
+                message_data = row.data
+                # Parse JSON metadata if present
+                if message_data.get('metadata') and isinstance(message_data['metadata'], str):
+                    message_data['metadata'] = json.loads(message_data['metadata'])
+                messages.append(ChatMessage.from_dict(message_data))
+
+            logger.info("Retrieved conversation history",
+                       character_id=character_id,
+                       npc_id=npc_id,
+                       count=len(messages),
+                       limit=limit,
+                       offset=offset)
+
+            return messages
+
+        except ChatMessagePermissionDenied:
+            raise
+        except Exception as e:
+            logger.error("Failed to get conversation history",
+                        character_id=character_id,
+                        npc_id=npc_id,
+                        error=str(e))
+            raise
+
+    def search_messages(
+        self,
+        character_id: str,
+        user_id: str,
+        search_text: str,
+        npc_id: Optional[str] = None,
+        context: Optional[MessageContext] = None,
+        date_from: Optional[str] = None,
+        date_to: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0
+    ) -> List[ChatMessage]:
+        """
+        Search messages by text with optional filters.
+
+        Note: Appwrite's full-text search may be limited. This performs basic filtering.
+        For production use, consider implementing a dedicated search service.
+
+        Args:
+            character_id: Player's character ID
+            user_id: User ID (for ownership validation)
+            search_text: Text to search for in player_message and npc_response
+            npc_id: Optional filter by specific NPC
+            context: Optional filter by message context type
+            date_from: Optional start date (ISO format)
+            date_to: Optional end date (ISO format)
+            limit: Maximum messages to return (default 50)
+            offset: Number of messages to skip for pagination
+
+        Returns:
+            List of matching ChatMessage instances
+
+        Raises:
+            ChatMessagePermissionDenied: If user doesn't own the character
+            AppwriteException: If database query fails
+        """
+        try:
+            # Validate ownership
+            self._validate_ownership(character_id, user_id)
+
+            # Build base query
+            queries = [
+                Query.equal('character_id', character_id),
+                Query.equal('is_deleted', False)
+            ]
+
+            # Add optional filters
+            if npc_id:
+                queries.append(Query.equal('npc_id', npc_id))
+
+            if context:
+                queries.append(Query.equal('context', context.value))
+
+            if date_from:
+                queries.append(Query.greater_than_equal('timestamp', date_from))
+
+            if date_to:
+                queries.append(Query.less_than_equal('timestamp', date_to))
+
+            # Add search (Appwrite uses Query.search() if available)
+            if search_text:
+                try:
+                    queries.append(Query.search('player_message', search_text))
+                except:
+                    # Fallback: will filter in Python if search not supported
+                    pass
+
+            queries.extend([
+                Query.order_desc('timestamp'),
+                Query.limit(min(limit, 100)),
+                Query.offset(offset)
+            ])
+
+            # Fetch messages
+            rows = self.db.list_rows(
+                table_id='chat_messages',
+                queries=queries
+            )
+
+            # Convert to ChatMessage objects and apply text filter if needed
+            messages = []
+            for row in rows:
+                message_data = row.data
+                # Parse JSON metadata if present
+                if message_data.get('metadata') and isinstance(message_data['metadata'], str):
+                    message_data['metadata'] = json.loads(message_data['metadata'])
+
+                # Filter by search text in Python if not handled by database
+                if search_text:
+                    player_msg = message_data.get('player_message', '').lower()
+                    npc_msg = message_data.get('npc_response', '').lower()
+                    if search_text.lower() not in player_msg and search_text.lower() not in npc_msg:
+                        continue
+
+                messages.append(ChatMessage.from_dict(message_data))
+
+            logger.info("Search completed",
+                       character_id=character_id,
+                       search_text=search_text,
+                       npc_id=npc_id,
+                       context=context.value if context else None,
+                       results=len(messages))
+
+            return messages
+
+        except ChatMessagePermissionDenied:
+            raise
+        except Exception as e:
+            logger.error("Failed to search messages",
+                        character_id=character_id,
+                        search_text=search_text,
+                        error=str(e))
+            raise
+
+    def get_all_conversations_summary(
+        self,
+        character_id: str,
+        user_id: str
+    ) -> List[ConversationSummary]:
+        """
+        Get summary of all NPC conversations for a character.
+
+        Returns list of NPCs the character has talked to, with message counts,
+        last message timestamp, and preview of most recent exchange.
+
+        Args:
+            character_id: Player's character ID
+            user_id: User ID (for ownership validation)
+
+        Returns:
+            List of ConversationSummary instances
+
+        Raises:
+            ChatMessagePermissionDenied: If user doesn't own the character
+        """
+        try:
+            # Validate ownership
+            self._validate_ownership(character_id, user_id)
+
+            # Get character to access npc_interactions
+            character = self.character_service.get_character(character_id, user_id)
+
+            # Build summaries from character's npc_interactions
+            summaries = []
+            for npc_id, interaction in character.npc_interactions.items():
+                # Get NPC name (if available from NPC data, otherwise use npc_id)
+                # TODO: When NPC service is available, fetch NPC name
+                npc_name = npc_id.replace('_', ' ').title()
+
+                # Get last message timestamp and preview from recent_messages
+                recent_messages = interaction.get('recent_messages', [])
+                last_timestamp = interaction.get('last_interaction', '')
+                recent_preview = ''
+
+                if recent_messages:
+                    last_msg = recent_messages[-1]
+                    last_timestamp = last_msg.get('timestamp', last_timestamp)
+                    recent_preview = last_msg.get('npc_response', '')[:100]  # First 100 chars
+
+                # Get total message count
+                total_messages = interaction.get('total_messages', interaction.get('interaction_count', 0))
+
+                summary = ConversationSummary(
+                    npc_id=npc_id,
+                    npc_name=npc_name,
+                    last_message_timestamp=last_timestamp,
+                    message_count=total_messages,
+                    recent_preview=recent_preview
+                )
+                summaries.append(summary)
+
+            # Sort by most recent first
+            summaries.sort(key=lambda s: s.last_message_timestamp, reverse=True)
+
+            logger.info("Retrieved conversation summaries",
+                       character_id=character_id,
+                       conversation_count=len(summaries))
+
+            return summaries
+
+        except ChatMessagePermissionDenied:
+            raise
+        except Exception as e:
+            logger.error("Failed to get conversation summaries",
+                        character_id=character_id,
+                        error=str(e))
+            raise
+
+    def soft_delete_message(
+        self,
+        message_id: str,
+        character_id: str,
+        user_id: str
+    ) -> bool:
+        """
+        Soft delete a message by setting is_deleted=True.
+
+        Used for privacy/moderation. Message remains in database but filtered from queries.
+
+        Args:
+            message_id: Message ID to delete
+            character_id: Character ID (for ownership validation)
+            user_id: User ID (for ownership validation)
+
+        Returns:
+            True if successful
+
+        Raises:
+            ChatMessageNotFound: If message not found
+            ChatMessagePermissionDenied: If user doesn't own the character/message
+        """
+        try:
+            # Validate ownership
+            self._validate_ownership(character_id, user_id)
+
+            # Fetch message to verify it belongs to this character
+            message_row = self.db.get_row(table_id='chat_messages', row_id=message_id)
+
+            if not message_row:
+                raise ChatMessageNotFound(f"Message {message_id} not found")
+
+            if message_row.data.get('character_id') != character_id:
+                raise ChatMessagePermissionDenied("Message does not belong to this character")
+
+            # Update message to set is_deleted=True
+            self.db.update_row(
+                table_id='chat_messages',
+                row_id=message_id,
+                data={'is_deleted': True}
+            )
+
+            logger.info("Message soft deleted",
+                       message_id=message_id,
+                       character_id=character_id)
+
+            return True
+
+        except (ChatMessageNotFound, ChatMessagePermissionDenied):
+            raise
+        except Exception as e:
+            logger.error("Failed to soft delete message",
+                        message_id=message_id,
+                        error=str(e))
+            raise
+
+    def delete_messages_by_session(self, session_id: str) -> int:
+        """
+        Permanently delete all chat messages associated with a session.
+
+        Used when a session is deleted to clean up associated messages.
+        This is a hard delete - messages are removed from the database entirely.
+
+        Args:
+            session_id: Session ID whose messages should be deleted
+
+        Returns:
+            Number of messages deleted
+
+        Note:
+            This method does not validate ownership because it's called from
+            session_service after ownership has already been validated.
+        """
+        try:
+            # Query all messages with this session_id
+            messages = self.db.list_rows(
+                table_id='chat_messages',
+                queries=[Query.equal('session_id', session_id)],
+                limit=1000  # Handle up to 1000 messages per session
+            )
+
+            deleted_count = 0
+            for message in messages:
+                try:
+                    self.db.delete_document(
+                        collection_id='chat_messages',
+                        document_id=message.id
+                    )
+                    deleted_count += 1
+                except Exception as e:
+                    logger.warning("Failed to delete individual message",
+                                  message_id=message.id,
+                                  session_id=session_id,
+                                  error=str(e))
+                    # Continue deleting other messages
+
+            logger.info("Deleted messages for session",
+                       session_id=session_id,
+                       deleted_count=deleted_count)
+
+            return deleted_count
+
+        except Exception as e:
+            logger.error("Failed to delete messages by session",
+                        session_id=session_id,
+                        error=str(e))
+            # Don't raise - session deletion should still proceed
+            return 0
+
+    # Helper Methods
+
+    def _update_recent_messages_preview(
+        self,
+        character_id: str,
+        user_id: str,
+        npc_id: str,
+        new_message: ChatMessage
+    ) -> None:
+        """
+        Update the recent_messages cache in character.npc_interactions[npc_id].
+
+        Maintains the last 3 messages for quick AI context retrieval without querying
+        the chat_messages collection.
+
+        Args:
+            character_id: Character ID
+            user_id: User ID
+            npc_id: NPC ID
+            new_message: New message to add to preview
+        """
+        try:
+            # Get character
+            character = self.character_service.get_character(character_id, user_id)
+
+            # Get or create NPC interaction
+            if npc_id not in character.npc_interactions:
+                character.npc_interactions[npc_id] = {
+                    'npc_id': npc_id,
+                    'first_met': new_message.timestamp,
+                    'last_interaction': new_message.timestamp,
+                    'interaction_count': 0,
+                    'revealed_secrets': [],
+                    'relationship_level': 50,
+                    'custom_flags': {},
+                    'recent_messages': [],
+                    'total_messages': 0
+                }
+
+            interaction = character.npc_interactions[npc_id]
+
+            # Add new message to recent_messages
+            recent_messages = interaction.get('recent_messages', [])
+            recent_messages.append(new_message.to_preview())
+
+            # Keep only last 3 messages
+            interaction['recent_messages'] = recent_messages[-3:]
+
+            # Update total message count
+            interaction['total_messages'] = interaction.get('total_messages', 0) + 1
+
+            # Update last_interaction timestamp
+            interaction['last_interaction'] = new_message.timestamp
+
+            # Save character
+            self.character_service.update_character(character_id, user_id, character)
+
+            logger.debug("Updated recent_messages preview",
+                        character_id=character_id,
+                        npc_id=npc_id,
+                        recent_count=len(interaction['recent_messages']))
+
+        except Exception as e:
+            logger.error("Failed to update recent_messages preview",
+                        character_id=character_id,
+                        npc_id=npc_id,
+                        error=str(e))
+            # Don't raise - this is a cache update, not critical
+
+    def _validate_ownership(self, character_id: str, user_id: str) -> None:
+        """
+        Validate that the user owns the character.
+
+        Args:
+            character_id: Character ID
+            user_id: User ID
+
+        Raises:
+            ChatMessagePermissionDenied: If user doesn't own the character
+        """
+        try:
+            self.character_service.get_character(character_id, user_id)
+        except Exception as e:
+            logger.warning("Ownership validation failed",
+                          character_id=character_id,
+                          user_id=user_id)
+            raise ChatMessagePermissionDenied(f"User {user_id} does not own character {character_id}")
+
+
+# Global instance for convenience
+_service_instance: Optional[ChatMessageService] = None
+
+
+def get_chat_message_service() -> ChatMessageService:
+    """
+    Get the global ChatMessageService instance.
+
+    Returns:
+        Singleton ChatMessageService instance
+    """
+    global _service_instance
+    if _service_instance is None:
+        _service_instance = ChatMessageService()
+    return _service_instance

api/app/services/combat_loot_service.py

@@ -0,0 +1,359 @@
+"""
+Combat Loot Service - Orchestrates loot generation from combat encounters.
+
+This service bridges the EnemyTemplate loot tables with both the StaticItemLoader
+(for consumables and materials) and ItemGenerator (for procedural equipment).
+
+The service calculates effective rarity based on:
+- Party average level
+- Enemy difficulty tier
+- Character luck stat
+- Optional loot bonus modifiers (from abilities, buffs, etc.)
+"""
+
+import random
+from dataclasses import dataclass
+from typing import List, Optional
+
+from app.models.enemy import EnemyTemplate, LootEntry, LootType, EnemyDifficulty
+from app.models.items import Item
+from app.services.item_generator import get_item_generator, ItemGenerator
+from app.services.static_item_loader import get_static_item_loader, StaticItemLoader
+from app.utils.logging import get_logger
+
+logger = get_logger(__file__)
+
+
+# Difficulty tier rarity bonuses (converted to effective luck points)
+# Higher difficulty enemies have better chances of dropping rare items
+DIFFICULTY_RARITY_BONUS = {
+    EnemyDifficulty.EASY: 0.0,
+    EnemyDifficulty.MEDIUM: 0.05,
+    EnemyDifficulty.HARD: 0.15,
+    EnemyDifficulty.BOSS: 0.30,
+}
+
+# Multiplier for converting rarity bonus to effective luck points
+# Each 0.05 bonus translates to +1 effective luck
+LUCK_CONVERSION_FACTOR = 20
+
+
+@dataclass
+class LootContext:
+    """
+    Context for loot generation calculations.
+
+    Provides all the factors that influence loot quality and rarity.
+
+    Attributes:
+        party_average_level: Average level of player characters in the encounter
+        enemy_difficulty: Difficulty tier of the enemy being looted
+        luck_stat: Party's luck stat (typically average or leader's luck)
+        loot_bonus: Additional bonus from abilities, buffs, or modifiers (0.0 to 1.0)
+    """
+    party_average_level: int = 1
+    enemy_difficulty: EnemyDifficulty = EnemyDifficulty.EASY
+    luck_stat: int = 8
+    loot_bonus: float = 0.0
+
+
+class CombatLootService:
+    """
+    Service for generating combat loot drops.
+
+    Supports two types of loot:
+    - STATIC: Predefined items loaded from YAML (consumables, materials)
+    - PROCEDURAL: Generated equipment with affixes (weapons, armor)
+
+    The service handles:
+    - Rolling for drops based on drop_chance
+    - Loading static items via StaticItemLoader
+    - Generating procedural items via ItemGenerator
+    - Calculating effective rarity based on context
+    """
+
+    def __init__(
+        self,
+        item_generator: Optional[ItemGenerator] = None,
+        static_loader: Optional[StaticItemLoader] = None
+    ):
+        """
+        Initialize the combat loot service.
+
+        Args:
+            item_generator: ItemGenerator instance (uses global singleton if None)
+            static_loader: StaticItemLoader instance (uses global singleton if None)
+        """
+        self.item_generator = item_generator or get_item_generator()
+        self.static_loader = static_loader or get_static_item_loader()
+        logger.info("CombatLootService initialized")
+
+    def generate_loot_from_enemy(
+        self,
+        enemy: EnemyTemplate,
+        context: LootContext
+    ) -> List[Item]:
+        """
+        Generate all loot drops from a defeated enemy.
+
+        Iterates through the enemy's loot table, rolling for each entry
+        and generating appropriate items based on loot type.
+
+        Args:
+            enemy: The defeated enemy template
+            context: Loot generation context (party level, luck, etc.)
+
+        Returns:
+            List of Item objects to add to player inventory
+        """
+        items = []
+
+        for entry in enemy.loot_table:
+            # Roll for drop chance
+            if random.random() >= entry.drop_chance:
+                continue
+
+            # Determine quantity
+            quantity = random.randint(entry.quantity_min, entry.quantity_max)
+
+            if entry.loot_type == LootType.STATIC:
+                # Static item: load from predefined templates
+                static_items = self._generate_static_items(entry, quantity)
+                items.extend(static_items)
+
+            elif entry.loot_type == LootType.PROCEDURAL:
+                # Procedural equipment: generate with ItemGenerator
+                procedural_items = self._generate_procedural_items(
+                    entry, quantity, context
+                )
+                items.extend(procedural_items)
+
+        logger.info(
+            "Loot generated from enemy",
+            enemy_id=enemy.enemy_id,
+            enemy_difficulty=enemy.difficulty.value,
+            item_count=len(items),
+            party_level=context.party_average_level,
+            luck=context.luck_stat
+        )
+
+        return items
+
+    def _generate_static_items(
+        self,
+        entry: LootEntry,
+        quantity: int
+    ) -> List[Item]:
+        """
+        Generate static items from a loot entry.
+
+        Args:
+            entry: The loot table entry
+            quantity: Number of items to generate
+
+        Returns:
+            List of Item instances
+        """
+        items = []
+
+        if not entry.item_id:
+            logger.warning(
+                "Static loot entry missing item_id",
+                entry=entry.to_dict()
+            )
+            return items
+
+        for _ in range(quantity):
+            item = self.static_loader.get_item(entry.item_id)
+            if item:
+                items.append(item)
+            else:
+                logger.warning(
+                    "Failed to load static item",
+                    item_id=entry.item_id
+                )
+
+        return items
+
+    def _generate_procedural_items(
+        self,
+        entry: LootEntry,
+        quantity: int,
+        context: LootContext
+    ) -> List[Item]:
+        """
+        Generate procedural items from a loot entry.
+
+        Calculates effective luck based on:
+        - Base luck stat
+        - Entry-specific rarity bonus
+        - Difficulty bonus
+        - Loot bonus from abilities/buffs
+
+        Args:
+            entry: The loot table entry
+            quantity: Number of items to generate
+            context: Loot generation context
+
+        Returns:
+            List of generated Item instances
+        """
+        items = []
+
+        if not entry.item_type:
+            logger.warning(
+                "Procedural loot entry missing item_type",
+                entry=entry.to_dict()
+            )
+            return items
+
+        # Calculate effective luck for rarity roll
+        effective_luck = self._calculate_effective_luck(entry, context)
+
+        for _ in range(quantity):
+            item = self.item_generator.generate_loot_drop(
+                character_level=context.party_average_level,
+                luck_stat=effective_luck,
+                item_type=entry.item_type
+            )
+            if item:
+                items.append(item)
+            else:
+                logger.warning(
+                    "Failed to generate procedural item",
+                    item_type=entry.item_type,
+                    level=context.party_average_level
+                )
+
+        return items
+
+    def _calculate_effective_luck(
+        self,
+        entry: LootEntry,
+        context: LootContext
+    ) -> int:
+        """
+        Calculate effective luck for rarity rolling.
+
+        Combines multiple factors:
+        - Base luck stat from party
+        - Entry-specific rarity bonus (defined per loot entry)
+        - Difficulty bonus (based on enemy tier)
+        - Loot bonus (from abilities, buffs, etc.)
+
+        The formula:
+            effective_luck = base_luck + (entry_bonus + difficulty_bonus + loot_bonus) * FACTOR
+
+        Args:
+            entry: The loot table entry
+            context: Loot generation context
+
+        Returns:
+            Effective luck stat for rarity calculations
+        """
+        # Get difficulty bonus
+        difficulty_bonus = DIFFICULTY_RARITY_BONUS.get(
+            context.enemy_difficulty, 0.0
+        )
+
+        # Sum all bonuses
+        total_bonus = (
+            entry.rarity_bonus +
+            difficulty_bonus +
+            context.loot_bonus
+        )
+
+        # Convert bonus to effective luck points
+        bonus_luck = int(total_bonus * LUCK_CONVERSION_FACTOR)
+
+        effective_luck = context.luck_stat + bonus_luck
+
+        logger.debug(
+            "Effective luck calculated",
+            base_luck=context.luck_stat,
+            entry_bonus=entry.rarity_bonus,
+            difficulty_bonus=difficulty_bonus,
+            loot_bonus=context.loot_bonus,
+            total_bonus=total_bonus,
+            effective_luck=effective_luck
+        )
+
+        return effective_luck
+
+    def generate_boss_loot(
+        self,
+        enemy: EnemyTemplate,
+        context: LootContext,
+        guaranteed_drops: int = 1
+    ) -> List[Item]:
+        """
+        Generate loot from a boss enemy with guaranteed drops.
+
+        Boss enemies are guaranteed to drop at least one piece of equipment
+        in addition to their normal loot table rolls.
+
+        Args:
+            enemy: The boss enemy template
+            context: Loot generation context
+            guaranteed_drops: Number of guaranteed equipment drops
+
+        Returns:
+            List of Item objects including guaranteed drops
+        """
+        # Generate normal loot first
+        items = self.generate_loot_from_enemy(enemy, context)
+
+        # Add guaranteed procedural drops for bosses
+        if enemy.is_boss():
+            context_for_boss = LootContext(
+                party_average_level=context.party_average_level,
+                enemy_difficulty=EnemyDifficulty.BOSS,
+                luck_stat=context.luck_stat,
+                loot_bonus=context.loot_bonus + 0.1  # Extra bonus for bosses
+            )
+
+            for _ in range(guaranteed_drops):
+                # Alternate between weapon and armor
+                item_type = random.choice(["weapon", "armor"])
+                effective_luck = self._calculate_effective_luck(
+                    LootEntry(
+                        loot_type=LootType.PROCEDURAL,
+                        item_type=item_type,
+                        rarity_bonus=0.15  # Boss-tier bonus
+                    ),
+                    context_for_boss
+                )
+
+                item = self.item_generator.generate_loot_drop(
+                    character_level=context.party_average_level,
+                    luck_stat=effective_luck,
+                    item_type=item_type
+                )
+                if item:
+                    items.append(item)
+
+            logger.info(
+                "Boss loot generated",
+                enemy_id=enemy.enemy_id,
+                guaranteed_drops=guaranteed_drops,
+                total_items=len(items)
+            )
+
+        return items
+
+
+# Global singleton
+_service_instance: Optional[CombatLootService] = None
+
+
+def get_combat_loot_service() -> CombatLootService:
+    """
+    Get the global CombatLootService instance.
+
+    Returns:
+        Singleton CombatLootService instance
+    """
+    global _service_instance
+    if _service_instance is None:
+        _service_instance = CombatLootService()
+    return _service_instance

api/app/services/damage_calculator.py

@@ -0,0 +1,590 @@
+"""
+Damage Calculator Service
+
+A comprehensive, formula-driven damage calculation system for Code of Conquest.
+Handles physical, magical, and elemental damage with LUK stat integration
+for variance, critical hits, and accuracy.
+
+Formulas:
+    Physical: (effective_stats.damage + ability_power) * Variance * Crit_Mult - DEF
+              where effective_stats.damage = int(STR * 0.75) + damage_bonus (from weapon)
+    Magical:  (effective_stats.spell_power + ability_power) * Variance * Crit_Mult - RES
+              where effective_stats.spell_power = int(INT * 0.75) + spell_power_bonus (from staff/wand)
+    Elemental: Split between physical and magical components using ratios
+
+LUK Integration:
+    - Miss reduction: 10% base - (LUK * 0.5%), hard cap at 5% miss
+    - Crit bonus: Base 5% + (LUK * 0.5%), max 25%
+    - Lucky variance: 5% + (LUK * 0.25%) chance for higher damage roll
+"""
+
+import random
+from dataclasses import dataclass, field
+from typing import Dict, Any, Optional, List
+
+from app.models.stats import Stats
+from app.models.enums import DamageType
+
+
+class CombatConstants:
+    """
+    Combat system tuning constants.
+
+    These values control the balance of combat mechanics and can be
+    adjusted for game balance without modifying formula logic.
+    """
+
+    # Stat Scaling
+    # How much primary stats (STR/INT) contribute to damage
+    # 0.75 means STR 14 adds +10.5 damage
+    STAT_SCALING_FACTOR: float = 0.75
+
+    # Hit/Miss System
+    BASE_MISS_CHANCE: float = 0.10      # 10% base miss rate
+    LUK_MISS_REDUCTION: float = 0.005   # 0.5% per LUK point
+    DEX_EVASION_BONUS: float = 0.0025   # 0.25% per DEX above 10
+    MIN_MISS_CHANCE: float = 0.05       # Hard cap: 5% minimum miss
+
+    # Critical Hits
+    DEFAULT_CRIT_CHANCE: float = 0.05   # 5% base crit
+    LUK_CRIT_BONUS: float = 0.005       # 0.5% per LUK point
+    MAX_CRIT_CHANCE: float = 0.25       # 25% cap (before skills)
+    DEFAULT_CRIT_MULTIPLIER: float = 2.0
+
+    # Damage Variance
+    BASE_VARIANCE_MIN: float = 0.95     # Minimum variance roll
+    BASE_VARIANCE_MAX: float = 1.05     # Maximum variance roll
+    LUCKY_VARIANCE_MIN: float = 1.00    # Lucky roll minimum
+    LUCKY_VARIANCE_MAX: float = 1.10    # Lucky roll maximum (10% bonus)
+    BASE_LUCKY_CHANCE: float = 0.05     # 5% base lucky roll chance
+    LUK_LUCKY_BONUS: float = 0.0025     # 0.25% per LUK point
+
+    # Defense Mitigation
+    # Ensures high-DEF targets still take meaningful damage
+    MIN_DAMAGE_RATIO: float = 0.20      # 20% of raw always goes through
+    MIN_DAMAGE: int = 1                  # Absolute minimum damage
+
+
+@dataclass
+class DamageResult:
+    """
+    Result of a damage calculation.
+
+    Contains the calculated damage values, whether the attack was a crit or miss,
+    and a human-readable message for the combat log.
+
+    Attributes:
+        total_damage: Final damage after all calculations
+        physical_damage: Physical component (for split damage)
+        elemental_damage: Elemental component (for split damage)
+        damage_type: Primary damage type (physical, fire, etc.)
+        is_critical: Whether the attack was a critical hit
+        is_miss: Whether the attack missed entirely
+        variance_roll: The variance multiplier that was applied
+        raw_damage: Damage before defense mitigation
+        message: Human-readable description for combat log
+    """
+
+    total_damage: int = 0
+    physical_damage: int = 0
+    elemental_damage: int = 0
+    damage_type: DamageType = DamageType.PHYSICAL
+    elemental_type: Optional[DamageType] = None
+    is_critical: bool = False
+    is_miss: bool = False
+    variance_roll: float = 1.0
+    raw_damage: int = 0
+    message: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize damage result to dictionary."""
+        return {
+            "total_damage": self.total_damage,
+            "physical_damage": self.physical_damage,
+            "elemental_damage": self.elemental_damage,
+            "damage_type": self.damage_type.value if self.damage_type else "physical",
+            "elemental_type": self.elemental_type.value if self.elemental_type else None,
+            "is_critical": self.is_critical,
+            "is_miss": self.is_miss,
+            "variance_roll": round(self.variance_roll, 3),
+            "raw_damage": self.raw_damage,
+            "message": self.message,
+        }
+
+
+class DamageCalculator:
+    """
+    Formula-driven damage calculator for combat.
+
+    This class provides static methods for calculating all types of damage
+    in the combat system, including hit/miss chances, critical hits,
+    damage variance, and defense mitigation.
+
+    All formulas integrate the LUK stat for meaningful randomness while
+    maintaining a hard cap on miss chance to prevent frustration.
+    """
+
+    @staticmethod
+    def calculate_hit_chance(
+        attacker_luck: int,
+        defender_dexterity: int,
+        skill_bonus: float = 0.0
+    ) -> float:
+        """
+        Calculate hit probability for an attack.
+
+        Formula:
+            miss_chance = max(0.05, 0.10 - (LUK * 0.005) + ((DEX - 10) * 0.0025))
+            hit_chance = 1.0 - miss_chance
+
+        Args:
+            attacker_luck: Attacker's LUK stat
+            defender_dexterity: Defender's DEX stat
+            skill_bonus: Additional hit chance from skills (0.0 to 1.0)
+
+        Returns:
+            Hit probability as a float between 0.0 and 1.0
+
+        Examples:
+            LUK 8, DEX 10: miss = 10% - 4% + 0% = 6%
+            LUK 12, DEX 10: miss = 10% - 6% + 0% = 4% -> capped at 5%
+            LUK 8, DEX 15: miss = 10% - 4% + 1.25% = 7.25%
+        """
+        # Base miss rate
+        base_miss = CombatConstants.BASE_MISS_CHANCE
+
+        # LUK reduces miss chance
+        luk_reduction = attacker_luck * CombatConstants.LUK_MISS_REDUCTION
+
+        # High DEX increases evasion (only DEX above 10 counts)
+        dex_above_base = max(0, defender_dexterity - 10)
+        dex_evasion = dex_above_base * CombatConstants.DEX_EVASION_BONUS
+
+        # Calculate final miss chance with hard cap
+        miss_chance = base_miss - luk_reduction + dex_evasion - skill_bonus
+        miss_chance = max(CombatConstants.MIN_MISS_CHANCE, miss_chance)
+
+        return 1.0 - miss_chance
+
+    @staticmethod
+    def calculate_crit_chance(
+        attacker_luck: int,
+        weapon_crit_chance: float = CombatConstants.DEFAULT_CRIT_CHANCE,
+        skill_bonus: float = 0.0
+    ) -> float:
+        """
+        Calculate critical hit probability.
+
+        Formula:
+            crit_chance = min(0.25, weapon_crit + (LUK * 0.005) + skill_bonus)
+
+        Args:
+            attacker_luck: Attacker's LUK stat
+            weapon_crit_chance: Base crit chance from weapon (default 5%)
+            skill_bonus: Additional crit chance from skills
+
+        Returns:
+            Crit probability as a float (capped at 25%)
+
+        Examples:
+            LUK 8, weapon 5%: crit = 5% + 4% = 9%
+            LUK 12, weapon 5%: crit = 5% + 6% = 11%
+            LUK 12, weapon 10%: crit = 10% + 6% = 16%
+        """
+        # LUK bonus to crit
+        luk_bonus = attacker_luck * CombatConstants.LUK_CRIT_BONUS
+
+        # Total crit chance with cap
+        total_crit = weapon_crit_chance + luk_bonus + skill_bonus
+
+        return min(CombatConstants.MAX_CRIT_CHANCE, total_crit)
+
+    @staticmethod
+    def calculate_variance(attacker_luck: int) -> float:
+        """
+        Calculate damage variance multiplier with LUK bonus.
+
+        Hybrid variance system:
+            - Base roll: 95% to 105% of damage
+            - LUK grants chance for "lucky roll": 100% to 110% instead
+
+        Args:
+            attacker_luck: Attacker's LUK stat
+
+        Returns:
+            Variance multiplier (typically 0.95 to 1.10)
+
+        Examples:
+            LUK 8: 7% chance for lucky roll (100-110%)
+            LUK 12: 8% chance for lucky roll
+        """
+        # Calculate lucky roll chance
+        lucky_chance = (
+            CombatConstants.BASE_LUCKY_CHANCE +
+            (attacker_luck * CombatConstants.LUK_LUCKY_BONUS)
+        )
+
+        # Roll for lucky variance
+        if random.random() < lucky_chance:
+            # Lucky roll: higher damage range
+            return random.uniform(
+                CombatConstants.LUCKY_VARIANCE_MIN,
+                CombatConstants.LUCKY_VARIANCE_MAX
+            )
+        else:
+            # Normal roll
+            return random.uniform(
+                CombatConstants.BASE_VARIANCE_MIN,
+                CombatConstants.BASE_VARIANCE_MAX
+            )
+
+    @staticmethod
+    def apply_defense(
+        raw_damage: int,
+        defense: int,
+        min_damage_ratio: float = CombatConstants.MIN_DAMAGE_RATIO
+    ) -> int:
+        """
+        Apply defense mitigation with minimum damage guarantee.
+
+        Ensures at least 20% of raw damage always goes through,
+        preventing high-DEF tanks from becoming unkillable.
+        Absolute minimum is always 1 damage.
+
+        Args:
+            raw_damage: Damage before defense
+            defense: Target's defense value
+            min_damage_ratio: Minimum % of raw damage that goes through
+
+        Returns:
+            Final damage after mitigation (minimum 1)
+
+        Examples:
+            raw=20, def=5: 20 - 5 = 15 damage
+            raw=20, def=18: max(4, 2) = 4 damage (20% minimum)
+            raw=10, def=100: max(2, -90) = 2 damage (20% minimum)
+        """
+        # Calculate mitigated damage
+        mitigated = raw_damage - defense
+
+        # Minimum damage is 20% of raw, or 1, whichever is higher
+        min_damage = max(CombatConstants.MIN_DAMAGE, int(raw_damage * min_damage_ratio))
+
+        return max(min_damage, mitigated)
+
+    @classmethod
+    def calculate_physical_damage(
+        cls,
+        attacker_stats: Stats,
+        defender_stats: Stats,
+        weapon_crit_chance: float = CombatConstants.DEFAULT_CRIT_CHANCE,
+        weapon_crit_multiplier: float = CombatConstants.DEFAULT_CRIT_MULTIPLIER,
+        ability_base_power: int = 0,
+        skill_hit_bonus: float = 0.0,
+        skill_crit_bonus: float = 0.0,
+    ) -> DamageResult:
+        """
+        Calculate physical damage for a melee/ranged attack.
+
+        Formula:
+            Base = attacker_stats.damage + ability_base_power
+            where attacker_stats.damage = int(STR * 0.75) + damage_bonus
+            Damage = Base * Variance * Crit_Mult - DEF
+
+        Args:
+            attacker_stats: Attacker's Stats (includes weapon damage via damage property)
+            defender_stats: Defender's Stats (DEX, CON used)
+            weapon_crit_chance: Crit chance from weapon (default 5%)
+            weapon_crit_multiplier: Crit damage multiplier (default 2.0x)
+            ability_base_power: Additional base power from ability
+            skill_hit_bonus: Hit chance bonus from skills
+            skill_crit_bonus: Crit chance bonus from skills
+
+        Returns:
+            DamageResult with calculated damage and metadata
+        """
+        result = DamageResult(damage_type=DamageType.PHYSICAL)
+
+        # Step 1: Check for miss
+        hit_chance = cls.calculate_hit_chance(
+            attacker_stats.luck,
+            defender_stats.dexterity,
+            skill_hit_bonus
+        )
+
+        if random.random() > hit_chance:
+            result.is_miss = True
+            result.message = "Attack missed!"
+            return result
+
+        # Step 2: Calculate base damage
+        # attacker_stats.damage already includes: int(STR * 0.75) + damage_bonus (weapon)
+        base_damage = attacker_stats.damage + ability_base_power
+
+        # Step 3: Apply variance
+        variance = cls.calculate_variance(attacker_stats.luck)
+        result.variance_roll = variance
+        damage = base_damage * variance
+
+        # Step 4: Check for critical hit
+        crit_chance = cls.calculate_crit_chance(
+            attacker_stats.luck,
+            weapon_crit_chance,
+            skill_crit_bonus
+        )
+
+        if random.random() < crit_chance:
+            result.is_critical = True
+            damage *= weapon_crit_multiplier
+
+        # Store raw damage before defense
+        result.raw_damage = int(damage)
+
+        # Step 5: Apply defense mitigation
+        final_damage = cls.apply_defense(int(damage), defender_stats.defense)
+
+        result.total_damage = final_damage
+        result.physical_damage = final_damage
+
+        # Build message
+        crit_text = " CRITICAL HIT!" if result.is_critical else ""
+        result.message = f"Dealt {final_damage} physical damage.{crit_text}"
+
+        return result
+
+    @classmethod
+    def calculate_magical_damage(
+        cls,
+        attacker_stats: Stats,
+        defender_stats: Stats,
+        ability_base_power: int,
+        damage_type: DamageType = DamageType.FIRE,
+        weapon_crit_chance: float = CombatConstants.DEFAULT_CRIT_CHANCE,
+        weapon_crit_multiplier: float = CombatConstants.DEFAULT_CRIT_MULTIPLIER,
+        skill_hit_bonus: float = 0.0,
+        skill_crit_bonus: float = 0.0,
+    ) -> DamageResult:
+        """
+        Calculate magical damage for a spell.
+
+        Spells CAN critically hit (same formula as physical).
+        LUK benefits all classes equally.
+
+        Formula:
+            Base = attacker_stats.spell_power + ability_base_power
+            where attacker_stats.spell_power = int(INT * 0.75) + spell_power_bonus
+            Damage = Base * Variance * Crit_Mult - RES
+
+        Args:
+            attacker_stats: Attacker's Stats (includes staff/wand spell_power via spell_power property)
+            defender_stats: Defender's Stats (DEX, WIS used)
+            ability_base_power: Base power of the spell
+            damage_type: Type of magical damage (fire, ice, etc.)
+            weapon_crit_chance: Crit chance (from focus/staff)
+            weapon_crit_multiplier: Crit damage multiplier
+            skill_hit_bonus: Hit chance bonus from skills
+            skill_crit_bonus: Crit chance bonus from skills
+
+        Returns:
+            DamageResult with calculated damage and metadata
+        """
+        result = DamageResult(damage_type=damage_type)
+
+        # Step 1: Check for miss (spells can miss too)
+        hit_chance = cls.calculate_hit_chance(
+            attacker_stats.luck,
+            defender_stats.dexterity,
+            skill_hit_bonus
+        )
+
+        if random.random() > hit_chance:
+            result.is_miss = True
+            result.message = "Spell missed!"
+            return result
+
+        # Step 2: Calculate base damage
+        # attacker_stats.spell_power already includes: int(INT * 0.75) + spell_power_bonus (staff/wand)
+        base_damage = attacker_stats.spell_power + ability_base_power
+
+        # Step 3: Apply variance
+        variance = cls.calculate_variance(attacker_stats.luck)
+        result.variance_roll = variance
+        damage = base_damage * variance
+
+        # Step 4: Check for critical hit (spells CAN crit)
+        crit_chance = cls.calculate_crit_chance(
+            attacker_stats.luck,
+            weapon_crit_chance,
+            skill_crit_bonus
+        )
+
+        if random.random() < crit_chance:
+            result.is_critical = True
+            damage *= weapon_crit_multiplier
+
+        # Store raw damage before resistance
+        result.raw_damage = int(damage)
+
+        # Step 5: Apply resistance mitigation
+        final_damage = cls.apply_defense(int(damage), defender_stats.resistance)
+
+        result.total_damage = final_damage
+        result.elemental_damage = final_damage
+
+        # Build message
+        crit_text = " CRITICAL HIT!" if result.is_critical else ""
+        result.message = f"Dealt {final_damage} {damage_type.value} damage.{crit_text}"
+
+        return result
+
+    @classmethod
+    def calculate_elemental_weapon_damage(
+        cls,
+        attacker_stats: Stats,
+        defender_stats: Stats,
+        weapon_crit_chance: float,
+        weapon_crit_multiplier: float,
+        physical_ratio: float,
+        elemental_ratio: float,
+        elemental_type: DamageType,
+        ability_base_power: int = 0,
+        skill_hit_bonus: float = 0.0,
+        skill_crit_bonus: float = 0.0,
+    ) -> DamageResult:
+        """
+        Calculate split damage for elemental weapons (e.g., Fire Sword).
+
+        Elemental weapons deal both physical AND elemental damage,
+        calculated separately against DEF and RES respectively.
+
+        Formula:
+            Physical = (attacker_stats.damage + ability_power) * PHYS_RATIO - DEF
+            Elemental = (attacker_stats.spell_power + ability_power) * ELEM_RATIO - RES
+            Total = Physical + Elemental
+
+        Recommended Split Ratios:
+            - Pure Physical: 100% / 0%
+            - Fire Sword: 70% / 30%
+            - Frost Blade: 60% / 40%
+            - Lightning Spear: 50% / 50%
+
+        Args:
+            attacker_stats: Attacker's Stats (damage and spell_power include equipment)
+            defender_stats: Defender's Stats
+            weapon_crit_chance: Crit chance from weapon
+            weapon_crit_multiplier: Crit damage multiplier
+            physical_ratio: Portion of damage that is physical (0.0-1.0)
+            elemental_ratio: Portion of damage that is elemental (0.0-1.0)
+            elemental_type: Type of elemental damage
+            ability_base_power: Additional base power from ability
+            skill_hit_bonus: Hit chance bonus from skills
+            skill_crit_bonus: Crit chance bonus from skills
+
+        Returns:
+            DamageResult with split physical/elemental damage
+        """
+        result = DamageResult(
+            damage_type=DamageType.PHYSICAL,
+            elemental_type=elemental_type
+        )
+
+        # Step 1: Check for miss (single roll for entire attack)
+        hit_chance = cls.calculate_hit_chance(
+            attacker_stats.luck,
+            defender_stats.dexterity,
+            skill_hit_bonus
+        )
+
+        if random.random() > hit_chance:
+            result.is_miss = True
+            result.message = "Attack missed!"
+            return result
+
+        # Step 2: Check for critical (single roll applies to both components)
+        variance = cls.calculate_variance(attacker_stats.luck)
+        result.variance_roll = variance
+
+        crit_chance = cls.calculate_crit_chance(
+            attacker_stats.luck,
+            weapon_crit_chance,
+            skill_crit_bonus
+        )
+        is_crit = random.random() < crit_chance
+        result.is_critical = is_crit
+        crit_mult = weapon_crit_multiplier if is_crit else 1.0
+
+        # Step 3: Calculate physical component
+        # attacker_stats.damage includes: int(STR * 0.75) + damage_bonus (weapon)
+        phys_base = (attacker_stats.damage + ability_base_power) * physical_ratio
+        phys_damage = phys_base * variance * crit_mult
+        phys_final = cls.apply_defense(int(phys_damage), defender_stats.defense)
+
+        # Step 4: Calculate elemental component
+        # attacker_stats.spell_power includes: int(INT * 0.75) + spell_power_bonus (staff/wand)
+        elem_base = (attacker_stats.spell_power + ability_base_power) * elemental_ratio
+        elem_damage = elem_base * variance * crit_mult
+        elem_final = cls.apply_defense(int(elem_damage), defender_stats.resistance)
+
+        # Step 5: Combine results
+        result.physical_damage = phys_final
+        result.elemental_damage = elem_final
+        result.total_damage = phys_final + elem_final
+        result.raw_damage = int(phys_damage + elem_damage)
+
+        # Build message
+        crit_text = " CRITICAL HIT!" if is_crit else ""
+        result.message = (
+            f"Dealt {result.total_damage} damage "
+            f"({phys_final} physical + {elem_final} {elemental_type.value}).{crit_text}"
+        )
+
+        return result
+
+    @classmethod
+    def calculate_aoe_damage(
+        cls,
+        attacker_stats: Stats,
+        defender_stats_list: List[Stats],
+        ability_base_power: int,
+        damage_type: DamageType = DamageType.FIRE,
+        weapon_crit_chance: float = CombatConstants.DEFAULT_CRIT_CHANCE,
+        weapon_crit_multiplier: float = CombatConstants.DEFAULT_CRIT_MULTIPLIER,
+        skill_hit_bonus: float = 0.0,
+        skill_crit_bonus: float = 0.0,
+    ) -> List[DamageResult]:
+        """
+        Calculate AoE spell damage against multiple targets.
+
+        AoE spells deal FULL damage to all targets (balanced by higher mana costs).
+        Each target has independent hit/crit rolls but shares the base calculation.
+
+        Args:
+            attacker_stats: Attacker's Stats
+            defender_stats_list: List of defender Stats (one per target)
+            ability_base_power: Base power of the AoE spell
+            damage_type: Type of magical damage
+            weapon_crit_chance: Crit chance from focus/staff
+            weapon_crit_multiplier: Crit damage multiplier
+            skill_hit_bonus: Hit chance bonus from skills
+            skill_crit_bonus: Crit chance bonus from skills
+
+        Returns:
+            List of DamageResult, one per target
+        """
+        results = []
+
+        # Each target gets independent damage calculation
+        for defender_stats in defender_stats_list:
+            result = cls.calculate_magical_damage(
+                attacker_stats=attacker_stats,
+                defender_stats=defender_stats,
+                ability_base_power=ability_base_power,
+                damage_type=damage_type,
+                weapon_crit_chance=weapon_crit_chance,
+                weapon_crit_multiplier=weapon_crit_multiplier,
+                skill_hit_bonus=skill_hit_bonus,
+                skill_crit_bonus=skill_crit_bonus,
+            )
+            results.append(result)
+
+        return results

api/app/services/database_init.py

@@ -97,6 +97,15 @@ class DatabaseInitService:
             logger.error("Failed to initialize ai_usage_logs table", error=str(e))
             results['ai_usage_logs'] = False
 
+        # Initialize chat_messages table
+        try:
+            self.init_chat_messages_table()
+            results['chat_messages'] = True
+            logger.info("Chat messages table initialized successfully")
+        except Exception as e:
+            logger.error("Failed to initialize chat_messages table", error=str(e))
+            results['chat_messages'] = False
+
         success_count = sum(1 for v in results.values() if v)
         total_count = len(results)
 
@@ -536,6 +545,207 @@ class DatabaseInitService:
                         code=e.code)
             raise
 
+    def init_chat_messages_table(self) -> bool:
+        """
+        Initialize the chat_messages table for storing player-NPC conversation history.
+
+        Table schema:
+        - message_id (string, required): Unique message identifier (UUID)
+        - character_id (string, required): Player's character ID
+        - npc_id (string, required): NPC identifier
+        - player_message (string, required): What the player said
+        - npc_response (string, required): NPC's reply
+        - timestamp (string, required): ISO timestamp when message was created
+        - session_id (string, optional): Game session reference
+        - location_id (string, optional): Where conversation happened
+        - context (string, required): Message context type (dialogue, quest, shop, etc.)
+        - metadata (string, optional): JSON metadata for quest_id, faction_id, etc.
+        - is_deleted (boolean, default=False): Soft delete flag
+
+        Indexes:
+        - character_id + npc_id + timestamp: Primary query pattern (conversation history)
+        - character_id + timestamp: All character messages
+        - session_id + timestamp: Session-based queries
+        - context: Filter by interaction type
+        - timestamp: Date range queries
+
+        Returns:
+            True if successful
+
+        Raises:
+            AppwriteException: If table creation fails
+        """
+        table_id = 'chat_messages'
+
+        logger.info("Initializing chat_messages table", table_id=table_id)
+
+        try:
+            # Check if table already exists
+            try:
+                self.tables_db.get_table(
+                    database_id=self.database_id,
+                    table_id=table_id
+                )
+                logger.info("Chat messages table already exists", table_id=table_id)
+                return True
+            except AppwriteException as e:
+                if e.code != 404:
+                    raise
+                logger.info("Chat messages table does not exist, creating...")
+
+            # Create table
+            logger.info("Creating chat_messages table")
+            table = self.tables_db.create_table(
+                database_id=self.database_id,
+                table_id=table_id,
+                name='Chat Messages'
+            )
+            logger.info("Chat messages table created", table_id=table['$id'])
+
+            # Create columns
+            self._create_column(
+                table_id=table_id,
+                column_id='message_id',
+                column_type='string',
+                size=36,  # UUID length
+                required=True
+            )
+
+            self._create_column(
+                table_id=table_id,
+                column_id='character_id',
+                column_type='string',
+                size=100,
+                required=True
+            )
+
+            self._create_column(
+                table_id=table_id,
+                column_id='npc_id',
+                column_type='string',
+                size=100,
+                required=True
+            )
+
+            self._create_column(
+                table_id=table_id,
+                column_id='player_message',
+                column_type='string',
+                size=2000,  # Player input limit
+                required=True
+            )
+
+            self._create_column(
+                table_id=table_id,
+                column_id='npc_response',
+                column_type='string',
+                size=5000,  # AI-generated response
+                required=True
+            )
+
+            self._create_column(
+                table_id=table_id,
+                column_id='timestamp',
+                column_type='string',
+                size=50,  # ISO timestamp format
+                required=True
+            )
+
+            self._create_column(
+                table_id=table_id,
+                column_id='session_id',
+                column_type='string',
+                size=100,
+                required=False
+            )
+
+            self._create_column(
+                table_id=table_id,
+                column_id='location_id',
+                column_type='string',
+                size=100,
+                required=False
+            )
+
+            self._create_column(
+                table_id=table_id,
+                column_id='context',
+                column_type='string',
+                size=50,  # MessageContext enum values
+                required=True
+            )
+
+            self._create_column(
+                table_id=table_id,
+                column_id='metadata',
+                column_type='string',
+                size=1000,  # JSON metadata
+                required=False
+            )
+
+            self._create_column(
+                table_id=table_id,
+                column_id='is_deleted',
+                column_type='boolean',
+                required=False,
+                default=False
+            )
+
+            # Wait for columns to fully propagate
+            logger.info("Waiting for columns to propagate before creating indexes...")
+            time.sleep(2)
+
+            # Create indexes for efficient querying
+            # Most common query: get conversation between character and specific NPC
+            self._create_index(
+                table_id=table_id,
+                index_id='idx_character_npc_time',
+                index_type='key',
+                attributes=['character_id', 'npc_id', 'timestamp']
+            )
+
+            # Get all messages for a character (across all NPCs)
+            self._create_index(
+                table_id=table_id,
+                index_id='idx_character_time',
+                index_type='key',
+                attributes=['character_id', 'timestamp']
+            )
+
+            # Session-based queries
+            self._create_index(
+                table_id=table_id,
+                index_id='idx_session_time',
+                index_type='key',
+                attributes=['session_id', 'timestamp']
+            )
+
+            # Filter by context (quest, shop, lore, etc.)
+            self._create_index(
+                table_id=table_id,
+                index_id='idx_context',
+                index_type='key',
+                attributes=['context']
+            )
+
+            # Date range queries
+            self._create_index(
+                table_id=table_id,
+                index_id='idx_timestamp',
+                index_type='key',
+                attributes=['timestamp']
+            )
+
+            logger.info("Chat messages table initialized successfully", table_id=table_id)
+            return True
+
+        except AppwriteException as e:
+            logger.error("Failed to initialize chat_messages table",
+                        table_id=table_id,
+                        error=str(e),
+                        code=e.code)
+            raise
+
     def _create_column(
         self,
         table_id: str,

api/app/services/enemy_loader.py

@@ -0,0 +1,260 @@
+"""
+Enemy Loader Service - YAML-based enemy template loading.
+
+This service loads enemy definitions from YAML files, providing a data-driven
+approach to defining monsters and enemies for combat encounters.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+import yaml
+
+from app.models.enemy import EnemyTemplate, EnemyDifficulty
+from app.utils.logging import get_logger
+
+logger = get_logger(__file__)
+
+
+class EnemyLoader:
+    """
+    Loads enemy templates from YAML configuration files.
+
+    This allows game designers to define enemies without touching code.
+    Enemy files are organized by difficulty in subdirectories.
+    """
+
+    def __init__(self, data_dir: Optional[str] = None):
+        """
+        Initialize the enemy loader.
+
+        Args:
+            data_dir: Path to directory containing enemy YAML files
+                     Defaults to /app/data/enemies/
+        """
+        if data_dir is None:
+            # Default to app/data/enemies relative to this file
+            current_file = Path(__file__)
+            app_dir = current_file.parent.parent  # Go up to /app
+            data_dir = str(app_dir / "data" / "enemies")
+
+        self.data_dir = Path(data_dir)
+        self._enemy_cache: Dict[str, EnemyTemplate] = {}
+        self._loaded = False
+
+        logger.info("EnemyLoader initialized", data_dir=str(self.data_dir))
+
+    def load_enemy(self, enemy_id: str) -> Optional[EnemyTemplate]:
+        """
+        Load a single enemy template by ID.
+
+        Args:
+            enemy_id: Unique enemy identifier
+
+        Returns:
+            EnemyTemplate instance or None if not found
+        """
+        # Check cache first
+        if enemy_id in self._enemy_cache:
+            return self._enemy_cache[enemy_id]
+
+        # If not cached, try loading all enemies first
+        if not self._loaded:
+            self.load_all_enemies()
+            if enemy_id in self._enemy_cache:
+                return self._enemy_cache[enemy_id]
+
+        # Try loading from specific YAML file
+        yaml_file = self.data_dir / f"{enemy_id}.yaml"
+        if yaml_file.exists():
+            return self._load_from_file(yaml_file)
+
+        # Search in subdirectories
+        for subdir in self.data_dir.iterdir():
+            if subdir.is_dir():
+                yaml_file = subdir / f"{enemy_id}.yaml"
+                if yaml_file.exists():
+                    return self._load_from_file(yaml_file)
+
+        logger.warning("Enemy not found", enemy_id=enemy_id)
+        return None
+
+    def _load_from_file(self, yaml_file: Path) -> Optional[EnemyTemplate]:
+        """
+        Load an enemy template from a specific YAML file.
+
+        Args:
+            yaml_file: Path to the YAML file
+
+        Returns:
+            EnemyTemplate instance or None on error
+        """
+        try:
+            with open(yaml_file, 'r') as f:
+                data = yaml.safe_load(f)
+
+            enemy = EnemyTemplate.from_dict(data)
+            self._enemy_cache[enemy.enemy_id] = enemy
+
+            logger.debug("Enemy loaded", enemy_id=enemy.enemy_id, file=str(yaml_file))
+            return enemy
+
+        except Exception as e:
+            logger.error("Failed to load enemy file",
+                        file=str(yaml_file),
+                        error=str(e))
+            return None
+
+    def load_all_enemies(self) -> Dict[str, EnemyTemplate]:
+        """
+        Load all enemy templates from the data directory.
+
+        Searches both the root directory and subdirectories for YAML files.
+
+        Returns:
+            Dictionary mapping enemy_id to EnemyTemplate instance
+        """
+        if not self.data_dir.exists():
+            logger.warning("Enemy data directory not found", path=str(self.data_dir))
+            return {}
+
+        enemies = {}
+
+        # Load from root directory
+        for yaml_file in self.data_dir.glob("*.yaml"):
+            enemy = self._load_from_file(yaml_file)
+            if enemy:
+                enemies[enemy.enemy_id] = enemy
+
+        # Load from subdirectories (organized by difficulty)
+        for subdir in self.data_dir.iterdir():
+            if subdir.is_dir():
+                for yaml_file in subdir.glob("*.yaml"):
+                    enemy = self._load_from_file(yaml_file)
+                    if enemy:
+                        enemies[enemy.enemy_id] = enemy
+
+        self._loaded = True
+        logger.info("All enemies loaded", count=len(enemies))
+
+        return enemies
+
+    def get_enemies_by_difficulty(
+        self,
+        difficulty: EnemyDifficulty
+    ) -> List[EnemyTemplate]:
+        """
+        Get all enemies matching a difficulty level.
+
+        Args:
+            difficulty: Difficulty level to filter by
+
+        Returns:
+            List of EnemyTemplate instances
+        """
+        if not self._loaded:
+            self.load_all_enemies()
+
+        return [
+            enemy for enemy in self._enemy_cache.values()
+            if enemy.difficulty == difficulty
+        ]
+
+    def get_enemies_by_tag(self, tag: str) -> List[EnemyTemplate]:
+        """
+        Get all enemies with a specific tag.
+
+        Args:
+            tag: Tag to filter by (e.g., "undead", "beast", "humanoid")
+
+        Returns:
+            List of EnemyTemplate instances with that tag
+        """
+        if not self._loaded:
+            self.load_all_enemies()
+
+        return [
+            enemy for enemy in self._enemy_cache.values()
+            if enemy.has_tag(tag)
+        ]
+
+    def get_random_enemies(
+        self,
+        count: int = 1,
+        difficulty: Optional[EnemyDifficulty] = None,
+        tag: Optional[str] = None,
+        exclude_bosses: bool = True
+    ) -> List[EnemyTemplate]:
+        """
+        Get random enemies for encounter generation.
+
+        Args:
+            count: Number of enemies to select
+            difficulty: Optional difficulty filter
+            tag: Optional tag filter
+            exclude_bosses: Whether to exclude boss enemies
+
+        Returns:
+            List of randomly selected EnemyTemplate instances
+        """
+        import random
+
+        if not self._loaded:
+            self.load_all_enemies()
+
+        # Build candidate list
+        candidates = list(self._enemy_cache.values())
+
+        # Apply filters
+        if difficulty:
+            candidates = [e for e in candidates if e.difficulty == difficulty]
+        if tag:
+            candidates = [e for e in candidates if e.has_tag(tag)]
+        if exclude_bosses:
+            candidates = [e for e in candidates if not e.is_boss()]
+
+        if not candidates:
+            logger.warning("No enemies match filters",
+                         difficulty=difficulty.value if difficulty else None,
+                         tag=tag)
+            return []
+
+        # Select random enemies (with replacement if needed)
+        if len(candidates) >= count:
+            return random.sample(candidates, count)
+        else:
+            # Not enough unique enemies, allow duplicates
+            return random.choices(candidates, k=count)
+
+    def clear_cache(self) -> None:
+        """Clear the enemy cache, forcing reload on next access."""
+        self._enemy_cache.clear()
+        self._loaded = False
+        logger.debug("Enemy cache cleared")
+
+    def get_all_cached(self) -> Dict[str, EnemyTemplate]:
+        """
+        Get all cached enemies.
+
+        Returns:
+            Dictionary of cached enemy templates
+        """
+        if not self._loaded:
+            self.load_all_enemies()
+        return self._enemy_cache.copy()
+
+
+# Global instance for convenience
+_loader_instance: Optional[EnemyLoader] = None
+
+
+def get_enemy_loader() -> EnemyLoader:
+    """
+    Get the global EnemyLoader instance.
+
+    Returns:
+        Singleton EnemyLoader instance
+    """
+    global _loader_instance
+    if _loader_instance is None:
+        _loader_instance = EnemyLoader()
+    return _loader_instance

api/app/services/inventory_service.py

@@ -0,0 +1,867 @@
+"""
+Inventory Service - Manages character inventory, equipment, and consumable usage.
+
+This service provides an orchestration layer on top of the Character model's
+inventory methods, adding:
+- Input validation and error handling
+- Equipment slot validation (weapon vs armor slots)
+- Level and class requirement checks
+- Consumable effect application
+- Integration with CharacterService for persistence
+
+Usage:
+    from app.services.inventory_service import get_inventory_service
+
+    inventory_service = get_inventory_service()
+    inventory_service.equip_item(character, item, "weapon", user_id)
+    inventory_service.use_consumable(character, "health_potion_small", user_id)
+"""
+
+from typing import List, Optional, Dict, Any, Tuple
+from dataclasses import dataclass
+
+from app.models.character import Character
+from app.models.items import Item
+from app.models.effects import Effect
+from app.models.enums import ItemType, EffectType
+from app.services.character_service import get_character_service, CharacterService
+from app.utils.logging import get_logger
+
+logger = get_logger(__file__)
+
+
+# =============================================================================
+# Custom Exceptions
+# =============================================================================
+
+class InventoryError(Exception):
+    """Base exception for inventory operations."""
+    pass
+
+
+class ItemNotFoundError(InventoryError):
+    """Raised when an item is not found in the character's inventory."""
+    pass
+
+
+class CannotEquipError(InventoryError):
+    """Raised when an item cannot be equipped (wrong slot, level requirement, etc.)."""
+    pass
+
+
+class InvalidSlotError(InventoryError):
+    """Raised when an invalid equipment slot is specified."""
+    pass
+
+
+class CannotUseItemError(InventoryError):
+    """Raised when an item cannot be used (not consumable, etc.)."""
+    pass
+
+
+class InventoryFullError(InventoryError):
+    """Raised when inventory capacity is exceeded."""
+    pass
+
+
+# =============================================================================
+# Equipment Slot Configuration
+# =============================================================================
+
+# Valid equipment slots in the game
+VALID_SLOTS = {
+    "weapon",       # Primary weapon
+    "off_hand",     # Shield or secondary weapon
+    "helmet",       # Head armor
+    "chest",        # Chest armor
+    "gloves",       # Hand armor
+    "boots",        # Foot armor
+    "accessory_1",  # Ring, amulet, etc.
+    "accessory_2",  # Secondary accessory
+}
+
+# Map item types to allowed slots
+ITEM_TYPE_SLOTS = {
+    ItemType.WEAPON: {"weapon", "off_hand"},
+    ItemType.ARMOR: {"helmet", "chest", "gloves", "boots"},
+}
+
+# Maximum inventory size (0 = unlimited)
+MAX_INVENTORY_SIZE = 100
+
+
+# =============================================================================
+# Consumable Effect Result
+# =============================================================================
+
+@dataclass
+class ConsumableResult:
+    """Result of using a consumable item."""
+
+    item_name: str
+    effects_applied: List[Dict[str, Any]]
+    hp_restored: int = 0
+    mp_restored: int = 0
+    message: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dictionary for API response."""
+        return {
+            "item_name": self.item_name,
+            "effects_applied": self.effects_applied,
+            "hp_restored": self.hp_restored,
+            "mp_restored": self.mp_restored,
+            "message": self.message,
+        }
+
+
+# =============================================================================
+# Inventory Service
+# =============================================================================
+
+class InventoryService:
+    """
+    Service for managing character inventory and equipment.
+
+    This service wraps the Character model's inventory methods with additional
+    validation, error handling, and persistence integration.
+
+    All methods that modify state will persist changes via CharacterService.
+    """
+
+    def __init__(self, character_service: Optional[CharacterService] = None):
+        """
+        Initialize inventory service.
+
+        Args:
+            character_service: Optional CharacterService instance (uses global if not provided)
+        """
+        self._character_service = character_service
+        logger.info("InventoryService initialized")
+
+    @property
+    def character_service(self) -> CharacterService:
+        """Get CharacterService instance (lazy-loaded)."""
+        if self._character_service is None:
+            self._character_service = get_character_service()
+        return self._character_service
+
+    # =========================================================================
+    # Read Operations
+    # =========================================================================
+
+    def get_inventory(self, character: Character) -> List[Item]:
+        """
+        Get all items in character's inventory.
+
+        Args:
+            character: Character instance
+
+        Returns:
+            List of Item objects in inventory
+        """
+        return list(character.inventory)
+
+    def get_equipped_items(self, character: Character) -> Dict[str, Item]:
+        """
+        Get all equipped items.
+
+        Args:
+            character: Character instance
+
+        Returns:
+            Dictionary mapping slot names to equipped Item objects
+        """
+        return dict(character.equipped)
+
+    def get_item_by_id(self, character: Character, item_id: str) -> Optional[Item]:
+        """
+        Find an item in inventory by ID.
+
+        Args:
+            character: Character instance
+            item_id: Item ID to find
+
+        Returns:
+            Item if found, None otherwise
+        """
+        for item in character.inventory:
+            if item.item_id == item_id:
+                return item
+        return None
+
+    def get_equipped_item(self, character: Character, slot: str) -> Optional[Item]:
+        """
+        Get the item equipped in a specific slot.
+
+        Args:
+            character: Character instance
+            slot: Equipment slot name
+
+        Returns:
+            Item if slot is occupied, None otherwise
+        """
+        return character.equipped.get(slot)
+
+    def get_inventory_count(self, character: Character) -> int:
+        """
+        Get the number of items in inventory.
+
+        Args:
+            character: Character instance
+
+        Returns:
+            Number of items in inventory
+        """
+        return len(character.inventory)
+
+    # =========================================================================
+    # Add/Remove Operations
+    # =========================================================================
+
+    def add_item(
+        self,
+        character: Character,
+        item: Item,
+        user_id: str,
+        save: bool = True
+    ) -> None:
+        """
+        Add an item to character's inventory.
+
+        Args:
+            character: Character instance
+            item: Item to add
+            user_id: User ID for persistence authorization
+            save: Whether to persist changes (default True)
+
+        Raises:
+            InventoryFullError: If inventory is at maximum capacity
+        """
+        # Check inventory capacity
+        if MAX_INVENTORY_SIZE > 0 and len(character.inventory) >= MAX_INVENTORY_SIZE:
+            raise InventoryFullError(
+                f"Inventory is full ({MAX_INVENTORY_SIZE} items max)"
+            )
+
+        # Add to inventory
+        character.add_item(item)
+
+        logger.info("Item added to inventory",
+                   character_id=character.character_id,
+                   item_id=item.item_id,
+                   item_name=item.get_display_name())
+
+        # Persist changes
+        if save:
+            self.character_service.update_character(character, user_id)
+
+    def remove_item(
+        self,
+        character: Character,
+        item_id: str,
+        user_id: str,
+        save: bool = True
+    ) -> Item:
+        """
+        Remove an item from character's inventory.
+
+        Args:
+            character: Character instance
+            item_id: ID of item to remove
+            user_id: User ID for persistence authorization
+            save: Whether to persist changes (default True)
+
+        Returns:
+            The removed Item
+
+        Raises:
+            ItemNotFoundError: If item is not in inventory
+        """
+        # Find item first (for better error message)
+        item = self.get_item_by_id(character, item_id)
+        if item is None:
+            raise ItemNotFoundError(f"Item not found in inventory: {item_id}")
+
+        # Remove from inventory
+        removed_item = character.remove_item(item_id)
+
+        logger.info("Item removed from inventory",
+                   character_id=character.character_id,
+                   item_id=item_id,
+                   item_name=item.get_display_name())
+
+        # Persist changes
+        if save:
+            self.character_service.update_character(character, user_id)
+
+        return removed_item
+
+    def drop_item(
+        self,
+        character: Character,
+        item_id: str,
+        user_id: str
+    ) -> Item:
+        """
+        Drop an item (remove permanently with no return).
+
+        This is an alias for remove_item, but semantically indicates
+        the item is being discarded rather than transferred.
+
+        Args:
+            character: Character instance
+            item_id: ID of item to drop
+            user_id: User ID for persistence authorization
+
+        Returns:
+            The dropped Item (for logging/notification purposes)
+
+        Raises:
+            ItemNotFoundError: If item is not in inventory
+        """
+        return self.remove_item(character, item_id, user_id, save=True)
+
+    # =========================================================================
+    # Equipment Operations
+    # =========================================================================
+
+    def equip_item(
+        self,
+        character: Character,
+        item_id: str,
+        slot: str,
+        user_id: str
+    ) -> Optional[Item]:
+        """
+        Equip an item from inventory to a specific slot.
+
+        Args:
+            character: Character instance
+            item_id: ID of item to equip (must be in inventory)
+            slot: Equipment slot to use
+            user_id: User ID for persistence authorization
+
+        Returns:
+            Previously equipped item in that slot (or None)
+
+        Raises:
+            ItemNotFoundError: If item is not in inventory
+            InvalidSlotError: If slot name is invalid
+            CannotEquipError: If item cannot be equipped (wrong type, level, etc.)
+        """
+        # Validate slot
+        if slot not in VALID_SLOTS:
+            raise InvalidSlotError(
+                f"Invalid equipment slot: '{slot}'. "
+                f"Valid slots: {', '.join(sorted(VALID_SLOTS))}"
+            )
+
+        # Find item in inventory
+        item = self.get_item_by_id(character, item_id)
+        if item is None:
+            raise ItemNotFoundError(f"Item not found in inventory: {item_id}")
+
+        # Validate item can be equipped
+        self._validate_equip(character, item, slot)
+
+        # Perform equip (Character.equip_item handles inventory management)
+        previous_item = character.equip_item(item, slot)
+
+        logger.info("Item equipped",
+                   character_id=character.character_id,
+                   item_id=item_id,
+                   slot=slot,
+                   previous_item=previous_item.item_id if previous_item else None)
+
+        # Persist changes
+        self.character_service.update_character(character, user_id)
+
+        return previous_item
+
+    def unequip_item(
+        self,
+        character: Character,
+        slot: str,
+        user_id: str
+    ) -> Optional[Item]:
+        """
+        Unequip an item from a specific slot (returns to inventory).
+
+        Args:
+            character: Character instance
+            slot: Equipment slot to unequip from
+            user_id: User ID for persistence authorization
+
+        Returns:
+            The unequipped Item (or None if slot was empty)
+
+        Raises:
+            InvalidSlotError: If slot name is invalid
+            InventoryFullError: If inventory is full and cannot receive the item
+        """
+        # Validate slot
+        if slot not in VALID_SLOTS:
+            raise InvalidSlotError(
+                f"Invalid equipment slot: '{slot}'. "
+                f"Valid slots: {', '.join(sorted(VALID_SLOTS))}"
+            )
+
+        # Check if slot has an item
+        equipped_item = character.equipped.get(slot)
+        if equipped_item is None:
+            logger.debug("Unequip from empty slot",
+                        character_id=character.character_id,
+                        slot=slot)
+            return None
+
+        # Check inventory capacity (item will return to inventory)
+        if MAX_INVENTORY_SIZE > 0 and len(character.inventory) >= MAX_INVENTORY_SIZE:
+            raise InventoryFullError(
+                "Cannot unequip: inventory is full"
+            )
+
+        # Perform unequip (Character.unequip_item handles inventory management)
+        unequipped_item = character.unequip_item(slot)
+
+        logger.info("Item unequipped",
+                   character_id=character.character_id,
+                   item_id=unequipped_item.item_id if unequipped_item else None,
+                   slot=slot)
+
+        # Persist changes
+        self.character_service.update_character(character, user_id)
+
+        return unequipped_item
+
+    def swap_equipment(
+        self,
+        character: Character,
+        item_id: str,
+        slot: str,
+        user_id: str
+    ) -> Optional[Item]:
+        """
+        Swap equipment: equip item and return the previous item.
+
+        This is semantically the same as equip_item but makes the swap
+        intention explicit.
+
+        Args:
+            character: Character instance
+            item_id: ID of item to equip
+            slot: Equipment slot to use
+            user_id: User ID for persistence authorization
+
+        Returns:
+            Previously equipped item (or None)
+        """
+        return self.equip_item(character, item_id, slot, user_id)
+
+    def _validate_equip(self, character: Character, item: Item, slot: str) -> None:
+        """
+        Validate that an item can be equipped to a slot.
+
+        Args:
+            character: Character instance
+            item: Item to validate
+            slot: Target equipment slot
+
+        Raises:
+            CannotEquipError: If item cannot be equipped
+        """
+        # Check item type is equippable
+        if item.item_type not in ITEM_TYPE_SLOTS:
+            raise CannotEquipError(
+                f"Cannot equip {item.item_type.value} items. "
+                f"Only weapons and armor can be equipped."
+            )
+
+        # Check slot matches item type
+        allowed_slots = ITEM_TYPE_SLOTS[item.item_type]
+        if slot not in allowed_slots:
+            raise CannotEquipError(
+                f"Cannot equip {item.item_type.value} to '{slot}' slot. "
+                f"Allowed slots: {', '.join(sorted(allowed_slots))}"
+            )
+
+        # Check level requirement
+        if not item.can_equip(character.level, character.class_id):
+            if character.level < item.required_level:
+                raise CannotEquipError(
+                    f"Cannot equip '{item.get_display_name()}': "
+                    f"requires level {item.required_level} (you are level {character.level})"
+                )
+            if item.required_class and item.required_class != character.class_id:
+                raise CannotEquipError(
+                    f"Cannot equip '{item.get_display_name()}': "
+                    f"requires class '{item.required_class}'"
+                )
+
+    # =========================================================================
+    # Consumable Operations
+    # =========================================================================
+
+    def use_consumable(
+        self,
+        character: Character,
+        item_id: str,
+        user_id: str,
+        current_hp: Optional[int] = None,
+        max_hp: Optional[int] = None,
+        current_mp: Optional[int] = None,
+        max_mp: Optional[int] = None
+    ) -> ConsumableResult:
+        """
+        Use a consumable item and apply its effects.
+
+        For HP/MP restoration effects, provide current/max values to calculate
+        actual restoration (clamped to max). If not provided, uses character's
+        computed max_hp from stats.
+
+        Note: Outside of combat, characters are always at full HP. During combat,
+        HP tracking is handled by the combat system and current_hp should be passed.
+
+        Args:
+            character: Character instance
+            item_id: ID of consumable to use
+            user_id: User ID for persistence authorization
+            current_hp: Current HP (for healing calculations)
+            max_hp: Maximum HP (for healing cap)
+            current_mp: Current MP (for mana restore calculations)
+            max_mp: Maximum MP (for mana restore cap)
+
+        Returns:
+            ConsumableResult with details of effects applied
+
+        Raises:
+            ItemNotFoundError: If item is not in inventory
+            CannotUseItemError: If item is not a consumable
+        """
+        # Find item in inventory
+        item = self.get_item_by_id(character, item_id)
+        if item is None:
+            raise ItemNotFoundError(f"Item not found in inventory: {item_id}")
+
+        # Validate item is consumable
+        if not item.is_consumable():
+            raise CannotUseItemError(
+                f"Cannot use '{item.get_display_name()}': not a consumable item"
+            )
+
+        # Use character computed values if not provided
+        if max_hp is None:
+            max_hp = character.max_hp
+        if current_hp is None:
+            current_hp = max_hp  # Outside combat, assume full HP
+
+        # MP handling (if character has MP system)
+        effective_stats = character.get_effective_stats()
+        if max_mp is None:
+            max_mp = getattr(effective_stats, 'magic_points', 100)
+        if current_mp is None:
+            current_mp = max_mp  # Outside combat, assume full MP
+
+        # Apply effects
+        result = self._apply_consumable_effects(
+            item, current_hp, max_hp, current_mp, max_mp
+        )
+
+        # Remove consumable from inventory (it's used up)
+        character.remove_item(item_id)
+
+        logger.info("Consumable used",
+                   character_id=character.character_id,
+                   item_id=item_id,
+                   item_name=item.get_display_name(),
+                   hp_restored=result.hp_restored,
+                   mp_restored=result.mp_restored)
+
+        # Persist changes
+        self.character_service.update_character(character, user_id)
+
+        return result
+
+    def _apply_consumable_effects(
+        self,
+        item: Item,
+        current_hp: int,
+        max_hp: int,
+        current_mp: int,
+        max_mp: int
+    ) -> ConsumableResult:
+        """
+        Apply consumable effects and calculate results.
+
+        Args:
+            item: Consumable item
+            current_hp: Current HP
+            max_hp: Maximum HP
+            current_mp: Current MP
+            max_mp: Maximum MP
+
+        Returns:
+            ConsumableResult with effect details
+        """
+        effects_applied = []
+        total_hp_restored = 0
+        total_mp_restored = 0
+        messages = []
+
+        for effect in item.effects_on_use:
+            effect_result = {
+                "effect_name": effect.name,
+                "effect_type": effect.effect_type.value,
+            }
+
+            if effect.effect_type == EffectType.HOT:
+                # Instant heal (for potions, treat HOT as instant outside combat)
+                heal_amount = effect.power * effect.stacks
+                actual_heal = min(heal_amount, max_hp - current_hp)
+                current_hp += actual_heal
+                total_hp_restored += actual_heal
+
+                effect_result["value"] = actual_heal
+                effect_result["message"] = f"Restored {actual_heal} HP"
+                messages.append(f"Restored {actual_heal} HP")
+
+            elif effect.effect_type == EffectType.BUFF:
+                # Stat buff - would be applied in combat context
+                stat_name = effect.stat_affected.value if effect.stat_affected else "unknown"
+                effect_result["stat_affected"] = stat_name
+                effect_result["modifier"] = effect.power
+                effect_result["duration"] = effect.duration
+                effect_result["message"] = f"+{effect.power} {stat_name} for {effect.duration} turns"
+                messages.append(f"+{effect.power} {stat_name}")
+
+            elif effect.effect_type == EffectType.SHIELD:
+                # Apply shield effect
+                shield_power = effect.power * effect.stacks
+                effect_result["shield_power"] = shield_power
+                effect_result["duration"] = effect.duration
+                effect_result["message"] = f"Shield for {shield_power} damage"
+                messages.append(f"Shield: {shield_power}")
+
+            else:
+                # Other effect types (DOT, DEBUFF, STUN - unusual for consumables)
+                effect_result["power"] = effect.power
+                effect_result["duration"] = effect.duration
+                effect_result["message"] = f"{effect.name} applied"
+
+            effects_applied.append(effect_result)
+
+        # Build summary message
+        summary = f"Used {item.get_display_name()}"
+        if messages:
+            summary += f": {', '.join(messages)}"
+
+        return ConsumableResult(
+            item_name=item.get_display_name(),
+            effects_applied=effects_applied,
+            hp_restored=total_hp_restored,
+            mp_restored=total_mp_restored,
+            message=summary,
+        )
+
+    def use_consumable_in_combat(
+        self,
+        character: Character,
+        item_id: str,
+        user_id: str,
+        current_hp: int,
+        max_hp: int,
+        current_mp: int = 0,
+        max_mp: int = 0
+    ) -> Tuple[ConsumableResult, List[Effect]]:
+        """
+        Use a consumable during combat.
+
+        Returns both the result summary and a list of Effect objects that
+        should be applied to the combatant for duration-based effects.
+
+        Args:
+            character: Character instance
+            item_id: ID of consumable to use
+            user_id: User ID for persistence authorization
+            current_hp: Current combat HP
+            max_hp: Maximum combat HP
+            current_mp: Current combat MP
+            max_mp: Maximum combat MP
+
+        Returns:
+            Tuple of (ConsumableResult, List[Effect]) for combat system
+
+        Raises:
+            ItemNotFoundError: If item not in inventory
+            CannotUseItemError: If item is not consumable
+        """
+        # Find item
+        item = self.get_item_by_id(character, item_id)
+        if item is None:
+            raise ItemNotFoundError(f"Item not found in inventory: {item_id}")
+
+        if not item.is_consumable():
+            raise CannotUseItemError(
+                f"Cannot use '{item.get_display_name()}': not a consumable"
+            )
+
+        # Separate instant effects from duration effects
+        instant_effects = []
+        duration_effects = []
+
+        for effect in item.effects_on_use:
+            # HOT effects in combat should tick, not instant heal
+            if effect.duration > 1 or effect.effect_type in [
+                EffectType.BUFF, EffectType.DEBUFF, EffectType.DOT,
+                EffectType.HOT, EffectType.SHIELD, EffectType.STUN
+            ]:
+                # Copy effect for combat tracking
+                combat_effect = Effect(
+                    effect_id=f"{item.item_id}_{effect.effect_id}",
+                    name=effect.name,
+                    effect_type=effect.effect_type,
+                    duration=effect.duration,
+                    power=effect.power,
+                    stat_affected=effect.stat_affected,
+                    stacks=effect.stacks,
+                    max_stacks=effect.max_stacks,
+                    source=item.item_id,
+                )
+                duration_effects.append(combat_effect)
+            else:
+                instant_effects.append(effect)
+
+        # Calculate instant effect results
+        result = self._apply_consumable_effects(
+            item, current_hp, max_hp, current_mp, max_mp
+        )
+
+        # Remove from inventory
+        character.remove_item(item_id)
+
+        logger.info("Consumable used in combat",
+                   character_id=character.character_id,
+                   item_id=item_id,
+                   duration_effects=len(duration_effects))
+
+        # Persist
+        self.character_service.update_character(character, user_id)
+
+        return result, duration_effects
+
+    # =========================================================================
+    # Bulk Operations
+    # =========================================================================
+
+    def add_items(
+        self,
+        character: Character,
+        items: List[Item],
+        user_id: str
+    ) -> int:
+        """
+        Add multiple items to inventory (e.g., loot drop).
+
+        Args:
+            character: Character instance
+            items: List of items to add
+            user_id: User ID for persistence
+
+        Returns:
+            Number of items actually added
+
+        Note:
+            Stops adding if inventory becomes full. Does not raise error
+            for partial success.
+        """
+        added_count = 0
+        for item in items:
+            try:
+                self.add_item(character, item, user_id, save=False)
+                added_count += 1
+            except InventoryFullError:
+                logger.warning("Inventory full, dropping remaining loot",
+                             character_id=character.character_id,
+                             items_dropped=len(items) - added_count)
+                break
+
+        # Save once after all items added
+        if added_count > 0:
+            self.character_service.update_character(character, user_id)
+
+        return added_count
+
+    def get_items_by_type(
+        self,
+        character: Character,
+        item_type: ItemType
+    ) -> List[Item]:
+        """
+        Get all inventory items of a specific type.
+
+        Args:
+            character: Character instance
+            item_type: Type to filter by
+
+        Returns:
+            List of matching items
+        """
+        return [
+            item for item in character.inventory
+            if item.item_type == item_type
+        ]
+
+    def get_equippable_items(
+        self,
+        character: Character,
+        slot: Optional[str] = None
+    ) -> List[Item]:
+        """
+        Get all items that can be equipped.
+
+        Args:
+            character: Character instance
+            slot: Optional slot to filter by
+
+        Returns:
+            List of equippable items (optionally filtered by slot)
+        """
+        equippable = []
+        for item in character.inventory:
+            # Skip non-equippable types
+            if item.item_type not in ITEM_TYPE_SLOTS:
+                continue
+
+            # Skip items that don't meet requirements
+            if not item.can_equip(character.level, character.class_id):
+                continue
+
+            # Filter by slot if specified
+            if slot:
+                allowed_slots = ITEM_TYPE_SLOTS[item.item_type]
+                if slot not in allowed_slots:
+                    continue
+
+            equippable.append(item)
+
+        return equippable
+
+
+# =============================================================================
+# Global Instance
+# =============================================================================
+
+_service_instance: Optional[InventoryService] = None
+
+
+def get_inventory_service() -> InventoryService:
+    """
+    Get the global InventoryService instance.
+
+    Returns:
+        Singleton InventoryService instance
+    """
+    global _service_instance
+    if _service_instance is None:
+        _service_instance = InventoryService()
+    return _service_instance

api/app/services/item_generator.py

@@ -0,0 +1,536 @@
+"""
+Item Generator Service - Procedural item generation with affixes.
+
+This service generates Diablo-style items by combining base templates with
+random affixes, creating items like "Flaming Dagger of Strength".
+"""
+
+import uuid
+import random
+from typing import List, Optional, Tuple, Dict, Any
+
+from app.models.items import Item
+from app.models.affixes import Affix, BaseItemTemplate
+from app.models.enums import ItemType, ItemRarity, DamageType, AffixTier
+from app.services.affix_loader import get_affix_loader, AffixLoader
+from app.services.base_item_loader import get_base_item_loader, BaseItemLoader
+from app.utils.logging import get_logger
+
+logger = get_logger(__file__)
+
+# Affix count by rarity (COMMON/UNCOMMON get 0 affixes - plain items)
+AFFIX_COUNTS = {
+    ItemRarity.COMMON: 0,
+    ItemRarity.UNCOMMON: 0,
+    ItemRarity.RARE: 1,
+    ItemRarity.EPIC: 2,
+    ItemRarity.LEGENDARY: 3,
+}
+
+# Tier selection probabilities by rarity
+# Higher rarity items have better chance at higher tier affixes
+TIER_WEIGHTS = {
+    ItemRarity.RARE: {
+        AffixTier.MINOR: 0.8,
+        AffixTier.MAJOR: 0.2,
+        AffixTier.LEGENDARY: 0.0,
+    },
+    ItemRarity.EPIC: {
+        AffixTier.MINOR: 0.3,
+        AffixTier.MAJOR: 0.7,
+        AffixTier.LEGENDARY: 0.0,
+    },
+    ItemRarity.LEGENDARY: {
+        AffixTier.MINOR: 0.1,
+        AffixTier.MAJOR: 0.4,
+        AffixTier.LEGENDARY: 0.5,
+    },
+}
+
+# Rarity value multipliers (higher rarity = more valuable)
+RARITY_VALUE_MULTIPLIER = {
+    ItemRarity.COMMON: 1.0,
+    ItemRarity.UNCOMMON: 1.5,
+    ItemRarity.RARE: 2.5,
+    ItemRarity.EPIC: 5.0,
+    ItemRarity.LEGENDARY: 10.0,
+}
+
+
+class ItemGenerator:
+    """
+    Generates procedural items with Diablo-style naming.
+
+    This service combines base item templates with randomly selected affixes
+    to create unique items with combined stats and generated names.
+    """
+
+    def __init__(
+        self,
+        affix_loader: Optional[AffixLoader] = None,
+        base_item_loader: Optional[BaseItemLoader] = None
+    ):
+        """
+        Initialize the item generator.
+
+        Args:
+            affix_loader: Optional custom AffixLoader instance
+            base_item_loader: Optional custom BaseItemLoader instance
+        """
+        self.affix_loader = affix_loader or get_affix_loader()
+        self.base_item_loader = base_item_loader or get_base_item_loader()
+
+        logger.info("ItemGenerator initialized")
+
+    def generate_item(
+        self,
+        item_type: str,
+        rarity: ItemRarity,
+        character_level: int = 1,
+        base_template_id: Optional[str] = None
+    ) -> Optional[Item]:
+        """
+        Generate a procedural item.
+
+        Args:
+            item_type: "weapon" or "armor"
+            rarity: Target rarity
+            character_level: Player level for template eligibility
+            base_template_id: Optional specific base template to use
+
+        Returns:
+            Generated Item instance or None if generation fails
+        """
+        # 1. Get base template
+        base_template = self._get_base_template(
+            item_type, rarity, character_level, base_template_id
+        )
+        if not base_template:
+            logger.warning(
+                "No base template available",
+                item_type=item_type,
+                rarity=rarity.value,
+                level=character_level
+            )
+            return None
+
+        # 2. Get affix count for this rarity
+        affix_count = AFFIX_COUNTS.get(rarity, 0)
+
+        # 3. Select affixes
+        prefixes, suffixes = self._select_affixes(
+            base_template.item_type, rarity, affix_count
+        )
+
+        # 4. Build the item
+        item = self._build_item(base_template, rarity, prefixes, suffixes)
+
+        logger.info(
+            "Item generated",
+            item_id=item.item_id,
+            name=item.get_display_name(),
+            rarity=rarity.value,
+            affixes=[a.affix_id for a in prefixes + suffixes]
+        )
+
+        return item
+
+    def _get_base_template(
+        self,
+        item_type: str,
+        rarity: ItemRarity,
+        character_level: int,
+        template_id: Optional[str] = None
+    ) -> Optional[BaseItemTemplate]:
+        """
+        Get a base template for item generation.
+
+        Args:
+            item_type: Type of item
+            rarity: Target rarity
+            character_level: Player level
+            template_id: Optional specific template ID
+
+        Returns:
+            BaseItemTemplate instance or None
+        """
+        if template_id:
+            return self.base_item_loader.get_template(template_id)
+
+        return self.base_item_loader.get_random_template(
+            item_type, rarity.value, character_level
+        )
+
+    def _select_affixes(
+        self,
+        item_type: str,
+        rarity: ItemRarity,
+        count: int
+    ) -> Tuple[List[Affix], List[Affix]]:
+        """
+        Select random affixes for an item.
+
+        Distribution logic:
+        - RARE (1 affix): 50% chance prefix, 50% chance suffix
+        - EPIC (2 affixes): 1 prefix AND 1 suffix
+        - LEGENDARY (3 affixes): Mix of prefixes and suffixes
+
+        Args:
+            item_type: Type of item
+            rarity: Item rarity
+            count: Number of affixes to select
+
+        Returns:
+            Tuple of (prefixes, suffixes)
+        """
+        prefixes: List[Affix] = []
+        suffixes: List[Affix] = []
+        used_ids: List[str] = []
+
+        if count == 0:
+            return prefixes, suffixes
+
+        # Determine tier for affix selection
+        tier = self._roll_affix_tier(rarity)
+
+        if count == 1:
+            # RARE: Either prefix OR suffix (50/50)
+            if random.random() < 0.5:
+                prefix = self.affix_loader.get_random_prefix(
+                    item_type, rarity.value, tier, used_ids
+                )
+                if prefix:
+                    prefixes.append(prefix)
+                    used_ids.append(prefix.affix_id)
+            else:
+                suffix = self.affix_loader.get_random_suffix(
+                    item_type, rarity.value, tier, used_ids
+                )
+                if suffix:
+                    suffixes.append(suffix)
+                    used_ids.append(suffix.affix_id)
+
+        elif count == 2:
+            # EPIC: 1 prefix AND 1 suffix
+            tier = self._roll_affix_tier(rarity)
+            prefix = self.affix_loader.get_random_prefix(
+                item_type, rarity.value, tier, used_ids
+            )
+            if prefix:
+                prefixes.append(prefix)
+                used_ids.append(prefix.affix_id)
+
+            tier = self._roll_affix_tier(rarity)
+            suffix = self.affix_loader.get_random_suffix(
+                item_type, rarity.value, tier, used_ids
+            )
+            if suffix:
+                suffixes.append(suffix)
+                used_ids.append(suffix.affix_id)
+
+        elif count >= 3:
+            # LEGENDARY: Mix of prefixes and suffixes
+            # Try: 2 prefixes + 1 suffix OR 1 prefix + 2 suffixes
+            distribution = random.choice([(2, 1), (1, 2)])
+            prefix_count, suffix_count = distribution
+
+            for _ in range(prefix_count):
+                tier = self._roll_affix_tier(rarity)
+                prefix = self.affix_loader.get_random_prefix(
+                    item_type, rarity.value, tier, used_ids
+                )
+                if prefix:
+                    prefixes.append(prefix)
+                    used_ids.append(prefix.affix_id)
+
+            for _ in range(suffix_count):
+                tier = self._roll_affix_tier(rarity)
+                suffix = self.affix_loader.get_random_suffix(
+                    item_type, rarity.value, tier, used_ids
+                )
+                if suffix:
+                    suffixes.append(suffix)
+                    used_ids.append(suffix.affix_id)
+
+        return prefixes, suffixes
+
+    def _roll_affix_tier(self, rarity: ItemRarity) -> Optional[AffixTier]:
+        """
+        Roll for affix tier based on item rarity.
+
+        Args:
+            rarity: Item rarity
+
+        Returns:
+            Selected AffixTier or None for no tier filter
+        """
+        weights = TIER_WEIGHTS.get(rarity)
+        if not weights:
+            return None
+
+        tiers = list(weights.keys())
+        tier_weights = list(weights.values())
+
+        # Filter out zero-weight options
+        valid_tiers = []
+        valid_weights = []
+        for t, w in zip(tiers, tier_weights):
+            if w > 0:
+                valid_tiers.append(t)
+                valid_weights.append(w)
+
+        if not valid_tiers:
+            return None
+
+        return random.choices(valid_tiers, weights=valid_weights, k=1)[0]
+
+    def _build_item(
+        self,
+        base_template: BaseItemTemplate,
+        rarity: ItemRarity,
+        prefixes: List[Affix],
+        suffixes: List[Affix]
+    ) -> Item:
+        """
+        Build an Item from base template and affixes.
+
+        Args:
+            base_template: Base item template
+            rarity: Item rarity
+            prefixes: List of prefix affixes
+            suffixes: List of suffix affixes
+
+        Returns:
+            Fully constructed Item instance
+        """
+        # Generate unique ID
+        item_id = f"gen_{uuid.uuid4().hex[:12]}"
+
+        # Build generated name
+        generated_name = self._build_name(base_template.name, prefixes, suffixes)
+
+        # Combine stats from all affixes
+        combined_stats = self._combine_affix_stats(prefixes + suffixes)
+
+        # Calculate final item values
+        item_type = ItemType.WEAPON if base_template.item_type == "weapon" else ItemType.ARMOR
+
+        # Base values from template
+        damage = base_template.base_damage + combined_stats["damage_bonus"]
+        spell_power = base_template.base_spell_power  # Magical weapon damage
+        defense = base_template.base_defense + combined_stats["defense_bonus"]
+        resistance = base_template.base_resistance + combined_stats["resistance_bonus"]
+        crit_chance = base_template.crit_chance + combined_stats["crit_chance_bonus"]
+        crit_multiplier = base_template.crit_multiplier + combined_stats["crit_multiplier_bonus"]
+
+        # Calculate value with rarity multiplier
+        base_value = base_template.base_value
+        rarity_mult = RARITY_VALUE_MULTIPLIER.get(rarity, 1.0)
+        # Add value for each affix
+        affix_value = len(prefixes + suffixes) * 25
+        final_value = int((base_value + affix_value) * rarity_mult)
+
+        # Determine elemental damage type (from prefix affixes)
+        elemental_damage_type = None
+        elemental_ratio = 0.0
+        for prefix in prefixes:
+            if prefix.applies_elemental_damage():
+                elemental_damage_type = prefix.damage_type
+                elemental_ratio = prefix.elemental_ratio
+                break  # Use first elemental prefix
+
+        # Track applied affixes
+        applied_affixes = [a.affix_id for a in prefixes + suffixes]
+
+        # Create the item
+        item = Item(
+            item_id=item_id,
+            name=base_template.name,  # Base name
+            item_type=item_type,
+            rarity=rarity,
+            description=base_template.description,
+            value=final_value,
+            is_tradeable=True,
+            stat_bonuses=combined_stats["stat_bonuses"],
+            effects_on_use=[],  # Not a consumable
+            damage=damage,
+            spell_power=spell_power,  # Magical weapon damage bonus
+            damage_type=DamageType(base_template.damage_type) if damage > 0 else None,
+            crit_chance=crit_chance,
+            crit_multiplier=crit_multiplier,
+            elemental_damage_type=elemental_damage_type,
+            physical_ratio=1.0 - elemental_ratio if elemental_ratio > 0 else 1.0,
+            elemental_ratio=elemental_ratio,
+            defense=defense,
+            resistance=resistance,
+            required_level=base_template.required_level,
+            required_class=None,
+            # Affix tracking
+            applied_affixes=applied_affixes,
+            base_template_id=base_template.template_id,
+            generated_name=generated_name,
+            is_generated=True,
+        )
+
+        return item
+
+    def _build_name(
+        self,
+        base_name: str,
+        prefixes: List[Affix],
+        suffixes: List[Affix]
+    ) -> str:
+        """
+        Build the full item name with affixes.
+
+        Examples:
+        - RARE (1 prefix): "Flaming Dagger"
+        - RARE (1 suffix): "Dagger of Strength"
+        - EPIC: "Flaming Dagger of Strength"
+        - LEGENDARY: "Blazing Glacial Dagger of the Titan"
+
+        Note: Rarity is NOT included in name (shown via UI).
+
+        Args:
+            base_name: Base item name (e.g., "Dagger")
+            prefixes: List of prefix affixes
+            suffixes: List of suffix affixes
+
+        Returns:
+            Full generated name string
+        """
+        parts = []
+
+        # Add prefix names (in order)
+        for prefix in prefixes:
+            parts.append(prefix.name)
+
+        # Add base name
+        parts.append(base_name)
+
+        # Build name string from parts
+        name = " ".join(parts)
+
+        # Add suffix names (they include "of")
+        for suffix in suffixes:
+            name += f" {suffix.name}"
+
+        return name
+
+    def _combine_affix_stats(self, affixes: List[Affix]) -> Dict[str, Any]:
+        """
+        Combine stats from multiple affixes.
+
+        Args:
+            affixes: List of affixes to combine
+
+        Returns:
+            Dictionary with combined stat values
+        """
+        combined = {
+            "stat_bonuses": {},
+            "damage_bonus": 0,
+            "defense_bonus": 0,
+            "resistance_bonus": 0,
+            "crit_chance_bonus": 0.0,
+            "crit_multiplier_bonus": 0.0,
+        }
+
+        for affix in affixes:
+            # Combine stat bonuses
+            for stat_name, bonus in affix.stat_bonuses.items():
+                current = combined["stat_bonuses"].get(stat_name, 0)
+                combined["stat_bonuses"][stat_name] = current + bonus
+
+            # Combine direct bonuses
+            combined["damage_bonus"] += affix.damage_bonus
+            combined["defense_bonus"] += affix.defense_bonus
+            combined["resistance_bonus"] += affix.resistance_bonus
+            combined["crit_chance_bonus"] += affix.crit_chance_bonus
+            combined["crit_multiplier_bonus"] += affix.crit_multiplier_bonus
+
+        return combined
+
+    def generate_loot_drop(
+        self,
+        character_level: int,
+        luck_stat: int = 8,
+        item_type: Optional[str] = None
+    ) -> Optional[Item]:
+        """
+        Generate a random loot drop with luck-influenced rarity.
+
+        Args:
+            character_level: Player level
+            luck_stat: Player's luck stat (affects rarity chance)
+            item_type: Optional item type filter
+
+        Returns:
+            Generated Item or None
+        """
+        # Choose random item type if not specified
+        if item_type is None:
+            item_type = random.choice(["weapon", "armor"])
+
+        # Roll rarity with luck bonus
+        rarity = self._roll_rarity(luck_stat)
+
+        return self.generate_item(item_type, rarity, character_level)
+
+    def _roll_rarity(self, luck_stat: int) -> ItemRarity:
+        """
+        Roll item rarity with luck bonus.
+
+        Base chances (luck 8):
+        - COMMON: 50%
+        - UNCOMMON: 30%
+        - RARE: 15%
+        - EPIC: 4%
+        - LEGENDARY: 1%
+
+        Luck modifies these chances slightly.
+
+        Args:
+            luck_stat: Player's luck stat
+
+        Returns:
+            Rolled ItemRarity
+        """
+        # Calculate luck bonus (luck 8 = baseline)
+        luck_bonus = (luck_stat - 8) * 0.005
+
+        roll = random.random()
+
+        # Thresholds (cumulative)
+        legendary_threshold = 0.01 + luck_bonus
+        epic_threshold = legendary_threshold + 0.04 + luck_bonus * 2
+        rare_threshold = epic_threshold + 0.15 + luck_bonus * 3
+        uncommon_threshold = rare_threshold + 0.30
+
+        if roll < legendary_threshold:
+            return ItemRarity.LEGENDARY
+        elif roll < epic_threshold:
+            return ItemRarity.EPIC
+        elif roll < rare_threshold:
+            return ItemRarity.RARE
+        elif roll < uncommon_threshold:
+            return ItemRarity.UNCOMMON
+        else:
+            return ItemRarity.COMMON
+
+
+# Global instance for convenience
+_generator_instance: Optional[ItemGenerator] = None
+
+
+def get_item_generator() -> ItemGenerator:
+    """
+    Get the global ItemGenerator instance.
+
+    Returns:
+        Singleton ItemGenerator instance
+    """
+    global _generator_instance
+    if _generator_instance is None:
+        _generator_instance = ItemGenerator()
+    return _generator_instance

api/app/services/npc_loader.py

@@ -212,6 +212,7 @@ class NPCLoader:
             name=data["name"],
             role=data["role"],
             location_id=data["location_id"],
+            image_url=data.get("image_url"),
             personality=personality,
             appearance=appearance,
             knowledge=knowledge,

api/app/services/rate_limiter_service.py

@@ -29,6 +29,7 @@ from typing import Optional
 from app.services.redis_service import RedisService, RedisServiceError
 from app.ai.model_selector import UserTier
 from app.utils.logging import get_logger
+from app.config import get_config
 
 
 # Initialize logger
@@ -75,25 +76,13 @@ class RateLimiterService:
     This service uses Redis to track daily AI usage per user and enforces
     limits based on subscription tier. Counters reset daily at midnight UTC.
 
-    Tier Limits:
-        - Free: 20 turns/day
-        - Basic: 50 turns/day
-        - Premium: 100 turns/day
-        - Elite: 200 turns/day
+    Tier limits are loaded from config (rate_limiting.tiers.{tier}.ai_calls_per_day).
+    A value of -1 means unlimited.
 
     Attributes:
         redis: RedisService instance for counter storage
-        tier_limits: Mapping of tier to daily turn limit
     """
 
-    # Daily turn limits per tier
-    TIER_LIMITS = {
-        UserTier.FREE: 20,
-        UserTier.BASIC: 50,
-        UserTier.PREMIUM: 100,
-        UserTier.ELITE: 200,
-    }
-
     # Daily DM question limits per tier
     DM_QUESTION_LIMITS = {
         UserTier.FREE: 10,
@@ -118,7 +107,7 @@ class RateLimiterService:
 
         logger.info(
             "RateLimiterService initialized",
-            tier_limits=self.TIER_LIMITS
+            dm_question_limits=self.DM_QUESTION_LIMITS
         )
 
     def _get_daily_key(self, user_id: str, day: Optional[date] = None) -> str:
@@ -167,15 +156,27 @@ class RateLimiterService:
 
     def get_limit_for_tier(self, user_tier: UserTier) -> int:
         """
-        Get the daily turn limit for a specific tier.
+        Get the daily turn limit for a specific tier from config.
 
         Args:
             user_tier: The user's subscription tier
 
         Returns:
-            Daily turn limit for the tier
+            Daily turn limit for the tier (-1 means unlimited)
         """
-        return self.TIER_LIMITS.get(user_tier, self.TIER_LIMITS[UserTier.FREE])
+        config = get_config()
+        tier_name = user_tier.value.lower()
+        tier_config = config.rate_limiting.tiers.get(tier_name)
+
+        if tier_config:
+            return tier_config.ai_calls_per_day
+
+        # Fallback to default if tier not found in config
+        logger.warning(
+            "Tier not found in config, using default limit",
+            tier=tier_name
+        )
+        return 50  # Default fallback
 
     def get_current_usage(self, user_id: str) -> int:
         """
@@ -227,9 +228,19 @@ class RateLimiterService:
             RateLimitExceeded: If the user has reached their daily limit
             RedisServiceError: If Redis operation fails
         """
-        current_usage = self.get_current_usage(user_id)
         limit = self.get_limit_for_tier(user_tier)
 
+        # -1 means unlimited
+        if limit == -1:
+            logger.debug(
+                "Rate limit check passed (unlimited)",
+                user_id=user_id,
+                user_tier=user_tier.value
+            )
+            return
+
+        current_usage = self.get_current_usage(user_id)
+
         if current_usage >= limit:
             reset_time = self._get_reset_time()
 
@@ -308,11 +319,15 @@ class RateLimiterService:
             user_tier: The user's subscription tier
 
         Returns:
-            Number of turns remaining (0 if limit reached)
+            Number of turns remaining (-1 if unlimited, 0 if limit reached)
         """
-        current_usage = self.get_current_usage(user_id)
         limit = self.get_limit_for_tier(user_tier)
 
+        # -1 means unlimited
+        if limit == -1:
+            return -1
+
+        current_usage = self.get_current_usage(user_id)
         remaining = max(0, limit - current_usage)
 
         logger.debug(
@@ -339,16 +354,25 @@ class RateLimiterService:
                 - user_id: User identifier
                 - user_tier: Subscription tier
                 - current_usage: Current daily usage
-                - daily_limit: Daily limit for tier
-                - remaining: Remaining turns
+                - daily_limit: Daily limit for tier (-1 means unlimited)
+                - remaining: Remaining turns (-1 if unlimited)
                 - reset_time: ISO format UTC reset time
-                - is_limited: Whether limit has been reached
+                - is_limited: Whether limit has been reached (always False if unlimited)
+                - is_unlimited: Whether user has unlimited turns
         """
         current_usage = self.get_current_usage(user_id)
         limit = self.get_limit_for_tier(user_tier)
-        remaining = max(0, limit - current_usage)
         reset_time = self._get_reset_time()
 
+        # Handle unlimited tier (-1)
+        is_unlimited = (limit == -1)
+        if is_unlimited:
+            remaining = -1
+            is_limited = False
+        else:
+            remaining = max(0, limit - current_usage)
+            is_limited = current_usage >= limit
+
         info = {
             "user_id": user_id,
             "user_tier": user_tier.value,
@@ -356,7 +380,8 @@ class RateLimiterService:
             "daily_limit": limit,
             "remaining": remaining,
             "reset_time": reset_time.isoformat(),
-            "is_limited": current_usage >= limit
+            "is_limited": is_limited,
+            "is_unlimited": is_unlimited
         }
 
         logger.debug("Retrieved usage info", **info)

api/app/services/session_cache_service.py

@@ -0,0 +1,346 @@
+"""
+Session Cache Service
+
+This service provides Redis-based caching for authenticated sessions to reduce
+Appwrite API calls. Instead of validating every request with Appwrite, we cache
+the session data and validate periodically (default: every 5 minutes).
+
+Security Features:
+- Session tokens are hashed (SHA-256) before use as cache keys
+- Session expiry is checked on every cache hit
+- Explicit invalidation on logout and password change
+- Graceful degradation on Redis failure (falls back to Appwrite)
+
+Usage:
+    from app.services.session_cache_service import SessionCacheService
+
+    cache = SessionCacheService()
+
+    # Get cached user (returns None on miss)
+    user = cache.get(token)
+
+    # Cache a validated session
+    cache.set(token, user_data, session_expire)
+
+    # Invalidate on logout
+    cache.invalidate_token(token)
+
+    # Invalidate all user sessions on password change
+    cache.invalidate_user(user_id)
+"""
+
+import hashlib
+import time
+from datetime import datetime, timezone
+from typing import Optional, Any, Dict
+
+from app.services.redis_service import RedisService, RedisServiceError
+from app.services.appwrite_service import UserData
+from app.config import get_config
+from app.utils.logging import get_logger
+
+
+# Initialize logger
+logger = get_logger(__file__)
+
+# Cache key prefixes
+SESSION_CACHE_PREFIX = "session_cache:"
+USER_INVALIDATION_PREFIX = "user_invalidated:"
+
+
+class SessionCacheService:
+    """
+    Redis-based session cache service.
+
+    This service caches validated session data to reduce the number of
+    Appwrite API calls per request. Sessions are cached with a configurable
+    TTL (default: 5 minutes) and are explicitly invalidated on logout or
+    password change.
+
+    Attributes:
+        enabled: Whether caching is enabled
+        ttl_seconds: Cache TTL in seconds
+        redis: RedisService instance
+    """
+
+    def __init__(self):
+        """
+        Initialize the session cache service.
+
+        Reads configuration from the auth.session_cache config section.
+        If caching is disabled or Redis connection fails, operates in
+        pass-through mode (always returns None).
+        """
+        self.config = get_config()
+        self.enabled = self.config.auth.session_cache.enabled
+        self.ttl_seconds = self.config.auth.session_cache.ttl_seconds
+        self.redis_db = self.config.auth.session_cache.redis_db
+        self._redis: Optional[RedisService] = None
+
+        if self.enabled:
+            try:
+                # Build Redis URL with the session cache database
+                redis_url = f"redis://{self.config.redis.host}:{self.config.redis.port}/{self.redis_db}"
+                self._redis = RedisService(redis_url=redis_url)
+                logger.info(
+                    "Session cache service initialized",
+                    ttl_seconds=self.ttl_seconds,
+                    redis_db=self.redis_db
+                )
+            except RedisServiceError as e:
+                logger.warning(
+                    "Failed to initialize session cache, operating in pass-through mode",
+                    error=str(e)
+                )
+                self.enabled = False
+
+    def _hash_token(self, token: str) -> str:
+        """
+        Hash a session token for use as a cache key.
+
+        Tokens are hashed to prevent enumeration attacks if Redis is
+        compromised. We use the first 32 characters of the SHA-256 hash
+        as a balance between collision resistance and key length.
+
+        Args:
+            token: The raw session token
+
+        Returns:
+            First 32 characters of the SHA-256 hash
+        """
+        return hashlib.sha256(token.encode()).hexdigest()[:32]
+
+    def _get_cache_key(self, token: str) -> str:
+        """
+        Generate a cache key for a session token.
+
+        Args:
+            token: The raw session token
+
+        Returns:
+            Cache key in format "session_cache:{hashed_token}"
+        """
+        return f"{SESSION_CACHE_PREFIX}{self._hash_token(token)}"
+
+    def _get_invalidation_key(self, user_id: str) -> str:
+        """
+        Generate an invalidation marker key for a user.
+
+        Args:
+            user_id: The user ID
+
+        Returns:
+            Invalidation key in format "user_invalidated:{user_id}"
+        """
+        return f"{USER_INVALIDATION_PREFIX}{user_id}"
+
+    def get(self, token: str) -> Optional[UserData]:
+        """
+        Retrieve cached user data for a session token.
+
+        This method:
+        1. Checks if caching is enabled
+        2. Retrieves cached data from Redis
+        3. Validates session hasn't expired
+        4. Checks user hasn't been invalidated (password change)
+        5. Returns UserData if valid, None otherwise
+
+        Args:
+            token: The session token to look up
+
+        Returns:
+            UserData if cache hit and valid, None if miss or invalid
+        """
+        if not self.enabled or not self._redis:
+            return None
+
+        try:
+            cache_key = self._get_cache_key(token)
+            cached_data = self._redis.get_json(cache_key)
+
+            if cached_data is None:
+                logger.debug("Session cache miss", cache_key=cache_key[:16])
+                return None
+
+            # Check if session has expired
+            session_expire = cached_data.get("session_expire")
+            if session_expire:
+                expire_time = datetime.fromisoformat(session_expire)
+                # Ensure both datetimes are timezone-aware for comparison
+                now = datetime.now(timezone.utc)
+                if expire_time.tzinfo is None:
+                    expire_time = expire_time.replace(tzinfo=timezone.utc)
+                if expire_time < now:
+                    logger.debug("Cached session expired", cache_key=cache_key[:16])
+                    self._redis.delete(cache_key)
+                    return None
+
+            # Check if user has been invalidated (password change)
+            user_id = cached_data.get("user_id")
+            if user_id:
+                invalidation_key = self._get_invalidation_key(user_id)
+                invalidated_at = self._redis.get(invalidation_key)
+                if invalidated_at:
+                    cached_at = cached_data.get("cached_at", 0)
+                    if float(invalidated_at) > cached_at:
+                        logger.debug(
+                            "User invalidated after cache, rejecting",
+                            user_id=user_id
+                        )
+                        self._redis.delete(cache_key)
+                        return None
+
+            # Reconstruct UserData
+            user_data = UserData(
+                id=cached_data["user_id"],
+                email=cached_data["email"],
+                name=cached_data["name"],
+                email_verified=cached_data["email_verified"],
+                tier=cached_data["tier"],
+                created_at=datetime.fromisoformat(cached_data["created_at"]),
+                updated_at=datetime.fromisoformat(cached_data["updated_at"])
+            )
+
+            logger.debug("Session cache hit", user_id=user_data.id)
+            return user_data
+
+        except RedisServiceError as e:
+            logger.warning("Session cache read failed, falling back to Appwrite", error=str(e))
+            return None
+        except (KeyError, ValueError, TypeError) as e:
+            logger.warning("Invalid cached session data", error=str(e))
+            return None
+
+    def set(
+        self,
+        token: str,
+        user_data: UserData,
+        session_expire: datetime
+    ) -> bool:
+        """
+        Cache a validated session.
+
+        Args:
+            token: The session token
+            user_data: The validated user data to cache
+            session_expire: When the session expires (from Appwrite)
+
+        Returns:
+            True if cached successfully, False otherwise
+        """
+        if not self.enabled or not self._redis:
+            return False
+
+        try:
+            cache_key = self._get_cache_key(token)
+
+            # Calculate effective TTL (min of config TTL and session remaining time)
+            # Ensure timezone-aware comparison
+            now = datetime.now(timezone.utc)
+            expire_aware = session_expire if session_expire.tzinfo else session_expire.replace(tzinfo=timezone.utc)
+            session_remaining = (expire_aware - now).total_seconds()
+            effective_ttl = min(self.ttl_seconds, max(1, int(session_remaining)))
+
+            cache_data: Dict[str, Any] = {
+                "user_id": user_data.id,
+                "email": user_data.email,
+                "name": user_data.name,
+                "email_verified": user_data.email_verified,
+                "tier": user_data.tier,
+                "created_at": user_data.created_at.isoformat() if isinstance(user_data.created_at, datetime) else user_data.created_at,
+                "updated_at": user_data.updated_at.isoformat() if isinstance(user_data.updated_at, datetime) else user_data.updated_at,
+                "session_expire": session_expire.isoformat(),
+                "cached_at": time.time()
+            }
+
+            success = self._redis.set_json(cache_key, cache_data, ttl=effective_ttl)
+
+            if success:
+                logger.debug(
+                    "Session cached",
+                    user_id=user_data.id,
+                    ttl=effective_ttl
+                )
+
+            return success
+
+        except RedisServiceError as e:
+            logger.warning("Session cache write failed", error=str(e))
+            return False
+
+    def invalidate_token(self, token: str) -> bool:
+        """
+        Invalidate a specific session token (used on logout).
+
+        Args:
+            token: The session token to invalidate
+
+        Returns:
+            True if invalidated successfully, False otherwise
+        """
+        if not self.enabled or not self._redis:
+            return False
+
+        try:
+            cache_key = self._get_cache_key(token)
+            deleted = self._redis.delete(cache_key)
+
+            logger.debug("Session cache invalidated", deleted_count=deleted)
+            return deleted > 0
+
+        except RedisServiceError as e:
+            logger.warning("Session cache invalidation failed", error=str(e))
+            return False
+
+    def invalidate_user(self, user_id: str) -> bool:
+        """
+        Invalidate all sessions for a user (used on password change).
+
+        This sets an invalidation marker with the current timestamp.
+        Any cached sessions created before this timestamp will be rejected.
+
+        Args:
+            user_id: The user ID to invalidate
+
+        Returns:
+            True if invalidation marker set successfully, False otherwise
+        """
+        if not self.enabled or not self._redis:
+            return False
+
+        try:
+            invalidation_key = self._get_invalidation_key(user_id)
+
+            # Set invalidation marker with TTL matching session duration
+            # Use the longer duration (remember_me) to ensure coverage
+            marker_ttl = self.config.auth.duration_remember_me
+            success = self._redis.set(
+                invalidation_key,
+                str(time.time()),
+                ttl=marker_ttl
+            )
+
+            if success:
+                logger.info(
+                    "User sessions invalidated",
+                    user_id=user_id,
+                    marker_ttl=marker_ttl
+                )
+
+            return success
+
+        except RedisServiceError as e:
+            logger.warning("User invalidation failed", error=str(e), user_id=user_id)
+            return False
+
+    def health_check(self) -> bool:
+        """
+        Check if the session cache is healthy.
+
+        Returns:
+            True if Redis is healthy and caching is enabled, False otherwise
+        """
+        if not self.enabled or not self._redis:
+            return False
+
+        return self._redis.health_check()

api/app/services/session_service.py

@@ -19,15 +19,13 @@ from app.services.database_service import get_database_service
 from app.services.appwrite_service import AppwriteService
 from app.services.character_service import get_character_service, CharacterNotFound
 from app.services.location_loader import get_location_loader
+from app.services.chat_message_service import get_chat_message_service
 from app.utils.logging import get_logger
+from app.config import get_config
 
 logger = get_logger(__file__)
 
 
-# Session limits per user
-MAX_ACTIVE_SESSIONS = 5
-
-
 class SessionNotFound(Exception):
     """Raised when session ID doesn't exist or user doesn't own it."""
     pass
@@ -129,16 +127,22 @@ class SessionService:
             if not starting_location_type:
                 starting_location_type = LocationType.TOWN
 
-            # Check session limit
+            # Check session limit based on user's subscription tier
+            user_tier = self.appwrite.get_user_tier(user_id)
+            config = get_config()
+            tier_config = config.rate_limiting.tiers.get(user_tier)
+            max_sessions = tier_config.max_sessions if tier_config else 1
+
             active_count = self.count_user_sessions(user_id, active_only=True)
-            if active_count >= MAX_ACTIVE_SESSIONS:
+            if active_count >= max_sessions:
                 logger.warning("Session limit exceeded",
                              user_id=user_id,
+                             tier=user_tier,
                              current=active_count,
-                             limit=MAX_ACTIVE_SESSIONS)
+                             limit=max_sessions)
                 raise SessionLimitExceeded(
-                    f"Maximum active sessions reached ({active_count}/{MAX_ACTIVE_SESSIONS}). "
-                    f"Please end an existing session to start a new one."
+                    f"Maximum active sessions reached for {user_tier} tier ({active_count}/{max_sessions}). "
+                    f"Please delete an existing session to start a new one."
                 )
 
             # Generate unique session ID
@@ -409,6 +413,131 @@ class SessionService:
                         error=str(e))
             raise
 
+    def delete_session(self, session_id: str, user_id: str) -> bool:
+        """
+        Permanently delete a session from the database.
+
+        Unlike end_session(), this method removes the session document entirely
+        from the database. Use this when the user wants to free up their session
+        slot and doesn't need to preserve the game history.
+
+        Also deletes all chat messages associated with this session.
+
+        Args:
+            session_id: Session ID to delete
+            user_id: User ID for ownership validation
+
+        Returns:
+            True if deleted successfully
+
+        Raises:
+            SessionNotFound: If session doesn't exist or user doesn't own it
+        """
+        try:
+            logger.info("Deleting session", session_id=session_id, user_id=user_id)
+
+            # Verify ownership first (raises SessionNotFound if invalid)
+            self.get_session(session_id, user_id)
+
+            # Delete associated chat messages first
+            chat_service = get_chat_message_service()
+            deleted_messages = chat_service.delete_messages_by_session(session_id)
+            logger.info("Deleted associated chat messages",
+                       session_id=session_id,
+                       message_count=deleted_messages)
+
+            # Delete session from database
+            self.db.delete_document(
+                collection_id=self.collection_id,
+                document_id=session_id
+            )
+
+            logger.info("Session deleted successfully",
+                       session_id=session_id,
+                       user_id=user_id)
+            return True
+
+        except SessionNotFound:
+            raise
+        except Exception as e:
+            logger.error("Failed to delete session",
+                        session_id=session_id,
+                        error=str(e))
+            raise
+
+    def delete_sessions_by_character(self, character_id: str) -> int:
+        """
+        Delete all sessions associated with a character.
+
+        Used during character deletion to clean up orphaned sessions.
+        This method finds all sessions where the character is either:
+        - The solo character (solo_character_id)
+        - A party member in multiplayer (party_member_ids)
+
+        For each session found, this method:
+        1. Deletes all associated chat messages
+        2. Hard deletes the session document from the database
+
+        Args:
+            character_id: Character ID to delete sessions for
+
+        Returns:
+            Number of sessions deleted
+        """
+        try:
+            logger.info("Deleting sessions for character",
+                       character_id=character_id)
+
+            # Query all sessions where characterId matches
+            # The characterId field is indexed at the document level
+            documents = self.db.list_rows(
+                table_id=self.collection_id,
+                queries=[Query.equal('characterId', character_id)]
+            )
+
+            if not documents:
+                logger.debug("No sessions found for character",
+                           character_id=character_id)
+                return 0
+
+            deleted_count = 0
+            chat_service = get_chat_message_service()
+
+            for document in documents:
+                session_id = document.id
+                try:
+                    # Delete associated chat messages first
+                    deleted_messages = chat_service.delete_messages_by_session(session_id)
+                    logger.debug("Deleted chat messages for session",
+                               session_id=session_id,
+                               message_count=deleted_messages)
+
+                    # Delete session document
+                    self.db.delete_document(
+                        collection_id=self.collection_id,
+                        document_id=session_id
+                    )
+                    deleted_count += 1
+
+                except Exception as e:
+                    # Log but continue with other sessions
+                    logger.error("Failed to delete session during character cleanup",
+                               session_id=session_id,
+                               character_id=character_id,
+                               error=str(e))
+                    continue
+
+            logger.info("Sessions deleted for character",
+                       character_id=character_id,
+                       deleted_count=deleted_count)
+            return deleted_count
+
+        except Exception as e:
+            logger.error("Failed to delete sessions for character",
+                        character_id=character_id,
+                        error=str(e))
+            raise
+
     def add_conversation_entry(
         self,
         session_id: str,

api/app/services/static_item_loader.py

@@ -0,0 +1,276 @@
+"""
+Static Item Loader Service - YAML-based static item loading.
+
+This service loads predefined item definitions (consumables, materials, quest items)
+from YAML files, providing a way to reference specific items by ID in loot tables.
+
+Static items differ from procedurally generated items in that they have fixed
+properties defined in YAML rather than randomly generated affixes.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+import uuid
+import yaml
+
+from app.models.items import Item
+from app.models.effects import Effect
+from app.models.enums import ItemType, ItemRarity, EffectType
+from app.utils.logging import get_logger
+
+logger = get_logger(__file__)
+
+
+class StaticItemLoader:
+    """
+    Loads and manages static item definitions from YAML configuration files.
+
+    Static items are predefined items (consumables, materials, quest items)
+    that can be referenced by item_id in enemy loot tables.
+
+    Items are loaded from:
+    - api/app/data/static_items/consumables.yaml
+    - api/app/data/static_items/materials.yaml
+
+    Each call to get_item() creates a new Item instance with a unique ID,
+    so multiple drops of the same item_id become distinct inventory items.
+    """
+
+    def __init__(self, data_dir: Optional[str] = None):
+        """
+        Initialize the static item loader.
+
+        Args:
+            data_dir: Path to directory containing static item YAML files.
+                     Defaults to /app/data/static_items/
+        """
+        if data_dir is None:
+            # Default to app/data/static_items relative to this file
+            current_file = Path(__file__)
+            app_dir = current_file.parent.parent  # Go up to /app
+            data_dir = str(app_dir / "data" / "static_items")
+
+        self.data_dir = Path(data_dir)
+        self._cache: Dict[str, dict] = {}
+        self._loaded = False
+
+        logger.info("StaticItemLoader initialized", data_dir=str(self.data_dir))
+
+    def _ensure_loaded(self) -> None:
+        """Ensure items are loaded before any operation."""
+        if not self._loaded:
+            self._load_all()
+
+    def _load_all(self) -> None:
+        """Load all static item YAML files."""
+        if not self.data_dir.exists():
+            logger.warning(
+                "Static items directory not found",
+                path=str(self.data_dir)
+            )
+            self._loaded = True
+            return
+
+        # Load all YAML files in the directory
+        for yaml_file in self.data_dir.glob("*.yaml"):
+            self._load_file(yaml_file)
+
+        self._loaded = True
+        logger.info("Static items loaded", count=len(self._cache))
+
+    def _load_file(self, yaml_file: Path) -> None:
+        """
+        Load items from a single YAML file.
+
+        Args:
+            yaml_file: Path to the YAML file
+        """
+        try:
+            with open(yaml_file, 'r') as f:
+                data = yaml.safe_load(f)
+
+            if data is None:
+                logger.warning("Empty YAML file", file=str(yaml_file))
+                return
+
+            items = data.get("items", {})
+            for item_id, item_data in items.items():
+                # Store the template data with its ID
+                item_data["_item_id"] = item_id
+                self._cache[item_id] = item_data
+
+            logger.debug(
+                "Static items loaded from file",
+                file=str(yaml_file),
+                count=len(items)
+            )
+
+        except Exception as e:
+            logger.error(
+                "Failed to load static items file",
+                file=str(yaml_file),
+                error=str(e)
+            )
+
+    def get_item(self, item_id: str, quantity: int = 1) -> Optional[Item]:
+        """
+        Get an item instance by ID.
+
+        Creates a new Item instance with a unique ID for each call,
+        so multiple drops become distinct inventory items.
+
+        Args:
+            item_id: The static item ID (e.g., "health_potion_small")
+            quantity: Requested quantity (not used for individual item,
+                     but available for future stackable item support)
+
+        Returns:
+            Item instance or None if item_id not found
+        """
+        self._ensure_loaded()
+
+        template = self._cache.get(item_id)
+        if template is None:
+            logger.warning("Static item not found", item_id=item_id)
+            return None
+
+        # Create new instance with unique ID
+        instance_id = f"{item_id}_{uuid.uuid4().hex[:8]}"
+
+        # Parse item type
+        item_type_str = template.get("item_type", "quest_item")
+        try:
+            item_type = ItemType(item_type_str)
+        except ValueError:
+            logger.warning(
+                "Unknown item type, defaulting to quest_item",
+                item_type=item_type_str,
+                item_id=item_id
+            )
+            item_type = ItemType.QUEST_ITEM
+
+        # Parse rarity
+        rarity_str = template.get("rarity", "common")
+        try:
+            rarity = ItemRarity(rarity_str)
+        except ValueError:
+            logger.warning(
+                "Unknown rarity, defaulting to common",
+                rarity=rarity_str,
+                item_id=item_id
+            )
+            rarity = ItemRarity.COMMON
+
+        # Parse effects if present
+        effects = []
+        for effect_data in template.get("effects_on_use", []):
+            try:
+                effect = self._parse_effect(effect_data)
+                if effect:
+                    effects.append(effect)
+            except Exception as e:
+                logger.warning(
+                    "Failed to parse effect",
+                    item_id=item_id,
+                    error=str(e)
+                )
+
+        # Parse stat bonuses if present
+        stat_bonuses = template.get("stat_bonuses", {})
+
+        return Item(
+            item_id=instance_id,
+            name=template.get("name", item_id),
+            item_type=item_type,
+            rarity=rarity,
+            description=template.get("description", ""),
+            value=template.get("value", 1),
+            is_tradeable=template.get("is_tradeable", True),
+            stat_bonuses=stat_bonuses,
+            effects_on_use=effects,
+        )
+
+    def _parse_effect(self, effect_data: Dict) -> Optional[Effect]:
+        """
+        Parse an effect from YAML data.
+
+        Supports simplified YAML format where effect_type is a string.
+
+        Args:
+            effect_data: Effect definition from YAML
+
+        Returns:
+            Effect instance or None if parsing fails
+        """
+        # Parse effect type
+        effect_type_str = effect_data.get("effect_type", "buff")
+        try:
+            effect_type = EffectType(effect_type_str)
+        except ValueError:
+            logger.warning(
+                "Unknown effect type",
+                effect_type=effect_type_str
+            )
+            return None
+
+        # Generate effect ID if not provided
+        effect_id = effect_data.get(
+            "effect_id",
+            f"effect_{uuid.uuid4().hex[:8]}"
+        )
+
+        return Effect(
+            effect_id=effect_id,
+            name=effect_data.get("name", "Unknown Effect"),
+            effect_type=effect_type,
+            duration=effect_data.get("duration", 1),
+            power=effect_data.get("power", 0),
+            stacks=effect_data.get("stacks", 1),
+            max_stacks=effect_data.get("max_stacks", 5),
+        )
+
+    def get_all_item_ids(self) -> List[str]:
+        """
+        Get list of all available static item IDs.
+
+        Returns:
+            List of item_id strings
+        """
+        self._ensure_loaded()
+        return list(self._cache.keys())
+
+    def has_item(self, item_id: str) -> bool:
+        """
+        Check if an item ID exists.
+
+        Args:
+            item_id: The item ID to check
+
+        Returns:
+            True if item exists in cache
+        """
+        self._ensure_loaded()
+        return item_id in self._cache
+
+    def clear_cache(self) -> None:
+        """Clear the item cache, forcing reload on next access."""
+        self._cache.clear()
+        self._loaded = False
+        logger.debug("Static item cache cleared")
+
+
+# Global instance for convenience
+_loader_instance: Optional[StaticItemLoader] = None
+
+
+def get_static_item_loader() -> StaticItemLoader:
+    """
+    Get the global StaticItemLoader instance.
+
+    Returns:
+        Singleton StaticItemLoader instance
+    """
+    global _loader_instance
+    if _loader_instance is None:
+        _loader_instance = StaticItemLoader()
+    return _loader_instance

api/app/tasks/ai_tasks.py

@@ -51,6 +51,8 @@ from app.models.ai_usage import TaskType as UsageTaskType
 from app.ai.response_parser import parse_ai_response, ParsedAIResponse, GameStateChanges
 from app.services.item_validator import get_item_validator, ItemValidationError
 from app.services.character_service import get_character_service
+from app.services.chat_message_service import get_chat_message_service
+from app.models.chat_message import MessageContext
 
 # Import for template rendering
 from app.ai.prompt_templates import get_prompt_templates
@@ -732,28 +734,37 @@ def _process_npc_dialogue_task(
             "conversation_history": previous_dialogue,  # History before this exchange
         }
 
-        # Save dialogue exchange to character's conversation history
-        if character_id:
+        # Save dialogue exchange to chat_messages collection and update character's recent_messages cache
+        if character_id and npc_id:
             try:
-                if npc_id:
-                    character_service = get_character_service()
-                    character_service.add_npc_dialogue_exchange(
-                        character_id=character_id,
-                        user_id=user_id,
-                        npc_id=npc_id,
-                        player_line=context['conversation_topic'],
-                        npc_response=response.narrative
-                    )
-                    logger.debug(
-                        "NPC dialogue exchange saved",
-                        character_id=character_id,
-                        npc_id=npc_id
-                    )
+                # Extract location from game_state if available
+                location_id = context.get('game_state', {}).get('current_location')
+
+                # Save to chat_messages collection (also updates character's recent_messages)
+                chat_service = get_chat_message_service()
+                chat_service.save_dialogue_exchange(
+                    character_id=character_id,
+                    user_id=user_id,
+                    npc_id=npc_id,
+                    player_message=context['conversation_topic'],
+                    npc_response=response.narrative,
+                    context=MessageContext.DIALOGUE,  # Default context, can be enhanced based on quest/shop interactions
+                    metadata={},  # Can add quest_id, item_id, etc. when those systems are implemented
+                    session_id=session_id,
+                    location_id=location_id
+                )
+                logger.debug(
+                    "NPC dialogue exchange saved to chat_messages",
+                    character_id=character_id,
+                    npc_id=npc_id,
+                    location_id=location_id
+                )
             except Exception as e:
                 # Don't fail the task if history save fails
                 logger.warning(
                     "Failed to save NPC dialogue exchange",
                     character_id=character_id,
+                    npc_id=npc_id,
                     error=str(e)
                 )
 

api/app/utils/auth.py

@@ -25,6 +25,7 @@ from typing import Optional, Callable
 from flask import request, g, jsonify, redirect, url_for
 
 from app.services.appwrite_service import AppwriteService, UserData
+from app.services.session_cache_service import SessionCacheService
 from app.utils.response import unauthorized_response, forbidden_response
 from app.utils.logging import get_logger
 from app.config import get_config
@@ -54,9 +55,13 @@ def verify_session(token: str) -> Optional[UserData]:
     Verify a session token and return the associated user data.
 
     This function:
-    1. Validates the session token with Appwrite
-    2. Checks if the session is still active (not expired)
-    3. Retrieves and returns the user data
+    1. Checks the Redis session cache for a valid cached session
+    2. On cache miss, validates the session token with Appwrite
+    3. Caches the validated session for future requests
+    4. Returns the user data if valid
+
+    The session cache reduces Appwrite API calls by ~90% by caching
+    validated sessions for a configurable TTL (default: 5 minutes).
 
     Args:
         token: Session token from cookie
@@ -64,6 +69,14 @@ def verify_session(token: str) -> Optional[UserData]:
     Returns:
         UserData object if session is valid, None otherwise
     """
+    # Try cache first (reduces Appwrite calls by ~90%)
+    cache = SessionCacheService()
+    cached_user = cache.get(token)
+
+    if cached_user is not None:
+        return cached_user
+
+    # Cache miss - validate with Appwrite
     try:
         appwrite = AppwriteService()
 
@@ -72,6 +85,10 @@ def verify_session(token: str) -> Optional[UserData]:
 
         # Get user data
         user_data = appwrite.get_user(user_id=session_data.user_id)
+
+        # Cache the validated session
+        cache.set(token, user_data, session_data.expire)
+
         return user_data
 
     except AppwriteException as e:

api/config/development.yaml

@@ -12,7 +12,7 @@ server:
   workers: 1
 
 redis:
-  host: "localhost"
+  host: "redis"  # Use "redis" for Docker, "localhost" for local dev without Docker
   port: 6379
   db: 0
   max_connections: 50
@@ -51,7 +51,7 @@ ai:
 
 rate_limiting:
   enabled: true
-  storage_url: "redis://localhost:6379/1"
+  storage_url: "redis://redis:6379/1"  # Use "redis" for Docker, "localhost" for local dev
 
   tiers:
     free:
@@ -59,21 +59,25 @@ rate_limiting:
       ai_calls_per_day: 50
       custom_actions_per_day: 10
       custom_action_char_limit: 150
+      max_sessions: 1
     basic:
       requests_per_minute: 60
       ai_calls_per_day: 200
       custom_actions_per_day: 50
       custom_action_char_limit: 300
+      max_sessions: 2
     premium:
       requests_per_minute: 120
       ai_calls_per_day: 1000
       custom_actions_per_day: -1  # Unlimited
       custom_action_char_limit: 500
+      max_sessions: 3
     elite:
       requests_per_minute: 300
       ai_calls_per_day: -1  # Unlimited
       custom_actions_per_day: -1  # Unlimited
       custom_action_char_limit: 500
+      max_sessions: 5
 
 session:
   timeout_minutes: 30
@@ -107,6 +111,12 @@ auth:
   name_max_length: 50
   email_max_length: 255
 
+  # Session cache settings (Redis-based, reduces Appwrite API calls)
+  session_cache:
+    enabled: true
+    ttl_seconds: 300       # 5 minutes
+    redis_db: 2            # Separate from RQ (db 0) and rate limiting (db 1)
+
 marketplace:
   auction_check_interval: 300  # 5 minutes
   max_listings_by_tier:

api/config/production.yaml

@@ -59,21 +59,25 @@ rate_limiting:
       ai_calls_per_day: 50
       custom_actions_per_day: 10
       custom_action_char_limit: 150
+      max_sessions: 1
     basic:
       requests_per_minute: 60
       ai_calls_per_day: 200
       custom_actions_per_day: 50
       custom_action_char_limit: 300
+      max_sessions: 2
     premium:
       requests_per_minute: 120
       ai_calls_per_day: 1000
       custom_actions_per_day: -1  # Unlimited
       custom_action_char_limit: 500
+      max_sessions: 3
     elite:
       requests_per_minute: 300
       ai_calls_per_day: -1  # Unlimited
       custom_actions_per_day: -1  # Unlimited
       custom_action_char_limit: 500
+      max_sessions: 5
 
 session:
   timeout_minutes: 30
@@ -107,6 +111,12 @@ auth:
   name_max_length: 50
   email_max_length: 255
 
+  # Session cache settings (Redis-based, reduces Appwrite API calls)
+  session_cache:
+    enabled: true
+    ttl_seconds: 300       # 5 minutes
+    redis_db: 2            # Separate from RQ (db 0) and rate limiting (db 1)
+
 marketplace:
   auction_check_interval: 300  # 5 minutes
   max_listings_by_tier:

api/docs/AI_INTEGRATION.md

@@ -473,14 +473,18 @@ monthly = tracker.get_monthly_cost("user_123", 2025, 11)
 
 Tier-based daily limits enforced via `app/services/rate_limiter_service.py`.
 
+Limits are loaded from config (`rate_limiting.tiers.{tier}.ai_calls_per_day`).
+
 ### AI Calls (Turns)
 
 | Tier | Daily Limit |
 |------|------------|
-| FREE | 20 turns |
-| BASIC | 50 turns |
-| PREMIUM | 100 turns |
-| ELITE | 200 turns |
+| FREE | 50 turns |
+| BASIC | 200 turns |
+| PREMIUM | 1000 turns |
+| ELITE | Unlimited |
+
+A value of `-1` in config means unlimited.
 
 ### Custom Actions
 

api/docs/API_REFERENCE.md

@@ -31,6 +31,9 @@ Authentication handled by Appwrite with HTTP-only cookies. Sessions are stored i
 - **Duration (normal):** 24 hours
 - **Duration (remember me):** 30 days
 
+**Session Caching:**
+Sessions are cached in Redis (db 2) to reduce Appwrite API calls by ~90%. Cache TTL is 5 minutes. Sessions are explicitly invalidated on logout and password change.
+
 ### Register
 
 | | |
@@ -132,6 +135,31 @@ Set-Cookie: coc_session=<session_token>; HttpOnly; Secure; SameSite=Lax; Max-Age
 }
 ```
 
+### Get Current User
+
+| | |
+|---|---|
+| **Endpoint** | `GET /api/v1/auth/me` |
+| **Description** | Get current authenticated user's data |
+| **Auth Required** | Yes |
+
+**Response (200 OK):**
+```json
+{
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 200,
+  "timestamp": "2025-11-14T12:00:00Z",
+  "result": {
+    "id": "user_id_123",
+    "email": "player@example.com",
+    "name": "Adventurer",
+    "email_verified": true,
+    "tier": "premium"
+  }
+}
+```
+
 ### Verify Email
 
 | | |
@@ -435,7 +463,7 @@ Set-Cookie: coc_session=<session_token>; HttpOnly; Secure; SameSite=Lax; Max-Age
 | | |
 |---|---|
 | **Endpoint** | `DELETE /api/v1/characters/<id>` |
-| **Description** | Delete character (soft delete - marks as inactive) |
+| **Description** | Permanently delete character and all associated game sessions |
 | **Auth Required** | Yes |
 
 **Response (200 OK):**
@@ -740,8 +768,75 @@ Set-Cookie: coc_session=<session_token>; HttpOnly; Secure; SameSite=Lax; Max-Age
 
 ---
 
+## Health
+
+### Health Check
+
+| | |
+|---|---|
+| **Endpoint** | `GET /api/v1/health` |
+| **Description** | Check API service status and version |
+| **Auth Required** | No |
+
+**Response (200 OK):**
+```json
+{
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 200,
+  "timestamp": "2025-11-16T10:30:00Z",
+  "result": {
+    "status": "ok",
+    "service": "Code of Conquest API",
+    "version": "0.1.0"
+  },
+  "error": null,
+  "meta": {}
+}
+```
+
+---
+
 ## Sessions
 
+### List Sessions
+
+| | |
+|---|---|
+| **Endpoint** | `GET /api/v1/sessions` |
+| **Description** | Get all active sessions for current user |
+| **Auth Required** | Yes |
+
+**Response (200 OK):**
+```json
+{
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 200,
+  "timestamp": "2025-11-16T10:30:00Z",
+  "result": [
+    {
+      "session_id": "sess_789",
+      "character_id": "char_456",
+      "turn_number": 5,
+      "status": "active",
+      "created_at": "2025-11-16T10:00:00Z",
+      "last_activity": "2025-11-16T10:25:00Z",
+      "game_state": {
+        "current_location": "crossville_village",
+        "location_type": "town"
+      }
+    }
+  ]
+}
+```
+
+**Error Responses:**
+- `401` - Not authenticated
+- `500` - Internal server error
+
+---
+
 ### Create Session
 
 | | |
@@ -780,7 +875,30 @@ Set-Cookie: coc_session=<session_token>; HttpOnly; Secure; SameSite=Lax; Max-Age
 **Error Responses:**
 - `400` - Validation error (missing character_id)
 - `404` - Character not found
-- `409` - Session limit exceeded (max 5 active sessions)
+- `409` - Session limit exceeded (tier-based limit)
+
+**Session Limits by Tier:**
+| Tier | Max Active Sessions |
+|------|---------------------|
+| FREE | 1 |
+| BASIC | 2 |
+| PREMIUM | 3 |
+| ELITE | 5 |
+
+**Error Response (409 Conflict - Session Limit Exceeded):**
+```json
+{
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 409,
+  "timestamp": "2025-11-16T10:30:00Z",
+  "result": null,
+  "error": {
+    "code": "SESSION_LIMIT_EXCEEDED",
+    "message": "Maximum active sessions reached for free tier (1/1). Please delete an existing session to start a new one."
+  }
+}
+```
 
 ---
 
@@ -1001,24 +1119,39 @@ Set-Cookie: coc_session=<session_token>; HttpOnly; Secure; SameSite=Lax; Max-Age
 
 ---
 
-### End Session
+### Delete Session
 
 | | |
 |---|---|
 | **Endpoint** | `DELETE /api/v1/sessions/<session_id>` |
-| **Description** | End and archive session |
+| **Description** | Permanently delete a session and all associated chat messages |
 | **Auth Required** | Yes |
 
+**Behavior:**
+- Permanently removes the session from the database (hard delete)
+- Also deletes all chat messages associated with this session
+- Frees up the session slot for the user's tier limit
+- Cannot be undone
+
 **Response (200 OK):**
 ```json
 {
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 200,
+  "timestamp": "2025-11-16T10:30:00Z",
   "result": {
-    "message": "Session ended",
-    "final_state": {}
+    "message": "Session deleted successfully",
+    "session_id": "sess_789"
   }
 }
 ```
 
+**Error Responses:**
+- `401` - Not authenticated
+- `404` - Session not found or not owned by user
+- `500` - Internal server error
+
 ---
 
 ### Export Session
@@ -1066,17 +1199,19 @@ The Travel API enables location-based world exploration. Locations are defined i
   "timestamp": "2025-11-25T10:30:00Z",
   "result": {
     "current_location": "crossville_village",
-    "available_locations": [
+    "destinations": [
       {
         "location_id": "crossville_tavern",
         "name": "The Rusty Anchor Tavern",
         "location_type": "tavern",
+        "region_id": "crossville",
         "description": "A cozy tavern where travelers share tales..."
       },
       {
         "location_id": "crossville_forest",
         "name": "Whispering Woods",
         "location_type": "wilderness",
+        "region_id": "crossville",
         "description": "A dense forest on the outskirts of town..."
       }
     ]
@@ -1084,6 +1219,11 @@ The Travel API enables location-based world exploration. Locations are defined i
 }
 ```
 
+**Error Responses:**
+- `400` - Missing session_id parameter
+- `404` - Session or character not found
+- `500` - Internal server error
+
 ### Travel to Location
 
 | | |
@@ -1100,20 +1240,40 @@ The Travel API enables location-based world exploration. Locations are defined i
 }
 ```
 
-**Response (202 Accepted):**
+**Response (200 OK):**
 ```json
 {
   "app": "Code of Conquest",
   "version": "0.1.0",
-  "status": 202,
+  "status": 200,
   "timestamp": "2025-11-25T10:30:00Z",
   "result": {
-    "job_id": "ai_travel_abc123",
-    "status": "queued",
-    "message": "Traveling to The Rusty Anchor Tavern...",
-    "destination": {
+    "location": {
       "location_id": "crossville_tavern",
-      "name": "The Rusty Anchor Tavern"
+      "name": "The Rusty Anchor Tavern",
+      "location_type": "tavern",
+      "region_id": "crossville",
+      "description": "A cozy tavern where travelers share tales...",
+      "lore": "Founded decades ago by a retired adventurer...",
+      "ambient_description": "The scent of ale and roasting meat fills the air...",
+      "available_quests": ["quest_missing_trader"],
+      "npc_ids": ["npc_grom_ironbeard"],
+      "discoverable_locations": ["crossville_forest"],
+      "is_starting_location": false,
+      "tags": ["tavern", "social", "merchant", "safe"]
+    },
+    "npcs_present": [
+      {
+        "npc_id": "npc_grom_ironbeard",
+        "name": "Grom Ironbeard",
+        "role": "bartender",
+        "appearance": "Stout dwarf with a braided grey beard"
+      }
+    ],
+    "game_state": {
+      "current_location": "crossville_tavern",
+      "location_type": "tavern",
+      "active_quests": []
     }
   }
 }
@@ -1121,7 +1281,9 @@ The Travel API enables location-based world exploration. Locations are defined i
 
 **Error Responses:**
 - `400` - Location not discovered
+- `403` - Location not discovered
 - `404` - Session or location not found
+- `500` - Internal server error
 
 ### Get Location Details
 
@@ -1139,22 +1301,36 @@ The Travel API enables location-based world exploration. Locations are defined i
   "status": 200,
   "timestamp": "2025-11-25T10:30:00Z",
   "result": {
-    "location_id": "crossville_village",
-    "name": "Crossville Village",
-    "location_type": "town",
-    "region_id": "crossville",
-    "description": "A modest farming village built around a central square...",
-    "lore": "Founded two centuries ago by settlers from the eastern kingdoms...",
-    "ambient_description": "The village square bustles with activity...",
-    "available_quests": ["quest_mayors_request"],
-    "npc_ids": ["npc_mayor_aldric", "npc_blacksmith_hilda"],
-    "discoverable_locations": ["crossville_tavern", "crossville_forest"],
-    "is_starting_location": true,
-    "tags": ["town", "social", "merchant", "safe"]
+    "location": {
+      "location_id": "crossville_village",
+      "name": "Crossville Village",
+      "location_type": "town",
+      "region_id": "crossville",
+      "description": "A modest farming village built around a central square...",
+      "lore": "Founded two centuries ago by settlers from the eastern kingdoms...",
+      "ambient_description": "The village square bustles with activity...",
+      "available_quests": ["quest_mayors_request"],
+      "npc_ids": ["npc_mayor_aldric", "npc_blacksmith_hilda"],
+      "discoverable_locations": ["crossville_tavern", "crossville_forest"],
+      "is_starting_location": true,
+      "tags": ["town", "social", "merchant", "safe"]
+    },
+    "npcs_present": [
+      {
+        "npc_id": "npc_mayor_aldric",
+        "name": "Mayor Aldric",
+        "role": "village mayor",
+        "appearance": "A portly man in fine robes"
+      }
+    ]
   }
 }
 ```
 
+**Error Responses:**
+- `404` - Location not found
+- `500` - Internal server error
+
 ### Get Current Location
 
 | | |
@@ -1225,6 +1401,7 @@ The NPC API enables interaction with persistent NPCs. NPCs have personalities, k
     "name": "Grom Ironbeard",
     "role": "bartender",
     "location_id": "crossville_tavern",
+    "image_url": "/static/images/npcs/crossville/grom_ironbeard.png",
     "personality": {
       "traits": ["gruff", "observant", "secretly kind"],
       "speech_style": "Uses dwarven expressions, speaks in short sentences",
@@ -1304,7 +1481,7 @@ The NPC API enables interaction with persistent NPCs. NPCs have personalities, k
     "dialogue": "*polishes mug thoughtfully* \"Ah, another adventurer. What'll it be?\"",
     "tokens_used": 728,
     "npc_name": "Grom Ironbeard",
-    "npc_id": "npc_grom_001",
+    "npc_id": "npc_grom_ironbeard",
     "character_name": "Thorin",
     "player_line": "greeting",
     "conversation_history": [
@@ -1327,6 +1504,11 @@ The NPC API enables interaction with persistent NPCs. NPCs have personalities, k
 - The AI receives the last 3 exchanges as context for continuity
 - The job result includes prior `conversation_history` for UI display
 
+**Bidirectional Dialogue:**
+- If `player_response` is provided in the request, it overrides `topic` and enables full bidirectional conversation
+- The player's response is stored in the conversation history
+- The NPC's reply takes into account the full conversation context
+
 **Error Responses:**
 - `400` - NPC not at current location
 - `404` - NPC or session not found
@@ -1354,14 +1536,16 @@ The NPC API enables interaction with persistent NPCs. NPCs have personalities, k
         "name": "Grom Ironbeard",
         "role": "bartender",
         "appearance": "Stout dwarf with a braided grey beard",
-        "tags": ["merchant", "quest_giver"]
+        "tags": ["merchant", "quest_giver"],
+        "image_url": "/static/images/npcs/crossville/grom_ironbeard.png"
       },
       {
         "npc_id": "npc_mira_swiftfoot",
         "name": "Mira Swiftfoot",
         "role": "traveling rogue",
         "appearance": "Lithe half-elf with sharp eyes",
-        "tags": ["information", "secret_keeper"]
+        "tags": ["information", "secret_keeper"],
+        "image_url": "/static/images/npcs/crossville/mira_swiftfoot.png"
       }
     ]
   }
@@ -1432,6 +1616,211 @@ The NPC API enables interaction with persistent NPCs. NPCs have personalities, k
 
 ---
 
+## Chat / Conversation History
+
+The Chat API provides access to complete player-NPC conversation history. All dialogue exchanges are stored in the `chat_messages` collection for unlimited history, with the most recent 3 messages cached in character documents for quick AI context.
+
+### Get All Conversations Summary
+
+| | |
+|---|---|
+| **Endpoint** | `GET /api/v1/characters/<character_id>/chats` |
+| **Description** | Get summary of all NPC conversations for a character |
+| **Auth Required** | Yes |
+
+**Response (200 OK):**
+```json
+{
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 200,
+  "timestamp": "2025-11-25T14:30:00Z",
+  "result": {
+    "conversations": [
+      {
+        "npc_id": "npc_grom_ironbeard",
+        "npc_name": "Grom Ironbeard",
+        "last_message_timestamp": "2025-11-25T14:30:00Z",
+        "message_count": 15,
+        "recent_preview": "Aye, the rats in the cellar have been causing trouble..."
+      },
+      {
+        "npc_id": "npc_mira_swiftfoot",
+        "npc_name": "Mira Swiftfoot",
+        "last_message_timestamp": "2025-11-25T12:15:00Z",
+        "message_count": 8,
+        "recent_preview": "*leans in and whispers* I've heard rumors about the mayor..."
+      }
+    ]
+  }
+}
+```
+
+### Get Conversation with Specific NPC
+
+| | |
+|---|---|
+| **Endpoint** | `GET /api/v1/characters/<character_id>/chats/<npc_id>` |
+| **Description** | Get paginated conversation history with a specific NPC |
+| **Auth Required** | Yes |
+
+**Query Parameters:**
+- `limit` (optional): Maximum messages to return (default: 50, max: 100)
+- `offset` (optional): Number of messages to skip (default: 0)
+
+**Response (200 OK):**
+```json
+{
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 200,
+  "timestamp": "2025-11-25T14:30:00Z",
+  "result": {
+    "npc_id": "npc_grom_ironbeard",
+    "npc_name": "Grom Ironbeard",
+    "total_messages": 15,
+    "messages": [
+      {
+        "message_id": "msg_abc123",
+        "character_id": "char_123",
+        "npc_id": "npc_grom_ironbeard",
+        "player_message": "What rumors have you heard?",
+        "npc_response": "*leans in* Strange folk been coming through lately...",
+        "timestamp": "2025-11-25T14:30:00Z",
+        "context": "dialogue",
+        "location_id": "crossville_tavern",
+        "session_id": "sess_789",
+        "metadata": {},
+        "is_deleted": false
+      },
+      {
+        "message_id": "msg_abc122",
+        "character_id": "char_123",
+        "npc_id": "npc_grom_ironbeard",
+        "player_message": "Hello there!",
+        "npc_response": "*nods gruffly* Welcome to the Rusty Anchor.",
+        "timestamp": "2025-11-25T14:25:00Z",
+        "context": "dialogue",
+        "location_id": "crossville_tavern",
+        "session_id": "sess_789",
+        "metadata": {},
+        "is_deleted": false
+      }
+    ],
+    "pagination": {
+      "limit": 50,
+      "offset": 0,
+      "has_more": false
+    }
+  }
+}
+```
+
+**Message Context Types:**
+- `dialogue` - General conversation
+- `quest_offered` - Quest offering dialogue
+- `quest_completed` - Quest completion dialogue
+- `shop` - Merchant transaction
+- `location_revealed` - New location discovered
+- `lore` - Lore/backstory reveals
+
+### Search Messages
+
+| | |
+|---|---|
+| **Endpoint** | `GET /api/v1/characters/<character_id>/chats/search` |
+| **Description** | Search messages by text with optional filters |
+| **Auth Required** | Yes |
+
+**Query Parameters:**
+- `q` (required): Search text to find in player_message and npc_response
+- `npc_id` (optional): Filter by specific NPC
+- `context` (optional): Filter by message context type
+- `date_from` (optional): Start date in ISO format (e.g., 2025-11-25T00:00:00Z)
+- `date_to` (optional): End date in ISO format
+- `limit` (optional): Maximum messages to return (default: 50, max: 100)
+- `offset` (optional): Number of messages to skip (default: 0)
+
+**Example Request:**
+```
+GET /api/v1/characters/char_123/chats/search?q=quest&npc_id=npc_grom_ironbeard&context=quest_offered
+```
+
+**Response (200 OK):**
+```json
+{
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 200,
+  "timestamp": "2025-11-25T14:30:00Z",
+  "result": {
+    "search_text": "quest",
+    "filters": {
+      "npc_id": "npc_grom_ironbeard",
+      "context": "quest_offered",
+      "date_from": null,
+      "date_to": null
+    },
+    "total_results": 2,
+    "messages": [
+      {
+        "message_id": "msg_abc125",
+        "character_id": "char_123",
+        "npc_id": "npc_grom_ironbeard",
+        "player_message": "Do you have any work for me?",
+        "npc_response": "*sighs heavily* Aye, there's rats in me cellar. Big ones.",
+        "timestamp": "2025-11-25T13:00:00Z",
+        "context": "quest_offered",
+        "location_id": "crossville_tavern",
+        "session_id": "sess_789",
+        "metadata": {
+          "quest_id": "quest_cellar_rats"
+        },
+        "is_deleted": false
+      }
+    ],
+    "pagination": {
+      "limit": 50,
+      "offset": 0,
+      "has_more": false
+    }
+  }
+}
+```
+
+### Delete Message (Soft Delete)
+
+| | |
+|---|---|
+| **Endpoint** | `DELETE /api/v1/characters/<character_id>/chats/<message_id>` |
+| **Description** | Soft delete a message (privacy/moderation) |
+| **Auth Required** | Yes |
+
+**Response (200 OK):**
+```json
+{
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 200,
+  "timestamp": "2025-11-25T14:30:00Z",
+  "result": {
+    "message_id": "msg_abc123",
+    "deleted": true
+  }
+}
+```
+
+**Notes:**
+- Messages are soft deleted (is_deleted=true), not removed from database
+- Deleted messages are filtered from all queries
+- Only the character owner can delete their own messages
+
+**Error Responses:**
+- `403` - User does not own the character
+- `404` - Message not found
+
+---
+
 ## Combat
 
 ### Attack
@@ -2238,6 +2627,7 @@ The NPC API enables interaction with persistent NPCs. NPCs have personalities, k
 | `INVALID_INPUT` | 400 | Validation error |
 | `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |
 | `CHARACTER_LIMIT_EXCEEDED` | 400 | User has reached character limit for their tier |
+| `SESSION_LIMIT_EXCEEDED` | 409 | User has reached session limit for their tier |
 | `CHARACTER_NOT_FOUND` | 404 | Character does not exist or not accessible |
 | `SKILL_UNLOCK_ERROR` | 400 | Skill unlock failed (prerequisites, points, or tier) |
 | `INSUFFICIENT_FUNDS` | 400 | Not enough gold |
@@ -2251,12 +2641,12 @@ The NPC API enables interaction with persistent NPCs. NPCs have personalities, k
 
 ## Rate Limiting
 
-| Tier | Requests/Minute | AI Calls/Day |
-|------|-----------------|--------------|
-| FREE | 30 | 50 |
-| BASIC | 60 | 200 |
-| PREMIUM | 120 | 1000 |
-| ELITE | 300 | Unlimited |
+| Tier | Requests/Minute | AI Calls/Day | Max Sessions |
+|------|-----------------|--------------|--------------|
+| FREE | 30 | 50 | 1 |
+| BASIC | 60 | 200 | 2 |
+| PREMIUM | 120 | 1000 | 3 |
+| ELITE | 300 | Unlimited | 5 |
 
 **Rate Limit Headers:**
 ```

api/docs/API_TESTING.md

@@ -634,7 +634,7 @@ curl -X POST http://localhost:5000/api/v1/characters \
 
 **Endpoint:** `DELETE /api/v1/characters/<character_id>`
 
-**Description:** Soft-delete a character (marks as inactive rather than removing).
+**Description:** Permanently delete a character from the database. Also cleans up all associated game sessions to prevent orphaned data.
 
 **Request:**
 
@@ -1447,6 +1447,166 @@ curl http://localhost:5000/api/v1/origins
 
 ---
 
+## Session Endpoints
+
+### 1. Create Session
+
+**Endpoint:** `POST /api/v1/sessions`
+
+**Description:** Create a new game session for a character. Subject to tier-based limits (Free: 1, Basic: 2, Premium: 3, Elite: 5).
+
+**Request:**
+
+```bash
+# httpie
+http --session=user1 POST localhost:5000/api/v1/sessions \
+  character_id="char_123"
+
+# curl
+curl -X POST http://localhost:5000/api/v1/sessions \
+  -H "Content-Type: application/json" \
+  -b cookies.txt \
+  -d '{
+    "character_id": "char_123"
+  }'
+```
+
+**Success Response (201 Created):**
+
+```json
+{
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 201,
+  "timestamp": "2025-11-26T10:30:00Z",
+  "result": {
+    "session_id": "sess_789",
+    "character_id": "char_123",
+    "turn_number": 0,
+    "game_state": {
+      "current_location": "crossville_village",
+      "location_type": "town",
+      "active_quests": []
+    }
+  }
+}
+```
+
+**Error Response (409 Conflict - Session Limit Exceeded):**
+
+```json
+{
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 409,
+  "timestamp": "2025-11-26T10:30:00Z",
+  "error": {
+    "code": "SESSION_LIMIT_EXCEEDED",
+    "message": "Maximum active sessions reached for free tier (1/1). Please delete an existing session to start a new one."
+  }
+}
+```
+
+---
+
+### 2. List Sessions
+
+**Endpoint:** `GET /api/v1/sessions`
+
+**Description:** Get all active sessions for the authenticated user.
+
+**Request:**
+
+```bash
+# httpie
+http --session=user1 GET localhost:5000/api/v1/sessions
+
+# curl
+curl http://localhost:5000/api/v1/sessions -b cookies.txt
+```
+
+**Success Response (200 OK):**
+
+```json
+{
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 200,
+  "timestamp": "2025-11-26T10:30:00Z",
+  "result": [
+    {
+      "session_id": "sess_789",
+      "character_id": "char_123",
+      "turn_number": 5,
+      "status": "active",
+      "created_at": "2025-11-26T10:00:00Z",
+      "last_activity": "2025-11-26T10:25:00Z",
+      "game_state": {
+        "current_location": "crossville_village",
+        "location_type": "town"
+      }
+    }
+  ]
+}
+```
+
+---
+
+### 3. Delete Session
+
+**Endpoint:** `DELETE /api/v1/sessions/<session_id>`
+
+**Description:** Permanently delete a session and all associated chat messages. This frees up a session slot for your tier limit.
+
+**Request:**
+
+```bash
+# httpie
+http --session=user1 DELETE localhost:5000/api/v1/sessions/sess_789
+
+# curl
+curl -X DELETE http://localhost:5000/api/v1/sessions/sess_789 \
+  -b cookies.txt
+```
+
+**Success Response (200 OK):**
+
+```json
+{
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 200,
+  "timestamp": "2025-11-26T10:30:00Z",
+  "result": {
+    "message": "Session deleted successfully",
+    "session_id": "sess_789"
+  }
+}
+```
+
+**Error Response (404 Not Found):**
+
+```json
+{
+  "app": "Code of Conquest",
+  "version": "0.1.0",
+  "status": 404,
+  "timestamp": "2025-11-26T10:30:00Z",
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "Session not found"
+  }
+}
+```
+
+**Note:** Deleting a session:
+- Permanently removes the session from the database
+- Deletes all chat messages associated with the session
+- Cannot be undone
+- Frees up a session slot for your tier limit
+
+---
+
 ## Testing Workflows
 
 ### Complete Registration Flow

api/docs/CHAT_SYSTEM.md

@@ -0,0 +1,459 @@
+# Chat / Conversation History System
+
+## Overview
+
+The Chat System provides complete player-NPC conversation history tracking with unlimited storage, fast AI context retrieval, and powerful search capabilities. It replaces the previous inline dialogue_history with a scalable, performant architecture.
+
+**Key Features:**
+- Unlimited conversation history (no 10-message cap)
+- Hybrid storage for performance (cache + full history)
+- Quest and faction tracking ready
+- Full-text search with filters
+- Soft delete for privacy/moderation
+- Future-ready for player-to-player chat
+
+---
+
+## Architecture
+
+### Hybrid Storage Design
+
+The system uses a **two-tier storage approach** for optimal performance:
+
+```
+┌─────────────────────────────────────────────────┐
+│ Character Document                              │
+│                                                 │
+│ npc_interactions[npc_id]:                      │
+│   └─ recent_messages: [last 3 messages]       │  ← AI Context (fast)
+│   └─ total_messages: 15                        │
+│   └─ relationship_level, flags, etc.           │
+└─────────────────────────────────────────────────┘
+                    │
+                    │ Updates on each new message
+                    ▼
+┌─────────────────────────────────────────────────┐
+│ chat_messages Collection                        │
+│                                                 │
+│ ┌─────────────────────────────────────────┐   │
+│ │ Message 1 (oldest)                       │   │
+│ │ Message 2                                │   │
+│ │ ...                                      │   │  ← Full History (queries)
+│ │ Message 15 (newest)                      │   │
+│ └─────────────────────────────────────────┘   │
+│                                                 │
+│ Indexes: character+npc+time, session, context  │
+└─────────────────────────────────────────────────┘
+```
+
+**Benefits:**
+- **90% of queries** (AI context) read from character document cache → No database query
+- **10% of queries** (user browsing history, search) use indexed collection → Fast retrieval
+- Character documents stay small (3 messages vs unlimited)
+- No performance degradation as conversations grow
+
+### Data Flow
+
+**Saving a New Message:**
+```
+User talks to NPC
+    │
+    ▼
+POST /api/v1/npcs/{npc_id}/talk
+    │
+    ▼
+AI generates dialogue (background task)
+    │
+    ▼
+ChatMessageService.save_dialogue_exchange()
+    │
+    ├─→ 1. Save to chat_messages collection (UUID, full data)
+    │
+    └─→ 2. Update character.npc_interactions[npc_id]:
+            - Append to recent_messages (keep last 3)
+            - Increment total_messages counter
+            - Update last_interaction timestamp
+```
+
+**Reading for AI Context:**
+```
+AI needs conversation history
+    │
+    ▼
+CharacterService.get_npc_dialogue_history()
+    │
+    └─→ Returns character.npc_interactions[npc_id].recent_messages
+        (Already loaded in memory, instant access)
+```
+
+**Reading for User UI:**
+```
+User views conversation history
+    │
+    ▼
+GET /api/v1/characters/{char_id}/chats/{npc_id}?limit=50&offset=0
+    │
+    ▼
+ChatMessageService.get_conversation_history()
+    │
+    └─→ Query chat_messages collection
+        WHERE character_id = X AND npc_id = Y
+        ORDER BY timestamp DESC
+        LIMIT 50 OFFSET 0
+```
+
+---
+
+## Database Schema
+
+### Collection: `chat_messages`
+
+| Column | Type | Size | Indexed | Description |
+|--------|------|------|---------|-------------|
+| `message_id` | string | 36 | Primary | UUID |
+| `character_id` | string | 100 | Yes | Player character |
+| `npc_id` | string | 100 | Yes | NPC identifier |
+| `player_message` | string | 2000 | No | Player input |
+| `npc_response` | string | 5000 | No | AI-generated reply |
+| `timestamp` | datetime | - | Yes | ISO 8601 format |
+| `session_id` | string | 100 | Yes | Game session |
+| `location_id` | string | 100 | No | Where conversation happened |
+| `context` | string | 50 | Yes | MessageContext enum |
+| `metadata` | string (JSON) | 1000 | No | Extensible (quest_id, etc.) |
+| `is_deleted` | boolean | - | No | Soft delete flag |
+
+### Indexes
+
+1. **idx_character_npc_time** (character_id + npc_id + timestamp DESC)
+   - **Purpose**: Get conversation between character and specific NPC
+   - **Query**: "Show me my chat with Grom"
+   - **Used by**: `get_conversation_history()`
+
+2. **idx_character_time** (character_id + timestamp DESC)
+   - **Purpose**: Get all messages for a character across all NPCs
+   - **Query**: "Show me all my conversations"
+   - **Used by**: `get_all_conversations_summary()`
+
+3. **idx_session_time** (session_id + timestamp DESC)
+   - **Purpose**: Get all chat messages from a specific game session
+   - **Query**: "What did I discuss during this session?"
+   - **Used by**: Session replay, analytics
+
+4. **idx_context** (context)
+   - **Purpose**: Filter messages by interaction type
+   - **Query**: "Show me all quest offers"
+   - **Used by**: `search_messages()` with context filter
+
+5. **idx_timestamp** (timestamp DESC)
+   - **Purpose**: Date range queries
+   - **Query**: "Show messages from last week"
+   - **Used by**: `search_messages()` with date filters
+
+---
+
+## Integration Points
+
+### 1. NPC Dialogue Generation (`/api/app/tasks/ai_tasks.py`)
+
+**Old Flow (Deprecated):**
+```python
+# Saved to character.npc_interactions[npc_id].dialogue_history
+character_service.add_npc_dialogue_exchange(
+    character_id, npc_id, player_line, npc_response
+)
+```
+
+**New Flow:**
+```python
+# Saves to chat_messages + updates recent_messages cache
+chat_service = get_chat_message_service()
+chat_service.save_dialogue_exchange(
+    character_id=character_id,
+    user_id=user_id,
+    npc_id=npc_id,
+    player_message=player_line,
+    npc_response=npc_response,
+    context=MessageContext.DIALOGUE,
+    metadata={},  # Can include quest_id, item_id when available
+    session_id=session_id,
+    location_id=current_location
+)
+```
+
+### 2. Character Service (`/api/app/services/character_service.py`)
+
+**Updated Method:**
+```python
+def get_npc_dialogue_history(character_id, user_id, npc_id, limit=5):
+    """
+    Get recent dialogue history from recent_messages cache.
+    Falls back to dialogue_history for backward compatibility.
+    """
+    interaction = character.npc_interactions.get(npc_id, {})
+
+    # NEW: Read from recent_messages (last 3 messages)
+    recent_messages = interaction.get("recent_messages")
+    if recent_messages is not None:
+        return recent_messages[-limit:]
+
+    # DEPRECATED: Fall back to old dialogue_history field
+    dialogue_history = interaction.get("dialogue_history", [])
+    return dialogue_history[-limit:]
+```
+
+### 3. Character Document Structure
+
+**Updated `npc_interactions` Field:**
+```python
+{
+    "npc_grom_ironbeard": {
+        "npc_id": "npc_grom_ironbeard",
+        "first_met": "2025-11-25T10:00:00Z",
+        "last_interaction": "2025-11-25T14:30:00Z",
+        "interaction_count": 5,
+        "revealed_secrets": [0, 2],
+        "relationship_level": 65,
+        "custom_flags": {"helped_with_rats": true},
+
+        # NEW FIELDS
+        "recent_messages": [  # Last 3 messages for AI context
+            {
+                "player_message": "What rumors have you heard?",
+                "npc_response": "*leans in* Strange folk...",
+                "timestamp": "2025-11-25T14:30:00Z"
+            }
+        ],
+        "total_messages": 15,  # Total count for UI display
+
+        # DEPRECATED (kept for backward compatibility)
+        "dialogue_history": []  # Will be removed after full migration
+    }
+}
+```
+
+---
+
+## API Endpoints
+
+See `API_REFERENCE.md` for complete endpoint documentation.
+
+**Summary:**
+- `GET /api/v1/characters/{char_id}/chats` - All conversations summary
+- `GET /api/v1/characters/{char_id}/chats/{npc_id}` - Full conversation with pagination
+- `GET /api/v1/characters/{char_id}/chats/search` - Search with filters
+- `DELETE /api/v1/characters/{char_id}/chats/{msg_id}` - Soft delete
+
+---
+
+## Performance Characteristics
+
+### Storage Estimates
+
+| Scenario | Messages | Storage per Character |
+|----------|----------|----------------------|
+| Casual player | 50 messages across 5 NPCs | ~25 KB |
+| Active player | 200 messages across 10 NPCs | ~100 KB |
+| Heavy player | 1000 messages across 20 NPCs | ~500 KB |
+
+**Character Document Impact:**
+- Recent messages (3 per NPC): ~1.5 KB per NPC
+- 10 NPCs: ~15 KB total (vs ~50 KB for old 10-message history)
+- 67% reduction in character document size
+
+### Query Performance
+
+**AI Context Retrieval:**
+- **Old**: ~50ms database query + deserialization
+- **New**: ~1ms (read from already-loaded character object)
+- **Improvement**: 50x faster
+
+**User History Browsing:**
+- **Old**: Limited to last 10 messages (no pagination)
+- **New**: Unlimited with pagination (50ms per page)
+- **Improvement**: Unlimited history with same performance
+
+**Search:**
+- **Old**: Not available (would require scanning all character docs)
+- **New**: ~100ms for filtered search across thousands of messages
+- **Improvement**: Previously impossible
+
+### Scalability
+
+**Growth Characteristics:**
+- Character document size: O(1) - Fixed at 3 messages per NPC
+- Chat collection size: O(n) - Linear growth with message count
+- Query performance: O(log n) - Indexed queries remain fast
+
+**Capacity Estimate:**
+- 1000 active players
+- Average 500 messages per player
+- Total: 500,000 messages = ~250 MB
+- Appwrite easily handles this scale
+
+---
+
+## Future Extensions
+
+### Quest Tracking
+```python
+# Save quest offer with metadata
+chat_service.save_dialogue_exchange(
+    ...,
+    context=MessageContext.QUEST_OFFERED,
+    metadata={"quest_id": "quest_cellar_rats"}
+)
+
+# Query all quest offers
+results = chat_service.search_messages(
+    ...,
+    context=MessageContext.QUEST_OFFERED
+)
+```
+
+### Faction Tracking
+```python
+# Save reputation change with metadata
+chat_service.save_dialogue_exchange(
+    ...,
+    context=MessageContext.DIALOGUE,
+    metadata={
+        "faction_id": "crossville_guard",
+        "reputation_change": +10
+    }
+)
+```
+
+### Player-to-Player Chat
+```python
+# Add message_type enum to distinguish chat types
+class MessageType(Enum):
+    PLAYER_TO_NPC = "player_to_npc"
+    NPC_TO_PLAYER = "npc_to_player"
+    PLAYER_TO_PLAYER = "player_to_player"
+    SYSTEM = "system"
+
+# Extend ChatMessage with message_type field
+# Extend indexes with sender_id + recipient_id
+```
+
+### Read Receipts
+```python
+# Add read_at field to ChatMessage
+# Update when player views conversation
+# Show "unread" badge in UI
+```
+
+### Chat Channels
+```python
+# Add channel_id field (party, guild, global)
+# Index by channel_id for group chats
+# Support broadcasting to multiple recipients
+```
+
+---
+
+## Migration Strategy
+
+### Phase 1: Dual Write (Current)
+- ✅ New messages saved to both locations
+- ✅ Old dialogue_history field still maintained
+- ✅ Reads prefer recent_messages, fallback to dialogue_history
+- ✅ Zero downtime migration
+
+### Phase 2: Data Backfill (Optional)
+- Migrate existing dialogue_history to chat_messages
+- Script: `/api/scripts/migrate_dialogue_history.py`
+- Can be run anytime without disrupting service
+
+### Phase 3: Deprecation (Future)
+- Stop writing to dialogue_history field
+- Remove field from Character model
+- Remove add_npc_dialogue_exchange() method
+
+**Timeline:** Phase 2-3 can wait until full testing complete. No rush.
+
+---
+
+## Security & Privacy
+
+**Access Control:**
+- Users can only access their own character's messages
+- Ownership validated on every request
+- Character service validates user_id matches
+
+**Soft Delete:**
+- Messages marked is_deleted=true, not removed
+- Filtered from all queries automatically
+- Preserved for audit/moderation if needed
+
+**Data Retention:**
+- No automatic cleanup implemented
+- Messages persist indefinitely
+- Future: Could add retention policy per user preference
+
+---
+
+## Monitoring & Analytics
+
+**Usage Tracking:**
+- Total messages per character (total_messages field)
+- Interaction counts per NPC (interaction_count field)
+- Message context distribution (via context field)
+
+**Performance Metrics:**
+- Query latency (via logging)
+- Cache hit rate (recent_messages vs full query)
+- Storage growth (collection size monitoring)
+
+**Business Metrics:**
+- Most-contacted NPCs
+- Average conversation length
+- Quest offer acceptance rate (via context tracking)
+- Player engagement (messages per session)
+
+---
+
+## Development Notes
+
+**File Locations:**
+- Model: `/app/models/chat_message.py`
+- Service: `/app/services/chat_message_service.py`
+- API: `/app/api/chat.py`
+- Database Init: `/app/services/database_init.py` (init_chat_messages_table)
+
+**Testing:**
+- Unit tests: `/tests/test_chat_message_service.py`
+- Integration tests: `/tests/test_chat_api.py`
+- Manual testing: See API_REFERENCE.md for curl examples
+
+**Dependencies:**
+- Appwrite SDK (database operations)
+- Character Service (ownership validation)
+- NPC Loader (NPC name resolution)
+
+---
+
+## Troubleshooting
+
+**Issue: Messages not appearing in history**
+- Check chat_messages collection exists (run init_database.py)
+- Verify ChatMessageService is being called in ai_tasks.py
+- Check logs for errors during save_dialogue_exchange()
+
+**Issue: Slow queries**
+- Verify indexes exist (check Appwrite console)
+- Monitor query patterns (check logs)
+- Consider adjusting pagination limits
+
+**Issue: Character document too large**
+- Should not happen (recent_messages capped at 3)
+- If occurring, check for old dialogue_history accumulation
+- Run migration script to clean up old data
+
+---
+
+## References
+
+- API_REFERENCE.md - Chat API endpoints
+- DATA_MODELS.md - ChatMessage model details
+- APPWRITE_SETUP.md - Database configuration

api/docs/DATA_MODELS.md

@@ -50,6 +50,7 @@ All enum types are defined in `/app/models/enums.py` for type safety throughout
 | `INTELLIGENCE` | Magical power |
 | `WISDOM` | Perception and insight |
 | `CHARISMA` | Social influence |
+| `LUCK` | Fortune and fate (affects crits, loot, random outcomes) |
 
 ### AbilityType
 
@@ -225,6 +226,7 @@ Main NPC definition with personality and dialogue data for AI generation.
 | `location_id` | str | ID of location where NPC resides |
 | `personality` | NPCPersonality | Personality traits and speech patterns |
 | `appearance` | NPCAppearance | Physical description |
+| `image_url` | Optional[str] | URL path to NPC portrait image (e.g., "/static/images/npcs/crossville/grom_ironbeard.png") |
 | `knowledge` | Optional[NPCKnowledge] | What the NPC knows (public and secret) |
 | `relationships` | List[NPCRelationship] | How NPC feels about other NPCs |
 | `inventory_for_sale` | List[NPCInventoryItem] | Items NPC sells (if merchant) |
@@ -320,18 +322,25 @@ Tracks a character's interaction history with an NPC. Stored on Character record
 | `revealed_secrets` | List[int] | Indices of secrets revealed |
 | `relationship_level` | int | 0-100 scale (50 is neutral) |
 | `custom_flags` | Dict[str, Any] | Arbitrary flags for special conditions |
-| `dialogue_history` | List[Dict] | Recent conversation exchanges (max 10 per NPC) |
+| `recent_messages` | List[Dict] | **Last 3 messages for quick AI context** |
+| `total_messages` | int | **Total conversation message count** |
+| `dialogue_history` | List[Dict] | **DEPRECATED** - Use ChatMessageService for full history |
 
-**Dialogue History Entry Format:**
+**Recent Messages Entry Format:**
 ```json
 {
-  "player_line": "What have you heard about the old mines?",
+  "player_message": "What have you heard about the old mines?",
   "npc_response": "Aye, strange noises coming from there lately...",
-  "timestamp": "2025-11-24T10:30:00Z"
+  "timestamp": "2025-11-25T10:30:00Z"
 }
 ```
 
-The dialogue history enables bidirectional NPC conversations - players can respond to NPC dialogue and continue conversations with context. The system maintains the last 10 exchanges per NPC to provide conversation context without excessive storage.
+**Conversation History Architecture:**
+- **Recent Messages Cache**: Last 3 messages stored in `recent_messages` field for quick AI context (no database query)
+- **Full History**: Complete unlimited conversation history stored in `chat_messages` collection
+- **Deprecated Field**: `dialogue_history` maintained for backward compatibility, will be removed after full migration
+
+The recent messages cache enables fast AI dialogue generation by providing immediate context without querying the chat_messages collection. For full conversation history, use the ChatMessageService (see Chat/Conversation History API endpoints).
 
 **Relationship Levels:**
 - 0-20: Hostile
@@ -346,6 +355,7 @@ npc_id: "npc_grom_001"
 name: "Grom Ironbeard"
 role: "bartender"
 location_id: "crossville_tavern"
+image_url: "/static/images/npcs/crossville/grom_ironbeard.png"
 personality:
   traits:
     - "gruff"
@@ -413,18 +423,190 @@ merchants = loader.get_npcs_by_tag("merchant")
 
 ---
 
+## Chat / Conversation History System
+
+The chat system stores complete player-NPC conversation history in a dedicated `chat_messages` collection for unlimited history, with a performance-optimized cache in character documents.
+
+### ChatMessage
+
+Complete message exchange between player and NPC.
+
+**Location:** `/app/models/chat_message.py`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `message_id` | str | Unique identifier (UUID) |
+| `character_id` | str | Player's character ID |
+| `npc_id` | str | NPC identifier |
+| `player_message` | str | What the player said (max 2000 chars) |
+| `npc_response` | str | NPC's reply (max 5000 chars) |
+| `timestamp` | str | ISO 8601 timestamp |
+| `session_id` | Optional[str] | Game session reference |
+| `location_id` | Optional[str] | Where conversation happened |
+| `context` | MessageContext | Type of interaction (enum) |
+| `metadata` | Dict[str, Any] | Extensible metadata (quest_id, item_id, etc.) |
+| `is_deleted` | bool | Soft delete flag (default: False) |
+
+**Storage:**
+- Stored in Appwrite `chat_messages` collection
+- Indexed by character_id, npc_id, timestamp for fast queries
+- Unlimited history (no cap on message count)
+
+**Example:**
+```json
+{
+  "message_id": "550e8400-e29b-41d4-a716-446655440000",
+  "character_id": "char_123",
+  "npc_id": "npc_grom_ironbeard",
+  "player_message": "What rumors have you heard?",
+  "npc_response": "*leans in* Strange folk been coming through lately...",
+  "timestamp": "2025-11-25T14:30:00Z",
+  "context": "dialogue",
+  "location_id": "crossville_tavern",
+  "session_id": "sess_789",
+  "metadata": {},
+  "is_deleted": false
+}
+```
+
+### MessageContext (Enum)
+
+Type of interaction that generated the message.
+
+| Value | Description |
+|-------|-------------|
+| `dialogue` | General conversation |
+| `quest_offered` | Quest offering dialogue |
+| `quest_completed` | Quest completion dialogue |
+| `shop` | Merchant transaction |
+| `location_revealed` | New location discovered through chat |
+| `lore` | Lore/backstory reveals |
+
+**Usage:**
+```python
+from app.models.chat_message import MessageContext
+
+context = MessageContext.QUEST_OFFERED
+```
+
+### ConversationSummary
+
+Summary of all messages with a specific NPC for UI display.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `npc_id` | str | NPC identifier |
+| `npc_name` | str | NPC display name |
+| `last_message_timestamp` | str | When the last message was sent |
+| `message_count` | int | Total number of messages exchanged |
+| `recent_preview` | str | Short preview of most recent NPC response |
+
+**Example:**
+```json
+{
+  "npc_id": "npc_grom_ironbeard",
+  "npc_name": "Grom Ironbeard",
+  "last_message_timestamp": "2025-11-25T14:30:00Z",
+  "message_count": 15,
+  "recent_preview": "Aye, the rats in the cellar have been causing trouble..."
+}
+```
+
+### ChatMessageService
+
+Service for managing player-NPC conversation history.
+
+**Location:** `/app/services/chat_message_service.py`
+
+**Core Methods:**
+
+```python
+from app.services.chat_message_service import get_chat_message_service
+from app.models.chat_message import MessageContext
+
+service = get_chat_message_service()
+
+# Save a dialogue exchange (also updates character's recent_messages cache)
+message = service.save_dialogue_exchange(
+    character_id="char_123",
+    user_id="user_456",
+    npc_id="npc_grom_ironbeard",
+    player_message="What rumors have you heard?",
+    npc_response="*leans in* Strange folk...",
+    context=MessageContext.DIALOGUE,
+    metadata={},
+    session_id="sess_789",
+    location_id="crossville_tavern"
+)
+
+# Get conversation history with pagination
+messages = service.get_conversation_history(
+    character_id="char_123",
+    user_id="user_456",
+    npc_id="npc_grom_ironbeard",
+    limit=50,
+    offset=0
+)
+
+# Search messages with filters
+results = service.search_messages(
+    character_id="char_123",
+    user_id="user_456",
+    search_text="quest",
+    npc_id="npc_grom_ironbeard",
+    context=MessageContext.QUEST_OFFERED,
+    date_from="2025-11-01T00:00:00Z",
+    date_to="2025-11-30T23:59:59Z",
+    limit=50,
+    offset=0
+)
+
+# Get all conversations summary for UI
+summaries = service.get_all_conversations_summary(
+    character_id="char_123",
+    user_id="user_456"
+)
+
+# Soft delete a message (privacy/moderation)
+success = service.soft_delete_message(
+    message_id="msg_abc123",
+    character_id="char_123",
+    user_id="user_456"
+)
+```
+
+**Performance Architecture:**
+- **Recent Messages Cache**: Last 3 messages stored in `character.npc_interactions[npc_id].recent_messages`
+- **Full History**: All messages in dedicated `chat_messages` collection
+- **AI Context**: Reads from cache (no database query) for 90% of cases
+- **User Queries**: Reads from collection with pagination and filters
+
+**Database Indexes:**
+1. `idx_character_npc_time` - character_id + npc_id + timestamp DESC
+2. `idx_character_time` - character_id + timestamp DESC
+3. `idx_session_time` - session_id + timestamp DESC
+4. `idx_context` - context
+5. `idx_timestamp` - timestamp DESC
+
+**See Also:**
+- Chat API endpoints in API_REFERENCE.md
+- CHAT_SYSTEM.md for architecture details
+
+---
+
 ## Character System
 
 ### Stats
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `strength` | int | Physical power |
-| `dexterity` | int | Agility and precision |
-| `constitution` | int | Endurance and health |
-| `intelligence` | int | Magical power |
-| `wisdom` | int | Perception and insight |
-| `charisma` | int | Social influence |
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `strength` | int | 10 | Physical power |
+| `dexterity` | int | 10 | Agility and precision |
+| `constitution` | int | 10 | Endurance and health |
+| `intelligence` | int | 10 | Magical power |
+| `wisdom` | int | 10 | Perception and insight |
+| `charisma` | int | 10 | Social influence |
+| `luck` | int | 8 | Fortune and fate (affects crits, loot, random outcomes) |
 
 **Derived Properties (Computed):**
 - `hit_points` = 10 + (constitution × 2)
@@ -434,6 +616,8 @@ merchants = loader.get_npcs_by_tag("merchant")
 
 **Note:** Defense and resistance are computed properties, not stored values. They are calculated on-the-fly from constitution and wisdom.
 
+**Luck Stat:** The luck stat has a lower default (8) compared to other stats (10). Each class has a specific luck value ranging from 7 (Necromancer) to 12 (Assassin). Luck will influence critical hit chance, hit/miss calculations, base damage variance, NPC interactions, loot generation, and spell power in future implementations.
+
 ### SkillNode
 
 | Field | Type | Description |
@@ -482,16 +666,26 @@ merchants = loader.get_npcs_by_tag("merchant")
 
 ### Initial 8 Player Classes
 
-| Class | Theme | Skill Tree 1 | Skill Tree 2 |
-|-------|-------|--------------|--------------|
-| **Vanguard** | Tank/melee | Defensive (shields, armor, taunts) | Offensive (weapon mastery, heavy strikes) |
-| **Assassin** | Stealth/critical | Assassination (critical hits, poisons) | Shadow (stealth, evasion) |
-| **Arcanist** | Elemental spells | Pyromancy (fire spells, DoT) | Cryomancy (ice spells, crowd control) |
-| **Luminary** | Healing/support | Holy (healing, buffs) | Divine Wrath (smite, undead damage) |
-| **Wildstrider** | Ranged/nature | Marksmanship (bow skills, critical shots) | Beast Master (pet companion, nature magic) |
-| **Oathkeeper** | Hybrid tank/healer | Protection (defensive auras, healing) | Retribution (holy damage, smites) |
-| **Necromancer** | Death magic/summon | Dark Arts (curses, life drain) | Summoning (undead minions) |
-| **Lorekeeper** | Support/control | Performance (buffs, debuffs via music) | Trickery (illusions, charm) |
+| Class | Theme | LUK | Skill Tree 1 | Skill Tree 2 |
+|-------|-------|-----|--------------|--------------|
+| **Vanguard** | Tank/melee | 8 | Defensive (shields, armor, taunts) | Offensive (weapon mastery, heavy strikes) |
+| **Assassin** | Stealth/critical | 12 | Assassination (critical hits, poisons) | Shadow (stealth, evasion) |
+| **Arcanist** | Elemental spells | 9 | Pyromancy (fire spells, DoT) | Cryomancy (ice spells, crowd control) |
+| **Luminary** | Healing/support | 11 | Holy (healing, buffs) | Divine Wrath (smite, undead damage) |
+| **Wildstrider** | Ranged/nature | 10 | Marksmanship (bow skills, critical shots) | Beast Master (pet companion, nature magic) |
+| **Oathkeeper** | Hybrid tank/healer | 9 | Protection (defensive auras, healing) | Retribution (holy damage, smites) |
+| **Necromancer** | Death magic/summon | 7 | Dark Arts (curses, life drain) | Summoning (undead minions) |
+| **Lorekeeper** | Support/control | 10 | Performance (buffs, debuffs via music) | Trickery (illusions, charm) |
+
+**Class Luck Values:**
+- **Assassin (12):** Highest luck - critical strike specialists benefit most from fortune
+- **Luminary (11):** Divine favor grants above-average luck
+- **Wildstrider (10):** Average luck - self-reliant nature
+- **Lorekeeper (10):** Average luck - knowledge is their advantage
+- **Arcanist (9):** Slight chaos magic influence
+- **Oathkeeper (9):** Honorable path grants modest fortune
+- **Vanguard (8):** Relies on strength and skill, not luck
+- **Necromancer (7):** Lowest luck - dark arts exact a toll
 
 **Extensibility:** Class system designed to easily add more classes in future updates.
 
@@ -514,6 +708,149 @@ merchants = loader.get_npcs_by_tag("merchant")
 - **Consumable:** One-time use (potions, scrolls)
 - **Quest Item:** Story-related, non-tradeable
 
+---
+
+## Procedural Item Generation (Affix System)
+
+The game uses a Diablo-style procedural item generation system where weapons and armor
+are created by combining base templates with random affixes.
+
+### Core Models
+
+#### Affix
+
+Represents a prefix or suffix that modifies an item's stats and name.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `affix_id` | str | Unique identifier |
+| `name` | str | Display name ("Flaming", "of Strength") |
+| `affix_type` | AffixType | PREFIX or SUFFIX |
+| `tier` | AffixTier | MINOR, MAJOR, or LEGENDARY |
+| `description` | str | Affix description |
+| `stat_bonuses` | Dict[str, int] | Stat modifications |
+| `damage_bonus` | int | Flat damage increase |
+| `defense_bonus` | int | Flat defense increase |
+| `resistance_bonus` | int | Flat resistance increase |
+| `damage_type` | DamageType | For elemental affixes |
+| `elemental_ratio` | float | Portion of damage converted to element |
+| `crit_chance_bonus` | float | Critical hit chance modifier |
+| `crit_multiplier_bonus` | float | Critical damage modifier |
+| `allowed_item_types` | List[str] | Item types this affix can apply to |
+| `required_rarity` | str | Minimum rarity required (for legendary affixes) |
+
+**Methods:**
+- `applies_elemental_damage() -> bool` - Check if affix adds elemental damage
+- `is_legendary_only() -> bool` - Check if requires legendary rarity
+- `can_apply_to(item_type, rarity) -> bool` - Check if affix can be applied
+
+#### BaseItemTemplate
+
+Foundation template for procedural item generation.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `template_id` | str | Unique identifier |
+| `name` | str | Base item name ("Dagger") |
+| `item_type` | str | "weapon" or "armor" |
+| `description` | str | Template description |
+| `base_damage` | int | Starting damage value |
+| `base_defense` | int | Starting defense value |
+| `base_resistance` | int | Starting resistance value |
+| `base_value` | int | Base gold value |
+| `damage_type` | str | Physical, fire, etc. |
+| `crit_chance` | float | Base critical chance |
+| `crit_multiplier` | float | Base critical multiplier |
+| `required_level` | int | Minimum level to use |
+| `min_rarity` | str | Minimum rarity this generates as |
+| `drop_weight` | int | Relative drop probability |
+
+**Methods:**
+- `can_generate_at_rarity(rarity) -> bool` - Check if template supports rarity
+- `can_drop_for_level(level) -> bool` - Check level requirement
+
+### Item Model Updates for Generated Items
+
+The `Item` dataclass includes fields for tracking generated items:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `applied_affixes` | List[str] | IDs of affixes on this item |
+| `base_template_id` | str | ID of base template used |
+| `generated_name` | str | Full name with affixes (e.g., "Flaming Dagger of Strength") |
+| `is_generated` | bool | True if procedurally generated |
+
+**Methods:**
+- `get_display_name() -> str` - Returns generated_name if available, otherwise base name
+
+### Generation Enumerations
+
+#### ItemRarity
+
+Item quality tiers affecting affix count and value:
+
+| Value | Affix Count | Value Multiplier |
+|-------|-------------|------------------|
+| `COMMON` | 0 | 1.0× |
+| `UNCOMMON` | 0 | 1.5× |
+| `RARE` | 1 | 2.5× |
+| `EPIC` | 2 | 5.0× |
+| `LEGENDARY` | 3 | 10.0× |
+
+#### AffixType
+
+| Value | Description |
+|-------|-------------|
+| `PREFIX` | Appears before item name ("Flaming Dagger") |
+| `SUFFIX` | Appears after item name ("Dagger of Strength") |
+
+#### AffixTier
+
+Affix power level, determines eligibility by item rarity:
+
+| Value | Description | Available For |
+|-------|-------------|---------------|
+| `MINOR` | Basic affixes | RARE+ |
+| `MAJOR` | Stronger affixes | RARE+ (higher weight at EPIC+) |
+| `LEGENDARY` | Most powerful affixes | LEGENDARY only |
+
+### Item Generation Service
+
+**Location:** `/app/services/item_generator.py`
+
+**Usage:**
+```python
+from app.services.item_generator import get_item_generator
+from app.models.enums import ItemRarity
+
+generator = get_item_generator()
+
+# Generate specific item
+item = generator.generate_item(
+    item_type="weapon",
+    rarity=ItemRarity.EPIC,
+    character_level=5
+)
+
+# Generate random loot drop with luck influence
+item = generator.generate_loot_drop(
+    character_level=10,
+    luck_stat=12
+)
+```
+
+**Related Loaders:**
+- `AffixLoader` (`/app/services/affix_loader.py`) - Loads affix definitions from YAML
+- `BaseItemLoader` (`/app/services/base_item_loader.py`) - Loads base templates from YAML
+
+**Data Files:**
+- `/app/data/affixes/prefixes.yaml` - Prefix definitions
+- `/app/data/affixes/suffixes.yaml` - Suffix definitions
+- `/app/data/base_items/weapons.yaml` - Weapon templates
+- `/app/data/base_items/armor.yaml` - Armor templates
+
+---
+
 ### Ability
 
 Abilities represent actions that can be taken in combat (attacks, spells, skills, item uses).

api/docs/GAME_SYSTEMS.md

@@ -402,6 +402,111 @@ effects_applied:
 
 ---
 
+## Procedural Item Generation
+
+### Overview
+
+Weapons and armor are procedurally generated using a Diablo-style affix system.
+Items are created by combining:
+1. **Base Template** - Defines item type, base stats, level requirement
+2. **Affixes** - Prefixes and suffixes that add stats and modify the name
+
+### Generation Process
+
+1. Select base template (filtered by level, rarity)
+2. Determine affix count based on rarity (0-3)
+3. Roll affix tier based on rarity weights
+4. Select random affixes avoiding duplicates
+5. Combine stats and generate name
+
+### Rarity System
+
+| Rarity | Affixes | Value Multiplier | Color |
+|--------|---------|------------------|-------|
+| COMMON | 0 | 1.0× | Gray |
+| UNCOMMON | 0 | 1.5× | Green |
+| RARE | 1 | 2.5× | Blue |
+| EPIC | 2 | 5.0× | Purple |
+| LEGENDARY | 3 | 10.0× | Orange |
+
+### Affix Distribution
+
+| Rarity | Affix Count | Distribution |
+|--------|-------------|--------------|
+| RARE | 1 | 50% prefix OR 50% suffix |
+| EPIC | 2 | 1 prefix AND 1 suffix |
+| LEGENDARY | 3 | Mix (2+1 or 1+2) |
+
+### Affix Tiers
+
+Higher rarity items have better chances at higher tier affixes:
+
+| Rarity | MINOR | MAJOR | LEGENDARY |
+|--------|-------|-------|-----------|
+| RARE | 80% | 20% | 0% |
+| EPIC | 30% | 70% | 0% |
+| LEGENDARY | 10% | 40% | 50% |
+
+### Name Generation Examples
+
+- **COMMON:** "Dagger"
+- **RARE (prefix):** "Flaming Dagger"
+- **RARE (suffix):** "Dagger of Strength"
+- **EPIC:** "Flaming Dagger of Strength"
+- **LEGENDARY:** "Blazing Glacial Dagger of the Titan"
+
+### Luck Influence
+
+Player's LUK stat affects rarity rolls for loot drops:
+
+**Base chances at LUK 8:**
+- COMMON: 50%
+- UNCOMMON: 30%
+- RARE: 15%
+- EPIC: 4%
+- LEGENDARY: 1%
+
+**Luck Bonus:**
+Each point of LUK above 8 adds +0.5% to higher rarity chances.
+
+**Examples:**
+- LUK 8 (baseline): 1% legendary chance
+- LUK 12: ~3% legendary chance
+- LUK 16: ~5% legendary chance
+
+### Service Usage
+
+```python
+from app.services.item_generator import get_item_generator
+from app.models.enums import ItemRarity
+
+generator = get_item_generator()
+
+# Generate item of specific rarity
+sword = generator.generate_item(
+    item_type="weapon",
+    rarity=ItemRarity.EPIC,
+    character_level=5
+)
+
+# Generate random loot with luck bonus
+loot = generator.generate_loot_drop(
+    character_level=10,
+    luck_stat=15
+)
+```
+
+### Data Files
+
+| File | Description |
+|------|-------------|
+| `/app/data/base_items/weapons.yaml` | 13 weapon templates |
+| `/app/data/base_items/armor.yaml` | 12 armor templates |
+| `/app/data/affixes/prefixes.yaml` | 18 prefix affixes |
+| `/app/data/affixes/suffixes.yaml` | 11 suffix affixes |
+
+---
+
 ## Quest System (Future)
 
 ### Quest Types

api/docs/SESSION_MANAGEMENT.md

@@ -126,13 +126,21 @@ session = service.create_solo_session(
 
 **Validations:**
 - User must own the character
-- User cannot exceed 5 active sessions
+- User cannot exceed their tier's session limit
+
+**Session Limits by Tier:**
+| Tier | Max Sessions |
+|------|--------------|
+| FREE | 1 |
+| BASIC | 2 |
+| PREMIUM | 3 |
+| ELITE | 5 |
 
 **Returns:** `GameSession` instance
 
 **Raises:**
 - `CharacterNotFound` - Character doesn't exist or user doesn't own it
-- `SessionLimitExceeded` - User has 5+ active sessions
+- `SessionLimitExceeded` - User has reached their tier's session limit
 
 ### Retrieving Sessions
 
@@ -284,10 +292,18 @@ session = service.add_world_event(
 
 | Limit | Value | Notes |
 |-------|-------|-------|
-| Active sessions per user | 5 | End existing sessions to create new |
+| Active sessions per user | Tier-based (1-5) | See tier limits below |
 | Active quests per session | 2 | Complete or abandon to accept new |
 | Conversation history | Unlimited | Consider archiving for very long sessions |
 
+**Session Limits by Tier:**
+| Tier | Max Sessions |
+|------|--------------|
+| FREE | 1 |
+| BASIC | 2 |
+| PREMIUM | 3 |
+| ELITE | 5 |
+
 ---
 
 ## Database Schema
@@ -400,7 +416,7 @@ except SessionNotFound:
 try:
     service.create_solo_session(user_id, char_id)
 except SessionLimitExceeded:
-    # User has 5+ active sessions
+    # User has reached their tier's session limit
     pass
 
 try:

api/docs/USAGE_TRACKING.md

@@ -270,14 +270,33 @@ class MonthlyUsageSummary:
 
 ### Daily Turn Limits
 
+Limits are loaded from config (`rate_limiting.tiers.{tier}.ai_calls_per_day`):
+
 | Tier | Limit | Cost Level |
 |------|-------|------------|
-| FREE | 20 turns/day | Zero |
-| BASIC | 50 turns/day | Low |
-| PREMIUM | 100 turns/day | Medium |
-| ELITE | 200 turns/day | High |
+| FREE | 50 turns/day | Zero |
+| BASIC | 200 turns/day | Low |
+| PREMIUM | 1000 turns/day | Medium |
+| ELITE | Unlimited | High |
 
-Counters reset at midnight UTC.
+Counters reset at midnight UTC. A value of `-1` in config means unlimited.
+
+### Usage API Endpoint
+
+Get current usage info via `GET /api/v1/usage`:
+
+```json
+{
+    "user_id": "user_123",
+    "user_tier": "free",
+    "current_usage": 15,
+    "daily_limit": 50,
+    "remaining": 35,
+    "reset_time": "2025-11-27T00:00:00+00:00",
+    "is_limited": false,
+    "is_unlimited": false
+}
+```
 
 ### Custom Action Limits
 
@@ -342,14 +361,15 @@ info = limiter.get_usage_info("user_123", UserTier.PREMIUM)
 #     "user_id": "user_123",
 #     "user_tier": "premium",
 #     "current_usage": 45,
-#     "daily_limit": 100,
-#     "remaining": 55,
+#     "daily_limit": 1000,
+#     "remaining": 955,
 #     "reset_time": "2025-11-22T00:00:00+00:00",
-#     "is_limited": False
+#     "is_limited": False,
+#     "is_unlimited": False
 # }
 
-# Get limit for tier
-limit = limiter.get_limit_for_tier(UserTier.ELITE)  # 200
+# Get limit for tier (-1 means unlimited)
+limit = limiter.get_limit_for_tier(UserTier.ELITE)  # -1 (unlimited)
 ```
 
 ### Admin Functions
@@ -539,9 +559,11 @@ When rate limited, prompt upgrades:
 
 ```python
 if e.user_tier == UserTier.FREE:
-    message = "Upgrade to Basic for 50 turns/day!"
+    message = "Upgrade to Basic for 200 turns/day!"
 elif e.user_tier == UserTier.BASIC:
-    message = "Upgrade to Premium for 100 turns/day!"
+    message = "Upgrade to Premium for 1000 turns/day!"
+elif e.user_tier == UserTier.PREMIUM:
+    message = "Upgrade to Elite for unlimited turns!"
 ```
 
 ---
@@ -585,8 +607,8 @@ def test_log_usage():
 def test_rate_limit_exceeded():
     limiter = RateLimiterService()
 
-    # Exceed free tier limit
-    for _ in range(20):
+    # Exceed free tier limit (50 from config)
+    for _ in range(50):
         limiter.increment_usage("test_user")
 
     with pytest.raises(RateLimitExceeded):

api/tests/test_character.py

@@ -452,3 +452,183 @@ def test_character_round_trip_serialization(basic_character):
     assert restored.unlocked_skills == basic_character.unlocked_skills
     assert "weapon" in restored.equipped
     assert restored.equipped["weapon"].item_id == "sword"
+
+
+# =============================================================================
+# Equipment Combat Bonuses (Task 2.5)
+# =============================================================================
+
+def test_get_effective_stats_weapon_damage_bonus(basic_character):
+    """Test that weapon damage is added to effective stats damage_bonus."""
+    # Create weapon with damage
+    weapon = Item(
+        item_id="iron_sword",
+        name="Iron Sword",
+        item_type=ItemType.WEAPON,
+        description="A sturdy iron sword",
+        damage=15,  # 15 damage
+    )
+
+    basic_character.equipped["weapon"] = weapon
+    effective = basic_character.get_effective_stats()
+
+    # Base strength is 12, so base damage = int(12 * 0.75) = 9
+    # Weapon damage = 15
+    # Total damage property = 9 + 15 = 24
+    assert effective.damage_bonus == 15
+    assert effective.damage == 24  # int(12 * 0.75) + 15
+
+
+def test_get_effective_stats_armor_defense_bonus(basic_character):
+    """Test that armor defense is added to effective stats defense_bonus."""
+    # Create armor with defense
+    armor = Item(
+        item_id="iron_chestplate",
+        name="Iron Chestplate",
+        item_type=ItemType.ARMOR,
+        description="A sturdy iron chestplate",
+        defense=10,
+        resistance=0,
+    )
+
+    basic_character.equipped["chest"] = armor
+    effective = basic_character.get_effective_stats()
+
+    # Base constitution is 14, so base defense = 14 // 2 = 7
+    # Armor defense = 10
+    # Total defense property = 7 + 10 = 17
+    assert effective.defense_bonus == 10
+    assert effective.defense == 17  # (14 // 2) + 10
+
+
+def test_get_effective_stats_armor_resistance_bonus(basic_character):
+    """Test that armor resistance is added to effective stats resistance_bonus."""
+    # Create armor with resistance
+    robe = Item(
+        item_id="magic_robe",
+        name="Magic Robe",
+        item_type=ItemType.ARMOR,
+        description="An enchanted robe",
+        defense=2,
+        resistance=8,
+    )
+
+    basic_character.equipped["chest"] = robe
+    effective = basic_character.get_effective_stats()
+
+    # Base wisdom is 10, so base resistance = 10 // 2 = 5
+    # Armor resistance = 8
+    # Total resistance property = 5 + 8 = 13
+    assert effective.resistance_bonus == 8
+    assert effective.resistance == 13  # (10 // 2) + 8
+
+
+def test_get_effective_stats_multiple_armor_pieces(basic_character):
+    """Test that multiple armor pieces stack their bonuses."""
+    # Create multiple armor pieces
+    helmet = Item(
+        item_id="iron_helmet",
+        name="Iron Helmet",
+        item_type=ItemType.ARMOR,
+        description="Protects your head",
+        defense=5,
+        resistance=2,
+    )
+
+    chestplate = Item(
+        item_id="iron_chestplate",
+        name="Iron Chestplate",
+        item_type=ItemType.ARMOR,
+        description="Protects your torso",
+        defense=10,
+        resistance=3,
+    )
+
+    boots = Item(
+        item_id="iron_boots",
+        name="Iron Boots",
+        item_type=ItemType.ARMOR,
+        description="Protects your feet",
+        defense=3,
+        resistance=1,
+    )
+
+    basic_character.equipped["helmet"] = helmet
+    basic_character.equipped["chest"] = chestplate
+    basic_character.equipped["boots"] = boots
+
+    effective = basic_character.get_effective_stats()
+
+    # Total defense bonus = 5 + 10 + 3 = 18
+    # Total resistance bonus = 2 + 3 + 1 = 6
+    assert effective.defense_bonus == 18
+    assert effective.resistance_bonus == 6
+
+    # Base constitution is 14: base defense = 7
+    # Base wisdom is 10: base resistance = 5
+    assert effective.defense == 25  # 7 + 18
+    assert effective.resistance == 11  # 5 + 6
+
+
+def test_get_effective_stats_weapon_and_armor_combined(basic_character):
+    """Test that weapon damage and armor defense/resistance work together."""
+    # Create weapon
+    weapon = Item(
+        item_id="flaming_sword",
+        name="Flaming Sword",
+        item_type=ItemType.WEAPON,
+        description="A sword wreathed in flame",
+        damage=18,
+        stat_bonuses={"strength": 3},  # Also has stat bonus
+    )
+
+    # Create armor
+    armor = Item(
+        item_id="dragon_armor",
+        name="Dragon Armor",
+        item_type=ItemType.ARMOR,
+        description="Forged from dragon scales",
+        defense=15,
+        resistance=10,
+        stat_bonuses={"constitution": 2},  # Also has stat bonus
+    )
+
+    basic_character.equipped["weapon"] = weapon
+    basic_character.equipped["chest"] = armor
+
+    effective = basic_character.get_effective_stats()
+
+    # Weapon: damage=18, +3 STR
+    # Armor: defense=15, resistance=10, +2 CON
+    # Base STR=12 -> 12+3=15, damage = int(15 * 0.75) + 18 = 11 + 18 = 29
+    assert effective.strength == 15
+    assert effective.damage_bonus == 18
+    assert effective.damage == 29
+
+    # Base CON=14 -> 14+2=16, defense = (16//2) + 15 = 8 + 15 = 23
+    assert effective.constitution == 16
+    assert effective.defense_bonus == 15
+    assert effective.defense == 23
+
+    # Base WIS=10, resistance = (10//2) + 10 = 5 + 10 = 15
+    assert effective.resistance_bonus == 10
+    assert effective.resistance == 15
+
+
+def test_get_effective_stats_no_equipment_bonuses(basic_character):
+    """Test that bonus fields are zero when no equipment is equipped."""
+    effective = basic_character.get_effective_stats()
+
+    assert effective.damage_bonus == 0
+    assert effective.defense_bonus == 0
+    assert effective.resistance_bonus == 0
+
+    # Damage/defense/resistance should just be base stat derived values
+    # Base STR=12, damage = int(12 * 0.75) = 9
+    assert effective.damage == 9
+
+    # Base CON=14, defense = 14 // 2 = 7
+    assert effective.defense == 7
+
+    # Base WIS=10, resistance = 10 // 2 = 5
+    assert effective.resistance == 5

api/tests/test_combat_api.py

@@ -0,0 +1,376 @@
+"""
+Integration tests for Combat API endpoints.
+
+Tests the REST API endpoints for combat functionality.
+"""
+
+import pytest
+from unittest.mock import Mock, patch, MagicMock
+from flask import Flask
+import json
+
+from app import create_app
+from app.api.combat import combat_bp
+from app.models.combat import CombatEncounter, Combatant, CombatStatus
+from app.models.stats import Stats
+from app.models.enemy import EnemyTemplate, EnemyDifficulty
+from app.services.combat_service import CombatService, ActionResult, CombatRewards
+
+
+# =============================================================================
+# Test Fixtures
+# =============================================================================
+
+@pytest.fixture
+def app():
+    """Create test Flask application."""
+    app = create_app('development')
+    app.config['TESTING'] = True
+    return app
+
+
+@pytest.fixture
+def client(app):
+    """Create test client."""
+    return app.test_client()
+
+
+@pytest.fixture
+def sample_stats():
+    """Sample stats for testing."""
+    return Stats(
+        strength=12,
+        dexterity=14,
+        constitution=10,
+        intelligence=10,
+        wisdom=10,
+        charisma=10,
+        luck=10
+    )
+
+
+@pytest.fixture
+def sample_combatant(sample_stats):
+    """Sample player combatant."""
+    return Combatant(
+        combatant_id="test_char_001",
+        name="Test Hero",
+        is_player=True,
+        current_hp=50,
+        max_hp=50,
+        current_mp=30,
+        max_mp=30,
+        stats=sample_stats,
+        abilities=["basic_attack", "power_strike"],
+    )
+
+
+@pytest.fixture
+def sample_enemy_combatant(sample_stats):
+    """Sample enemy combatant."""
+    return Combatant(
+        combatant_id="test_goblin_0",
+        name="Test Goblin",
+        is_player=False,
+        current_hp=25,
+        max_hp=25,
+        current_mp=10,
+        max_mp=10,
+        stats=sample_stats,
+        abilities=["basic_attack"],
+    )
+
+
+@pytest.fixture
+def sample_encounter(sample_combatant, sample_enemy_combatant):
+    """Sample combat encounter."""
+    encounter = CombatEncounter(
+        encounter_id="test_encounter_001",
+        combatants=[sample_combatant, sample_enemy_combatant],
+        turn_order=[sample_combatant.combatant_id, sample_enemy_combatant.combatant_id],
+        round_number=1,
+        current_turn_index=0,
+        status=CombatStatus.ACTIVE,
+    )
+    return encounter
+
+
+# =============================================================================
+# List Enemies Endpoint Tests
+# =============================================================================
+
+class TestListEnemiesEndpoint:
+    """Tests for GET /api/v1/combat/enemies endpoint."""
+
+    def test_list_enemies_success(self, client):
+        """Test listing all enemy templates."""
+        response = client.get('/api/v1/combat/enemies')
+
+        assert response.status_code == 200
+        data = response.get_json()
+
+        assert data['status'] == 200
+        assert 'result' in data
+        assert 'enemies' in data['result']
+
+        enemies = data['result']['enemies']
+        assert isinstance(enemies, list)
+        assert len(enemies) >= 6  # We have 6 sample enemies
+
+        # Verify enemy structure
+        enemy_ids = [e['enemy_id'] for e in enemies]
+        assert 'goblin' in enemy_ids
+
+    def test_list_enemies_filter_by_difficulty(self, client):
+        """Test filtering enemies by difficulty."""
+        response = client.get('/api/v1/combat/enemies?difficulty=easy')
+
+        assert response.status_code == 200
+        data = response.get_json()
+
+        enemies = data['result']['enemies']
+        for enemy in enemies:
+            assert enemy['difficulty'] == 'easy'
+
+    def test_list_enemies_filter_by_tag(self, client):
+        """Test filtering enemies by tag."""
+        response = client.get('/api/v1/combat/enemies?tag=humanoid')
+
+        assert response.status_code == 200
+        data = response.get_json()
+
+        enemies = data['result']['enemies']
+        for enemy in enemies:
+            assert 'humanoid' in [t.lower() for t in enemy['tags']]
+
+
+# =============================================================================
+# Get Enemy Details Endpoint Tests
+# =============================================================================
+
+class TestGetEnemyEndpoint:
+    """Tests for GET /api/v1/combat/enemies/<enemy_id> endpoint."""
+
+    def test_get_enemy_success(self, client):
+        """Test getting enemy details."""
+        response = client.get('/api/v1/combat/enemies/goblin')
+
+        assert response.status_code == 200
+        data = response.get_json()
+
+        assert data['status'] == 200
+        # Enemy data is returned directly in result (not nested under 'enemy' key)
+        assert data['result']['enemy_id'] == 'goblin'
+        assert 'base_stats' in data['result']
+        assert 'loot_table' in data['result']
+
+    def test_get_enemy_not_found(self, client):
+        """Test getting non-existent enemy."""
+        response = client.get('/api/v1/combat/enemies/nonexistent_12345')
+
+        assert response.status_code == 404
+        data = response.get_json()
+        assert data['status'] == 404
+
+
+# =============================================================================
+# Start Combat Endpoint Tests
+# =============================================================================
+
+class TestStartCombatEndpoint:
+    """Tests for POST /api/v1/combat/start endpoint."""
+
+    def test_start_combat_requires_auth(self, client):
+        """Test that start combat endpoint requires authentication."""
+        response = client.post(
+            '/api/v1/combat/start',
+            json={
+                'session_id': 'test_session_001',
+                'enemy_ids': ['goblin', 'goblin']
+            }
+        )
+
+        # Should return 401 Unauthorized without valid session
+        assert response.status_code == 401
+
+    def test_start_combat_missing_session_id(self, client):
+        """Test starting combat without session_id."""
+        response = client.post(
+            '/api/v1/combat/start',
+            json={'enemy_ids': ['goblin']},
+        )
+
+        assert response.status_code in [400, 401]
+
+    def test_start_combat_missing_enemies(self, client):
+        """Test starting combat without enemies."""
+        response = client.post(
+            '/api/v1/combat/start',
+            json={'session_id': 'test_session'},
+        )
+
+        assert response.status_code in [400, 401]
+
+
+# =============================================================================
+# Execute Action Endpoint Tests
+# =============================================================================
+
+class TestExecuteActionEndpoint:
+    """Tests for POST /api/v1/combat/<session_id>/action endpoint."""
+
+    def test_action_requires_auth(self, client):
+        """Test that action endpoint requires authentication."""
+        response = client.post(
+            '/api/v1/combat/test_session/action',
+            json={
+                'action_type': 'attack',
+                'target_ids': ['enemy_001']
+            }
+        )
+
+        # Should return 401 Unauthorized without valid session
+        assert response.status_code == 401
+
+    def test_action_missing_type(self, client):
+        """Test action with missing action_type still requires auth."""
+        # Without auth, returns 401 regardless of payload issues
+        response = client.post(
+            '/api/v1/combat/test_session/action',
+            json={'target_ids': ['enemy_001']}
+        )
+
+        assert response.status_code == 401
+
+
+# =============================================================================
+# Enemy Turn Endpoint Tests
+# =============================================================================
+
+class TestEnemyTurnEndpoint:
+    """Tests for POST /api/v1/combat/<session_id>/enemy-turn endpoint."""
+
+    def test_enemy_turn_requires_auth(self, client):
+        """Test that enemy turn endpoint requires authentication."""
+        response = client.post('/api/v1/combat/test_session/enemy-turn')
+
+        assert response.status_code == 401
+
+
+# =============================================================================
+# Flee Endpoint Tests
+# =============================================================================
+
+class TestFleeEndpoint:
+    """Tests for POST /api/v1/combat/<session_id>/flee endpoint."""
+
+    def test_flee_requires_auth(self, client):
+        """Test that flee endpoint requires authentication."""
+        response = client.post('/api/v1/combat/test_session/flee')
+
+        assert response.status_code == 401
+
+
+# =============================================================================
+# Get Combat State Endpoint Tests
+# =============================================================================
+
+class TestGetCombatStateEndpoint:
+    """Tests for GET /api/v1/combat/<session_id>/state endpoint."""
+
+    def test_state_requires_auth(self, client):
+        """Test that state endpoint requires authentication."""
+        response = client.get('/api/v1/combat/test_session/state')
+
+        assert response.status_code == 401
+
+
+# =============================================================================
+# End Combat Endpoint Tests
+# =============================================================================
+
+class TestEndCombatEndpoint:
+    """Tests for POST /api/v1/combat/<session_id>/end endpoint."""
+
+    def test_end_requires_auth(self, client):
+        """Test that end combat endpoint requires authentication."""
+        response = client.post('/api/v1/combat/test_session/end')
+
+        assert response.status_code == 401
+
+
+# =============================================================================
+# Response Format Tests
+# =============================================================================
+
+class TestCombatAPIResponseFormat:
+    """Tests for API response format consistency."""
+
+    def test_enemies_response_format(self, client):
+        """Test that enemies list has standard response format."""
+        response = client.get('/api/v1/combat/enemies')
+        data = response.get_json()
+
+        # Standard response fields
+        assert 'app' in data
+        assert 'version' in data
+        assert 'status' in data
+        assert 'timestamp' in data
+        assert 'result' in data
+
+        # Should not have error for successful request
+        assert data['error'] is None or 'error' not in data or data['error'] == {}
+
+    def test_enemy_details_response_format(self, client):
+        """Test that enemy details has standard response format."""
+        response = client.get('/api/v1/combat/enemies/goblin')
+        data = response.get_json()
+
+        assert data['status'] == 200
+        assert 'result' in data
+
+        # Enemy data is returned directly in result
+        enemy = data['result']
+        # Required enemy fields
+        assert 'enemy_id' in enemy
+        assert 'name' in enemy
+        assert 'description' in enemy
+        assert 'base_stats' in enemy
+        assert 'difficulty' in enemy
+
+    def test_not_found_response_format(self, client):
+        """Test 404 response format."""
+        response = client.get('/api/v1/combat/enemies/nonexistent_enemy_xyz')
+        data = response.get_json()
+
+        assert data['status'] == 404
+        assert 'error' in data
+        assert data['error'] is not None
+
+
+# =============================================================================
+# Content Type Tests
+# =============================================================================
+
+class TestCombatAPIContentType:
+    """Tests for content type handling."""
+
+    def test_json_content_type_response(self, client):
+        """Test that API returns JSON content type."""
+        response = client.get('/api/v1/combat/enemies')
+
+        assert response.content_type == 'application/json'
+
+    def test_accepts_json_payload(self, client):
+        """Test that API accepts JSON payloads."""
+        response = client.post(
+            '/api/v1/combat/start',
+            data=json.dumps({
+                'session_id': 'test',
+                'enemy_ids': ['goblin']
+            }),
+            content_type='application/json'
+        )
+
+        # Should process JSON (even if auth fails)
+        assert response.status_code in [200, 400, 401]

api/tests/test_combat_loot_service.py

@@ -0,0 +1,428 @@
+"""
+Tests for CombatLootService.
+
+Tests the service that orchestrates loot generation from combat,
+supporting both static and procedural loot drops.
+"""
+
+import pytest
+from unittest.mock import Mock, patch
+
+from app.services.combat_loot_service import (
+    CombatLootService,
+    LootContext,
+    get_combat_loot_service,
+    DIFFICULTY_RARITY_BONUS,
+    LUCK_CONVERSION_FACTOR
+)
+from app.models.enemy import (
+    EnemyTemplate,
+    EnemyDifficulty,
+    LootEntry,
+    LootType
+)
+from app.models.stats import Stats
+from app.models.items import Item
+from app.models.enums import ItemType, ItemRarity
+
+
+class TestLootContext:
+    """Test LootContext dataclass."""
+
+    def test_default_values(self):
+        """Test default context values."""
+        context = LootContext()
+
+        assert context.party_average_level == 1
+        assert context.enemy_difficulty == EnemyDifficulty.EASY
+        assert context.luck_stat == 8
+        assert context.loot_bonus == 0.0
+
+    def test_custom_values(self):
+        """Test creating context with custom values."""
+        context = LootContext(
+            party_average_level=10,
+            enemy_difficulty=EnemyDifficulty.HARD,
+            luck_stat=15,
+            loot_bonus=0.1
+        )
+
+        assert context.party_average_level == 10
+        assert context.enemy_difficulty == EnemyDifficulty.HARD
+        assert context.luck_stat == 15
+        assert context.loot_bonus == 0.1
+
+
+class TestDifficultyBonuses:
+    """Test difficulty rarity bonus constants."""
+
+    def test_easy_bonus(self):
+        """Easy enemies have no bonus."""
+        assert DIFFICULTY_RARITY_BONUS[EnemyDifficulty.EASY] == 0.0
+
+    def test_medium_bonus(self):
+        """Medium enemies have small bonus."""
+        assert DIFFICULTY_RARITY_BONUS[EnemyDifficulty.MEDIUM] == 0.05
+
+    def test_hard_bonus(self):
+        """Hard enemies have moderate bonus."""
+        assert DIFFICULTY_RARITY_BONUS[EnemyDifficulty.HARD] == 0.15
+
+    def test_boss_bonus(self):
+        """Boss enemies have large bonus."""
+        assert DIFFICULTY_RARITY_BONUS[EnemyDifficulty.BOSS] == 0.30
+
+
+class TestCombatLootServiceInit:
+    """Test service initialization."""
+
+    def test_init_uses_defaults(self):
+        """Service should initialize with default dependencies."""
+        service = CombatLootService()
+
+        assert service.item_generator is not None
+        assert service.static_loader is not None
+
+    def test_singleton_returns_same_instance(self):
+        """get_combat_loot_service should return singleton."""
+        service1 = get_combat_loot_service()
+        service2 = get_combat_loot_service()
+
+        assert service1 is service2
+
+
+class TestCombatLootServiceEffectiveLuck:
+    """Test effective luck calculation."""
+
+    def test_base_luck_no_bonus(self):
+        """With no bonuses, effective luck equals base luck."""
+        service = CombatLootService()
+
+        entry = LootEntry(
+            loot_type=LootType.PROCEDURAL,
+            item_type="weapon",
+            rarity_bonus=0.0
+        )
+        context = LootContext(
+            luck_stat=8,
+            enemy_difficulty=EnemyDifficulty.EASY,
+            loot_bonus=0.0
+        )
+
+        effective = service._calculate_effective_luck(entry, context)
+
+        # No bonus, so effective should equal base
+        assert effective == 8
+
+    def test_difficulty_bonus_adds_luck(self):
+        """Difficulty bonus should increase effective luck."""
+        service = CombatLootService()
+
+        entry = LootEntry(
+            loot_type=LootType.PROCEDURAL,
+            item_type="weapon",
+            rarity_bonus=0.0
+        )
+        context = LootContext(
+            luck_stat=8,
+            enemy_difficulty=EnemyDifficulty.BOSS,  # 0.30 bonus
+            loot_bonus=0.0
+        )
+
+        effective = service._calculate_effective_luck(entry, context)
+
+        # Boss bonus = 0.30 * 20 = 6 extra luck
+        assert effective == 8 + 6
+
+    def test_entry_rarity_bonus_adds_luck(self):
+        """Entry rarity bonus should increase effective luck."""
+        service = CombatLootService()
+
+        entry = LootEntry(
+            loot_type=LootType.PROCEDURAL,
+            item_type="weapon",
+            rarity_bonus=0.10  # Entry-specific bonus
+        )
+        context = LootContext(
+            luck_stat=8,
+            enemy_difficulty=EnemyDifficulty.EASY,
+            loot_bonus=0.0
+        )
+
+        effective = service._calculate_effective_luck(entry, context)
+
+        # 0.10 * 20 = 2 extra luck
+        assert effective == 8 + 2
+
+    def test_combined_bonuses(self):
+        """All bonuses should stack."""
+        service = CombatLootService()
+
+        entry = LootEntry(
+            loot_type=LootType.PROCEDURAL,
+            item_type="weapon",
+            rarity_bonus=0.10
+        )
+        context = LootContext(
+            luck_stat=10,
+            enemy_difficulty=EnemyDifficulty.HARD,  # 0.15
+            loot_bonus=0.05
+        )
+
+        effective = service._calculate_effective_luck(entry, context)
+
+        # Total bonus = 0.10 + 0.15 + 0.05 = 0.30
+        # Extra luck = 0.30 * 20 = 6
+        expected = 10 + 6
+        assert effective == expected
+
+
+class TestCombatLootServiceStaticItems:
+    """Test static item generation."""
+
+    def test_generate_static_items_returns_items(self):
+        """Should return Item instances for static entries."""
+        service = CombatLootService()
+
+        entry = LootEntry(
+            loot_type=LootType.STATIC,
+            item_id="health_potion_small",
+            drop_chance=1.0
+        )
+
+        items = service._generate_static_items(entry, quantity=1)
+
+        assert len(items) == 1
+        assert items[0].name == "Small Health Potion"
+
+    def test_generate_static_items_respects_quantity(self):
+        """Should generate correct quantity of items."""
+        service = CombatLootService()
+
+        entry = LootEntry(
+            loot_type=LootType.STATIC,
+            item_id="goblin_ear",
+            drop_chance=1.0
+        )
+
+        items = service._generate_static_items(entry, quantity=3)
+
+        assert len(items) == 3
+        # All should be goblin ears with unique IDs
+        for item in items:
+            assert "goblin_ear" in item.item_id
+
+    def test_generate_static_items_missing_id(self):
+        """Should return empty list if item_id is missing."""
+        service = CombatLootService()
+
+        entry = LootEntry(
+            loot_type=LootType.STATIC,
+            item_id=None,
+            drop_chance=1.0
+        )
+
+        items = service._generate_static_items(entry, quantity=1)
+
+        assert len(items) == 0
+
+
+class TestCombatLootServiceProceduralItems:
+    """Test procedural item generation."""
+
+    def test_generate_procedural_items_returns_items(self):
+        """Should return generated Item instances."""
+        service = CombatLootService()
+
+        entry = LootEntry(
+            loot_type=LootType.PROCEDURAL,
+            item_type="weapon",
+            drop_chance=1.0,
+            rarity_bonus=0.0
+        )
+        context = LootContext(party_average_level=5)
+
+        items = service._generate_procedural_items(entry, quantity=1, context=context)
+
+        assert len(items) == 1
+        assert items[0].is_weapon()
+
+    def test_generate_procedural_armor(self):
+        """Should generate armor when item_type is armor."""
+        service = CombatLootService()
+
+        entry = LootEntry(
+            loot_type=LootType.PROCEDURAL,
+            item_type="armor",
+            drop_chance=1.0
+        )
+        context = LootContext(party_average_level=5)
+
+        items = service._generate_procedural_items(entry, quantity=1, context=context)
+
+        assert len(items) == 1
+        assert items[0].is_armor()
+
+    def test_generate_procedural_missing_type(self):
+        """Should return empty list if item_type is missing."""
+        service = CombatLootService()
+
+        entry = LootEntry(
+            loot_type=LootType.PROCEDURAL,
+            item_type=None,
+            drop_chance=1.0
+        )
+        context = LootContext()
+
+        items = service._generate_procedural_items(entry, quantity=1, context=context)
+
+        assert len(items) == 0
+
+
+class TestCombatLootServiceGenerateFromEnemy:
+    """Test full loot generation from enemy templates."""
+
+    @pytest.fixture
+    def sample_enemy(self):
+        """Create a sample enemy template for testing."""
+        return EnemyTemplate(
+            enemy_id="test_goblin",
+            name="Test Goblin",
+            description="A test goblin",
+            base_stats=Stats(),
+            abilities=["basic_attack"],
+            loot_table=[
+                LootEntry(
+                    loot_type=LootType.STATIC,
+                    item_id="goblin_ear",
+                    drop_chance=1.0,  # Guaranteed drop for testing
+                    quantity_min=1,
+                    quantity_max=1
+                )
+            ],
+            experience_reward=10,
+            difficulty=EnemyDifficulty.EASY
+        )
+
+    def test_generate_loot_from_enemy_basic(self, sample_enemy):
+        """Should generate loot from enemy loot table."""
+        service = CombatLootService()
+        context = LootContext()
+
+        items = service.generate_loot_from_enemy(sample_enemy, context)
+
+        assert len(items) == 1
+        assert "goblin_ear" in items[0].item_id
+
+    def test_generate_loot_respects_drop_chance(self):
+        """Items with 0 drop chance should never drop."""
+        enemy = EnemyTemplate(
+            enemy_id="test_enemy",
+            name="Test Enemy",
+            description="Test",
+            base_stats=Stats(),
+            abilities=[],
+            loot_table=[
+                LootEntry(
+                    loot_type=LootType.STATIC,
+                    item_id="rare_item",
+                    drop_chance=0.0,  # Never drops
+                )
+            ],
+            difficulty=EnemyDifficulty.EASY
+        )
+        service = CombatLootService()
+        context = LootContext()
+
+        # Run multiple times to ensure it never drops
+        for _ in range(10):
+            items = service.generate_loot_from_enemy(enemy, context)
+            assert len(items) == 0
+
+    def test_generate_loot_multiple_entries(self):
+        """Should process all loot table entries."""
+        enemy = EnemyTemplate(
+            enemy_id="test_enemy",
+            name="Test Enemy",
+            description="Test",
+            base_stats=Stats(),
+            abilities=[],
+            loot_table=[
+                LootEntry(
+                    loot_type=LootType.STATIC,
+                    item_id="goblin_ear",
+                    drop_chance=1.0,
+                ),
+                LootEntry(
+                    loot_type=LootType.STATIC,
+                    item_id="health_potion_small",
+                    drop_chance=1.0,
+                )
+            ],
+            difficulty=EnemyDifficulty.EASY
+        )
+        service = CombatLootService()
+        context = LootContext()
+
+        items = service.generate_loot_from_enemy(enemy, context)
+
+        assert len(items) == 2
+
+
+class TestCombatLootServiceBossLoot:
+    """Test boss loot generation."""
+
+    @pytest.fixture
+    def boss_enemy(self):
+        """Create a boss enemy template for testing."""
+        return EnemyTemplate(
+            enemy_id="test_boss",
+            name="Test Boss",
+            description="A test boss",
+            base_stats=Stats(strength=20, constitution=20),
+            abilities=["basic_attack"],
+            loot_table=[
+                LootEntry(
+                    loot_type=LootType.STATIC,
+                    item_id="goblin_chieftain_token",
+                    drop_chance=1.0,
+                )
+            ],
+            experience_reward=100,
+            difficulty=EnemyDifficulty.BOSS
+        )
+
+    def test_generate_boss_loot_includes_guaranteed_drops(self, boss_enemy):
+        """Boss loot should include guaranteed equipment drops."""
+        service = CombatLootService()
+        context = LootContext(party_average_level=10)
+
+        items = service.generate_boss_loot(boss_enemy, context, guaranteed_drops=1)
+
+        # Should have at least the loot table drop + guaranteed drop
+        assert len(items) >= 2
+
+    def test_generate_boss_loot_non_boss_skips_guaranteed(self):
+        """Non-boss enemies shouldn't get guaranteed drops."""
+        enemy = EnemyTemplate(
+            enemy_id="test_enemy",
+            name="Test Enemy",
+            description="Test",
+            base_stats=Stats(),
+            abilities=[],
+            loot_table=[
+                LootEntry(
+                    loot_type=LootType.STATIC,
+                    item_id="goblin_ear",
+                    drop_chance=1.0,
+                )
+            ],
+            difficulty=EnemyDifficulty.EASY  # Not a boss
+        )
+        service = CombatLootService()
+        context = LootContext()
+
+        items = service.generate_boss_loot(enemy, context, guaranteed_drops=2)
+
+        # Should only have the one loot table drop
+        assert len(items) == 1

api/tests/test_combat_service.py

@@ -0,0 +1,657 @@
+"""
+Unit tests for CombatService.
+
+Tests combat lifecycle, action execution, and reward distribution.
+Uses mocked dependencies to isolate combat logic testing.
+"""
+
+import pytest
+from unittest.mock import Mock, MagicMock, patch
+from uuid import uuid4
+
+from app.models.combat import Combatant, CombatEncounter
+from app.models.character import Character
+from app.models.stats import Stats
+from app.models.enemy import EnemyTemplate, EnemyDifficulty
+from app.models.enums import CombatStatus, AbilityType, DamageType
+from app.models.abilities import Ability
+from app.services.combat_service import (
+    CombatService,
+    CombatAction,
+    ActionResult,
+    CombatRewards,
+    NotInCombatError,
+    AlreadyInCombatError,
+    InvalidActionError,
+)
+
+
+# =============================================================================
+# Test Fixtures
+# =============================================================================
+
+@pytest.fixture
+def mock_stats():
+    """Create mock stats for testing."""
+    return Stats(
+        strength=12,
+        dexterity=10,
+        constitution=14,
+        intelligence=10,
+        wisdom=10,
+        charisma=8,
+        luck=8,
+    )
+
+
+@pytest.fixture
+def mock_character(mock_stats):
+    """Create a mock character for testing."""
+    char = Mock(spec=Character)
+    char.character_id = "test_char_001"
+    char.name = "Test Hero"
+    char.user_id = "test_user"
+    char.level = 5
+    char.experience = 1000
+    char.gold = 100
+    char.unlocked_skills = ["power_strike"]
+    char.equipped = {}  # No equipment by default
+    char.get_effective_stats = Mock(return_value=mock_stats)
+    return char
+
+
+@pytest.fixture
+def mock_enemy_template():
+    """Create a mock enemy template."""
+    return EnemyTemplate(
+        enemy_id="test_goblin",
+        name="Test Goblin",
+        description="A test goblin",
+        base_stats=Stats(
+            strength=8,
+            dexterity=12,
+            constitution=6,
+            intelligence=6,
+            wisdom=6,
+            charisma=4,
+            luck=8,
+        ),
+        abilities=["basic_attack"],
+        experience_reward=15,
+        gold_reward_min=2,
+        gold_reward_max=8,
+        difficulty=EnemyDifficulty.EASY,
+        tags=["humanoid", "goblinoid"],
+        base_damage=4,
+    )
+
+
+@pytest.fixture
+def mock_combatant():
+    """Create a mock player combatant."""
+    return Combatant(
+        combatant_id="test_char_001",
+        name="Test Hero",
+        is_player=True,
+        current_hp=38,  # 10 + 14*2
+        max_hp=38,
+        current_mp=30,  # 10 + 10*2
+        max_mp=30,
+        stats=Stats(
+            strength=12,
+            dexterity=10,
+            constitution=14,
+            intelligence=10,
+            wisdom=10,
+            charisma=8,
+            luck=8,
+        ),
+        abilities=["basic_attack", "power_strike"],
+    )
+
+
+@pytest.fixture
+def mock_enemy_combatant():
+    """Create a mock enemy combatant."""
+    return Combatant(
+        combatant_id="test_goblin_0",
+        name="Test Goblin",
+        is_player=False,
+        current_hp=22,  # 10 + 6*2
+        max_hp=22,
+        current_mp=22,
+        max_mp=22,
+        stats=Stats(
+            strength=8,
+            dexterity=12,
+            constitution=6,
+            intelligence=6,
+            wisdom=6,
+            charisma=4,
+            luck=8,
+        ),
+        abilities=["basic_attack"],
+    )
+
+
+@pytest.fixture
+def mock_encounter(mock_combatant, mock_enemy_combatant):
+    """Create a mock combat encounter."""
+    encounter = CombatEncounter(
+        encounter_id="test_encounter_001",
+        combatants=[mock_combatant, mock_enemy_combatant],
+    )
+    encounter.initialize_combat()
+    return encounter
+
+
+@pytest.fixture
+def mock_session(mock_encounter):
+    """Create a mock game session."""
+    session = Mock()
+    session.session_id = "test_session_001"
+    session.solo_character_id = "test_char_001"
+    session.is_solo = Mock(return_value=True)
+    session.is_in_combat = Mock(return_value=False)
+    session.combat_encounter = None
+    session.start_combat = Mock()
+    session.end_combat = Mock()
+    return session
+
+
+# =============================================================================
+# CombatAction Tests
+# =============================================================================
+
+class TestCombatAction:
+    """Tests for CombatAction dataclass."""
+
+    def test_create_attack_action(self):
+        """Test creating an attack action."""
+        action = CombatAction(
+            action_type="attack",
+            target_ids=["enemy_1"],
+        )
+
+        assert action.action_type == "attack"
+        assert action.target_ids == ["enemy_1"]
+        assert action.ability_id is None
+
+    def test_create_ability_action(self):
+        """Test creating an ability action."""
+        action = CombatAction(
+            action_type="ability",
+            target_ids=["enemy_1", "enemy_2"],
+            ability_id="fireball",
+        )
+
+        assert action.action_type == "ability"
+        assert action.ability_id == "fireball"
+        assert len(action.target_ids) == 2
+
+    def test_from_dict(self):
+        """Test creating action from dictionary."""
+        data = {
+            "action_type": "ability",
+            "target_ids": ["enemy_1"],
+            "ability_id": "heal",
+        }
+
+        action = CombatAction.from_dict(data)
+
+        assert action.action_type == "ability"
+        assert action.ability_id == "heal"
+
+    def test_to_dict(self):
+        """Test serializing action to dictionary."""
+        action = CombatAction(
+            action_type="defend",
+            target_ids=[],
+        )
+
+        data = action.to_dict()
+
+        assert data["action_type"] == "defend"
+        assert data["target_ids"] == []
+
+
+# =============================================================================
+# ActionResult Tests
+# =============================================================================
+
+class TestActionResult:
+    """Tests for ActionResult dataclass."""
+
+    def test_create_success_result(self):
+        """Test creating a successful action result."""
+        result = ActionResult(
+            success=True,
+            message="Attack hits for 15 damage!",
+        )
+
+        assert result.success is True
+        assert "15 damage" in result.message
+        assert result.combat_ended is False
+
+    def test_to_dict(self):
+        """Test serializing result to dictionary."""
+        result = ActionResult(
+            success=True,
+            message="Victory!",
+            combat_ended=True,
+            combat_status=CombatStatus.VICTORY,
+        )
+
+        data = result.to_dict()
+
+        assert data["success"] is True
+        assert data["combat_ended"] is True
+        assert data["combat_status"] == "victory"
+
+
+# =============================================================================
+# CombatRewards Tests
+# =============================================================================
+
+class TestCombatRewards:
+    """Tests for CombatRewards dataclass."""
+
+    def test_create_rewards(self):
+        """Test creating combat rewards."""
+        rewards = CombatRewards(
+            experience=100,
+            gold=50,
+            items=[{"item_id": "sword", "quantity": 1}],
+            level_ups=["char_1"],
+        )
+
+        assert rewards.experience == 100
+        assert rewards.gold == 50
+        assert len(rewards.items) == 1
+
+    def test_to_dict(self):
+        """Test serializing rewards to dictionary."""
+        rewards = CombatRewards(experience=50, gold=25)
+        data = rewards.to_dict()
+
+        assert data["experience"] == 50
+        assert data["gold"] == 25
+        assert data["items"] == []
+
+
+# =============================================================================
+# Combatant Creation Tests
+# =============================================================================
+
+class TestCombatantCreation:
+    """Tests for combatant creation methods."""
+
+    def test_create_combatant_from_character(self, mock_character):
+        """Test creating a combatant from a player character."""
+        service = CombatService.__new__(CombatService)
+
+        combatant = service._create_combatant_from_character(mock_character)
+
+        assert combatant.combatant_id == mock_character.character_id
+        assert combatant.name == mock_character.name
+        assert combatant.is_player is True
+        assert combatant.current_hp == combatant.max_hp
+        assert "basic_attack" in combatant.abilities
+
+    def test_create_combatant_from_enemy(self, mock_enemy_template):
+        """Test creating a combatant from an enemy template."""
+        service = CombatService.__new__(CombatService)
+
+        combatant = service._create_combatant_from_enemy(mock_enemy_template, instance_index=0)
+
+        assert combatant.combatant_id == "test_goblin_0"
+        assert combatant.name == mock_enemy_template.name
+        assert combatant.is_player is False
+        assert combatant.current_hp == combatant.max_hp
+        assert "basic_attack" in combatant.abilities
+
+    def test_create_multiple_enemy_instances(self, mock_enemy_template):
+        """Test creating multiple instances of same enemy."""
+        service = CombatService.__new__(CombatService)
+
+        combatant1 = service._create_combatant_from_enemy(mock_enemy_template, instance_index=0)
+        combatant2 = service._create_combatant_from_enemy(mock_enemy_template, instance_index=1)
+        combatant3 = service._create_combatant_from_enemy(mock_enemy_template, instance_index=2)
+
+        # IDs should be unique
+        assert combatant1.combatant_id != combatant2.combatant_id
+        assert combatant2.combatant_id != combatant3.combatant_id
+
+        # Names should be numbered
+        assert "#" in combatant2.name
+        assert "#" in combatant3.name
+
+
+# =============================================================================
+# Combat Lifecycle Tests
+# =============================================================================
+
+class TestCombatLifecycle:
+    """Tests for combat lifecycle methods."""
+
+    @patch('app.services.combat_service.get_session_service')
+    @patch('app.services.combat_service.get_character_service')
+    @patch('app.services.combat_service.get_enemy_loader')
+    def test_start_combat_success(
+        self,
+        mock_get_enemy_loader,
+        mock_get_char_service,
+        mock_get_session_service,
+        mock_session,
+        mock_character,
+        mock_enemy_template,
+    ):
+        """Test starting combat successfully."""
+        # Setup mocks
+        mock_session_service = Mock()
+        mock_session_service.get_session.return_value = mock_session
+        mock_session_service.update_session = Mock()
+        mock_get_session_service.return_value = mock_session_service
+
+        mock_char_service = Mock()
+        mock_char_service.get_character.return_value = mock_character
+        mock_get_char_service.return_value = mock_char_service
+
+        mock_enemy_loader = Mock()
+        mock_enemy_loader.load_enemy.return_value = mock_enemy_template
+        mock_get_enemy_loader.return_value = mock_enemy_loader
+
+        # Create service and start combat
+        service = CombatService()
+        encounter = service.start_combat(
+            session_id="test_session",
+            user_id="test_user",
+            enemy_ids=["test_goblin"],
+        )
+
+        assert encounter is not None
+        assert encounter.status == CombatStatus.ACTIVE
+        assert len(encounter.combatants) == 2  # 1 player + 1 enemy
+        assert len(encounter.turn_order) == 2
+        mock_session.start_combat.assert_called_once()
+
+    @patch('app.services.combat_service.get_session_service')
+    @patch('app.services.combat_service.get_character_service')
+    @patch('app.services.combat_service.get_enemy_loader')
+    def test_start_combat_already_in_combat(
+        self,
+        mock_get_enemy_loader,
+        mock_get_char_service,
+        mock_get_session_service,
+        mock_session,
+    ):
+        """Test starting combat when already in combat."""
+        mock_session.is_in_combat.return_value = True
+
+        mock_session_service = Mock()
+        mock_session_service.get_session.return_value = mock_session
+        mock_get_session_service.return_value = mock_session_service
+
+        service = CombatService()
+
+        with pytest.raises(AlreadyInCombatError):
+            service.start_combat(
+                session_id="test_session",
+                user_id="test_user",
+                enemy_ids=["goblin"],
+            )
+
+    @patch('app.services.combat_service.get_session_service')
+    def test_get_combat_state_not_in_combat(
+        self,
+        mock_get_session_service,
+        mock_session,
+    ):
+        """Test getting combat state when not in combat."""
+        mock_session.combat_encounter = None
+
+        mock_session_service = Mock()
+        mock_session_service.get_session.return_value = mock_session
+        mock_get_session_service.return_value = mock_session_service
+
+        service = CombatService()
+        result = service.get_combat_state("test_session", "test_user")
+
+        assert result is None
+
+
+# =============================================================================
+# Attack Execution Tests
+# =============================================================================
+
+class TestAttackExecution:
+    """Tests for attack action execution."""
+
+    def test_execute_attack_hit(self, mock_encounter, mock_combatant, mock_enemy_combatant):
+        """Test executing a successful attack."""
+        service = CombatService.__new__(CombatService)
+        service.ability_loader = Mock()
+
+        # Mock attacker as current combatant
+        mock_encounter.turn_order = [mock_combatant.combatant_id, mock_enemy_combatant.combatant_id]
+        mock_encounter.current_turn_index = 0
+
+        result = service._execute_attack(
+            mock_encounter,
+            mock_combatant,
+            [mock_enemy_combatant.combatant_id]
+        )
+
+        assert result.success is True
+        assert len(result.damage_results) == 1
+        # Damage should have been dealt (HP should be reduced)
+
+    def test_execute_attack_no_target(self, mock_encounter, mock_combatant):
+        """Test attack with auto-targeting."""
+        service = CombatService.__new__(CombatService)
+        service.ability_loader = Mock()
+
+        result = service._execute_attack(
+            mock_encounter,
+            mock_combatant,
+            []  # No targets specified
+        )
+
+        # Should auto-target and succeed
+        assert result.success is True
+
+
+# =============================================================================
+# Defend Action Tests
+# =============================================================================
+
+class TestDefendExecution:
+    """Tests for defend action execution."""
+
+    def test_execute_defend(self, mock_encounter, mock_combatant):
+        """Test executing a defend action."""
+        service = CombatService.__new__(CombatService)
+
+        initial_effects = len(mock_combatant.active_effects)
+
+        result = service._execute_defend(mock_encounter, mock_combatant)
+
+        assert result.success is True
+        assert "defensive stance" in result.message.lower()
+        assert len(result.effects_applied) == 1
+        # Combatant should have a new effect
+        assert len(mock_combatant.active_effects) == initial_effects + 1
+
+
+# =============================================================================
+# Flee Action Tests
+# =============================================================================
+
+class TestFleeExecution:
+    """Tests for flee action execution."""
+
+    def test_execute_flee_success(self, mock_encounter, mock_combatant, mock_session):
+        """Test successful flee attempt."""
+        service = CombatService.__new__(CombatService)
+
+        # Force success by patching random
+        with patch('random.random', return_value=0.1):  # Low roll = success
+            result = service._execute_flee(
+                mock_encounter,
+                mock_combatant,
+                mock_session,
+                "test_user"
+            )
+
+        assert result.success is True
+        assert result.combat_ended is True
+        assert result.combat_status == CombatStatus.FLED
+
+    def test_execute_flee_failure(self, mock_encounter, mock_combatant, mock_session):
+        """Test failed flee attempt."""
+        service = CombatService.__new__(CombatService)
+
+        # Force failure by patching random
+        with patch('random.random', return_value=0.9):  # High roll = failure
+            result = service._execute_flee(
+                mock_encounter,
+                mock_combatant,
+                mock_session,
+                "test_user"
+            )
+
+        assert result.success is False
+        assert result.combat_ended is False
+
+
+# =============================================================================
+# Enemy AI Tests
+# =============================================================================
+
+class TestEnemyAI:
+    """Tests for enemy AI logic."""
+
+    def test_choose_enemy_action(self, mock_encounter, mock_enemy_combatant):
+        """Test enemy AI action selection."""
+        service = CombatService.__new__(CombatService)
+
+        action_type, targets = service._choose_enemy_action(
+            mock_encounter,
+            mock_enemy_combatant
+        )
+
+        # Should choose attack or ability
+        assert action_type in ["attack", "ability"]
+        # Should target a player
+        assert len(targets) > 0
+
+    def test_choose_enemy_targets_lowest_hp(self, mock_encounter, mock_enemy_combatant):
+        """Test that enemy AI targets lowest HP player."""
+        # Add another player with lower HP
+        low_hp_player = Combatant(
+            combatant_id="low_hp_player",
+            name="Wounded Hero",
+            is_player=True,
+            current_hp=5,  # Very low HP
+            max_hp=38,
+            current_mp=30,
+            max_mp=30,
+            stats=Stats(),
+            abilities=["basic_attack"],
+        )
+        mock_encounter.combatants.append(low_hp_player)
+
+        service = CombatService.__new__(CombatService)
+
+        _, targets = service._choose_enemy_action(
+            mock_encounter,
+            mock_enemy_combatant
+        )
+
+        # Should target the lowest HP player
+        assert targets[0] == "low_hp_player"
+
+
+# =============================================================================
+# Combat End Condition Tests
+# =============================================================================
+
+class TestCombatEndConditions:
+    """Tests for combat end condition checking."""
+
+    def test_victory_when_all_enemies_dead(self, mock_encounter, mock_combatant, mock_enemy_combatant):
+        """Test victory is detected when all enemies are dead."""
+        # Kill the enemy
+        mock_enemy_combatant.current_hp = 0
+
+        status = mock_encounter.check_end_condition()
+
+        assert status == CombatStatus.VICTORY
+
+    def test_defeat_when_all_players_dead(self, mock_encounter, mock_combatant, mock_enemy_combatant):
+        """Test defeat is detected when all players are dead."""
+        # Kill the player
+        mock_combatant.current_hp = 0
+
+        status = mock_encounter.check_end_condition()
+
+        assert status == CombatStatus.DEFEAT
+
+    def test_active_when_both_alive(self, mock_encounter, mock_combatant, mock_enemy_combatant):
+        """Test combat remains active when both sides have survivors."""
+        # Both alive
+        assert mock_combatant.current_hp > 0
+        assert mock_enemy_combatant.current_hp > 0
+
+        status = mock_encounter.check_end_condition()
+
+        assert status == CombatStatus.ACTIVE
+
+
+# =============================================================================
+# Rewards Calculation Tests
+# =============================================================================
+
+class TestRewardsCalculation:
+    """Tests for reward distribution."""
+
+    def test_calculate_rewards_from_enemies(self, mock_encounter, mock_enemy_combatant):
+        """Test reward calculation from defeated enemies."""
+        # Mark enemy as dead
+        mock_enemy_combatant.current_hp = 0
+
+        service = CombatService.__new__(CombatService)
+        service.enemy_loader = Mock()
+        service.character_service = Mock()
+        service.loot_service = Mock()
+
+        # Mock enemy template for rewards
+        mock_template = Mock()
+        mock_template.experience_reward = 50
+        mock_template.get_gold_reward.return_value = 25
+        mock_template.difficulty = Mock()
+        mock_template.difficulty.value = "easy"
+        mock_template.is_boss.return_value = False
+        service.enemy_loader.load_enemy.return_value = mock_template
+
+        # Mock loot service to return mock items
+        mock_item = Mock()
+        mock_item.to_dict.return_value = {"item_id": "sword", "quantity": 1}
+        service.loot_service.generate_loot_from_enemy.return_value = [mock_item]
+
+        mock_session = Mock()
+        mock_session.is_solo.return_value = True
+        mock_session.solo_character_id = "test_char"
+
+        mock_char = Mock()
+        mock_char.level = 1
+        mock_char.experience = 0
+        mock_char.gold = 0
+        service.character_service.get_character.return_value = mock_char
+        service.character_service.update_character = Mock()
+
+        rewards = service._calculate_rewards(mock_encounter, mock_session, "test_user")
+
+        assert rewards.experience == 50
+        assert rewards.gold == 25
+        assert len(rewards.items) == 1

api/tests/test_damage_calculator.py

@@ -0,0 +1,674 @@
+"""
+Unit tests for the DamageCalculator service.
+
+Tests cover:
+- Hit chance calculations with LUK/DEX
+- Critical hit chance calculations
+- Damage variance with lucky rolls
+- Physical damage formula
+- Magical damage formula
+- Elemental split damage
+- Defense mitigation with minimum guarantee
+- AoE damage calculations
+"""
+
+import pytest
+import random
+from unittest.mock import patch
+
+from app.models.stats import Stats
+from app.models.enums import DamageType
+from app.services.damage_calculator import (
+    DamageCalculator,
+    DamageResult,
+    CombatConstants,
+)
+
+
+# =============================================================================
+# Hit Chance Tests
+# =============================================================================
+
+class TestHitChance:
+    """Tests for calculate_hit_chance()."""
+
+    def test_base_hit_chance_with_average_stats(self):
+        """Test hit chance with average LUK (8) and DEX (10)."""
+        # LUK 8: miss = 10% - 4% = 6%
+        hit_chance = DamageCalculator.calculate_hit_chance(
+            attacker_luck=8,
+            defender_dexterity=10,
+        )
+        assert hit_chance == pytest.approx(0.94, abs=0.001)
+
+    def test_high_luck_reduces_miss_chance(self):
+        """Test that high LUK reduces miss chance."""
+        # LUK 12: miss = 10% - 6% = 4%, but capped at 5%
+        hit_chance = DamageCalculator.calculate_hit_chance(
+            attacker_luck=12,
+            defender_dexterity=10,
+        )
+        assert hit_chance == pytest.approx(0.95, abs=0.001)
+
+    def test_miss_chance_hard_cap_at_five_percent(self):
+        """Test that miss chance cannot go below 5% (hard cap)."""
+        # LUK 20: would be 10% - 10% = 0%, but capped at 5%
+        hit_chance = DamageCalculator.calculate_hit_chance(
+            attacker_luck=20,
+            defender_dexterity=10,
+        )
+        assert hit_chance == pytest.approx(0.95, abs=0.001)
+
+    def test_high_dex_increases_evasion(self):
+        """Test that defender's high DEX increases miss chance."""
+        # LUK 8, DEX 15: miss = 10% - 4% + 1.25% = 7.25%
+        hit_chance = DamageCalculator.calculate_hit_chance(
+            attacker_luck=8,
+            defender_dexterity=15,
+        )
+        assert hit_chance == pytest.approx(0.9275, abs=0.001)
+
+    def test_dex_below_ten_has_no_evasion_bonus(self):
+        """Test that DEX below 10 doesn't reduce attacker's hit chance."""
+        # DEX 5 should be same as DEX 10 (no negative evasion)
+        hit_low_dex = DamageCalculator.calculate_hit_chance(
+            attacker_luck=8,
+            defender_dexterity=5,
+        )
+        hit_base_dex = DamageCalculator.calculate_hit_chance(
+            attacker_luck=8,
+            defender_dexterity=10,
+        )
+        assert hit_low_dex == hit_base_dex
+
+    def test_skill_bonus_improves_hit_chance(self):
+        """Test that skill bonus adds to hit chance."""
+        base_hit = DamageCalculator.calculate_hit_chance(
+            attacker_luck=8,
+            defender_dexterity=10,
+        )
+        skill_hit = DamageCalculator.calculate_hit_chance(
+            attacker_luck=8,
+            defender_dexterity=10,
+            skill_bonus=0.05,  # 5% bonus
+        )
+        assert skill_hit > base_hit
+
+
+# =============================================================================
+# Critical Hit Tests
+# =============================================================================
+
+class TestCritChance:
+    """Tests for calculate_crit_chance()."""
+
+    def test_base_crit_with_average_luck(self):
+        """Test crit chance with average LUK (8)."""
+        # Base 5% + LUK 8 * 0.5% = 5% + 4% = 9%
+        crit_chance = DamageCalculator.calculate_crit_chance(
+            attacker_luck=8,
+        )
+        assert crit_chance == pytest.approx(0.09, abs=0.001)
+
+    def test_high_luck_increases_crit(self):
+        """Test that high LUK increases crit chance."""
+        # Base 5% + LUK 12 * 0.5% = 5% + 6% = 11%
+        crit_chance = DamageCalculator.calculate_crit_chance(
+            attacker_luck=12,
+        )
+        assert crit_chance == pytest.approx(0.11, abs=0.001)
+
+    def test_weapon_crit_stacks_with_luck(self):
+        """Test that weapon crit chance stacks with LUK bonus."""
+        # Weapon 10% + LUK 12 * 0.5% = 10% + 6% = 16%
+        crit_chance = DamageCalculator.calculate_crit_chance(
+            attacker_luck=12,
+            weapon_crit_chance=0.10,
+        )
+        assert crit_chance == pytest.approx(0.16, abs=0.001)
+
+    def test_crit_chance_hard_cap_at_25_percent(self):
+        """Test that crit chance is capped at 25%."""
+        # Weapon 20% + LUK 20 * 0.5% = 20% + 10% = 30%, but capped at 25%
+        crit_chance = DamageCalculator.calculate_crit_chance(
+            attacker_luck=20,
+            weapon_crit_chance=0.20,
+        )
+        assert crit_chance == pytest.approx(0.25, abs=0.001)
+
+    def test_skill_bonus_adds_to_crit(self):
+        """Test that skill bonus adds to crit chance."""
+        base_crit = DamageCalculator.calculate_crit_chance(
+            attacker_luck=8,
+        )
+        skill_crit = DamageCalculator.calculate_crit_chance(
+            attacker_luck=8,
+            skill_bonus=0.05,
+        )
+        assert skill_crit == base_crit + 0.05
+
+
+# =============================================================================
+# Damage Variance Tests
+# =============================================================================
+
+class TestDamageVariance:
+    """Tests for calculate_variance()."""
+
+    @patch('random.random')
+    @patch('random.uniform')
+    def test_normal_variance_roll(self, mock_uniform, mock_random):
+        """Test normal variance roll (95%-105%)."""
+        # Not a lucky roll (random returns high value)
+        mock_random.return_value = 0.99
+        mock_uniform.return_value = 1.0
+
+        variance = DamageCalculator.calculate_variance(attacker_luck=8)
+
+        # Should call uniform with base variance range
+        mock_uniform.assert_called_with(
+            CombatConstants.BASE_VARIANCE_MIN,
+            CombatConstants.BASE_VARIANCE_MAX,
+        )
+        assert variance == 1.0
+
+    @patch('random.random')
+    @patch('random.uniform')
+    def test_lucky_variance_roll(self, mock_uniform, mock_random):
+        """Test lucky variance roll (100%-110%)."""
+        # Lucky roll (random returns low value)
+        mock_random.return_value = 0.01
+        mock_uniform.return_value = 1.08
+
+        variance = DamageCalculator.calculate_variance(attacker_luck=8)
+
+        # Should call uniform with lucky variance range
+        mock_uniform.assert_called_with(
+            CombatConstants.LUCKY_VARIANCE_MIN,
+            CombatConstants.LUCKY_VARIANCE_MAX,
+        )
+        assert variance == 1.08
+
+    def test_high_luck_increases_lucky_chance(self):
+        """Test that high LUK increases chance for lucky roll."""
+        # LUK 8: lucky chance = 5% + 2% = 7%
+        # LUK 12: lucky chance = 5% + 3% = 8%
+        # Run many iterations to verify probability
+        lucky_count_low = 0
+        lucky_count_high = 0
+        iterations = 10000
+
+        random.seed(42)  # Reproducible
+        for _ in range(iterations):
+            variance = DamageCalculator.calculate_variance(8)
+            if variance >= 1.0:
+                lucky_count_low += 1
+
+        random.seed(42)  # Same seed
+        for _ in range(iterations):
+            variance = DamageCalculator.calculate_variance(12)
+            if variance >= 1.0:
+                lucky_count_high += 1
+
+        # Higher LUK should have more lucky rolls
+        # Note: This is a statistical test, might have some variance
+        # Just verify the high LUK isn't dramatically lower
+        assert lucky_count_high >= lucky_count_low * 0.9
+
+
+# =============================================================================
+# Defense Mitigation Tests
+# =============================================================================
+
+class TestDefenseMitigation:
+    """Tests for apply_defense()."""
+
+    def test_normal_defense_mitigation(self):
+        """Test standard defense subtraction."""
+        # 20 damage - 5 defense = 15 damage
+        result = DamageCalculator.apply_defense(raw_damage=20, defense=5)
+        assert result == 15
+
+    def test_minimum_damage_guarantee(self):
+        """Test that minimum 20% damage always goes through."""
+        # 20 damage - 18 defense = 2 damage (but min is 20% of 20 = 4)
+        result = DamageCalculator.apply_defense(raw_damage=20, defense=18)
+        assert result == 4
+
+    def test_defense_higher_than_damage(self):
+        """Test when defense exceeds raw damage."""
+        # 10 damage - 100 defense = -90, but min is 20% of 10 = 2
+        result = DamageCalculator.apply_defense(raw_damage=10, defense=100)
+        assert result == 2
+
+    def test_absolute_minimum_damage_is_one(self):
+        """Test that absolute minimum damage is 1."""
+        # 3 damage - 100 defense = negative, but 20% of 3 = 0.6, so min is 1
+        result = DamageCalculator.apply_defense(raw_damage=3, defense=100)
+        assert result == 1
+
+    def test_custom_minimum_ratio(self):
+        """Test custom minimum damage ratio."""
+        # 20 damage with 30% minimum = at least 6 damage
+        result = DamageCalculator.apply_defense(
+            raw_damage=20,
+            defense=18,
+            min_damage_ratio=0.30,
+        )
+        assert result == 6
+
+
+# =============================================================================
+# Physical Damage Tests
+# =============================================================================
+
+class TestPhysicalDamage:
+    """Tests for calculate_physical_damage()."""
+
+    def test_basic_physical_damage_formula(self):
+        """Test the basic physical damage formula."""
+        # Formula: (stats.damage + ability_power) * Variance - DEF
+        # where stats.damage = int(STR * 0.75) + damage_bonus
+        attacker = Stats(strength=14, luck=0, damage_bonus=8)  # Weapon damage in bonus
+        defender = Stats(constitution=10, dexterity=10)  # DEF = 5
+
+        # Mock to ensure no miss and no crit, variance = 1.0
+        with patch.object(DamageCalculator, 'calculate_hit_chance', return_value=1.0):
+            with patch.object(DamageCalculator, 'calculate_variance', return_value=1.0):
+                with patch.object(DamageCalculator, 'calculate_crit_chance', return_value=0.0):
+                    result = DamageCalculator.calculate_physical_damage(
+                        attacker_stats=attacker,
+                        defender_stats=defender,
+                    )
+
+        # int(14 * 0.75) + 8 = 10 + 8 = 18, 18 - 5 DEF = 13
+        assert result.total_damage == 13
+        assert result.is_miss is False
+        assert result.is_critical is False
+        assert result.damage_type == DamageType.PHYSICAL
+
+    def test_physical_damage_miss(self):
+        """Test that misses deal zero damage."""
+        attacker = Stats(strength=14, luck=0, damage_bonus=8)  # Weapon damage in bonus
+        defender = Stats(dexterity=30)  # Very high DEX
+
+        # Force a miss
+        with patch('random.random', return_value=0.99):
+            result = DamageCalculator.calculate_physical_damage(
+                attacker_stats=attacker,
+                defender_stats=defender,
+            )
+
+        assert result.is_miss is True
+        assert result.total_damage == 0
+        assert "missed" in result.message.lower()
+
+    def test_physical_damage_critical_hit(self):
+        """Test critical hit doubles damage."""
+        attacker = Stats(strength=14, luck=20, damage_bonus=8)  # High LUK for crit, weapon in bonus
+        defender = Stats(constitution=10, dexterity=10)
+
+        # Force hit and crit
+        with patch('random.random', side_effect=[0.01, 0.01]):  # Hit, then crit
+            with patch.object(DamageCalculator, 'calculate_variance', return_value=1.0):
+                result = DamageCalculator.calculate_physical_damage(
+                    attacker_stats=attacker,
+                    defender_stats=defender,
+                    weapon_crit_multiplier=2.0,
+                )
+
+        assert result.is_critical is True
+        # Base: int(14 * 0.75) + 8 = 10 + 8 = 18
+        # Crit: 18 * 2 = 36
+        # After DEF 5: 36 - 5 = 31
+        assert result.total_damage == 31
+        assert "critical" in result.message.lower()
+
+
+# =============================================================================
+# Magical Damage Tests
+# =============================================================================
+
+class TestMagicalDamage:
+    """Tests for calculate_magical_damage()."""
+
+    def test_basic_magical_damage_formula(self):
+        """Test the basic magical damage formula."""
+        # Formula: (Ability + INT * 0.75) * Variance - RES
+        attacker = Stats(intelligence=15, luck=0)
+        defender = Stats(wisdom=10, dexterity=10)  # RES = 5
+
+        with patch.object(DamageCalculator, 'calculate_hit_chance', return_value=1.0):
+            with patch.object(DamageCalculator, 'calculate_variance', return_value=1.0):
+                with patch.object(DamageCalculator, 'calculate_crit_chance', return_value=0.0):
+                    result = DamageCalculator.calculate_magical_damage(
+                        attacker_stats=attacker,
+                        defender_stats=defender,
+                        ability_base_power=12,
+                        damage_type=DamageType.FIRE,
+                    )
+
+        # 12 + (15 * 0.75) = 12 + 11.25 = 23.25 -> 23 - 5 = 18
+        assert result.total_damage == 18
+        assert result.damage_type == DamageType.FIRE
+        assert result.is_miss is False
+
+    def test_spells_can_critically_hit(self):
+        """Test that spells can crit (per user requirement)."""
+        attacker = Stats(intelligence=15, luck=20)
+        defender = Stats(wisdom=10, dexterity=10)
+
+        # Force hit and crit
+        with patch('random.random', side_effect=[0.01, 0.01]):
+            with patch.object(DamageCalculator, 'calculate_variance', return_value=1.0):
+                result = DamageCalculator.calculate_magical_damage(
+                    attacker_stats=attacker,
+                    defender_stats=defender,
+                    ability_base_power=12,
+                    damage_type=DamageType.FIRE,
+                    weapon_crit_multiplier=2.0,
+                )
+
+        assert result.is_critical is True
+        # Base: 12 + 15*0.75 = 23.25 -> 23
+        # Crit: 23 * 2 = 46
+        # After RES 5: 46 - 5 = 41
+        assert result.total_damage == 41
+
+    def test_magical_damage_with_different_types(self):
+        """Test that different damage types are recorded correctly."""
+        attacker = Stats(intelligence=10)
+        defender = Stats(wisdom=10, dexterity=10)
+
+        with patch.object(DamageCalculator, 'calculate_hit_chance', return_value=1.0):
+            with patch.object(DamageCalculator, 'calculate_variance', return_value=1.0):
+                with patch.object(DamageCalculator, 'calculate_crit_chance', return_value=0.0):
+                    for damage_type in [DamageType.ICE, DamageType.LIGHTNING, DamageType.HOLY]:
+                        result = DamageCalculator.calculate_magical_damage(
+                            attacker_stats=attacker,
+                            defender_stats=defender,
+                            ability_base_power=10,
+                            damage_type=damage_type,
+                        )
+                        assert result.damage_type == damage_type
+
+
+# =============================================================================
+# Elemental Weapon (Split Damage) Tests
+# =============================================================================
+
+class TestElementalWeaponDamage:
+    """Tests for calculate_elemental_weapon_damage()."""
+
+    def test_split_damage_calculation(self):
+        """Test 70/30 physical/fire split damage."""
+        # Fire Sword: 70% physical, 30% fire
+        # Weapon contributes to both damage_bonus (physical) and spell_power_bonus (elemental)
+        attacker = Stats(strength=14, intelligence=8, luck=0, damage_bonus=15, spell_power_bonus=15)
+        defender = Stats(constitution=10, wisdom=10, dexterity=10)  # DEF=5, RES=5
+
+        with patch.object(DamageCalculator, 'calculate_hit_chance', return_value=1.0):
+            with patch.object(DamageCalculator, 'calculate_variance', return_value=1.0):
+                with patch.object(DamageCalculator, 'calculate_crit_chance', return_value=0.0):
+                    result = DamageCalculator.calculate_elemental_weapon_damage(
+                        attacker_stats=attacker,
+                        defender_stats=defender,
+                        weapon_crit_chance=0.05,
+                        weapon_crit_multiplier=2.0,
+                        physical_ratio=0.7,
+                        elemental_ratio=0.3,
+                        elemental_type=DamageType.FIRE,
+                    )
+
+        # stats.damage = int(14 * 0.75) + 15 = 10 + 15 = 25
+        # stats.spell_power = int(8 * 0.75) + 15 = 6 + 15 = 21
+        # Physical: 25 * 0.7 = 17.5 -> 17 - 5 DEF = 12
+        # Elemental: 21 * 0.3 = 6.3 -> 6 - 5 RES = 1
+
+        assert result.physical_damage > 0
+        assert result.elemental_damage >= 1  # At least minimum damage
+        assert result.total_damage == result.physical_damage + result.elemental_damage
+        assert result.elemental_type == DamageType.FIRE
+
+    def test_50_50_split_damage(self):
+        """Test 50/50 physical/elemental split (Lightning Spear)."""
+        # Same stats and weapon bonuses means similar damage on both sides
+        attacker = Stats(strength=12, intelligence=12, luck=0, damage_bonus=20, spell_power_bonus=20)
+        defender = Stats(constitution=10, wisdom=10, dexterity=10)
+
+        with patch.object(DamageCalculator, 'calculate_hit_chance', return_value=1.0):
+            with patch.object(DamageCalculator, 'calculate_variance', return_value=1.0):
+                with patch.object(DamageCalculator, 'calculate_crit_chance', return_value=0.0):
+                    result = DamageCalculator.calculate_elemental_weapon_damage(
+                        attacker_stats=attacker,
+                        defender_stats=defender,
+                        weapon_crit_chance=0.05,
+                        weapon_crit_multiplier=2.0,
+                        physical_ratio=0.5,
+                        elemental_ratio=0.5,
+                        elemental_type=DamageType.LIGHTNING,
+                    )
+
+        # Both components should be similar (same stat values and weapon bonuses)
+        assert abs(result.physical_damage - result.elemental_damage) <= 2
+
+    def test_elemental_crit_applies_to_both_components(self):
+        """Test that crit multiplier applies to both damage types."""
+        attacker = Stats(strength=14, intelligence=8, luck=20, damage_bonus=15, spell_power_bonus=15)
+        defender = Stats(constitution=10, wisdom=10, dexterity=10)
+
+        # Force hit and crit
+        with patch('random.random', side_effect=[0.01, 0.01]):
+            with patch.object(DamageCalculator, 'calculate_variance', return_value=1.0):
+                result = DamageCalculator.calculate_elemental_weapon_damage(
+                    attacker_stats=attacker,
+                    defender_stats=defender,
+                    weapon_crit_chance=0.05,
+                    weapon_crit_multiplier=2.0,
+                    physical_ratio=0.7,
+                    elemental_ratio=0.3,
+                    elemental_type=DamageType.FIRE,
+                )
+
+        assert result.is_critical is True
+        # Both components should be doubled
+
+
+# =============================================================================
+# AoE Damage Tests
+# =============================================================================
+
+class TestAoEDamage:
+    """Tests for calculate_aoe_damage()."""
+
+    def test_aoe_full_damage_to_all_targets(self):
+        """Test that AoE deals full damage to each target."""
+        attacker = Stats(intelligence=15, luck=0)
+        defenders = [
+            Stats(wisdom=10, dexterity=10),
+            Stats(wisdom=10, dexterity=10),
+            Stats(wisdom=10, dexterity=10),
+        ]
+
+        with patch.object(DamageCalculator, 'calculate_hit_chance', return_value=1.0):
+            with patch.object(DamageCalculator, 'calculate_variance', return_value=1.0):
+                with patch.object(DamageCalculator, 'calculate_crit_chance', return_value=0.0):
+                    results = DamageCalculator.calculate_aoe_damage(
+                        attacker_stats=attacker,
+                        defender_stats_list=defenders,
+                        ability_base_power=20,
+                        damage_type=DamageType.FIRE,
+                    )
+
+        assert len(results) == 3
+        # All targets should take the same damage (same stats)
+        for result in results:
+            assert result.total_damage == results[0].total_damage
+
+    def test_aoe_independent_hit_checks(self):
+        """Test that each target has independent hit/miss rolls."""
+        attacker = Stats(intelligence=15, luck=8)
+        defenders = [
+            Stats(wisdom=10, dexterity=10),
+            Stats(wisdom=10, dexterity=10),
+        ]
+
+        # First target hit, second target miss
+        hit_sequence = [0.5, 0.99]  # Below hit chance, above hit chance
+        with patch('random.random', side_effect=hit_sequence * 2):  # Extra for crit checks
+            results = DamageCalculator.calculate_aoe_damage(
+                attacker_stats=attacker,
+                defender_stats_list=defenders,
+                ability_base_power=20,
+                damage_type=DamageType.FIRE,
+            )
+
+        # At least verify we got results for both
+        assert len(results) == 2
+
+    def test_aoe_with_varying_resistance(self):
+        """Test that AoE respects different resistances per target."""
+        attacker = Stats(intelligence=15, luck=0)
+        defenders = [
+            Stats(wisdom=10, dexterity=10),  # RES = 5
+            Stats(wisdom=20, dexterity=10),  # RES = 10
+        ]
+
+        with patch.object(DamageCalculator, 'calculate_hit_chance', return_value=1.0):
+            with patch.object(DamageCalculator, 'calculate_variance', return_value=1.0):
+                with patch.object(DamageCalculator, 'calculate_crit_chance', return_value=0.0):
+                    results = DamageCalculator.calculate_aoe_damage(
+                        attacker_stats=attacker,
+                        defender_stats_list=defenders,
+                        ability_base_power=20,
+                        damage_type=DamageType.FIRE,
+                    )
+
+        # First target (lower RES) should take more damage
+        assert results[0].total_damage > results[1].total_damage
+
+
+# =============================================================================
+# DamageResult Tests
+# =============================================================================
+
+class TestDamageResult:
+    """Tests for DamageResult dataclass."""
+
+    def test_damage_result_to_dict(self):
+        """Test serialization of DamageResult."""
+        result = DamageResult(
+            total_damage=25,
+            physical_damage=25,
+            elemental_damage=0,
+            damage_type=DamageType.PHYSICAL,
+            is_critical=True,
+            is_miss=False,
+            variance_roll=1.05,
+            raw_damage=30,
+            message="Dealt 25 physical damage. CRITICAL HIT!",
+        )
+
+        data = result.to_dict()
+
+        assert data["total_damage"] == 25
+        assert data["physical_damage"] == 25
+        assert data["damage_type"] == "physical"
+        assert data["is_critical"] is True
+        assert data["is_miss"] is False
+        assert data["variance_roll"] == pytest.approx(1.05, abs=0.001)
+
+
+# =============================================================================
+# Combat Constants Tests
+# =============================================================================
+
+class TestCombatConstants:
+    """Tests for CombatConstants configuration."""
+
+    def test_stat_scaling_factor(self):
+        """Verify scaling factor is 0.75."""
+        assert CombatConstants.STAT_SCALING_FACTOR == 0.75
+
+    def test_miss_chance_hard_cap(self):
+        """Verify miss chance hard cap is 5%."""
+        assert CombatConstants.MIN_MISS_CHANCE == 0.05
+
+    def test_crit_chance_cap(self):
+        """Verify crit chance cap is 25%."""
+        assert CombatConstants.MAX_CRIT_CHANCE == 0.25
+
+    def test_minimum_damage_ratio(self):
+        """Verify minimum damage ratio is 20%."""
+        assert CombatConstants.MIN_DAMAGE_RATIO == 0.20
+
+
+# =============================================================================
+# Integration Tests (Full Combat Flow)
+# =============================================================================
+
+class TestCombatIntegration:
+    """Integration tests for complete combat scenarios."""
+
+    def test_vanguard_attack_scenario(self):
+        """Test Vanguard (STR 14) basic attack."""
+        # Vanguard: STR 14, LUK 8, equipped with Rusty Sword (8 damage)
+        vanguard = Stats(strength=14, dexterity=10, constitution=14, luck=8, damage_bonus=8)
+        goblin = Stats(constitution=10, dexterity=10)  # DEF = 5
+
+        with patch.object(DamageCalculator, 'calculate_hit_chance', return_value=1.0):
+            with patch.object(DamageCalculator, 'calculate_variance', return_value=1.0):
+                with patch.object(DamageCalculator, 'calculate_crit_chance', return_value=0.0):
+                    result = DamageCalculator.calculate_physical_damage(
+                        attacker_stats=vanguard,
+                        defender_stats=goblin,
+                    )
+
+        # int(14 * 0.75) + 8 = 10 + 8 = 18, 18 - 5 DEF = 13
+        assert result.total_damage == 13
+
+    def test_arcanist_fireball_scenario(self):
+        """Test Arcanist (INT 15) Fireball."""
+        # Arcanist: INT 15, LUK 9 (no staff equipped, pure ability damage)
+        arcanist = Stats(intelligence=15, dexterity=10, wisdom=12, luck=9)
+        goblin = Stats(wisdom=10, dexterity=10)  # RES = 5
+
+        with patch.object(DamageCalculator, 'calculate_hit_chance', return_value=1.0):
+            with patch.object(DamageCalculator, 'calculate_variance', return_value=1.0):
+                with patch.object(DamageCalculator, 'calculate_crit_chance', return_value=0.0):
+                    result = DamageCalculator.calculate_magical_damage(
+                        attacker_stats=arcanist,
+                        defender_stats=goblin,
+                        ability_base_power=12,  # Fireball base
+                        damage_type=DamageType.FIRE,
+                    )
+
+        # stats.spell_power = int(15 * 0.75) + 0 = 11
+        # 11 + 12 (ability) = 23 - 5 RES = 18
+        assert result.total_damage == 18
+
+    def test_physical_vs_magical_balance(self):
+        """Test that physical and magical damage are comparable."""
+        # Same-tier characters should deal similar damage
+        vanguard = Stats(strength=14, luck=8, damage_bonus=8)  # Melee with weapon
+        arcanist = Stats(intelligence=15, luck=9)  # Caster (no staff)
+        target = Stats(constitution=10, wisdom=10, dexterity=10)  # DEF=5, RES=5
+
+        with patch.object(DamageCalculator, 'calculate_hit_chance', return_value=1.0):
+            with patch.object(DamageCalculator, 'calculate_variance', return_value=1.0):
+                with patch.object(DamageCalculator, 'calculate_crit_chance', return_value=0.0):
+                    phys_result = DamageCalculator.calculate_physical_damage(
+                        attacker_stats=vanguard,
+                        defender_stats=target,
+                    )
+                    magic_result = DamageCalculator.calculate_magical_damage(
+                        attacker_stats=arcanist,
+                        defender_stats=target,
+                        ability_base_power=12,
+                        damage_type=DamageType.FIRE,
+                    )
+
+        # Mage should deal slightly more (compensates for mana cost)
+        assert magic_result.total_damage >= phys_result.total_damage
+        # But not drastically more (within ~50%)
+        assert magic_result.total_damage <= phys_result.total_damage * 1.5

api/tests/test_enemy_loader.py

@@ -0,0 +1,399 @@
+"""
+Unit tests for EnemyTemplate model and EnemyLoader service.
+
+Tests enemy loading, serialization, and filtering functionality.
+"""
+
+import pytest
+from pathlib import Path
+
+from app.models.enemy import EnemyTemplate, EnemyDifficulty, LootEntry
+from app.models.stats import Stats
+from app.services.enemy_loader import EnemyLoader
+
+
+# =============================================================================
+# EnemyTemplate Model Tests
+# =============================================================================
+
+class TestEnemyTemplate:
+    """Tests for EnemyTemplate dataclass."""
+
+    def test_create_basic_enemy(self):
+        """Test creating an enemy with minimal attributes."""
+        enemy = EnemyTemplate(
+            enemy_id="test_enemy",
+            name="Test Enemy",
+            description="A test enemy",
+            base_stats=Stats(strength=10, constitution=8),
+        )
+
+        assert enemy.enemy_id == "test_enemy"
+        assert enemy.name == "Test Enemy"
+        assert enemy.base_stats.strength == 10
+        assert enemy.difficulty == EnemyDifficulty.EASY  # Default
+
+    def test_enemy_with_full_attributes(self):
+        """Test creating an enemy with all attributes."""
+        loot = [
+            LootEntry(item_id="sword", drop_chance=0.5),
+            LootEntry(item_id="gold", drop_chance=1.0, quantity_min=5, quantity_max=10),
+        ]
+
+        enemy = EnemyTemplate(
+            enemy_id="goblin_boss",
+            name="Goblin Boss",
+            description="A fearsome goblin leader",
+            base_stats=Stats(strength=14, dexterity=12, constitution=12),
+            abilities=["basic_attack", "power_strike"],
+            loot_table=loot,
+            experience_reward=100,
+            gold_reward_min=20,
+            gold_reward_max=50,
+            difficulty=EnemyDifficulty.HARD,
+            tags=["humanoid", "goblinoid", "boss"],
+            base_damage=12,
+            crit_chance=0.15,
+            flee_chance=0.25,
+        )
+
+        assert enemy.enemy_id == "goblin_boss"
+        assert enemy.experience_reward == 100
+        assert enemy.difficulty == EnemyDifficulty.HARD
+        assert len(enemy.loot_table) == 2
+        assert len(enemy.abilities) == 2
+        assert "boss" in enemy.tags
+
+    def test_is_boss(self):
+        """Test boss detection."""
+        easy_enemy = EnemyTemplate(
+            enemy_id="minion",
+            name="Minion",
+            description="",
+            base_stats=Stats(),
+            difficulty=EnemyDifficulty.EASY,
+        )
+        boss_enemy = EnemyTemplate(
+            enemy_id="boss",
+            name="Boss",
+            description="",
+            base_stats=Stats(),
+            difficulty=EnemyDifficulty.BOSS,
+        )
+
+        assert not easy_enemy.is_boss()
+        assert boss_enemy.is_boss()
+
+    def test_has_tag(self):
+        """Test tag checking."""
+        enemy = EnemyTemplate(
+            enemy_id="zombie",
+            name="Zombie",
+            description="",
+            base_stats=Stats(),
+            tags=["undead", "slow", "Humanoid"],  # Mixed case
+        )
+
+        assert enemy.has_tag("undead")
+        assert enemy.has_tag("UNDEAD")  # Case insensitive
+        assert enemy.has_tag("humanoid")
+        assert not enemy.has_tag("beast")
+
+    def test_get_gold_reward(self):
+        """Test gold reward generation."""
+        enemy = EnemyTemplate(
+            enemy_id="test",
+            name="Test",
+            description="",
+            base_stats=Stats(),
+            gold_reward_min=10,
+            gold_reward_max=20,
+        )
+
+        # Run multiple times to check range
+        for _ in range(50):
+            gold = enemy.get_gold_reward()
+            assert 10 <= gold <= 20
+
+    def test_roll_loot_empty_table(self):
+        """Test loot rolling with empty table."""
+        enemy = EnemyTemplate(
+            enemy_id="test",
+            name="Test",
+            description="",
+            base_stats=Stats(),
+            loot_table=[],
+        )
+
+        drops = enemy.roll_loot()
+        assert drops == []
+
+    def test_roll_loot_guaranteed_drop(self):
+        """Test loot rolling with guaranteed drop."""
+        enemy = EnemyTemplate(
+            enemy_id="test",
+            name="Test",
+            description="",
+            base_stats=Stats(),
+            loot_table=[
+                LootEntry(item_id="guaranteed_item", drop_chance=1.0),
+            ],
+        )
+
+        drops = enemy.roll_loot()
+        assert len(drops) == 1
+        assert drops[0]["item_id"] == "guaranteed_item"
+
+    def test_serialization_round_trip(self):
+        """Test that to_dict/from_dict preserves data."""
+        original = EnemyTemplate(
+            enemy_id="test_enemy",
+            name="Test Enemy",
+            description="A test description",
+            base_stats=Stats(strength=15, dexterity=12, luck=10),
+            abilities=["attack", "defend"],
+            loot_table=[
+                LootEntry(item_id="sword", drop_chance=0.5),
+            ],
+            experience_reward=50,
+            gold_reward_min=10,
+            gold_reward_max=25,
+            difficulty=EnemyDifficulty.MEDIUM,
+            tags=["humanoid", "test"],
+            base_damage=8,
+            crit_chance=0.10,
+            flee_chance=0.40,
+        )
+
+        # Serialize and deserialize
+        data = original.to_dict()
+        restored = EnemyTemplate.from_dict(data)
+
+        # Verify all fields match
+        assert restored.enemy_id == original.enemy_id
+        assert restored.name == original.name
+        assert restored.description == original.description
+        assert restored.base_stats.strength == original.base_stats.strength
+        assert restored.base_stats.luck == original.base_stats.luck
+        assert restored.abilities == original.abilities
+        assert len(restored.loot_table) == len(original.loot_table)
+        assert restored.experience_reward == original.experience_reward
+        assert restored.gold_reward_min == original.gold_reward_min
+        assert restored.gold_reward_max == original.gold_reward_max
+        assert restored.difficulty == original.difficulty
+        assert restored.tags == original.tags
+        assert restored.base_damage == original.base_damage
+        assert restored.crit_chance == pytest.approx(original.crit_chance)
+        assert restored.flee_chance == pytest.approx(original.flee_chance)
+
+
+class TestLootEntry:
+    """Tests for LootEntry dataclass."""
+
+    def test_create_loot_entry(self):
+        """Test creating a loot entry."""
+        entry = LootEntry(
+            item_id="gold_coin",
+            drop_chance=0.75,
+            quantity_min=5,
+            quantity_max=15,
+        )
+
+        assert entry.item_id == "gold_coin"
+        assert entry.drop_chance == 0.75
+        assert entry.quantity_min == 5
+        assert entry.quantity_max == 15
+
+    def test_loot_entry_defaults(self):
+        """Test loot entry default values."""
+        entry = LootEntry(item_id="item")
+
+        assert entry.drop_chance == 0.1
+        assert entry.quantity_min == 1
+        assert entry.quantity_max == 1
+
+
+# =============================================================================
+# EnemyLoader Service Tests
+# =============================================================================
+
+class TestEnemyLoader:
+    """Tests for EnemyLoader service."""
+
+    @pytest.fixture
+    def loader(self):
+        """Create an enemy loader with the actual data directory."""
+        return EnemyLoader()
+
+    def test_load_goblin(self, loader):
+        """Test loading the goblin enemy."""
+        enemy = loader.load_enemy("goblin")
+
+        assert enemy is not None
+        assert enemy.enemy_id == "goblin"
+        assert enemy.name == "Goblin Scout"
+        assert enemy.difficulty == EnemyDifficulty.EASY
+        assert "humanoid" in enemy.tags
+        assert "goblinoid" in enemy.tags
+
+    def test_load_goblin_shaman(self, loader):
+        """Test loading the goblin shaman."""
+        enemy = loader.load_enemy("goblin_shaman")
+
+        assert enemy is not None
+        assert enemy.enemy_id == "goblin_shaman"
+        assert enemy.base_stats.intelligence == 12  # Caster stats
+        assert "caster" in enemy.tags
+
+    def test_load_dire_wolf(self, loader):
+        """Test loading the dire wolf."""
+        enemy = loader.load_enemy("dire_wolf")
+
+        assert enemy is not None
+        assert enemy.difficulty == EnemyDifficulty.MEDIUM
+        assert "beast" in enemy.tags
+        assert enemy.base_stats.strength == 14
+
+    def test_load_bandit(self, loader):
+        """Test loading the bandit."""
+        enemy = loader.load_enemy("bandit")
+
+        assert enemy is not None
+        assert enemy.difficulty == EnemyDifficulty.MEDIUM
+        assert "rogue" in enemy.tags
+        assert enemy.crit_chance == 0.12
+
+    def test_load_skeleton_warrior(self, loader):
+        """Test loading the skeleton warrior."""
+        enemy = loader.load_enemy("skeleton_warrior")
+
+        assert enemy is not None
+        assert "undead" in enemy.tags
+        assert "fearless" in enemy.tags
+
+    def test_load_orc_berserker(self, loader):
+        """Test loading the orc berserker."""
+        enemy = loader.load_enemy("orc_berserker")
+
+        assert enemy is not None
+        assert enemy.difficulty == EnemyDifficulty.HARD
+        assert enemy.base_stats.strength == 18
+        assert enemy.base_damage == 15
+
+    def test_load_nonexistent_enemy(self, loader):
+        """Test loading an enemy that doesn't exist."""
+        enemy = loader.load_enemy("nonexistent_enemy_12345")
+
+        assert enemy is None
+
+    def test_load_all_enemies(self, loader):
+        """Test loading all enemies."""
+        enemies = loader.load_all_enemies()
+
+        # Should have at least our 6 sample enemies
+        assert len(enemies) >= 6
+        assert "goblin" in enemies
+        assert "goblin_shaman" in enemies
+        assert "dire_wolf" in enemies
+        assert "bandit" in enemies
+        assert "skeleton_warrior" in enemies
+        assert "orc_berserker" in enemies
+
+    def test_get_enemies_by_difficulty(self, loader):
+        """Test filtering enemies by difficulty."""
+        loader.load_all_enemies()  # Ensure loaded
+
+        easy_enemies = loader.get_enemies_by_difficulty(EnemyDifficulty.EASY)
+        medium_enemies = loader.get_enemies_by_difficulty(EnemyDifficulty.MEDIUM)
+        hard_enemies = loader.get_enemies_by_difficulty(EnemyDifficulty.HARD)
+
+        # Check we got enemies in each category
+        assert len(easy_enemies) >= 2  # goblin, goblin_shaman
+        assert len(medium_enemies) >= 3  # dire_wolf, bandit, skeleton_warrior
+        assert len(hard_enemies) >= 1  # orc_berserker
+
+        # Verify difficulty is correct
+        for enemy in easy_enemies:
+            assert enemy.difficulty == EnemyDifficulty.EASY
+
+    def test_get_enemies_by_tag(self, loader):
+        """Test filtering enemies by tag."""
+        loader.load_all_enemies()
+
+        humanoids = loader.get_enemies_by_tag("humanoid")
+        undead = loader.get_enemies_by_tag("undead")
+        beasts = loader.get_enemies_by_tag("beast")
+
+        # Verify results
+        assert len(humanoids) >= 3  # goblin, goblin_shaman, bandit, orc
+        assert len(undead) >= 1  # skeleton_warrior
+        assert len(beasts) >= 1  # dire_wolf
+
+        # Verify tags
+        for enemy in humanoids:
+            assert enemy.has_tag("humanoid")
+
+    def test_get_random_enemies(self, loader):
+        """Test random enemy selection."""
+        loader.load_all_enemies()
+
+        # Get 3 random enemies
+        random_enemies = loader.get_random_enemies(count=3)
+
+        assert len(random_enemies) == 3
+        # All should be EnemyTemplate instances
+        for enemy in random_enemies:
+            assert isinstance(enemy, EnemyTemplate)
+
+    def test_get_random_enemies_with_filters(self, loader):
+        """Test random selection with difficulty filter."""
+        loader.load_all_enemies()
+
+        # Get only easy enemies
+        easy_enemies = loader.get_random_enemies(
+            count=5,
+            difficulty=EnemyDifficulty.EASY,
+        )
+
+        # All returned enemies should be easy
+        for enemy in easy_enemies:
+            assert enemy.difficulty == EnemyDifficulty.EASY
+
+    def test_cache_behavior(self, loader):
+        """Test that caching works correctly."""
+        # Load an enemy twice
+        enemy1 = loader.load_enemy("goblin")
+        enemy2 = loader.load_enemy("goblin")
+
+        # Should be the same object (cached)
+        assert enemy1 is enemy2
+
+        # Clear cache
+        loader.clear_cache()
+
+        # Load again
+        enemy3 = loader.load_enemy("goblin")
+
+        # Should be a new object
+        assert enemy3 is not enemy1
+        assert enemy3.enemy_id == enemy1.enemy_id
+
+
+# =============================================================================
+# EnemyDifficulty Enum Tests
+# =============================================================================
+
+class TestEnemyDifficulty:
+    """Tests for EnemyDifficulty enum."""
+
+    def test_difficulty_values(self):
+        """Test difficulty enum values."""
+        assert EnemyDifficulty.EASY.value == "easy"
+        assert EnemyDifficulty.MEDIUM.value == "medium"
+        assert EnemyDifficulty.HARD.value == "hard"
+        assert EnemyDifficulty.BOSS.value == "boss"
+
+    def test_difficulty_from_string(self):
+        """Test creating difficulty from string."""
+        assert EnemyDifficulty("easy") == EnemyDifficulty.EASY
+        assert EnemyDifficulty("hard") == EnemyDifficulty.HARD

api/tests/test_inventory_api.py

@@ -0,0 +1,462 @@
+"""
+Integration tests for Inventory API endpoints.
+
+Tests the REST API endpoints for inventory management functionality.
+"""
+
+import pytest
+from unittest.mock import Mock, patch, MagicMock
+from flask import Flask
+import json
+
+from app import create_app
+from app.api.inventory import inventory_bp
+from app.models.items import Item
+from app.models.character import Character
+from app.models.stats import Stats
+from app.models.skills import PlayerClass
+from app.models.origins import Origin
+from app.models.enums import ItemType, ItemRarity, DamageType
+from app.services.inventory_service import (
+    InventoryService,
+    ItemNotFoundError,
+    CannotEquipError,
+    InvalidSlotError,
+    CannotUseItemError,
+    InventoryFullError,
+    VALID_SLOTS,
+)
+from app.services.character_service import CharacterNotFound
+
+
+# =============================================================================
+# Test Fixtures
+# =============================================================================
+
+@pytest.fixture
+def app():
+    """Create test Flask application."""
+    app = create_app('development')
+    app.config['TESTING'] = True
+    return app
+
+
+@pytest.fixture
+def client(app):
+    """Create test client."""
+    return app.test_client()
+
+
+@pytest.fixture
+def sample_stats():
+    """Sample stats for testing."""
+    return Stats(
+        strength=12,
+        dexterity=14,
+        constitution=10,
+        intelligence=10,
+        wisdom=10,
+        charisma=10,
+        luck=10
+    )
+
+
+@pytest.fixture
+def sample_weapon():
+    """Sample weapon item."""
+    return Item(
+        item_id="test_sword_001",
+        name="Iron Sword",
+        item_type=ItemType.WEAPON,
+        rarity=ItemRarity.COMMON,
+        description="A sturdy iron sword",
+        value=50,
+        damage=8,
+        damage_type=DamageType.PHYSICAL,
+        crit_chance=0.05,
+        crit_multiplier=2.0,
+        required_level=1,
+    )
+
+
+@pytest.fixture
+def sample_armor():
+    """Sample armor item."""
+    return Item(
+        item_id="test_helmet_001",
+        name="Iron Helmet",
+        item_type=ItemType.ARMOR,
+        rarity=ItemRarity.COMMON,
+        description="A sturdy iron helmet",
+        value=30,
+        defense=5,
+        resistance=2,
+        required_level=1,
+    )
+
+
+@pytest.fixture
+def sample_consumable():
+    """Sample consumable item."""
+    return Item(
+        item_id="health_potion_small",
+        name="Small Health Potion",
+        item_type=ItemType.CONSUMABLE,
+        rarity=ItemRarity.COMMON,
+        description="Restores a small amount of health",
+        value=25,
+        effects_on_use=[],  # Simplified for testing
+    )
+
+
+@pytest.fixture
+def sample_class():
+    """Sample player class."""
+    return PlayerClass(
+        class_id="vanguard",
+        name="Vanguard",
+        description="A heavily armored warrior",
+        base_stats=Stats(
+            strength=14,
+            dexterity=10,
+            constitution=14,
+            intelligence=8,
+            wisdom=8,
+            charisma=10,
+            luck=10
+        ),
+        skill_trees=[],
+        starting_equipment=[],
+        starting_abilities=[],
+    )
+
+
+@pytest.fixture
+def sample_origin():
+    """Sample origin."""
+    return Origin(
+        id="soul_revenant",
+        name="Soul Revenant",
+        description="Returned from death",
+        starting_location={"area": "graveyard", "name": "Graveyard"},
+        narrative_hooks=[],
+        starting_bonus={},
+    )
+
+
+@pytest.fixture
+def sample_character(sample_class, sample_origin, sample_weapon, sample_armor, sample_consumable):
+    """Sample character with inventory."""
+    char = Character(
+        character_id="test_char_001",
+        user_id="test_user_001",
+        name="Test Hero",
+        player_class=sample_class,
+        origin=sample_origin,
+        level=5,
+        experience=0,
+        gold=100,
+        inventory=[sample_weapon, sample_armor, sample_consumable],
+        equipped={},
+        unlocked_skills=[],
+    )
+    return char
+
+
+# =============================================================================
+# GET Inventory Endpoint Tests
+# =============================================================================
+
+class TestGetInventoryEndpoint:
+    """Tests for GET /api/v1/characters/<id>/inventory endpoint."""
+
+    def test_get_inventory_requires_auth(self, client):
+        """Test that inventory endpoint requires authentication."""
+        response = client.get('/api/v1/characters/test_char_001/inventory')
+
+        # Should return 401 Unauthorized without valid session
+        assert response.status_code == 401
+
+    def test_get_inventory_character_not_found(self, client):
+        """Test getting inventory for non-existent character returns 404 (after auth)."""
+        # Without auth, returns 401 regardless
+        response = client.get('/api/v1/characters/nonexistent_12345/inventory')
+
+        assert response.status_code == 401
+
+
+# =============================================================================
+# POST Equip Endpoint Tests
+# =============================================================================
+
+class TestEquipEndpoint:
+    """Tests for POST /api/v1/characters/<id>/inventory/equip endpoint."""
+
+    def test_equip_requires_auth(self, client):
+        """Test that equip endpoint requires authentication."""
+        response = client.post(
+            '/api/v1/characters/test_char_001/inventory/equip',
+            json={
+                'item_id': 'test_sword_001',
+                'slot': 'weapon'
+            }
+        )
+
+        # Should return 401 Unauthorized without valid session
+        assert response.status_code == 401
+
+    def test_equip_missing_item_id(self, client):
+        """Test equip without item_id still requires auth first."""
+        response = client.post(
+            '/api/v1/characters/test_char_001/inventory/equip',
+            json={'slot': 'weapon'}
+        )
+
+        # Without auth, returns 401 regardless of payload issues
+        assert response.status_code == 401
+
+    def test_equip_missing_slot(self, client):
+        """Test equip without slot still requires auth first."""
+        response = client.post(
+            '/api/v1/characters/test_char_001/inventory/equip',
+            json={'item_id': 'test_sword_001'}
+        )
+
+        # Without auth, returns 401 regardless of payload issues
+        assert response.status_code == 401
+
+    def test_equip_missing_body(self, client):
+        """Test equip without request body still requires auth first."""
+        response = client.post('/api/v1/characters/test_char_001/inventory/equip')
+
+        # Without auth, returns 401 regardless of payload issues
+        assert response.status_code == 401
+
+
+# =============================================================================
+# POST Unequip Endpoint Tests
+# =============================================================================
+
+class TestUnequipEndpoint:
+    """Tests for POST /api/v1/characters/<id>/inventory/unequip endpoint."""
+
+    def test_unequip_requires_auth(self, client):
+        """Test that unequip endpoint requires authentication."""
+        response = client.post(
+            '/api/v1/characters/test_char_001/inventory/unequip',
+            json={'slot': 'weapon'}
+        )
+
+        # Should return 401 Unauthorized without valid session
+        assert response.status_code == 401
+
+    def test_unequip_missing_slot(self, client):
+        """Test unequip without slot still requires auth first."""
+        response = client.post(
+            '/api/v1/characters/test_char_001/inventory/unequip',
+            json={}
+        )
+
+        # Without auth, returns 401 regardless of payload issues
+        assert response.status_code == 401
+
+    def test_unequip_missing_body(self, client):
+        """Test unequip without request body still requires auth first."""
+        response = client.post('/api/v1/characters/test_char_001/inventory/unequip')
+
+        # Without auth, returns 401 regardless of payload issues
+        assert response.status_code == 401
+
+
+# =============================================================================
+# POST Use Item Endpoint Tests
+# =============================================================================
+
+class TestUseItemEndpoint:
+    """Tests for POST /api/v1/characters/<id>/inventory/use endpoint."""
+
+    def test_use_requires_auth(self, client):
+        """Test that use item endpoint requires authentication."""
+        response = client.post(
+            '/api/v1/characters/test_char_001/inventory/use',
+            json={'item_id': 'health_potion_small'}
+        )
+
+        # Should return 401 Unauthorized without valid session
+        assert response.status_code == 401
+
+    def test_use_missing_item_id(self, client):
+        """Test use item without item_id still requires auth first."""
+        response = client.post(
+            '/api/v1/characters/test_char_001/inventory/use',
+            json={}
+        )
+
+        # Without auth, returns 401 regardless of payload issues
+        assert response.status_code == 401
+
+    def test_use_missing_body(self, client):
+        """Test use item without request body still requires auth first."""
+        response = client.post('/api/v1/characters/test_char_001/inventory/use')
+
+        # Without auth, returns 401 regardless of payload issues
+        assert response.status_code == 401
+
+
+# =============================================================================
+# DELETE Drop Item Endpoint Tests
+# =============================================================================
+
+class TestDropItemEndpoint:
+    """Tests for DELETE /api/v1/characters/<id>/inventory/<item_id> endpoint."""
+
+    def test_drop_requires_auth(self, client):
+        """Test that drop item endpoint requires authentication."""
+        response = client.delete(
+            '/api/v1/characters/test_char_001/inventory/test_sword_001'
+        )
+
+        # Should return 401 Unauthorized without valid session
+        assert response.status_code == 401
+
+
+# =============================================================================
+# Valid Slot Tests (Unit level)
+# =============================================================================
+
+class TestValidSlots:
+    """Tests to verify slot configuration."""
+
+    def test_valid_slots_defined(self):
+        """Test that all expected slots are defined."""
+        expected_slots = {
+            'weapon', 'off_hand', 'helmet', 'chest',
+            'gloves', 'boots', 'accessory_1', 'accessory_2'
+        }
+        assert VALID_SLOTS == expected_slots
+
+    def test_valid_slots_count(self):
+        """Test that we have exactly 8 equipment slots."""
+        assert len(VALID_SLOTS) == 8
+
+
+# =============================================================================
+# Endpoint URL Pattern Tests
+# =============================================================================
+
+class TestEndpointURLPatterns:
+    """Tests to verify correct URL patterns."""
+
+    def test_get_inventory_url(self, client):
+        """Test GET inventory URL pattern."""
+        response = client.get('/api/v1/characters/any_id/inventory')
+        # Should be 401 (auth required), not 404 (route not found)
+        assert response.status_code == 401
+
+    def test_equip_url(self, client):
+        """Test POST equip URL pattern."""
+        response = client.post(
+            '/api/v1/characters/any_id/inventory/equip',
+            json={'item_id': 'x', 'slot': 'weapon'}
+        )
+        # Should be 401 (auth required), not 404 (route not found)
+        assert response.status_code == 401
+
+    def test_unequip_url(self, client):
+        """Test POST unequip URL pattern."""
+        response = client.post(
+            '/api/v1/characters/any_id/inventory/unequip',
+            json={'slot': 'weapon'}
+        )
+        # Should be 401 (auth required), not 404 (route not found)
+        assert response.status_code == 401
+
+    def test_use_url(self, client):
+        """Test POST use URL pattern."""
+        response = client.post(
+            '/api/v1/characters/any_id/inventory/use',
+            json={'item_id': 'x'}
+        )
+        # Should be 401 (auth required), not 404 (route not found)
+        assert response.status_code == 401
+
+    def test_drop_url(self, client):
+        """Test DELETE drop URL pattern."""
+        response = client.delete('/api/v1/characters/any_id/inventory/item_123')
+        # Should be 401 (auth required), not 404 (route not found)
+        assert response.status_code == 401
+
+
+# =============================================================================
+# Response Format Tests (verifying blueprint registration)
+# =============================================================================
+
+class TestResponseFormats:
+    """Tests to verify API response format consistency."""
+
+    def test_get_inventory_401_format(self, client):
+        """Test that 401 response follows standard format."""
+        response = client.get('/api/v1/characters/test_char_001/inventory')
+
+        assert response.status_code == 401
+        data = response.get_json()
+
+        # Standard response format should include status
+        assert data is not None
+        assert 'status' in data
+        assert data['status'] == 401
+
+    def test_equip_401_format(self, client):
+        """Test that equip 401 response follows standard format."""
+        response = client.post(
+            '/api/v1/characters/test_char_001/inventory/equip',
+            json={'item_id': 'test', 'slot': 'weapon'}
+        )
+
+        assert response.status_code == 401
+        data = response.get_json()
+
+        assert data is not None
+        assert 'status' in data
+        assert data['status'] == 401
+
+    def test_unequip_401_format(self, client):
+        """Test that unequip 401 response follows standard format."""
+        response = client.post(
+            '/api/v1/characters/test_char_001/inventory/unequip',
+            json={'slot': 'weapon'}
+        )
+
+        assert response.status_code == 401
+        data = response.get_json()
+
+        assert data is not None
+        assert 'status' in data
+        assert data['status'] == 401
+
+    def test_use_401_format(self, client):
+        """Test that use 401 response follows standard format."""
+        response = client.post(
+            '/api/v1/characters/test_char_001/inventory/use',
+            json={'item_id': 'test'}
+        )
+
+        assert response.status_code == 401
+        data = response.get_json()
+
+        assert data is not None
+        assert 'status' in data
+        assert data['status'] == 401
+
+    def test_drop_401_format(self, client):
+        """Test that drop 401 response follows standard format."""
+        response = client.delete(
+            '/api/v1/characters/test_char_001/inventory/test_item'
+        )
+
+        assert response.status_code == 401
+        data = response.get_json()
+
+        assert data is not None
+        assert 'status' in data
+        assert data['status'] == 401

api/tests/test_inventory_service.py

@@ -0,0 +1,819 @@
+"""
+Unit tests for the InventoryService.
+
+Tests cover:
+- Adding and removing items
+- Equipment slot validation
+- Level and class requirement checks
+- Consumable usage and effect application
+- Bulk operations
+- Error handling
+"""
+
+import pytest
+from unittest.mock import Mock, patch, MagicMock
+from typing import List
+
+from app.models.character import Character
+from app.models.items import Item
+from app.models.effects import Effect
+from app.models.stats import Stats
+from app.models.enums import ItemType, ItemRarity, EffectType, StatType, DamageType
+from app.models.skills import PlayerClass
+from app.models.origins import Origin
+from app.services.inventory_service import (
+    InventoryService,
+    ItemNotFoundError,
+    CannotEquipError,
+    InvalidSlotError,
+    CannotUseItemError,
+    InventoryFullError,
+    ConsumableResult,
+    VALID_SLOTS,
+    ITEM_TYPE_SLOTS,
+    MAX_INVENTORY_SIZE,
+    get_inventory_service,
+)
+
+
+# =============================================================================
+# Test Fixtures
+# =============================================================================
+
+@pytest.fixture
+def mock_character_service():
+    """Create a mock CharacterService."""
+    service = Mock()
+    service.update_character = Mock()
+    return service
+
+
+@pytest.fixture
+def inventory_service(mock_character_service):
+    """Create InventoryService with mocked dependencies."""
+    return InventoryService(character_service=mock_character_service)
+
+
+@pytest.fixture
+def mock_origin():
+    """Create a minimal Origin for testing."""
+    from app.models.origins import StartingLocation, StartingBonus
+
+    starting_location = StartingLocation(
+        id="test_location",
+        name="Test Village",
+        region="Test Region",
+        description="A test location"
+    )
+
+    return Origin(
+        id="test_origin",
+        name="Test Origin",
+        description="A test origin for testing purposes",
+        starting_location=starting_location,
+        narrative_hooks=["test hook"],
+        starting_bonus=None,
+    )
+
+
+@pytest.fixture
+def mock_player_class():
+    """Create a minimal PlayerClass for testing."""
+    return PlayerClass(
+        class_id="warrior",
+        name="Warrior",
+        description="A mighty warrior",
+        base_stats=Stats(
+            strength=14,
+            dexterity=10,
+            constitution=12,
+            intelligence=8,
+            wisdom=10,
+            charisma=8,
+            luck=8,
+        ),
+        skill_trees=[],
+        starting_abilities=["basic_attack"],
+    )
+
+
+@pytest.fixture
+def test_character(mock_player_class, mock_origin):
+    """Create a test character."""
+    return Character(
+        character_id="char_test_123",
+        user_id="user_test_456",
+        name="Test Hero",
+        player_class=mock_player_class,
+        origin=mock_origin,
+        level=5,
+        experience=0,
+        base_stats=mock_player_class.base_stats.copy(),
+        inventory=[],
+        equipped={},
+        gold=100,
+    )
+
+
+@pytest.fixture
+def test_weapon():
+    """Create a test weapon item."""
+    return Item(
+        item_id="iron_sword",
+        name="Iron Sword",
+        item_type=ItemType.WEAPON,
+        rarity=ItemRarity.COMMON,
+        description="A sturdy iron sword",
+        value=50,
+        damage=10,
+        damage_type=DamageType.PHYSICAL,
+        crit_chance=0.05,
+        crit_multiplier=2.0,
+        required_level=1,
+    )
+
+
+@pytest.fixture
+def test_armor():
+    """Create a test armor item."""
+    return Item(
+        item_id="leather_chest",
+        name="Leather Chestpiece",
+        item_type=ItemType.ARMOR,
+        rarity=ItemRarity.COMMON,
+        description="Simple leather armor",
+        value=40,
+        defense=5,
+        resistance=2,
+        required_level=1,
+    )
+
+
+@pytest.fixture
+def test_helmet():
+    """Create a test helmet item."""
+    return Item(
+        item_id="iron_helm",
+        name="Iron Helmet",
+        item_type=ItemType.ARMOR,
+        rarity=ItemRarity.UNCOMMON,
+        description="A protective iron helmet",
+        value=30,
+        defense=3,
+        resistance=1,
+        required_level=3,
+    )
+
+
+@pytest.fixture
+def test_consumable():
+    """Create a test consumable item (health potion)."""
+    return Item(
+        item_id="health_potion_small",
+        name="Small Health Potion",
+        item_type=ItemType.CONSUMABLE,
+        rarity=ItemRarity.COMMON,
+        description="Restores 25 HP",
+        value=10,
+        effects_on_use=[
+            Effect(
+                effect_id="heal_25",
+                name="Minor Healing",
+                effect_type=EffectType.HOT,
+                duration=1,
+                power=25,
+                stacks=1,
+            )
+        ],
+    )
+
+
+@pytest.fixture
+def test_buff_potion():
+    """Create a test buff potion."""
+    return Item(
+        item_id="strength_potion",
+        name="Potion of Strength",
+        item_type=ItemType.CONSUMABLE,
+        rarity=ItemRarity.UNCOMMON,
+        description="Increases strength temporarily",
+        value=25,
+        effects_on_use=[
+            Effect(
+                effect_id="str_buff",
+                name="Strength Boost",
+                effect_type=EffectType.BUFF,
+                duration=3,
+                power=5,
+                stat_affected=StatType.STRENGTH,
+                stacks=1,
+            )
+        ],
+    )
+
+
+@pytest.fixture
+def test_quest_item():
+    """Create a test quest item."""
+    return Item(
+        item_id="ancient_key",
+        name="Ancient Key",
+        item_type=ItemType.QUEST_ITEM,
+        rarity=ItemRarity.RARE,
+        description="An ornate key to the ancient tomb",
+        value=0,
+        is_tradeable=False,
+    )
+
+
+@pytest.fixture
+def high_level_weapon():
+    """Create a weapon with high level requirement."""
+    return Item(
+        item_id="legendary_blade",
+        name="Blade of Ages",
+        item_type=ItemType.WEAPON,
+        rarity=ItemRarity.LEGENDARY,
+        description="A blade forged in ancient times",
+        value=5000,
+        damage=50,
+        damage_type=DamageType.PHYSICAL,
+        required_level=20,  # Higher than test character's level 5
+    )
+
+
+# =============================================================================
+# Read Operation Tests
+# =============================================================================
+
+class TestGetInventory:
+    """Tests for get_inventory() and related read operations."""
+
+    def test_get_empty_inventory(self, inventory_service, test_character):
+        """Test getting inventory when it's empty."""
+        items = inventory_service.get_inventory(test_character)
+        assert items == []
+
+    def test_get_inventory_with_items(self, inventory_service, test_character, test_weapon, test_armor):
+        """Test getting inventory with items."""
+        test_character.inventory = [test_weapon, test_armor]
+
+        items = inventory_service.get_inventory(test_character)
+
+        assert len(items) == 2
+        assert test_weapon in items
+        assert test_armor in items
+
+    def test_get_inventory_returns_copy(self, inventory_service, test_character, test_weapon):
+        """Test that get_inventory returns a new list (not the original)."""
+        test_character.inventory = [test_weapon]
+
+        items = inventory_service.get_inventory(test_character)
+        items.append(test_weapon)  # Modify returned list
+
+        # Original inventory should be unchanged
+        assert len(test_character.inventory) == 1
+
+    def test_get_item_by_id_found(self, inventory_service, test_character, test_weapon):
+        """Test finding an item by ID."""
+        test_character.inventory = [test_weapon]
+
+        item = inventory_service.get_item_by_id(test_character, "iron_sword")
+
+        assert item is test_weapon
+
+    def test_get_item_by_id_not_found(self, inventory_service, test_character, test_weapon):
+        """Test item not found returns None."""
+        test_character.inventory = [test_weapon]
+
+        item = inventory_service.get_item_by_id(test_character, "nonexistent_item")
+
+        assert item is None
+
+    def test_get_equipped_items_empty(self, inventory_service, test_character):
+        """Test getting equipped items when nothing equipped."""
+        equipped = inventory_service.get_equipped_items(test_character)
+        assert equipped == {}
+
+    def test_get_equipped_items_with_equipment(self, inventory_service, test_character, test_weapon):
+        """Test getting equipped items."""
+        test_character.equipped = {"weapon": test_weapon}
+
+        equipped = inventory_service.get_equipped_items(test_character)
+
+        assert "weapon" in equipped
+        assert equipped["weapon"] is test_weapon
+
+    def test_get_equipped_item_specific_slot(self, inventory_service, test_character, test_weapon):
+        """Test getting item from a specific slot."""
+        test_character.equipped = {"weapon": test_weapon}
+
+        item = inventory_service.get_equipped_item(test_character, "weapon")
+
+        assert item is test_weapon
+
+    def test_get_equipped_item_empty_slot(self, inventory_service, test_character):
+        """Test getting item from empty slot returns None."""
+        item = inventory_service.get_equipped_item(test_character, "weapon")
+        assert item is None
+
+    def test_get_inventory_count(self, inventory_service, test_character, test_weapon, test_armor):
+        """Test counting inventory items."""
+        test_character.inventory = [test_weapon, test_armor]
+
+        count = inventory_service.get_inventory_count(test_character)
+
+        assert count == 2
+
+
+# =============================================================================
+# Add/Remove Item Tests
+# =============================================================================
+
+class TestAddItem:
+    """Tests for add_item()."""
+
+    def test_add_item_success(self, inventory_service, test_character, test_weapon, mock_character_service):
+        """Test successfully adding an item."""
+        inventory_service.add_item(test_character, test_weapon, "user_test_456")
+
+        assert test_weapon in test_character.inventory
+        mock_character_service.update_character.assert_called_once()
+
+    def test_add_item_without_save(self, inventory_service, test_character, test_weapon, mock_character_service):
+        """Test adding item without persistence."""
+        inventory_service.add_item(test_character, test_weapon, "user_test_456", save=False)
+
+        assert test_weapon in test_character.inventory
+        mock_character_service.update_character.assert_not_called()
+
+    def test_add_multiple_items(self, inventory_service, test_character, test_weapon, test_armor, mock_character_service):
+        """Test adding multiple items."""
+        inventory_service.add_item(test_character, test_weapon, "user_test_456")
+        inventory_service.add_item(test_character, test_armor, "user_test_456")
+
+        assert len(test_character.inventory) == 2
+
+
+class TestRemoveItem:
+    """Tests for remove_item()."""
+
+    def test_remove_item_success(self, inventory_service, test_character, test_weapon, mock_character_service):
+        """Test successfully removing an item."""
+        test_character.inventory = [test_weapon]
+
+        removed = inventory_service.remove_item(test_character, "iron_sword", "user_test_456")
+
+        assert removed is test_weapon
+        assert test_weapon not in test_character.inventory
+        mock_character_service.update_character.assert_called_once()
+
+    def test_remove_item_not_found(self, inventory_service, test_character):
+        """Test removing non-existent item raises error."""
+        with pytest.raises(ItemNotFoundError) as exc:
+            inventory_service.remove_item(test_character, "nonexistent", "user_test_456")
+
+        assert "nonexistent" in str(exc.value)
+
+    def test_remove_item_from_multiple(self, inventory_service, test_character, test_weapon, test_armor):
+        """Test removing one item from multiple."""
+        test_character.inventory = [test_weapon, test_armor]
+
+        inventory_service.remove_item(test_character, "iron_sword", "user_test_456")
+
+        assert test_weapon not in test_character.inventory
+        assert test_armor in test_character.inventory
+
+    def test_drop_item_alias(self, inventory_service, test_character, test_weapon, mock_character_service):
+        """Test drop_item is an alias for remove_item."""
+        test_character.inventory = [test_weapon]
+
+        dropped = inventory_service.drop_item(test_character, "iron_sword", "user_test_456")
+
+        assert dropped is test_weapon
+        assert test_weapon not in test_character.inventory
+
+
+# =============================================================================
+# Equipment Tests
+# =============================================================================
+
+class TestEquipItem:
+    """Tests for equip_item()."""
+
+    def test_equip_weapon_to_weapon_slot(self, inventory_service, test_character, test_weapon, mock_character_service):
+        """Test equipping a weapon to weapon slot."""
+        test_character.inventory = [test_weapon]
+
+        previous = inventory_service.equip_item(
+            test_character, "iron_sword", "weapon", "user_test_456"
+        )
+
+        assert previous is None
+        assert test_character.equipped.get("weapon") is test_weapon
+        assert test_weapon not in test_character.inventory
+        mock_character_service.update_character.assert_called_once()
+
+    def test_equip_armor_to_chest_slot(self, inventory_service, test_character, test_armor, mock_character_service):
+        """Test equipping armor to chest slot."""
+        test_character.inventory = [test_armor]
+
+        inventory_service.equip_item(test_character, "leather_chest", "chest", "user_test_456")
+
+        assert test_character.equipped.get("chest") is test_armor
+
+    def test_equip_returns_previous_item(self, inventory_service, test_character, test_weapon, mock_character_service):
+        """Test that equipping returns the previously equipped item."""
+        old_weapon = Item(
+            item_id="old_sword",
+            name="Old Sword",
+            item_type=ItemType.WEAPON,
+            damage=5,
+        )
+        test_character.inventory = [test_weapon]
+        test_character.equipped = {"weapon": old_weapon}
+
+        previous = inventory_service.equip_item(
+            test_character, "iron_sword", "weapon", "user_test_456"
+        )
+
+        assert previous is old_weapon
+        assert old_weapon in test_character.inventory  # Returned to inventory
+
+    def test_equip_to_invalid_slot_raises_error(self, inventory_service, test_character, test_weapon):
+        """Test equipping to invalid slot raises InvalidSlotError."""
+        test_character.inventory = [test_weapon]
+
+        with pytest.raises(InvalidSlotError) as exc:
+            inventory_service.equip_item(
+                test_character, "iron_sword", "invalid_slot", "user_test_456"
+            )
+
+        assert "invalid_slot" in str(exc.value)
+        assert "Valid slots" in str(exc.value)
+
+    def test_equip_weapon_to_armor_slot_raises_error(self, inventory_service, test_character, test_weapon):
+        """Test equipping weapon to armor slot raises CannotEquipError."""
+        test_character.inventory = [test_weapon]
+
+        with pytest.raises(CannotEquipError) as exc:
+            inventory_service.equip_item(
+                test_character, "iron_sword", "chest", "user_test_456"
+            )
+
+        assert "weapon" in str(exc.value).lower()
+
+    def test_equip_armor_to_weapon_slot_raises_error(self, inventory_service, test_character, test_armor):
+        """Test equipping armor to weapon slot raises CannotEquipError."""
+        test_character.inventory = [test_armor]
+
+        with pytest.raises(CannotEquipError) as exc:
+            inventory_service.equip_item(
+                test_character, "leather_chest", "weapon", "user_test_456"
+            )
+
+        assert "armor" in str(exc.value).lower()
+
+    def test_equip_item_not_in_inventory(self, inventory_service, test_character):
+        """Test equipping item not in inventory raises ItemNotFoundError."""
+        with pytest.raises(ItemNotFoundError):
+            inventory_service.equip_item(
+                test_character, "nonexistent", "weapon", "user_test_456"
+            )
+
+    def test_equip_item_level_requirement_not_met(self, inventory_service, test_character, high_level_weapon):
+        """Test equipping item with unmet level requirement raises error."""
+        test_character.inventory = [high_level_weapon]
+        test_character.level = 5  # Item requires level 20
+
+        with pytest.raises(CannotEquipError) as exc:
+            inventory_service.equip_item(
+                test_character, "legendary_blade", "weapon", "user_test_456"
+            )
+
+        assert "level 20" in str(exc.value)
+        assert "level 5" in str(exc.value)
+
+    def test_equip_consumable_raises_error(self, inventory_service, test_character, test_consumable):
+        """Test equipping consumable raises CannotEquipError."""
+        test_character.inventory = [test_consumable]
+
+        with pytest.raises(CannotEquipError) as exc:
+            inventory_service.equip_item(
+                test_character, "health_potion_small", "weapon", "user_test_456"
+            )
+
+        assert "consumable" in str(exc.value).lower()
+
+    def test_equip_quest_item_raises_error(self, inventory_service, test_character, test_quest_item):
+        """Test equipping quest item raises CannotEquipError."""
+        test_character.inventory = [test_quest_item]
+
+        with pytest.raises(CannotEquipError) as exc:
+            inventory_service.equip_item(
+                test_character, "ancient_key", "weapon", "user_test_456"
+            )
+
+    def test_equip_weapon_to_off_hand(self, inventory_service, test_character, test_weapon, mock_character_service):
+        """Test equipping weapon to off_hand slot."""
+        test_character.inventory = [test_weapon]
+
+        inventory_service.equip_item(
+            test_character, "iron_sword", "off_hand", "user_test_456"
+        )
+
+        assert test_character.equipped.get("off_hand") is test_weapon
+
+
+class TestUnequipItem:
+    """Tests for unequip_item()."""
+
+    def test_unequip_item_success(self, inventory_service, test_character, test_weapon, mock_character_service):
+        """Test successfully unequipping an item."""
+        test_character.equipped = {"weapon": test_weapon}
+
+        unequipped = inventory_service.unequip_item(test_character, "weapon", "user_test_456")
+
+        assert unequipped is test_weapon
+        assert "weapon" not in test_character.equipped
+        assert test_weapon in test_character.inventory
+        mock_character_service.update_character.assert_called_once()
+
+    def test_unequip_empty_slot_returns_none(self, inventory_service, test_character, mock_character_service):
+        """Test unequipping from empty slot returns None."""
+        unequipped = inventory_service.unequip_item(test_character, "weapon", "user_test_456")
+
+        assert unequipped is None
+
+    def test_unequip_invalid_slot_raises_error(self, inventory_service, test_character):
+        """Test unequipping from invalid slot raises InvalidSlotError."""
+        with pytest.raises(InvalidSlotError):
+            inventory_service.unequip_item(test_character, "invalid_slot", "user_test_456")
+
+
+# =============================================================================
+# Consumable Tests
+# =============================================================================
+
+class TestUseConsumable:
+    """Tests for use_consumable()."""
+
+    def test_use_health_potion(self, inventory_service, test_character, test_consumable, mock_character_service):
+        """Test using a health potion restores HP."""
+        test_character.inventory = [test_consumable]
+
+        result = inventory_service.use_consumable(
+            test_character, "health_potion_small", "user_test_456",
+            current_hp=50, max_hp=100
+        )
+
+        assert isinstance(result, ConsumableResult)
+        assert result.hp_restored == 25  # Potion restores 25, capped at missing HP
+        assert result.item_name == "Small Health Potion"
+        assert test_consumable not in test_character.inventory
+        mock_character_service.update_character.assert_called_once()
+
+    def test_use_health_potion_capped_at_max(self, inventory_service, test_character, test_consumable):
+        """Test HP restoration is capped at max HP."""
+        test_character.inventory = [test_consumable]
+
+        result = inventory_service.use_consumable(
+            test_character, "health_potion_small", "user_test_456",
+            current_hp=90, max_hp=100  # Only missing 10 HP
+        )
+
+        assert result.hp_restored == 10  # Only restores missing amount
+
+    def test_use_consumable_at_full_hp(self, inventory_service, test_character, test_consumable):
+        """Test using potion at full HP restores 0."""
+        test_character.inventory = [test_consumable]
+
+        result = inventory_service.use_consumable(
+            test_character, "health_potion_small", "user_test_456",
+            current_hp=100, max_hp=100
+        )
+
+        assert result.hp_restored == 0
+
+    def test_use_buff_potion(self, inventory_service, test_character, test_buff_potion, mock_character_service):
+        """Test using a buff potion."""
+        test_character.inventory = [test_buff_potion]
+
+        result = inventory_service.use_consumable(
+            test_character, "strength_potion", "user_test_456"
+        )
+
+        assert result.item_name == "Potion of Strength"
+        assert len(result.effects_applied) == 1
+        assert result.effects_applied[0]["effect_type"] == "buff"
+        assert result.effects_applied[0]["stat_affected"] == "strength"
+
+    def test_use_non_consumable_raises_error(self, inventory_service, test_character, test_weapon):
+        """Test using non-consumable item raises CannotUseItemError."""
+        test_character.inventory = [test_weapon]
+
+        with pytest.raises(CannotUseItemError) as exc:
+            inventory_service.use_consumable(
+                test_character, "iron_sword", "user_test_456"
+            )
+
+        assert "not a consumable" in str(exc.value)
+
+    def test_use_item_not_in_inventory_raises_error(self, inventory_service, test_character):
+        """Test using item not in inventory raises ItemNotFoundError."""
+        with pytest.raises(ItemNotFoundError):
+            inventory_service.use_consumable(
+                test_character, "nonexistent", "user_test_456"
+            )
+
+    def test_consumable_result_to_dict(self, inventory_service, test_character, test_consumable):
+        """Test ConsumableResult serialization."""
+        test_character.inventory = [test_consumable]
+
+        result = inventory_service.use_consumable(
+            test_character, "health_potion_small", "user_test_456",
+            current_hp=50, max_hp=100
+        )
+
+        result_dict = result.to_dict()
+
+        assert "item_name" in result_dict
+        assert "hp_restored" in result_dict
+        assert "effects_applied" in result_dict
+        assert "message" in result_dict
+
+
+class TestUseConsumableInCombat:
+    """Tests for use_consumable_in_combat()."""
+
+    def test_combat_consumable_returns_effects(self, inventory_service, test_character, test_buff_potion):
+        """Test combat consumable returns duration effects."""
+        test_character.inventory = [test_buff_potion]
+
+        result, effects = inventory_service.use_consumable_in_combat(
+            test_character, "strength_potion", "user_test_456",
+            current_hp=50, max_hp=100
+        )
+
+        assert isinstance(result, ConsumableResult)
+        assert len(effects) == 1
+        assert effects[0].effect_type == EffectType.BUFF
+        assert effects[0].duration == 3
+
+    def test_combat_instant_heal_potion(self, inventory_service, test_character, test_consumable):
+        """Test instant heal in combat."""
+        test_character.inventory = [test_consumable]
+
+        result, effects = inventory_service.use_consumable_in_combat(
+            test_character, "health_potion_small", "user_test_456",
+            current_hp=50, max_hp=100
+        )
+
+        # HOT with duration 1 should be returned as duration effect for combat tracking
+        assert len(effects) >= 0  # Implementation may vary
+
+
+# =============================================================================
+# Bulk Operation Tests
+# =============================================================================
+
+class TestBulkOperations:
+    """Tests for bulk inventory operations."""
+
+    def test_add_items_bulk(self, inventory_service, test_character, test_weapon, test_armor, mock_character_service):
+        """Test adding multiple items at once."""
+        items = [test_weapon, test_armor]
+
+        count = inventory_service.add_items(test_character, items, "user_test_456")
+
+        assert count == 2
+        assert len(test_character.inventory) == 2
+        mock_character_service.update_character.assert_called_once()
+
+    def test_get_items_by_type(self, inventory_service, test_character, test_weapon, test_armor, test_consumable):
+        """Test filtering items by type."""
+        test_character.inventory = [test_weapon, test_armor, test_consumable]
+
+        weapons = inventory_service.get_items_by_type(test_character, ItemType.WEAPON)
+        armor = inventory_service.get_items_by_type(test_character, ItemType.ARMOR)
+        consumables = inventory_service.get_items_by_type(test_character, ItemType.CONSUMABLE)
+
+        assert len(weapons) == 1
+        assert test_weapon in weapons
+        assert len(armor) == 1
+        assert test_armor in armor
+        assert len(consumables) == 1
+
+    def test_get_equippable_items(self, inventory_service, test_character, test_weapon, test_armor, test_consumable):
+        """Test getting only equippable items."""
+        test_character.inventory = [test_weapon, test_armor, test_consumable]
+
+        equippable = inventory_service.get_equippable_items(test_character)
+
+        assert test_weapon in equippable
+        assert test_armor in equippable
+        assert test_consumable not in equippable
+
+    def test_get_equippable_items_for_slot(self, inventory_service, test_character, test_weapon, test_armor):
+        """Test getting equippable items for a specific slot."""
+        test_character.inventory = [test_weapon, test_armor]
+
+        for_weapon = inventory_service.get_equippable_items(test_character, slot="weapon")
+        for_chest = inventory_service.get_equippable_items(test_character, slot="chest")
+
+        assert test_weapon in for_weapon
+        assert test_armor not in for_weapon
+        assert test_armor in for_chest
+        assert test_weapon not in for_chest
+
+    def test_get_equippable_items_excludes_high_level(self, inventory_service, test_character, test_weapon, high_level_weapon):
+        """Test that items above character level are excluded."""
+        test_character.inventory = [test_weapon, high_level_weapon]
+        test_character.level = 5
+
+        equippable = inventory_service.get_equippable_items(test_character)
+
+        assert test_weapon in equippable
+        assert high_level_weapon not in equippable
+
+
+# =============================================================================
+# Edge Cases and Error Handling
+# =============================================================================
+
+class TestEdgeCases:
+    """Tests for edge cases and error handling."""
+
+    def test_valid_slots_constant(self):
+        """Test VALID_SLOTS contains expected slots."""
+        expected = {"weapon", "off_hand", "helmet", "chest", "gloves", "boots", "accessory_1", "accessory_2"}
+        assert VALID_SLOTS == expected
+
+    def test_item_type_slots_mapping(self):
+        """Test ITEM_TYPE_SLOTS mapping is correct."""
+        assert ItemType.WEAPON in ITEM_TYPE_SLOTS
+        assert "weapon" in ITEM_TYPE_SLOTS[ItemType.WEAPON]
+        assert "off_hand" in ITEM_TYPE_SLOTS[ItemType.WEAPON]
+        assert ItemType.ARMOR in ITEM_TYPE_SLOTS
+        assert "chest" in ITEM_TYPE_SLOTS[ItemType.ARMOR]
+        assert "helmet" in ITEM_TYPE_SLOTS[ItemType.ARMOR]
+
+    def test_generated_item_with_unique_id(self, inventory_service, test_character, mock_character_service):
+        """Test handling of generated items with unique IDs."""
+        generated_item = Item(
+            item_id="gen_abc123",  # Generated item ID format
+            name="Dagger",
+            item_type=ItemType.WEAPON,
+            rarity=ItemRarity.RARE,
+            damage=15,
+            is_generated=True,
+            generated_name="Flaming Dagger of Strength",
+            base_template_id="dagger",
+            applied_affixes=["flaming", "of_strength"],
+        )
+
+        inventory_service.add_item(test_character, generated_item, "user_test_456")
+
+        assert generated_item in test_character.inventory
+        assert generated_item.get_display_name() == "Flaming Dagger of Strength"
+
+    def test_equip_generated_item(self, inventory_service, test_character, mock_character_service):
+        """Test equipping a generated item."""
+        generated_item = Item(
+            item_id="gen_xyz789",
+            name="Sword",
+            item_type=ItemType.WEAPON,
+            rarity=ItemRarity.EPIC,
+            damage=25,
+            is_generated=True,
+            generated_name="Blazing Sword of Power",
+            required_level=1,
+        )
+        test_character.inventory = [generated_item]
+
+        inventory_service.equip_item(test_character, "gen_xyz789", "weapon", "user_test_456")
+
+        assert test_character.equipped.get("weapon") is generated_item
+
+
+# =============================================================================
+# Global Instance Tests
+# =============================================================================
+
+class TestGlobalInstance:
+    """Tests for the global singleton pattern."""
+
+    def test_get_inventory_service_returns_instance(self):
+        """Test get_inventory_service returns InventoryService."""
+        with patch('app.services.inventory_service._service_instance', None):
+            with patch('app.services.inventory_service.get_character_service'):
+                service = get_inventory_service()
+                assert isinstance(service, InventoryService)
+
+    def test_get_inventory_service_returns_same_instance(self):
+        """Test get_inventory_service returns singleton."""
+        with patch('app.services.inventory_service._service_instance', None):
+            with patch('app.services.inventory_service.get_character_service'):
+                service1 = get_inventory_service()
+                service2 = get_inventory_service()
+                assert service1 is service2

api/tests/test_item_generator.py

@@ -0,0 +1,527 @@
+"""
+Tests for the Item Generator and Affix System.
+
+Tests cover:
+- Affix loading from YAML
+- Base item template loading
+- Item generation with affixes
+- Name generation
+- Stat combination
+"""
+
+import pytest
+from unittest.mock import patch, MagicMock
+
+from app.models.affixes import Affix, BaseItemTemplate
+from app.models.enums import AffixType, AffixTier, ItemRarity, ItemType, DamageType
+from app.services.affix_loader import AffixLoader, get_affix_loader
+from app.services.base_item_loader import BaseItemLoader, get_base_item_loader
+from app.services.item_generator import ItemGenerator, get_item_generator
+
+
+class TestAffixModel:
+    """Tests for the Affix dataclass."""
+
+    def test_affix_creation(self):
+        """Test creating an Affix instance."""
+        affix = Affix(
+            affix_id="flaming",
+            name="Flaming",
+            affix_type=AffixType.PREFIX,
+            tier=AffixTier.MINOR,
+            description="Fire damage",
+            damage_type=DamageType.FIRE,
+            elemental_ratio=0.25,
+            damage_bonus=3,
+        )
+
+        assert affix.affix_id == "flaming"
+        assert affix.name == "Flaming"
+        assert affix.affix_type == AffixType.PREFIX
+        assert affix.tier == AffixTier.MINOR
+        assert affix.applies_elemental_damage()
+
+    def test_affix_can_apply_to(self):
+        """Test affix eligibility checking."""
+        # Weapon-only affix
+        weapon_affix = Affix(
+            affix_id="sharp",
+            name="Sharp",
+            affix_type=AffixType.PREFIX,
+            tier=AffixTier.MINOR,
+            allowed_item_types=["weapon"],
+        )
+
+        assert weapon_affix.can_apply_to("weapon", "rare")
+        assert not weapon_affix.can_apply_to("armor", "rare")
+
+    def test_affix_legendary_only(self):
+        """Test legendary-only affix restriction."""
+        legendary_affix = Affix(
+            affix_id="vorpal",
+            name="Vorpal",
+            affix_type=AffixType.PREFIX,
+            tier=AffixTier.LEGENDARY,
+            required_rarity="legendary",
+        )
+
+        assert legendary_affix.is_legendary_only()
+        assert legendary_affix.can_apply_to("weapon", "legendary")
+        assert not legendary_affix.can_apply_to("weapon", "epic")
+
+    def test_affix_serialization(self):
+        """Test affix to_dict and from_dict."""
+        affix = Affix(
+            affix_id="of_strength",
+            name="of Strength",
+            affix_type=AffixType.SUFFIX,
+            tier=AffixTier.MINOR,
+            stat_bonuses={"strength": 2},
+        )
+
+        data = affix.to_dict()
+        restored = Affix.from_dict(data)
+
+        assert restored.affix_id == affix.affix_id
+        assert restored.name == affix.name
+        assert restored.stat_bonuses == affix.stat_bonuses
+
+
+class TestBaseItemTemplate:
+    """Tests for the BaseItemTemplate dataclass."""
+
+    def test_template_creation(self):
+        """Test creating a BaseItemTemplate instance."""
+        template = BaseItemTemplate(
+            template_id="dagger",
+            name="Dagger",
+            item_type="weapon",
+            base_damage=6,
+            base_value=15,
+            crit_chance=0.08,
+            required_level=1,
+        )
+
+        assert template.template_id == "dagger"
+        assert template.base_damage == 6
+        assert template.crit_chance == 0.08
+
+    def test_template_rarity_eligibility(self):
+        """Test template rarity checking."""
+        template = BaseItemTemplate(
+            template_id="plate_armor",
+            name="Plate Armor",
+            item_type="armor",
+            min_rarity="rare",
+        )
+
+        assert template.can_generate_at_rarity("rare")
+        assert template.can_generate_at_rarity("epic")
+        assert template.can_generate_at_rarity("legendary")
+        assert not template.can_generate_at_rarity("common")
+        assert not template.can_generate_at_rarity("uncommon")
+
+    def test_template_level_eligibility(self):
+        """Test template level checking."""
+        template = BaseItemTemplate(
+            template_id="greatsword",
+            name="Greatsword",
+            item_type="weapon",
+            required_level=5,
+        )
+
+        assert template.can_drop_for_level(5)
+        assert template.can_drop_for_level(10)
+        assert not template.can_drop_for_level(4)
+
+
+class TestAffixLoader:
+    """Tests for the AffixLoader service."""
+
+    def test_loader_initialization(self):
+        """Test AffixLoader initializes correctly."""
+        loader = get_affix_loader()
+        assert loader is not None
+
+    def test_load_prefixes(self):
+        """Test loading prefixes from YAML."""
+        loader = get_affix_loader()
+        loader.load_all()
+
+        prefixes = loader.get_all_prefixes()
+        assert len(prefixes) > 0
+
+        # Check for known prefix
+        flaming = loader.get_affix("flaming")
+        assert flaming is not None
+        assert flaming.affix_type == AffixType.PREFIX
+        assert flaming.name == "Flaming"
+
+    def test_load_suffixes(self):
+        """Test loading suffixes from YAML."""
+        loader = get_affix_loader()
+        loader.load_all()
+
+        suffixes = loader.get_all_suffixes()
+        assert len(suffixes) > 0
+
+        # Check for known suffix
+        of_strength = loader.get_affix("of_strength")
+        assert of_strength is not None
+        assert of_strength.affix_type == AffixType.SUFFIX
+        assert of_strength.name == "of Strength"
+
+    def test_get_eligible_prefixes(self):
+        """Test filtering eligible prefixes."""
+        loader = get_affix_loader()
+
+        # Get weapon prefixes for rare items
+        eligible = loader.get_eligible_prefixes("weapon", "rare")
+        assert len(eligible) > 0
+
+        # All should be applicable to weapons
+        for prefix in eligible:
+            assert prefix.can_apply_to("weapon", "rare")
+
+    def test_get_random_prefix(self):
+        """Test random prefix selection."""
+        loader = get_affix_loader()
+
+        prefix = loader.get_random_prefix("weapon", "rare")
+        assert prefix is not None
+        assert prefix.affix_type == AffixType.PREFIX
+
+
+class TestBaseItemLoader:
+    """Tests for the BaseItemLoader service."""
+
+    def test_loader_initialization(self):
+        """Test BaseItemLoader initializes correctly."""
+        loader = get_base_item_loader()
+        assert loader is not None
+
+    def test_load_weapons(self):
+        """Test loading weapon templates from YAML."""
+        loader = get_base_item_loader()
+        loader.load_all()
+
+        weapons = loader.get_all_weapons()
+        assert len(weapons) > 0
+
+        # Check for known weapon
+        dagger = loader.get_template("dagger")
+        assert dagger is not None
+        assert dagger.item_type == "weapon"
+        assert dagger.base_damage > 0
+
+    def test_load_armor(self):
+        """Test loading armor templates from YAML."""
+        loader = get_base_item_loader()
+        loader.load_all()
+
+        armor = loader.get_all_armor()
+        assert len(armor) > 0
+
+        # Check for known armor
+        chainmail = loader.get_template("chainmail")
+        assert chainmail is not None
+        assert chainmail.item_type == "armor"
+        assert chainmail.base_defense > 0
+
+    def test_get_eligible_templates(self):
+        """Test filtering eligible templates."""
+        loader = get_base_item_loader()
+
+        # Get weapons for level 1, common rarity
+        eligible = loader.get_eligible_templates("weapon", "common", 1)
+        assert len(eligible) > 0
+
+        # All should be eligible
+        for template in eligible:
+            assert template.can_drop_for_level(1)
+            assert template.can_generate_at_rarity("common")
+
+    def test_get_random_template(self):
+        """Test random template selection."""
+        loader = get_base_item_loader()
+
+        template = loader.get_random_template("weapon", "common", 1)
+        assert template is not None
+        assert template.item_type == "weapon"
+
+
+class TestItemGenerator:
+    """Tests for the ItemGenerator service."""
+
+    def test_generator_initialization(self):
+        """Test ItemGenerator initializes correctly."""
+        generator = get_item_generator()
+        assert generator is not None
+
+    def test_generate_common_item(self):
+        """Test generating a common item (no affixes)."""
+        generator = get_item_generator()
+
+        item = generator.generate_item("weapon", ItemRarity.COMMON, 1)
+        assert item is not None
+        assert item.rarity == ItemRarity.COMMON
+        assert item.is_generated
+        assert len(item.applied_affixes) == 0
+        # Common items have no generated name
+        assert item.generated_name == item.name
+
+    def test_generate_rare_item(self):
+        """Test generating a rare item (1 affix)."""
+        generator = get_item_generator()
+
+        item = generator.generate_item("weapon", ItemRarity.RARE, 1)
+        assert item is not None
+        assert item.rarity == ItemRarity.RARE
+        assert item.is_generated
+        assert len(item.applied_affixes) == 1
+        assert item.generated_name != item.name
+
+    def test_generate_epic_item(self):
+        """Test generating an epic item (2 affixes)."""
+        generator = get_item_generator()
+
+        item = generator.generate_item("weapon", ItemRarity.EPIC, 1)
+        assert item is not None
+        assert item.rarity == ItemRarity.EPIC
+        assert item.is_generated
+        assert len(item.applied_affixes) == 2
+
+    def test_generate_legendary_item(self):
+        """Test generating a legendary item (3 affixes)."""
+        generator = get_item_generator()
+
+        item = generator.generate_item("weapon", ItemRarity.LEGENDARY, 5)
+        assert item is not None
+        assert item.rarity == ItemRarity.LEGENDARY
+        assert item.is_generated
+        assert len(item.applied_affixes) == 3
+
+    def test_generated_name_format(self):
+        """Test that generated names follow the expected format."""
+        generator = get_item_generator()
+
+        # Generate multiple items and check name patterns
+        for _ in range(10):
+            item = generator.generate_item("weapon", ItemRarity.EPIC, 1)
+            if item:
+                name = item.get_display_name()
+                # EPIC should have both prefix and suffix (typically)
+                # Name should contain the base item name
+                assert item.name in name or item.base_template_id in name.lower()
+
+    def test_stat_combination(self):
+        """Test that affix stats are properly combined."""
+        generator = get_item_generator()
+
+        # Generate items and verify stat bonuses are present
+        for _ in range(5):
+            item = generator.generate_item("weapon", ItemRarity.RARE, 1)
+            if item and item.applied_affixes:
+                # Item should have some stat modifications
+                # Either stat_bonuses, damage_bonus, or elemental properties
+                has_stats = (
+                    bool(item.stat_bonuses) or
+                    item.damage > 0 or
+                    item.elemental_ratio > 0
+                )
+                assert has_stats
+
+    def test_generate_armor(self):
+        """Test generating armor items."""
+        generator = get_item_generator()
+
+        item = generator.generate_item("armor", ItemRarity.RARE, 1)
+        assert item is not None
+        assert item.item_type == ItemType.ARMOR
+        assert item.defense > 0 or item.resistance > 0
+
+    def test_generate_loot_drop(self):
+        """Test random loot drop generation."""
+        generator = get_item_generator()
+
+        # Generate multiple drops to test randomness
+        rarities_seen = set()
+        for _ in range(50):
+            item = generator.generate_loot_drop(5, luck_stat=8)
+            if item:
+                rarities_seen.add(item.rarity)
+
+        # Should see at least common and uncommon
+        assert ItemRarity.COMMON in rarities_seen or ItemRarity.UNCOMMON in rarities_seen
+
+    def test_luck_affects_rarity(self):
+        """Test that higher luck increases rare drops."""
+        generator = get_item_generator()
+
+        # This is a statistical test - higher luck should trend toward better rarity
+        low_luck_rares = 0
+        high_luck_rares = 0
+
+        for _ in range(100):
+            low_luck_item = generator.generate_loot_drop(5, luck_stat=1)
+            high_luck_item = generator.generate_loot_drop(5, luck_stat=20)
+
+            if low_luck_item and low_luck_item.rarity in [ItemRarity.RARE, ItemRarity.EPIC, ItemRarity.LEGENDARY]:
+                low_luck_rares += 1
+            if high_luck_item and high_luck_item.rarity in [ItemRarity.RARE, ItemRarity.EPIC, ItemRarity.LEGENDARY]:
+                high_luck_rares += 1
+
+        # High luck should generally produce more rare+ items
+        # (This may occasionally fail due to randomness, but should pass most of the time)
+        # We're just checking the trend, not a strict guarantee
+        # logger.info(f"Low luck rares: {low_luck_rares}, High luck rares: {high_luck_rares}")
+
+
+class TestNameGeneration:
+    """Tests specifically for item name generation."""
+
+    def test_prefix_only_name(self):
+        """Test name with only a prefix."""
+        generator = get_item_generator()
+
+        # Create mock affixes
+        prefix = Affix(
+            affix_id="flaming",
+            name="Flaming",
+            affix_type=AffixType.PREFIX,
+            tier=AffixTier.MINOR,
+        )
+
+        name = generator._build_name("Dagger", [prefix], [])
+        assert name == "Flaming Dagger"
+
+    def test_suffix_only_name(self):
+        """Test name with only a suffix."""
+        generator = get_item_generator()
+
+        suffix = Affix(
+            affix_id="of_strength",
+            name="of Strength",
+            affix_type=AffixType.SUFFIX,
+            tier=AffixTier.MINOR,
+        )
+
+        name = generator._build_name("Dagger", [], [suffix])
+        assert name == "Dagger of Strength"
+
+    def test_full_name(self):
+        """Test name with prefix and suffix."""
+        generator = get_item_generator()
+
+        prefix = Affix(
+            affix_id="flaming",
+            name="Flaming",
+            affix_type=AffixType.PREFIX,
+            tier=AffixTier.MINOR,
+        )
+        suffix = Affix(
+            affix_id="of_strength",
+            name="of Strength",
+            affix_type=AffixType.SUFFIX,
+            tier=AffixTier.MINOR,
+        )
+
+        name = generator._build_name("Dagger", [prefix], [suffix])
+        assert name == "Flaming Dagger of Strength"
+
+    def test_multiple_prefixes(self):
+        """Test name with multiple prefixes."""
+        generator = get_item_generator()
+
+        prefix1 = Affix(
+            affix_id="flaming",
+            name="Flaming",
+            affix_type=AffixType.PREFIX,
+            tier=AffixTier.MINOR,
+        )
+        prefix2 = Affix(
+            affix_id="sharp",
+            name="Sharp",
+            affix_type=AffixType.PREFIX,
+            tier=AffixTier.MINOR,
+        )
+
+        name = generator._build_name("Dagger", [prefix1, prefix2], [])
+        assert name == "Flaming Sharp Dagger"
+
+
+class TestStatCombination:
+    """Tests for combining affix stats."""
+
+    def test_combine_stat_bonuses(self):
+        """Test combining stat bonuses from multiple affixes."""
+        generator = get_item_generator()
+
+        affix1 = Affix(
+            affix_id="test1",
+            name="Test1",
+            affix_type=AffixType.PREFIX,
+            tier=AffixTier.MINOR,
+            stat_bonuses={"strength": 2, "constitution": 1},
+        )
+        affix2 = Affix(
+            affix_id="test2",
+            name="Test2",
+            affix_type=AffixType.SUFFIX,
+            tier=AffixTier.MINOR,
+            stat_bonuses={"strength": 3, "dexterity": 2},
+        )
+
+        combined = generator._combine_affix_stats([affix1, affix2])
+
+        assert combined["stat_bonuses"]["strength"] == 5
+        assert combined["stat_bonuses"]["constitution"] == 1
+        assert combined["stat_bonuses"]["dexterity"] == 2
+
+    def test_combine_damage_bonuses(self):
+        """Test combining damage bonuses."""
+        generator = get_item_generator()
+
+        affix1 = Affix(
+            affix_id="sharp",
+            name="Sharp",
+            affix_type=AffixType.PREFIX,
+            tier=AffixTier.MINOR,
+            damage_bonus=3,
+        )
+        affix2 = Affix(
+            affix_id="keen",
+            name="Keen",
+            affix_type=AffixType.PREFIX,
+            tier=AffixTier.MAJOR,
+            damage_bonus=5,
+        )
+
+        combined = generator._combine_affix_stats([affix1, affix2])
+
+        assert combined["damage_bonus"] == 8
+
+    def test_combine_crit_bonuses(self):
+        """Test combining crit chance and multiplier bonuses."""
+        generator = get_item_generator()
+
+        affix1 = Affix(
+            affix_id="sharp",
+            name="Sharp",
+            affix_type=AffixType.PREFIX,
+            tier=AffixTier.MINOR,
+            crit_chance_bonus=0.02,
+        )
+        affix2 = Affix(
+            affix_id="keen",
+            name="Keen",
+            affix_type=AffixType.PREFIX,
+            tier=AffixTier.MAJOR,
+            crit_chance_bonus=0.04,
+            crit_multiplier_bonus=0.5,
+        )
+
+        combined = generator._combine_affix_stats([affix1, affix2])
+
+        assert combined["crit_chance_bonus"] == pytest.approx(0.06)
+        assert combined["crit_multiplier_bonus"] == pytest.approx(0.5)

api/tests/test_items.py

@@ -0,0 +1,387 @@
+"""
+Unit tests for Item dataclass and ItemRarity enum.
+
+Tests item creation, rarity, type checking, and serialization.
+"""
+
+import pytest
+from app.models.items import Item
+from app.models.enums import ItemType, ItemRarity, DamageType
+
+
+class TestItemRarityEnum:
+    """Tests for ItemRarity enum."""
+
+    def test_rarity_values(self):
+        """Test all rarity values exist and have correct string values."""
+        assert ItemRarity.COMMON.value == "common"
+        assert ItemRarity.UNCOMMON.value == "uncommon"
+        assert ItemRarity.RARE.value == "rare"
+        assert ItemRarity.EPIC.value == "epic"
+        assert ItemRarity.LEGENDARY.value == "legendary"
+
+    def test_rarity_from_string(self):
+        """Test creating rarity from string value."""
+        assert ItemRarity("common") == ItemRarity.COMMON
+        assert ItemRarity("uncommon") == ItemRarity.UNCOMMON
+        assert ItemRarity("rare") == ItemRarity.RARE
+        assert ItemRarity("epic") == ItemRarity.EPIC
+        assert ItemRarity("legendary") == ItemRarity.LEGENDARY
+
+    def test_rarity_count(self):
+        """Test that there are exactly 5 rarity tiers."""
+        assert len(ItemRarity) == 5
+
+
+class TestItemCreation:
+    """Tests for creating Item instances."""
+
+    def test_create_basic_item(self):
+        """Test creating a basic item with minimal fields."""
+        item = Item(
+            item_id="test_item",
+            name="Test Item",
+            item_type=ItemType.QUEST_ITEM,
+        )
+
+        assert item.item_id == "test_item"
+        assert item.name == "Test Item"
+        assert item.item_type == ItemType.QUEST_ITEM
+        assert item.rarity == ItemRarity.COMMON  # Default
+        assert item.description == ""
+        assert item.value == 0
+        assert item.is_tradeable == True
+
+    def test_item_default_rarity_is_common(self):
+        """Test that items default to COMMON rarity."""
+        item = Item(
+            item_id="sword_1",
+            name="Iron Sword",
+            item_type=ItemType.WEAPON,
+        )
+
+        assert item.rarity == ItemRarity.COMMON
+
+    def test_create_item_with_rarity(self):
+        """Test creating items with different rarity levels."""
+        uncommon = Item(
+            item_id="sword_2",
+            name="Steel Sword",
+            item_type=ItemType.WEAPON,
+            rarity=ItemRarity.UNCOMMON,
+        )
+        assert uncommon.rarity == ItemRarity.UNCOMMON
+
+        rare = Item(
+            item_id="sword_3",
+            name="Mithril Sword",
+            item_type=ItemType.WEAPON,
+            rarity=ItemRarity.RARE,
+        )
+        assert rare.rarity == ItemRarity.RARE
+
+        epic = Item(
+            item_id="sword_4",
+            name="Dragon Sword",
+            item_type=ItemType.WEAPON,
+            rarity=ItemRarity.EPIC,
+        )
+        assert epic.rarity == ItemRarity.EPIC
+
+        legendary = Item(
+            item_id="sword_5",
+            name="Excalibur",
+            item_type=ItemType.WEAPON,
+            rarity=ItemRarity.LEGENDARY,
+        )
+        assert legendary.rarity == ItemRarity.LEGENDARY
+
+    def test_create_weapon(self):
+        """Test creating a weapon with all weapon-specific fields."""
+        weapon = Item(
+            item_id="fire_sword",
+            name="Flame Blade",
+            item_type=ItemType.WEAPON,
+            rarity=ItemRarity.RARE,
+            description="A sword wreathed in flames.",
+            value=500,
+            damage=25,
+            damage_type=DamageType.PHYSICAL,
+            crit_chance=0.15,
+            crit_multiplier=2.5,
+            elemental_damage_type=DamageType.FIRE,
+            physical_ratio=0.7,
+            elemental_ratio=0.3,
+        )
+
+        assert weapon.is_weapon() == True
+        assert weapon.is_elemental_weapon() == True
+        assert weapon.damage == 25
+        assert weapon.crit_chance == 0.15
+        assert weapon.crit_multiplier == 2.5
+        assert weapon.elemental_damage_type == DamageType.FIRE
+        assert weapon.physical_ratio == 0.7
+        assert weapon.elemental_ratio == 0.3
+
+    def test_create_armor(self):
+        """Test creating armor with defense/resistance."""
+        armor = Item(
+            item_id="plate_armor",
+            name="Steel Plate Armor",
+            item_type=ItemType.ARMOR,
+            rarity=ItemRarity.UNCOMMON,
+            description="Heavy steel armor.",
+            value=300,
+            defense=15,
+            resistance=5,
+        )
+
+        assert armor.is_armor() == True
+        assert armor.defense == 15
+        assert armor.resistance == 5
+
+    def test_create_consumable(self):
+        """Test creating a consumable item."""
+        potion = Item(
+            item_id="health_potion",
+            name="Health Potion",
+            item_type=ItemType.CONSUMABLE,
+            rarity=ItemRarity.COMMON,
+            description="Restores 50 HP.",
+            value=25,
+        )
+
+        assert potion.is_consumable() == True
+        assert potion.is_tradeable == True
+
+
+class TestItemTypeMethods:
+    """Tests for item type checking methods."""
+
+    def test_is_weapon(self):
+        """Test is_weapon() method."""
+        weapon = Item(item_id="w", name="W", item_type=ItemType.WEAPON)
+        armor = Item(item_id="a", name="A", item_type=ItemType.ARMOR)
+
+        assert weapon.is_weapon() == True
+        assert armor.is_weapon() == False
+
+    def test_is_armor(self):
+        """Test is_armor() method."""
+        weapon = Item(item_id="w", name="W", item_type=ItemType.WEAPON)
+        armor = Item(item_id="a", name="A", item_type=ItemType.ARMOR)
+
+        assert armor.is_armor() == True
+        assert weapon.is_armor() == False
+
+    def test_is_consumable(self):
+        """Test is_consumable() method."""
+        consumable = Item(item_id="c", name="C", item_type=ItemType.CONSUMABLE)
+        weapon = Item(item_id="w", name="W", item_type=ItemType.WEAPON)
+
+        assert consumable.is_consumable() == True
+        assert weapon.is_consumable() == False
+
+    def test_is_quest_item(self):
+        """Test is_quest_item() method."""
+        quest = Item(item_id="q", name="Q", item_type=ItemType.QUEST_ITEM)
+        weapon = Item(item_id="w", name="W", item_type=ItemType.WEAPON)
+
+        assert quest.is_quest_item() == True
+        assert weapon.is_quest_item() == False
+
+
+class TestItemSerialization:
+    """Tests for Item serialization and deserialization."""
+
+    def test_to_dict_includes_rarity(self):
+        """Test that to_dict() includes rarity as string."""
+        item = Item(
+            item_id="test",
+            name="Test",
+            item_type=ItemType.WEAPON,
+            rarity=ItemRarity.EPIC,
+            description="Test item",
+        )
+
+        data = item.to_dict()
+
+        assert data["rarity"] == "epic"
+        assert data["item_type"] == "weapon"
+
+    def test_from_dict_parses_rarity(self):
+        """Test that from_dict() parses rarity correctly."""
+        data = {
+            "item_id": "test",
+            "name": "Test",
+            "item_type": "weapon",
+            "rarity": "legendary",
+            "description": "Test item",
+        }
+
+        item = Item.from_dict(data)
+
+        assert item.rarity == ItemRarity.LEGENDARY
+        assert item.item_type == ItemType.WEAPON
+
+    def test_from_dict_defaults_to_common_rarity(self):
+        """Test that from_dict() defaults to COMMON if rarity missing."""
+        data = {
+            "item_id": "test",
+            "name": "Test",
+            "item_type": "weapon",
+            "description": "Test item",
+            # No rarity field
+        }
+
+        item = Item.from_dict(data)
+
+        assert item.rarity == ItemRarity.COMMON
+
+    def test_round_trip_serialization(self):
+        """Test serialization and deserialization preserve all data."""
+        original = Item(
+            item_id="flame_sword",
+            name="Flame Blade",
+            item_type=ItemType.WEAPON,
+            rarity=ItemRarity.RARE,
+            description="A fiery blade.",
+            value=500,
+            damage=25,
+            damage_type=DamageType.PHYSICAL,
+            crit_chance=0.12,
+            crit_multiplier=2.5,
+            elemental_damage_type=DamageType.FIRE,
+            physical_ratio=0.7,
+            elemental_ratio=0.3,
+            defense=0,
+            resistance=0,
+            required_level=5,
+            stat_bonuses={"strength": 3},
+        )
+
+        # Serialize then deserialize
+        data = original.to_dict()
+        restored = Item.from_dict(data)
+
+        assert restored.item_id == original.item_id
+        assert restored.name == original.name
+        assert restored.item_type == original.item_type
+        assert restored.rarity == original.rarity
+        assert restored.description == original.description
+        assert restored.value == original.value
+        assert restored.damage == original.damage
+        assert restored.damage_type == original.damage_type
+        assert restored.crit_chance == original.crit_chance
+        assert restored.crit_multiplier == original.crit_multiplier
+        assert restored.elemental_damage_type == original.elemental_damage_type
+        assert restored.physical_ratio == original.physical_ratio
+        assert restored.elemental_ratio == original.elemental_ratio
+        assert restored.required_level == original.required_level
+        assert restored.stat_bonuses == original.stat_bonuses
+
+    def test_round_trip_all_rarities(self):
+        """Test round-trip serialization for all rarity levels."""
+        for rarity in ItemRarity:
+            original = Item(
+                item_id=f"item_{rarity.value}",
+                name=f"{rarity.value.title()} Item",
+                item_type=ItemType.CONSUMABLE,
+                rarity=rarity,
+            )
+
+            data = original.to_dict()
+            restored = Item.from_dict(data)
+
+            assert restored.rarity == rarity
+
+
+class TestItemEquippability:
+    """Tests for item equip requirements."""
+
+    def test_can_equip_level_requirement(self):
+        """Test level requirement checking."""
+        item = Item(
+            item_id="high_level_sword",
+            name="Epic Sword",
+            item_type=ItemType.WEAPON,
+            required_level=10,
+        )
+
+        assert item.can_equip(character_level=5) == False
+        assert item.can_equip(character_level=10) == True
+        assert item.can_equip(character_level=15) == True
+
+    def test_can_equip_class_requirement(self):
+        """Test class requirement checking."""
+        item = Item(
+            item_id="mage_staff",
+            name="Mage Staff",
+            item_type=ItemType.WEAPON,
+            required_class="mage",
+        )
+
+        assert item.can_equip(character_level=1, character_class="warrior") == False
+        assert item.can_equip(character_level=1, character_class="mage") == True
+
+
+class TestItemStatBonuses:
+    """Tests for item stat bonus methods."""
+
+    def test_get_total_stat_bonus(self):
+        """Test getting stat bonuses from items."""
+        item = Item(
+            item_id="ring_of_power",
+            name="Ring of Power",
+            item_type=ItemType.ARMOR,
+            stat_bonuses={"strength": 5, "constitution": 3},
+        )
+
+        assert item.get_total_stat_bonus("strength") == 5
+        assert item.get_total_stat_bonus("constitution") == 3
+        assert item.get_total_stat_bonus("dexterity") == 0  # Not in bonuses
+
+
+class TestItemRepr:
+    """Tests for item string representation."""
+
+    def test_weapon_repr(self):
+        """Test weapon __repr__ output."""
+        weapon = Item(
+            item_id="sword",
+            name="Iron Sword",
+            item_type=ItemType.WEAPON,
+            damage=10,
+            value=50,
+        )
+
+        repr_str = repr(weapon)
+        assert "Iron Sword" in repr_str
+        assert "weapon" in repr_str
+
+    def test_armor_repr(self):
+        """Test armor __repr__ output."""
+        armor = Item(
+            item_id="armor",
+            name="Leather Armor",
+            item_type=ItemType.ARMOR,
+            defense=5,
+            value=30,
+        )
+
+        repr_str = repr(armor)
+        assert "Leather Armor" in repr_str
+        assert "armor" in repr_str
+
+    def test_consumable_repr(self):
+        """Test consumable __repr__ output."""
+        potion = Item(
+            item_id="potion",
+            name="Health Potion",
+            item_type=ItemType.CONSUMABLE,
+            value=10,
+        )
+
+        repr_str = repr(potion)
+        assert "Health Potion" in repr_str
+        assert "consumable" in repr_str

api/tests/test_loot_entry.py

@@ -0,0 +1,224 @@
+"""
+Tests for LootEntry model with hybrid loot support.
+
+Tests the extended LootEntry dataclass that supports both static
+and procedural loot types with backward compatibility.
+"""
+
+import pytest
+
+from app.models.enemy import LootEntry, LootType
+
+
+class TestLootEntryBackwardCompatibility:
+    """Test that existing YAML format still works."""
+
+    def test_from_dict_defaults_to_static(self):
+        """Old-style entries without loot_type should default to STATIC."""
+        entry_data = {
+            "item_id": "rusty_dagger",
+            "drop_chance": 0.15,
+        }
+        entry = LootEntry.from_dict(entry_data)
+
+        assert entry.loot_type == LootType.STATIC
+        assert entry.item_id == "rusty_dagger"
+        assert entry.drop_chance == 0.15
+        assert entry.quantity_min == 1
+        assert entry.quantity_max == 1
+
+    def test_from_dict_with_all_old_fields(self):
+        """Test entry with all old-style fields."""
+        entry_data = {
+            "item_id": "gold_coin",
+            "drop_chance": 0.50,
+            "quantity_min": 1,
+            "quantity_max": 3,
+        }
+        entry = LootEntry.from_dict(entry_data)
+
+        assert entry.loot_type == LootType.STATIC
+        assert entry.item_id == "gold_coin"
+        assert entry.drop_chance == 0.50
+        assert entry.quantity_min == 1
+        assert entry.quantity_max == 3
+
+    def test_to_dict_includes_loot_type(self):
+        """Serialization should include loot_type."""
+        entry = LootEntry(
+            loot_type=LootType.STATIC,
+            item_id="health_potion",
+            drop_chance=0.2
+        )
+        data = entry.to_dict()
+
+        assert data["loot_type"] == "static"
+        assert data["item_id"] == "health_potion"
+        assert data["drop_chance"] == 0.2
+
+
+class TestLootEntryStaticType:
+    """Test static loot entries."""
+
+    def test_static_entry_creation(self):
+        """Test creating a static loot entry."""
+        entry = LootEntry(
+            loot_type=LootType.STATIC,
+            item_id="goblin_ear",
+            drop_chance=0.60,
+            quantity_min=1,
+            quantity_max=2
+        )
+
+        assert entry.loot_type == LootType.STATIC
+        assert entry.item_id == "goblin_ear"
+        assert entry.item_type is None
+        assert entry.rarity_bonus == 0.0
+
+    def test_static_from_dict_explicit(self):
+        """Test parsing explicit static entry."""
+        entry_data = {
+            "loot_type": "static",
+            "item_id": "health_potion_small",
+            "drop_chance": 0.10,
+        }
+        entry = LootEntry.from_dict(entry_data)
+
+        assert entry.loot_type == LootType.STATIC
+        assert entry.item_id == "health_potion_small"
+
+    def test_static_to_dict_omits_procedural_fields(self):
+        """Static entries should omit procedural-only fields."""
+        entry = LootEntry(
+            loot_type=LootType.STATIC,
+            item_id="gold_coin",
+            drop_chance=0.5
+        )
+        data = entry.to_dict()
+
+        assert "item_id" in data
+        assert "item_type" not in data
+        assert "rarity_bonus" not in data
+
+
+class TestLootEntryProceduralType:
+    """Test procedural loot entries."""
+
+    def test_procedural_entry_creation(self):
+        """Test creating a procedural loot entry."""
+        entry = LootEntry(
+            loot_type=LootType.PROCEDURAL,
+            item_type="weapon",
+            drop_chance=0.10,
+            rarity_bonus=0.15
+        )
+
+        assert entry.loot_type == LootType.PROCEDURAL
+        assert entry.item_type == "weapon"
+        assert entry.rarity_bonus == 0.15
+        assert entry.item_id is None
+
+    def test_procedural_from_dict(self):
+        """Test parsing procedural entry from dict."""
+        entry_data = {
+            "loot_type": "procedural",
+            "item_type": "armor",
+            "drop_chance": 0.08,
+            "rarity_bonus": 0.05,
+        }
+        entry = LootEntry.from_dict(entry_data)
+
+        assert entry.loot_type == LootType.PROCEDURAL
+        assert entry.item_type == "armor"
+        assert entry.drop_chance == 0.08
+        assert entry.rarity_bonus == 0.05
+
+    def test_procedural_to_dict_includes_item_type(self):
+        """Procedural entries should include item_type and rarity_bonus."""
+        entry = LootEntry(
+            loot_type=LootType.PROCEDURAL,
+            item_type="weapon",
+            drop_chance=0.15,
+            rarity_bonus=0.10
+        )
+        data = entry.to_dict()
+
+        assert data["loot_type"] == "procedural"
+        assert data["item_type"] == "weapon"
+        assert data["rarity_bonus"] == 0.10
+        assert "item_id" not in data
+
+    def test_procedural_default_rarity_bonus(self):
+        """Procedural entries default to 0.0 rarity bonus."""
+        entry_data = {
+            "loot_type": "procedural",
+            "item_type": "weapon",
+            "drop_chance": 0.10,
+        }
+        entry = LootEntry.from_dict(entry_data)
+
+        assert entry.rarity_bonus == 0.0
+
+
+class TestLootTypeEnum:
+    """Test LootType enum values."""
+
+    def test_static_value(self):
+        """Test STATIC enum value."""
+        assert LootType.STATIC.value == "static"
+
+    def test_procedural_value(self):
+        """Test PROCEDURAL enum value."""
+        assert LootType.PROCEDURAL.value == "procedural"
+
+    def test_from_string(self):
+        """Test creating enum from string."""
+        assert LootType("static") == LootType.STATIC
+        assert LootType("procedural") == LootType.PROCEDURAL
+
+    def test_invalid_string_raises(self):
+        """Test that invalid string raises ValueError."""
+        with pytest.raises(ValueError):
+            LootType("invalid")
+
+
+class TestLootEntryRoundTrip:
+    """Test serialization/deserialization round trips."""
+
+    def test_static_round_trip(self):
+        """Static entry should survive round trip."""
+        original = LootEntry(
+            loot_type=LootType.STATIC,
+            item_id="health_potion_small",
+            drop_chance=0.15,
+            quantity_min=1,
+            quantity_max=2
+        )
+
+        data = original.to_dict()
+        restored = LootEntry.from_dict(data)
+
+        assert restored.loot_type == original.loot_type
+        assert restored.item_id == original.item_id
+        assert restored.drop_chance == original.drop_chance
+        assert restored.quantity_min == original.quantity_min
+        assert restored.quantity_max == original.quantity_max
+
+    def test_procedural_round_trip(self):
+        """Procedural entry should survive round trip."""
+        original = LootEntry(
+            loot_type=LootType.PROCEDURAL,
+            item_type="weapon",
+            drop_chance=0.25,
+            rarity_bonus=0.15,
+            quantity_min=1,
+            quantity_max=1
+        )
+
+        data = original.to_dict()
+        restored = LootEntry.from_dict(data)
+
+        assert restored.loot_type == original.loot_type
+        assert restored.item_type == original.item_type
+        assert restored.drop_chance == original.drop_chance
+        assert restored.rarity_bonus == original.rarity_bonus

api/tests/test_session_service.py

@@ -18,8 +18,10 @@ from app.services.session_service import (
     SessionNotFound,
     SessionLimitExceeded,
     SessionValidationError,
-    MAX_ACTIVE_SESSIONS,
 )
+
+# Session limits are now tier-based, using a test default
+MAX_ACTIVE_SESSIONS_TEST = 3
 from app.models.session import GameSession, GameState, ConversationEntry
 from app.models.enums import SessionStatus, SessionType, LocationType
 from app.models.character import Character
@@ -116,7 +118,7 @@ class TestSessionServiceCreation:
     def test_create_solo_session_limit_exceeded(self, mock_db, mock_appwrite, mock_character_service, sample_character):
         """Test session creation fails when limit exceeded."""
         mock_character_service.get_character.return_value = sample_character
-        mock_db.count_documents.return_value = MAX_ACTIVE_SESSIONS
+        mock_db.count_documents.return_value = MAX_ACTIVE_SESSIONS_TEST
 
         service = SessionService()
         with pytest.raises(SessionLimitExceeded):

api/tests/test_static_item_loader.py

@@ -0,0 +1,194 @@
+"""
+Tests for StaticItemLoader service.
+
+Tests the service that loads predefined items (consumables, materials)
+from YAML files for use in loot tables.
+"""
+
+import pytest
+from pathlib import Path
+
+from app.services.static_item_loader import StaticItemLoader, get_static_item_loader
+from app.models.enums import ItemType, ItemRarity
+
+
+class TestStaticItemLoaderInitialization:
+    """Test service initialization."""
+
+    def test_init_with_default_path(self):
+        """Service should initialize with default data path."""
+        loader = StaticItemLoader()
+        assert loader.data_dir.exists() or not loader._loaded
+
+    def test_init_with_custom_path(self, tmp_path):
+        """Service should accept custom data path."""
+        loader = StaticItemLoader(data_dir=str(tmp_path))
+        assert loader.data_dir == tmp_path
+
+    def test_singleton_returns_same_instance(self):
+        """get_static_item_loader should return singleton."""
+        loader1 = get_static_item_loader()
+        loader2 = get_static_item_loader()
+        assert loader1 is loader2
+
+
+class TestStaticItemLoaderLoading:
+    """Test YAML loading functionality."""
+
+    def test_loads_consumables(self):
+        """Should load consumable items from YAML."""
+        loader = get_static_item_loader()
+
+        # Check that health potion exists
+        assert loader.has_item("health_potion_small")
+        assert loader.has_item("health_potion_medium")
+
+    def test_loads_materials(self):
+        """Should load material items from YAML."""
+        loader = get_static_item_loader()
+
+        # Check that materials exist
+        assert loader.has_item("goblin_ear")
+        assert loader.has_item("wolf_pelt")
+
+    def test_get_all_item_ids_returns_list(self):
+        """get_all_item_ids should return list of item IDs."""
+        loader = get_static_item_loader()
+        item_ids = loader.get_all_item_ids()
+
+        assert isinstance(item_ids, list)
+        assert len(item_ids) > 0
+        assert "health_potion_small" in item_ids
+
+    def test_has_item_returns_false_for_missing(self):
+        """has_item should return False for non-existent items."""
+        loader = get_static_item_loader()
+        assert not loader.has_item("nonexistent_item_xyz")
+
+
+class TestStaticItemLoaderGetItem:
+    """Test item retrieval."""
+
+    def test_get_item_returns_item_object(self):
+        """get_item should return an Item instance."""
+        loader = get_static_item_loader()
+        item = loader.get_item("health_potion_small")
+
+        assert item is not None
+        assert item.name == "Small Health Potion"
+        assert item.item_type == ItemType.CONSUMABLE
+        assert item.rarity == ItemRarity.COMMON
+
+    def test_get_item_has_unique_id(self):
+        """Each call should create item with unique ID."""
+        loader = get_static_item_loader()
+
+        item1 = loader.get_item("health_potion_small")
+        item2 = loader.get_item("health_potion_small")
+
+        assert item1.item_id != item2.item_id
+        assert "health_potion_small" in item1.item_id
+        assert "health_potion_small" in item2.item_id
+
+    def test_get_item_returns_none_for_missing(self):
+        """get_item should return None for non-existent items."""
+        loader = get_static_item_loader()
+        item = loader.get_item("nonexistent_item_xyz")
+
+        assert item is None
+
+    def test_get_item_consumable_has_effects(self):
+        """Consumable items should have effects_on_use."""
+        loader = get_static_item_loader()
+        item = loader.get_item("health_potion_small")
+
+        assert len(item.effects_on_use) > 0
+        effect = item.effects_on_use[0]
+        assert effect.name == "Minor Healing"
+        assert effect.power > 0
+
+    def test_get_item_quest_item_type(self):
+        """Quest items should have correct type."""
+        loader = get_static_item_loader()
+        item = loader.get_item("goblin_ear")
+
+        assert item is not None
+        assert item.item_type == ItemType.QUEST_ITEM
+        assert item.rarity == ItemRarity.COMMON
+
+    def test_get_item_has_value(self):
+        """Items should have value set."""
+        loader = get_static_item_loader()
+        item = loader.get_item("health_potion_small")
+
+        assert item.value > 0
+
+    def test_get_item_is_tradeable(self):
+        """Items should default to tradeable."""
+        loader = get_static_item_loader()
+        item = loader.get_item("goblin_ear")
+
+        assert item.is_tradeable is True
+
+
+class TestStaticItemLoaderVariousItems:
+    """Test loading various item types."""
+
+    def test_medium_health_potion(self):
+        """Test medium health potion properties."""
+        loader = get_static_item_loader()
+        item = loader.get_item("health_potion_medium")
+
+        assert item is not None
+        assert item.rarity == ItemRarity.UNCOMMON
+        assert item.value > 25  # More expensive than small
+
+    def test_large_health_potion(self):
+        """Test large health potion properties."""
+        loader = get_static_item_loader()
+        item = loader.get_item("health_potion_large")
+
+        assert item is not None
+        assert item.rarity == ItemRarity.RARE
+
+    def test_chieftain_token_rarity(self):
+        """Test that chieftain token is rare."""
+        loader = get_static_item_loader()
+        item = loader.get_item("goblin_chieftain_token")
+
+        assert item is not None
+        assert item.rarity == ItemRarity.RARE
+
+    def test_elixir_has_buff_effect(self):
+        """Test that elixirs have buff effects."""
+        loader = get_static_item_loader()
+        item = loader.get_item("elixir_of_strength")
+
+        if item:  # Only test if item exists
+            assert len(item.effects_on_use) > 0
+
+
+class TestStaticItemLoaderCache:
+    """Test caching behavior."""
+
+    def test_clear_cache(self):
+        """clear_cache should reset loaded state."""
+        loader = StaticItemLoader()
+
+        # Trigger loading
+        loader._ensure_loaded()
+        assert loader._loaded is True
+
+        # Clear cache
+        loader.clear_cache()
+        assert loader._loaded is False
+        assert len(loader._cache) == 0
+
+    def test_lazy_loading(self):
+        """Items should be loaded lazily on first access."""
+        loader = StaticItemLoader()
+        assert loader._loaded is False
+
+        # Access triggers loading
+        _ = loader.has_item("health_potion_small")
+        assert loader._loaded is True

api/tests/test_stats.py

@@ -196,3 +196,186 @@ def test_stats_repr():
     assert "INT=10" in repr_str
     assert "HP=" in repr_str
     assert "MP=" in repr_str
+
+
+# =============================================================================
+# LUK Computed Properties (Combat System Integration)
+# =============================================================================
+
+def test_crit_bonus_calculation():
+    """Test crit bonus calculation: luck * 0.5%."""
+    stats = Stats(luck=8)
+    assert stats.crit_bonus == pytest.approx(0.04, abs=0.001)  # 4%
+
+    stats = Stats(luck=12)
+    assert stats.crit_bonus == pytest.approx(0.06, abs=0.001)  # 6%
+
+    stats = Stats(luck=0)
+    assert stats.crit_bonus == pytest.approx(0.0, abs=0.001)  # 0%
+
+
+def test_hit_bonus_calculation():
+    """Test hit bonus (miss reduction): luck * 0.5%."""
+    stats = Stats(luck=8)
+    assert stats.hit_bonus == pytest.approx(0.04, abs=0.001)  # 4%
+
+    stats = Stats(luck=12)
+    assert stats.hit_bonus == pytest.approx(0.06, abs=0.001)  # 6%
+
+    stats = Stats(luck=20)
+    assert stats.hit_bonus == pytest.approx(0.10, abs=0.001)  # 10%
+
+
+def test_lucky_roll_chance_calculation():
+    """Test lucky roll chance: 5% + (luck * 0.25%)."""
+    stats = Stats(luck=8)
+    # 5% + (8 * 0.25%) = 5% + 2% = 7%
+    assert stats.lucky_roll_chance == pytest.approx(0.07, abs=0.001)
+
+    stats = Stats(luck=12)
+    # 5% + (12 * 0.25%) = 5% + 3% = 8%
+    assert stats.lucky_roll_chance == pytest.approx(0.08, abs=0.001)
+
+    stats = Stats(luck=0)
+    # 5% + (0 * 0.25%) = 5%
+    assert stats.lucky_roll_chance == pytest.approx(0.05, abs=0.001)
+
+
+def test_repr_includes_combat_bonuses():
+    """Test that repr includes LUK-based combat bonuses."""
+    stats = Stats(luck=10)
+    repr_str = repr(stats)
+
+    assert "CRIT_BONUS=" in repr_str
+    assert "HIT_BONUS=" in repr_str
+
+
+# =============================================================================
+# Equipment Bonus Fields (Task 2.5)
+# =============================================================================
+
+def test_bonus_fields_default_to_zero():
+    """Test that equipment bonus fields default to zero."""
+    stats = Stats()
+
+    assert stats.damage_bonus == 0
+    assert stats.defense_bonus == 0
+    assert stats.resistance_bonus == 0
+
+
+def test_damage_property_with_no_bonus():
+    """Test damage calculation: int(strength * 0.75) + damage_bonus with no bonus."""
+    stats = Stats(strength=10)
+    # int(10 * 0.75) = 7, no bonus
+    assert stats.damage == 7
+
+    stats = Stats(strength=14)
+    # int(14 * 0.75) = 10, no bonus
+    assert stats.damage == 10
+
+
+def test_damage_property_with_bonus():
+    """Test damage calculation includes damage_bonus from weapons."""
+    stats = Stats(strength=10, damage_bonus=15)
+    # int(10 * 0.75) + 15 = 7 + 15 = 22
+    assert stats.damage == 22
+
+    stats = Stats(strength=14, damage_bonus=8)
+    # int(14 * 0.75) + 8 = 10 + 8 = 18
+    assert stats.damage == 18
+
+
+def test_defense_property_with_bonus():
+    """Test defense calculation includes defense_bonus from armor."""
+    stats = Stats(constitution=10, defense_bonus=10)
+    # (10 // 2) + 10 = 5 + 10 = 15
+    assert stats.defense == 15
+
+    stats = Stats(constitution=20, defense_bonus=5)
+    # (20 // 2) + 5 = 10 + 5 = 15
+    assert stats.defense == 15
+
+
+def test_resistance_property_with_bonus():
+    """Test resistance calculation includes resistance_bonus from armor."""
+    stats = Stats(wisdom=10, resistance_bonus=8)
+    # (10 // 2) + 8 = 5 + 8 = 13
+    assert stats.resistance == 13
+
+    stats = Stats(wisdom=14, resistance_bonus=3)
+    # (14 // 2) + 3 = 7 + 3 = 10
+    assert stats.resistance == 10
+
+
+def test_bonus_fields_serialization():
+    """Test that bonus fields are included in to_dict()."""
+    stats = Stats(
+        strength=15,
+        damage_bonus=12,
+        defense_bonus=8,
+        resistance_bonus=5,
+    )
+
+    data = stats.to_dict()
+
+    assert data["damage_bonus"] == 12
+    assert data["defense_bonus"] == 8
+    assert data["resistance_bonus"] == 5
+
+
+def test_bonus_fields_deserialization():
+    """Test that bonus fields are restored from from_dict()."""
+    data = {
+        "strength": 15,
+        "damage_bonus": 12,
+        "defense_bonus": 8,
+        "resistance_bonus": 5,
+    }
+
+    stats = Stats.from_dict(data)
+
+    assert stats.damage_bonus == 12
+    assert stats.defense_bonus == 8
+    assert stats.resistance_bonus == 5
+
+
+def test_bonus_fields_deserialization_defaults():
+    """Test that missing bonus fields default to zero on deserialization."""
+    data = {
+        "strength": 15,
+        # No bonus fields
+    }
+
+    stats = Stats.from_dict(data)
+
+    assert stats.damage_bonus == 0
+    assert stats.defense_bonus == 0
+    assert stats.resistance_bonus == 0
+
+
+def test_copy_includes_bonus_fields():
+    """Test that copy() preserves bonus fields."""
+    original = Stats(
+        strength=15,
+        damage_bonus=10,
+        defense_bonus=8,
+        resistance_bonus=5,
+    )
+    copy = original.copy()
+
+    assert copy.damage_bonus == 10
+    assert copy.defense_bonus == 8
+    assert copy.resistance_bonus == 5
+
+    # Verify independence
+    copy.damage_bonus = 20
+    assert original.damage_bonus == 10
+    assert copy.damage_bonus == 20
+
+
+def test_repr_includes_damage():
+    """Test that repr includes the damage computed property."""
+    stats = Stats(strength=10, damage_bonus=15)
+    repr_str = repr(stats)
+
+    assert "DMG=" in repr_str

docs/VECTOR_DATABASE_STRATEGY.md

@@ -0,0 +1,481 @@
+# Vector Database Strategy
+
+## Overview
+
+This document outlines the strategy for implementing layered knowledge systems using vector databases to provide NPCs and the Dungeon Master with contextual lore, regional history, and world knowledge.
+
+**Status:** Planning Phase
+**Last Updated:** November 26, 2025
+**Decision:** Use Weaviate for vector database implementation
+
+---
+
+## Knowledge Hierarchy
+
+### Three-Tier Vector Database Structure
+
+1. **World Lore DB** (Global)
+   - Broad historical events, mythology, major kingdoms, legendary figures
+   - Accessible to all NPCs and DM for player questions
+   - Examples: "The Great War 200 years ago", "The origin of magic", "The Five Kingdoms"
+   - **Scope:** Universal knowledge any educated NPC might know
+
+2. **Regional/Town Lore DB** (Location-specific)
+   - Local history, notable events, landmarks, politics, rumors
+   - Current town leadership, recent events, local legends
+   - Trade routes, neighboring settlements, regional conflicts
+   - **Scope:** Knowledge specific to geographic area
+
+3. **NPC Persona** (Individual, YAML-defined)
+   - Personal background, personality, motivations
+   - Specific knowledge based on profession/role
+   - Personal relationships and secrets
+   - **Scope:** Character-specific information (already implemented in `/api/app/data/npcs/*.yaml`)
+
+---
+
+## How Knowledge Layers Work Together
+
+### Contextual Knowledge Layering
+
+When an NPC engages in conversation, build their knowledge context by:
+- **Always include**: NPC persona + their region's lore DB
+- **Conditionally include**: World lore (if the topic seems historical/broad)
+- **Use semantic search**: Query each DB for relevant chunks based on conversation topic
+
+### Example Interaction Flow
+
+**Player asks tavern keeper:** "Tell me about the old ruins north of town"
+
+1. Check NPC persona: "Are ruins mentioned in their background?"
+2. Query Regional DB: "old ruins + north + [town name]"
+3. If no hits, query World Lore DB: "ancient ruins + [region name]"
+4. Combine results with NPC personality filter
+
+**Result:** NPC responds with appropriate lore, or authentically says "I don't know about that" if nothing is found.
+
+---
+
+## Knowledge Boundaries & Authenticity
+
+### NPCs Have Knowledge Limitations Based On:
+
+- **Profession**: Blacksmith knows metallurgy lore, scholar knows history, farmer knows agricultural traditions
+- **Social Status**: Nobles know court politics, commoners know street rumors
+- **Age/Experience**: Elder NPCs might reference events from decades ago
+- **Travel History**: Has this NPC been outside their region?
+
+### Implementation of "I don't know"
+
+Add metadata to vector DB entries:
+- `required_profession: ["scholar", "priest"]`
+- `social_class: ["noble", "merchant"]`
+- `knowledge_type: "academic" | "common" | "secret"`
+- `region_id: "thornhelm"`
+- `time_period: "ancient" | "recent" | "current"`
+
+Filter results before passing to the NPC's AI context, allowing authentic "I haven't heard of that" responses.
+
+---
+
+## Retrieval-Augmented Generation (RAG) Pattern
+
+### Building AI Prompts for NPC Dialogue
+
+```
+[NPC Persona from YAML]
++
+[Top 3-5 relevant chunks from Regional DB based on conversation topic]
++
+[Top 2-3 relevant chunks from World Lore if topic is broad/historical]
++
+[Conversation history from character's npc_interactions]
+→ Feed to Claude with instruction to stay in character and admit ignorance if uncertain
+```
+
+### DM Knowledge vs NPC Knowledge
+
+**DM Mode** (Player talks directly to DM, not through NPC):
+- DM has access to ALL databases without restrictions
+- DM can reveal as much or as little as narratively appropriate
+- DM can generate content not in databases (creative liberty)
+
+**NPC Mode** (Player talks to specific NPC):
+- NPC knowledge filtered by persona/role/location
+- NPC can redirect: "You should ask the town elder about that" or "I've heard scholars at the university know more"
+- Creates natural quest hooks and information-gathering gameplay
+
+---
+
+## Technical Implementation
+
+### Technology Choice: Weaviate
+
+**Reasons for Weaviate:**
+- Self-hosted option for dev/beta
+- Managed cloud service (Weaviate Cloud Services) for production
+- **Same API** for both self-hosted and managed (easy migration)
+- Rich metadata filtering capabilities
+- Multi-tenancy support
+- GraphQL API (fits strong typing preference)
+- Hybrid search (semantic + keyword)
+
+### Storage & Indexing Strategy
+
+**Where Each DB Lives:**
+
+- **World Lore**: Single global vector DB collection
+- **Regional DBs**: One collection with region metadata filtering
+  - Could use Weaviate multi-tenancy for efficient isolation
+  - Lazy-load when character enters region
+  - Cache in Redis for active sessions
+- **NPC Personas**: Remain in YAML (structured data, not semantic search needed)
+
+**Weaviate Collections Structure:**
+
+```
+Collections:
+- WorldLore
+  - Metadata: knowledge_type, time_period, required_profession
+- RegionalLore
+  - Metadata: region_id, knowledge_type, social_class
+- Rumors (optional: dynamic/time-sensitive content)
+  - Metadata: region_id, expiration_date, source_npc
+```
+
+### Semantic Chunk Strategy
+
+Chunk lore content by logical units:
+- **Events**: "The Battle of Thornhelm (Year 1204) - A decisive victory..."
+- **Locations**: "The Abandoned Lighthouse - Once a beacon for traders..."
+- **Figures**: "Lord Varric the Stern - Current ruler of Thornhelm..."
+- **Rumors/Gossip**: "Strange lights have been seen in the forest lately..."
+
+Each chunk gets embedded and stored with rich metadata for filtering.
+
+---
+
+## Development Workflow
+
+### Index-Once Strategy
+
+**Rationale:**
+- Lore is relatively static (updates only during major version releases)
+- Read-heavy workload (perfect for vector DBs)
+- Cost-effective (one-time embedding generation)
+- Allows thorough testing before deployment
+
+### Workflow Phases
+
+**Development:**
+1. Write lore content (YAML/JSON/Markdown)
+2. Run embedding script locally
+3. Upload to local Weaviate instance (Docker)
+4. Test NPC conversations
+5. Iterate on lore content
+
+**Beta/Staging:**
+1. Same self-hosted Weaviate, separate instance
+2. Finalize lore content
+3. Generate production embeddings
+4. Performance testing
+
+**Production:**
+1. Migrate to Weaviate Cloud Services
+2. Upload final embedded lore
+3. Players query read-only
+4. No changes until next major update
+
+### Self-Hosted Development Setup
+
+**Docker Compose Example:**
+
+```yaml
+services:
+  weaviate:
+    image: semitechnologies/weaviate:latest
+    ports:
+      - "8080:8080"
+    environment:
+      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'  # Dev only
+      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
+    volumes:
+      - weaviate_data:/var/lib/weaviate
+```
+
+**Hardware Requirements (Self-Hosted):**
+- RAM: 4-8GB sufficient for beta
+- CPU: Low (no heavy re-indexing)
+- Storage: Minimal (vectors are compact)
+
+---
+
+## Migration Path: Dev → Production
+
+### Zero-Code Migration
+
+1. Export data from self-hosted Weaviate (backup tools)
+2. Create Weaviate Cloud Services cluster
+3. Import data to WCS
+4. Change environment variable: `WEAVIATE_URL`
+5. Deploy code (no code changes required)
+
+**Environment Configuration:**
+
+```yaml
+# /api/config/development.yaml
+weaviate:
+  url: "http://localhost:8080"
+  api_key: null
+
+# /api/config/production.yaml
+weaviate:
+  url: "https://your-cluster.weaviate.network"
+  api_key: "${WEAVIATE_API_KEY}"  # From .env
+```
+
+---
+
+## Embedding Strategy
+
+### One-Time Embedding Generation
+
+Since embeddings are generated once per release, prioritize **quality over cost**.
+
+**Embedding Model Options:**
+
+| Model | Pros | Cons | Recommendation |
+|-------|------|------|----------------|
+| OpenAI `text-embedding-3-large` | High quality, good semantic understanding | Paid per use | **Production** |
+| Cohere Embed v3 | Optimized for search, multilingual | Paid per use | **Production Alternative** |
+| sentence-transformers (OSS) | Free, self-host, fast iteration | Lower quality | **Development/Testing** |
+
+**Recommendation:**
+- **Development:** Use open-source models (iterate faster, zero cost)
+- **Production:** Use OpenAI or Replicate https://replicate.com/beautyyuyanli/multilingual-e5-large (quality matters for player experience)
+
+### Embedding Generation Script
+
+Will be implemented in `/api/scripts/generate_lore_embeddings.py`:
+1. Read lore files (YAML/JSON/Markdown)
+2. Chunk content appropriately
+3. Generate embeddings using chosen model
+4. Upload to Weaviate with metadata
+5. Validate retrieval quality
+
+---
+
+## Content Management
+
+### Lore Content Structure
+
+**Storage Location:** `/api/app/data/lore/`
+
+```
+/api/app/data/lore/
+  world/
+    history.yaml
+    mythology.yaml
+    kingdoms.yaml
+  regions/
+    thornhelm/
+      history.yaml
+      locations.yaml
+      rumors.yaml
+    silverwood/
+      history.yaml
+      locations.yaml
+      rumors.yaml
+```
+
+**Example Lore Entry (YAML):**
+
+```yaml
+- id: "thornhelm_founding"
+  title: "The Founding of Thornhelm"
+  content: |
+    Thornhelm was founded in the year 847 by Lord Theron the Bold,
+    a retired general seeking to establish a frontier town...
+  metadata:
+    region_id: "thornhelm"
+    knowledge_type: "common"
+    time_period: "historical"
+    required_profession: null  # Anyone can know this
+    social_class: null  # All classes
+  tags:
+    - "founding"
+    - "lord-theron"
+    - "history"
+```
+
+### Version Control for Lore Updates
+
+**Complete Re-Index Strategy** (Simplest, recommended):
+1. Delete old collections during maintenance window
+2. Upload new lore with embeddings
+3. Atomic cutover
+4. Works great for infrequent major updates
+
+**Alternative: Versioned Collections** (Overkill for our use case):
+- `WorldLore_v1`, `WorldLore_v2`
+- More overhead, probably unnecessary
+
+---
+
+## Performance & Cost Optimization
+
+### Cost Considerations
+
+**Embedding Generation:**
+- One-time cost per lore chunk
+- Only re-generate during major updates
+- Estimated cost: $X per 1000 chunks (TBD based on model choice)
+
+**Vector Search:**
+- No embedding cost for queries (just retrieval)
+- Self-hosted: Infrastructure cost only
+- Managed (WCS): Pay for storage + queries
+
+**Optimization Strategies:**
+- Pre-compute all embeddings at build time
+- Cache frequently accessed regional DBs in Redis
+- Only search World Lore DB if regional search returns no results (fallback pattern)
+- Use cheaper embedding models for non-critical content
+
+### Retrieval Performance
+
+**Expected Query Times:**
+- Semantic search: < 100ms
+- With metadata filtering: < 150ms
+- Hybrid search: < 200ms
+
+**Caching Strategy:**
+- Cache top N regional lore chunks per active region in Redis
+- TTL: 1 hour (or until session ends)
+- Invalidate on major lore updates
+
+---
+
+## Multiplayer Considerations
+
+### Shared World State
+
+If multiple characters are in the same town talking to NPCs:
+- **Regional DB**: Shared (same lore for everyone)
+- **World DB**: Shared
+- **NPC Interactions**: Character-specific (stored in `character.npc_interactions`)
+
+**Result:** NPCs can reference world events consistently across players while maintaining individual relationships.
+
+---
+
+## Testing Strategy
+
+### Validation Steps
+
+1. **Retrieval Quality Testing**
+   - Does semantic search return relevant lore?
+   - Are metadata filters working correctly?
+   - Do NPCs find appropriate information?
+
+2. **NPC Knowledge Boundaries**
+   - Can a farmer access academic knowledge? (Should be filtered out)
+   - Do profession filters work as expected?
+   - Do NPCs authentically say "I don't know" when appropriate?
+
+3. **Performance Testing**
+   - Query response times under load
+   - Cache hit rates
+   - Memory usage with multiple active regions
+
+4. **Content Quality**
+   - Is lore consistent across databases?
+   - Are there contradictions between world/regional lore?
+   - Is chunk size appropriate for context?
+
+---
+
+## Implementation Phases
+
+### Phase 1: Proof of Concept (Current)
+- [ ] Set up local Weaviate with Docker
+- [ ] Create sample lore chunks (20-30 entries for one town)
+- [ ] Generate embeddings and upload to Weaviate
+- [ ] Build simple API endpoint for querying Weaviate
+- [ ] Test NPC conversation with lore augmentation
+
+### Phase 2: Core Implementation
+- [ ] Define lore content structure (YAML schema)
+- [ ] Write lore for starter region
+- [ ] Implement embedding generation script
+- [ ] Create Weaviate service layer in `/api/app/services/weaviate_service.py`
+- [ ] Integrate with NPC conversation system
+- [ ] Add DM lore query endpoints
+
+### Phase 3: Content Expansion
+- [ ] Write world lore content
+- [ ] Write lore for additional regions
+- [ ] Implement knowledge filtering logic
+- [ ] Add lore discovery system (optional: player codex)
+
+### Phase 4: Production Readiness
+- [ ] Migrate to Weaviate Cloud Services
+- [ ] Performance optimization and caching
+- [ ] Backup and disaster recovery
+- [ ] Monitoring and alerting
+
+---
+
+## Open Questions
+
+1. **Authoring Tools**: How will we create/maintain lore content efficiently?
+   - Manual YAML editing?
+   - AI-generated lore with human review?
+   - Web-based CMS?
+
+2. **Lore Discovery**: Should players unlock lore entries (codex-style) as they learn about them?
+   - Could be fun for completionists
+   - Adds gameplay loop around exploration
+
+3. **Dynamic Lore**: How to handle time-sensitive rumors or evolving world state?
+   - Separate "Rumors" collection with expiration dates?
+   - Regional events that trigger new lore entries?
+
+4. **Chunk Size**: What's optimal for context vs. precision?
+   - Too small: NPCs miss broader context
+   - Too large: Less precise retrieval
+   - Needs testing to determine
+
+5. **Consistency Validation**: How to ensure regional lore doesn't contradict world lore?
+   - Automated consistency checks?
+   - Manual review process?
+   - Lore versioning and dependency tracking?
+
+---
+
+## Future Enhancements
+
+- **Player-Generated Lore**: Allow DMs to add custom lore entries during sessions
+- **Lore Relationships**: Graph connections between related lore entries
+- **Multilingual Support**: Embed lore in multiple languages
+- **Seasonal/Event Lore**: Time-based lore that appears during special events
+- **Quest Integration**: Automatic lore unlock based on quest completion
+
+---
+
+## References
+
+- **Weaviate Documentation**: https://weaviate.io/developers/weaviate
+- **RAG Pattern Best Practices**: (TBD)
+- **Embedding Model Comparisons**: (TBD)
+
+---
+
+## Notes
+
+This strategy aligns with the project's core principles:
+- **Strong typing**: Lore models will use dataclasses
+- **Configuration-driven**: Lore content in YAML/JSON
+- **Microservices architecture**: Weaviate is independent service
+- **Cost-conscious**: Index-once strategy minimizes ongoing costs
+- **Future-proof**: Easy migration from self-hosted to managed

docs/WEB_VS_CLIENT_SYSTEMS.md

@@ -1,926 +0,0 @@
-# Web vs Client Feature Distribution
-
-**Version:** 1.0
-**Last Updated:** November 17, 2025
-**Status:** Architectural Decision Document
-
----
-
-## Overview
-
-This document defines the feature distribution strategy between **Public Web Frontend** (`/public_web`) and **Godot Game Client** (`/godot_client`). It outlines what features belong in each frontend, security considerations, and implementation priorities.
-
-**Core Principle:** Both frontends are **thin clients** that make HTTP calls to the API backend. The API is the single source of truth for all business logic, data persistence, and validation.
-
----
-
-## Architecture Pattern
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        User Access                          │
-├──────────────────────────┬──────────────────────────────────┤
-│                          │                                  │
-│   Public Web Frontend    │      Godot Game Client          │
-│   (Flask + Jinja2)       │      (Godot 4.5)                │
-│                          │                                  │
-│   - Account Management   │      - Gameplay Experience       │
-│   - Character Viewing    │      - Combat & Quests          │
-│   - Marketplace          │      - Real-time Multiplayer    │
-│   - Community            │      - Inventory & Equipment    │
-│                          │                                  │
-└──────────────────────────┴──────────────────────────────────┘
-                            │
-                            ▼
-                   ┌────────────────────┐
-                   │   API Backend      │
-                   │   (Flask REST)     │
-                   │                    │
-                   │ - Business Logic   │
-                   │ - Validation       │
-                   │ - Data Persistence │
-                   │ - AI Integration   │
-                   └────────────────────┘
-                            │
-                            ▼
-                   ┌────────────────────┐
-                   │   Appwrite DB      │
-                   │   + Redis Cache    │
-                   └────────────────────┘
-```
-
-**Key Points:**
-- Both frontends are **untrusted clients** - API validates everything
-- No business logic in frontends (only UI/UX)
-- No direct database access from frontends
-- API enforces permissions, rate limits, tier restrictions
-
----
-
-## Feature Distribution Strategy
-
-### Decision Framework
-
-When deciding where a feature belongs, consider:
-
-1. **Security Sensitivity** - Payment/account changes → Web only
-2. **Gameplay Integration** - Combat/quests → Game only
-3. **Accessibility** - Planning/browsing → Web preferred
-4. **User Experience** - Visual/immersive → Game preferred
-5. **Performance** - Real-time updates → Game preferred
-6. **SEO/Marketing** - Public content → Web preferred
-
----
-
-## Public Web Frontend Features
-
-The web frontend serves as the **Management Plane** - where players manage their account, characters, and community presence outside of active gameplay.
-
-### ✅ Core Account Management (Security-Critical)
-
-**Authentication & Security:**
-- User registration with email verification
-- Login with session management
-- Password reset flow (email-based)
-- Change password (requires re-authentication)
-- Change email address (with verification)
-- Two-Factor Authentication (2FA) setup
-- View active sessions (device management)
-- Login history and security audit log
-- Account deletion (GDPR compliance)
-
-**Why Web?**
-- Security-critical operations require robust email flows
-- PCI/GDPR compliance easier on web
-- Better audit trails with server logs
-- Standard user expectation (manage accounts in browsers)
-- HTTPS, CSP headers, secure cookie handling
-
-### ✅ Subscription & Payment Management
-
-**Billing Features:**
-- View current subscription tier
-- Upgrade/downgrade between tiers (Free, Basic, Premium, Elite)
-- Payment method management (add/remove cards)
-- Billing history and invoices
-- Cancel subscription
-- Gift code redemption
-- Referral program tracking
-
-**Why Web?**
-- **PCI DSS compliance** - Never handle payments in game clients
-- Standard payment gateways (Stripe, PayPal) are web-first
-- Easier to secure against client-side tampering
-- Legal/regulatory requirements (receipts, invoices)
-- Integration with Stripe Customer Portal
-
-**Security:**
-- No payment data stored in database (Stripe handles)
-- Webhook verification for subscription changes
-- Transaction logging for audit compliance
-
-### ✅ Character Management (Viewing & Light Editing)
-
-**Character Features:**
-- **Character Gallery** - View all characters with stats, equipment, level, achievements
-- **Character Detail View** - Full character sheet (read-only)
-- **Character Comparison** - Side-by-side stat comparison (useful for planning builds)
-- **Character Renaming** - Simple text field edit
-- **Character Deletion** - Soft delete with confirmation modal
-- **Skill Tree Viewer** - Read-only interactive skill tree (planning builds)
-
-**Why Web?**
-- Accessible from anywhere (phone, work, tablet)
-- Good for planning sessions while away from desktop
-- Faster load times than booting game client
-- Industry standard: WoW Armory, FFXIV Lodestone, D&D Beyond
-
-**Note:** Character **creation** wizard can be on web OR game (see recommendations below)
-
-### ✅ Marketplace (Full-Featured Trading Hub)
-
-**Marketplace Features:**
-- **Browse Listings** - Search, filter, sort with pagination
-- **Advanced Search** - Filter by item type, rarity, level, price range
-- **Place Bids** - Auction bidding system with bid history
-- **Buyout** - Instant purchase at buyout price
-- **Create Listing** - List items for auction or fixed price
-- **My Listings** - View/cancel your active listings
-- **My Bids** - View/manage your active bids
-- **Transaction History** - Full audit trail of purchases/sales
-- **Price Analytics** - Charts, market trends, price history
-- **Watchlist** - Save listings to watch later
-- **Notification Preferences** - Email/in-game alerts for auction wins/outbid
-
-**Why Web?**
-- Better for serious trading (multiple tabs, spreadsheets, price comparison)
-- Data visualization for market trends (charts work better on web)
-- Pagination-friendly (hundreds of listings)
-- Can browse while at work/away from game
-- SEO benefits (public listings can be indexed)
-
-**Note:** Game client should have **light marketplace access** for convenience (quick browse/buy during gameplay)
-
-### ✅ Community & Content
-
-**Community Features:**
-- **Dev Blog** - Patch notes, announcements, event schedules
-- **Game News** - Latest updates, maintenance windows, new features
-- **Forums** - Player discussions (or link to Discord/Reddit)
-- **Leaderboards** - Global rankings, seasonal standings, category leaderboards
-- **Guild Directory** - Browse guilds, recruitment listings, guild pages
-- **Player Profiles** - Public character pages (if user enables)
-- **Session Replays** - View past session logs (markdown export from API)
-- **Knowledge Base** - Game wiki, guides, FAQs, tutorials
-- **Feedback/Suggestions** - Submit feedback, vote on features
-
-**Why Web?**
-- **SEO benefits** - Google can index news, guides, wiki pages (marketing)
-- Accessible to non-players (prospect research before signing up)
-- Easier content updates (no client patches required)
-- Standard for all MMOs/online games (WoW, FFXIV, GW2, etc.)
-- Community engagement outside of gameplay
-
-### ✅ Analytics & Progress Tracking
-
-**Dashboard Features:**
-- **Account Stats** - Total playtime, characters created, sessions played
-- **Character Progress** - XP charts, gold history, level progression timeline
-- **Combat Analytics** - Win/loss rate, damage dealt, kills, deaths
-- **Achievement Tracker** - Progress toward achievements, completion percentage
-- **Quest Log** - View active/completed quests across all characters
-- **Collection Tracker** - Items collected, rare drops, completionist progress
-
-**Why Web?**
-- Always accessible (check progress on phone)
-- Better for data visualization (charts, graphs, timelines)
-- Doesn't clutter game UI
-- Can share stats publicly (profile pages)
-
-### ✅ Support & Help
-
-**Support Features:**
-- **Help Desk** - Submit support tickets, track status
-- **FAQ / Knowledge Base** - Searchable help articles
-- **Contact Form** - Direct contact with support team
-- **Bug Reports** - Submit bug reports with screenshots
-- **Email Preferences** - Newsletter subscriptions, notification settings
-
-**Why Web?**
-- Standard support workflow (ticket systems)
-- Easier to attach screenshots/logs
-- Can access while game is broken
-- GDPR compliance (manage email consent)
-
-### ✅ Guild Management Hub (Future Feature)
-
-**Guild Features:**
-- **Create Guild** - Setup guild with name, description, emblem
-- **Manage Guild** - Edit details, set permissions, manage roster
-- **Guild Bank** - View/manage shared resources
-- **Guild Events** - Schedule raids, events with calendar integration
-- **Guild Permissions** - Role-based access control
-- **Recruitment** - Post recruitment listings to directory
-
-**Why Web?**
-- Guild management is administrative (not gameplay)
-- Better UX for roster management (tables, sorting)
-- Calendar integration works better on web
-- Officers can manage guild without booting game
-
----
-
-## Godot Game Client Features
-
-The game client serves as the **Experience Plane** - where players engage with gameplay, combat, story, and real-time interactions.
-
-### ✅ Core Gameplay
-
-**Gameplay Features:**
-- **Character Creation** - Full visual wizard with 3D character previews
-- **Combat System** - Turn-based combat UI with animations, effects, sound
-- **Quest System** - Quest tracking, objectives, turn-ins, rewards
-- **Story Progression** - AI DM interactions, narrative choices, action prompts
-- **Exploration** - World map navigation, location discovery, fast travel
-- **NPC Interactions** - Dialogue trees, shop browsing, quest givers
-- **Session Management** - Join/create sessions, invite players, session state
-
-**Why Game?**
-- Rich UI/UX (animations, particle effects, sound design)
-- Immersive experience (3D environments, music, atmosphere)
-- Real-time interactions with AI DM
-- This is what players launch the game for
-
-### ✅ Inventory & Equipment Management
-
-**Inventory Features:**
-- **Inventory UI** - Drag-drop interface, auto-sort, filtering
-- **Equipment System** - Character sheet, equip/unequip with visual updates
-- **Item Tooltips** - Detailed stats, stat comparisons (current vs new)
-- **Item Usage** - Consume potions, activate items, combine items
-- **Loot System** - Loot drops, auto-loot settings, loot rolling (multiplayer)
-
-**Why Game?**
-- Drag-drop is better in native UI than web
-- Visual feedback (character model updates when equipped)
-- Tight integration with combat/gameplay
-- Real-time item usage during combat
-
-### ✅ Social & Multiplayer
-
-**Social Features:**
-- **Party Formation** - Invite players to party, manage party composition
-- **Chat System** - Party chat, global chat, whispers, guild chat
-- **Multiplayer Sessions** - Real-time session joining, turn coordination
-- **Emotes** - Character animations, quick messages
-- **Friend List** - Add friends, see online status, invite to party
-- **Voice Chat Integration** - Discord Rich Presence or in-game voice
-
-**Why Game?**
-- Real-time communication during gameplay
-- WebSocket integration for live updates (Appwrite Realtime)
-- Better performance for rapid message updates
-- Social features enhance gameplay immersion
-
-### ✅ Character Customization
-
-**Customization Features:**
-- **Appearance Editor** - Visual character customization (face, hair, body type)
-- **Skill Tree** - Interactive skill unlocking with visual tree UI
-- **Talent Respec** - Preview changes, confirm spend, visual feedback
-- **Cosmetics** - Apply skins, mount cosmetics, visual effects
-- **Character Sheet** - Live stat updates, equipment preview
-
-**Why Game?**
-- Visual feedback (see changes immediately on 3D model)
-- Integrated with character rendering engine
-- Better UX for complex skill trees (zoom, pan, tooltips)
-- Drag-drop equipment for easy comparison
-
-### ✅ Combat & Abilities
-
-**Combat Features:**
-- **Attack System** - Target selection, attack animations, damage numbers
-- **Spell Casting** - Spell targeting, visual effects, cooldown tracking
-- **Item Usage** - Combat items (potions, scrolls), inventory shortcuts
-- **Defensive Actions** - Dodge, block, defend with animations
-- **Combat Log** - Real-time combat text log with color coding
-- **Status Effects** - Visual indicators for buffs/debuffs, duration tracking
-
-**Why Game?**
-- Animations, sound effects, particle systems
-- Real-time feedback during combat
-- Immersive combat experience
-- Tight integration with game loop
-
-### ✅ NPC Shops & Marketplace (Light Access)
-
-**In-Game Commerce:**
-- **NPC Shops** - Browse shop inventory, purchase items, sell loot
-- **Marketplace (Quick Access)** - Simple search, quick buy, notifications
-- **Auction Alerts** - Pop-up notifications for auction wins/outbid
-- **Transaction Confirmation** - In-game purchase confirmations
-
-**Why Game?**
-- Convenience during gameplay (buy potions before dungeon)
-- Quick transactions without alt-tabbing
-- NPC shops are part of world immersion
-
-**Note:** Serious trading should still happen on web (better UX for market analysis)
-
-### ✅ Map & Navigation
-
-**Navigation Features:**
-- **World Map** - Interactive map with zoom, fog of war
-- **Minimap** - Real-time position tracking during exploration
-- **Waypoints** - Set custom waypoints, quest markers
-- **Fast Travel** - Teleport to discovered locations
-- **Location Discovery** - Reveal map as you explore
-
-**Why Game?**
-- Real-time position updates during movement
-- Integration with 3D world rendering
-- Better performance for map rendering
-
----
-
-## Features That Should Be in BOTH (Different UX)
-
-Some features benefit from being accessible in both frontends with different user experiences:
-
-### 🔄 Marketplace
-- **Web:** Full-featured trading hub (serious trading, market analysis, price charts)
-- **Game:** Quick access (buy potions, check if auction won, browse while waiting)
-
-### 🔄 Character Viewing
-- **Web:** Planning builds (read-only skill trees, stat calculators, gear comparisons)
-- **Game:** Active gameplay (equip items, unlock skills, use abilities)
-
-### 🔄 News & Events
-- **Web:** Read patch notes, browse dev blog, event calendars
-- **Game:** In-game notifications (event starting soon, new patch available)
-
-### 🔄 Achievements
-- **Web:** Achievement tracker, progress bars, leaderboards, collection view
-- **Game:** Achievement pop-ups, unlock notifications, sound effects
-
-### 🔄 Friends & Social
-- **Web:** Manage friend list, send friend requests, view profiles
-- **Game:** See online status, invite to party, send messages
-
----
-
-## Security Best Practices
-
-### 🔒 Web-Only (High Security Operations)
-
-These features MUST be web-only for security/compliance reasons:
-
-1. **Payment Processing**
-   - PCI DSS compliance is easier on web
-   - Standard payment gateways (Stripe, PayPal) are web-first
-   - Easier to secure against client-side tampering
-   - Audit trails for regulatory compliance
-   - **NEVER handle payment info in game client**
-
-2. **Password Management**
-   - Password reset flows require email verification
-   - Password change requires re-authentication
-   - Web is more secure (HTTPS, CSP headers, no client tampering)
-   - **NEVER allow password changes in game client**
-
-3. **Email/Account Recovery**
-   - Email verification links (click to verify in browser)
-   - 2FA setup (QR codes for authenticator apps)
-   - Backup code generation and storage
-   - **Web-based flows are standard**
-
-4. **Account Deletion / Critical Operations**
-   - Requires email confirmation (prevent accidental deletion)
-   - Legal compliance (GDPR right to deletion, data export)
-   - Audit trail requirements
-   - **Too risky for game client**
-
-### 🎮 Game Client (Lower Security Risk)
-
-These operations are safe in game client (with API validation):
-
-- Gameplay actions (combat, quests, item usage)
-- Character creation (not security-critical)
-- Inventory management (server validates all transactions)
-- Social features (chat, parties - API handles rate limits)
-
-**Why Safe?**
-- All validated server-side by API
-- Game client is just a UI (thin client architecture)
-- Cheating attempts fail at API validation layer
-- API enforces permissions, tier limits, rate limits
-
-### 🔐 Security Architecture Principle
-
-```
-[Untrusted Client] → [API Validates Everything] → [Database]
-```
-
-**Both frontends are untrusted:**
-- Never trust client-side data
-- API validates all inputs (sanitize, type check, permission check)
-- API enforces business rules (tier limits, cooldowns, costs)
-- Database transactions ensure data integrity
-
----
-
-## Security Checklist for Web Frontend
-
-When implementing web features, ensure:
-
-### Authentication & Sessions
-- [ ] HTTPS everywhere (Cloudflare, Let's Encrypt, SSL certificate)
-- [ ] HTTP-only cookies for sessions (JavaScript cannot access)
-- [ ] Secure flag on cookies (HTTPS only in production)
-- [ ] SameSite: Lax or Strict (CSRF protection)
-- [ ] Session expiration (24 hours normal, 30 days remember-me)
-- [ ] Session regeneration after login (prevent session fixation)
-
-### Input Validation & Protection
-- [ ] CSRF protection on all forms (Flask-WTF)
-- [ ] Input validation and sanitization (prevent XSS, SQLi)
-- [ ] Content Security Policy (CSP) headers
-- [ ] Rate limiting on sensitive endpoints (login, registration, password reset)
-- [ ] CAPTCHA on registration/login (prevent bots)
-
-### Payment Security
-- [ ] Use Stripe/PayPal hosted checkout (no card data in your DB)
-- [ ] Verify webhook signatures (prevent fake payment confirmations)
-- [ ] PCI DSS compliance (use certified payment processors)
-- [ ] Transaction logging for audit compliance
-
-### Account Security
-- [ ] Two-Factor Authentication (2FA) support (TOTP, backup codes)
-- [ ] Email verification on registration
-- [ ] Email confirmation for critical operations (password change, email change)
-- [ ] Account lockout after N failed login attempts (5-10 attempts)
-- [ ] Login history tracking (IP, device, timestamp)
-- [ ] Security event notifications (new device login, password changed)
-
-### Data Protection & Compliance
-- [ ] GDPR compliance (data export, right to deletion)
-- [ ] Privacy policy and terms of service
-- [ ] Cookie consent banner (EU requirements)
-- [ ] Data encryption at rest (database encryption)
-- [ ] Data encryption in transit (TLS 1.2+ for API calls)
-- [ ] Secure password storage (bcrypt, Argon2)
-
-### HTTP Security Headers
-- [ ] Strict-Transport-Security (HSTS)
-- [ ] X-Content-Type-Options: nosniff
-- [ ] X-Frame-Options: DENY (prevent clickjacking)
-- [ ] X-XSS-Protection: 1; mode=block
-- [ ] Referrer-Policy: strict-origin-when-cross-origin
-
-### Logging & Monitoring
-- [ ] Audit logging (who did what, when)
-- [ ] Error tracking (Sentry, Rollbar)
-- [ ] Security event alerts (failed logins, suspicious activity)
-- [ ] Uptime monitoring (status page)
-
----
-
-## Industry Examples & Best Practices
-
-### World of Warcraft (Blizzard)
-
-**Web (Battle.net):**
-- Account management (register, login, 2FA, password reset)
-- Shop (game time, expansions, mounts, pets)
-- Armory (character profiles, gear, achievements)
-- News (patch notes, events, hotfixes)
-- Forums (community discussions)
-- Guild finder
-
-**Game Client:**
-- All gameplay (quests, combat, exploration)
-- Character customization (transmog, talents)
-- Auction house (but also web armory for viewing)
-- In-game shop (quick access to mounts/pets)
-
-**Key Insight:** Players use web for planning (checking gear, reading news) and game for playing
-
----
-
-### Final Fantasy XIV (Square Enix)
-
-**Web (Lodestone + Mog Station):**
-- Lodestone: News, character profiles, free company search, event calendar
-- Mog Station: Account management, subscription, shop (mounts, cosmetics)
-- Market board history and price trends
-
-**Game Client:**
-- All gameplay
-- Retainer market board (player-driven economy)
-- Glamour system (cosmetics)
-- In-game shop access
-
-**Key Insight:** Separate web properties for community (Lodestone) vs account (Mog Station)
-
----
-
-### Path of Exile (Grinding Gear Games)
-
-**Web:**
-- Official trade marketplace (advanced search, price indexing)
-- Account management (login, 2FA, linked accounts)
-- News and patch notes
-- Build guides and community wiki
-- Passive skill tree planner
-
-**Game Client:**
-- All gameplay (combat, loot, skill gems)
-- In-game item searching (but serious traders use web)
-- Hideout customization
-- MTX shop access
-
-**Key Insight:** Community created trade tools before official web version (PoE.trade) - web is essential for complex economies
-
----
-
-### EVE Online (CCP Games)
-
-**Web:**
-- Extensive market tools (price history, regional comparison)
-- Killboards (combat logs, ship losses)
-- Contract browsing (item contracts, courier contracts)
-- Account management and subscription
-- Skill planner
-
-**Game Client:**
-- Flying ships, combat, exploration
-- Quick market trades (local market)
-- Contract management
-- Corporation (guild) management
-
-**Key Insight:** EVE's complexity REQUIRES web tools - players use spreadsheets alongside web for market trading
-
----
-
-### D&D Beyond (Wizards of the Coast)
-
-**Web:**
-- Character builder (digital character sheets)
-- Campaign management (DM tools)
-- Rules reference (searchable rules, spells, items)
-- Marketplace (digital books, adventures)
-- Dice roller
-
-**In-Person Gameplay:**
-- Players use tablets/phones to access web character sheets
-- DM uses web for campaign notes
-
-**Key Insight:** Tabletop RPG went digital - web is perfect for character management, rules lookup
-
----
-
-### Common Patterns Across Industry
-
-**Web = "Management Plane"**
-- Account, billing, subscription
-- Character planning and build theory
-- Trading, market analysis, economics
-- Community, news, forums
-- Wiki, guides, knowledge base
-
-**Game = "Experience Plane"**
-- Gameplay, combat, quests, story
-- Real-time multiplayer and chat
-- Immersive visuals, sound, animations
-- Social features during gameplay
-
----
-
-## Recommended Implementation Phases
-
-### Phase 1: Essential Web Features (MVP)
-
-**Goal:** Fix technical debt, enable basic account/character management
-
-1. **Refactor public_web to use API** (Technical Debt)
-   - Replace stub service calls with HTTP requests to API
-   - Update auth helpers to validate sessions via API
-   - Remove stub service modules
-   - Test all existing views
-
-2. **Authentication Flows**
-   - User registration with email verification
-   - Login with session management
-   - Password reset flow
-   - Logout
-
-3. **Character Gallery**
-   - View all characters (read-only)
-   - Character detail pages
-   - Basic stats and equipment display
-
-4. **Account Settings**
-   - Change password (requires re-auth)
-   - Change email (with verification)
-   - View account info (registration date, tier)
-
-5. **Dev Blog / News Feed**
-   - Simple blog posts (markdown-based)
-   - Announcement system
-   - RSS feed
-
-**Deliverable:** Functional web frontend that complements game client
-
----
-
-### Phase 2: Monetization (Revenue)
-
-**Goal:** Enable subscription management and payment processing
-
-6. **Subscription Management**
-   - View current tier (Free, Basic, Premium, Elite)
-   - Upgrade/downgrade flows
-   - Stripe integration (Customer Portal)
-   - Subscription confirmation emails
-
-7. **Payment Processing**
-   - Stripe Checkout integration
-   - Webhook handling (subscription updates)
-   - Payment method management
-
-8. **Billing History**
-   - View past invoices
-   - Download receipts (PDF)
-   - Transaction log
-
-9. **Gift Code Redemption**
-   - Enter gift codes
-   - Apply promotional codes
-   - Track code usage
-
-**Deliverable:** Monetization system to support ongoing development
-
----
-
-### Phase 3: Community & Engagement
-
-**Goal:** Build community, increase retention
-
-10. **Marketplace (Web Version)**
-    - Browse listings (search, filter, sort, pagination)
-    - Place bids on auctions
-    - Create listings (auction or fixed price)
-    - My listings / My bids
-    - Transaction history
-    - Price analytics and charts
-
-11. **Leaderboards**
-    - Global rankings (level, wealth, achievements)
-    - Seasonal leaderboards
-    - Category leaderboards (PvP, crafting, questing)
-    - Player profile links
-
-12. **Session History Viewer**
-    - View past session logs (markdown export from API)
-    - Search sessions by date, characters, party members
-    - Share session links publicly (if enabled)
-
-13. **Player Profiles**
-    - Public character pages (if user enables)
-    - Achievement showcase
-    - Stats and analytics
-    - Session history
-
-**Deliverable:** Community features to keep players engaged
-
----
-
-### Phase 4: Advanced Features
-
-**Goal:** Expand platform, add convenience features
-
-14. **Guild Management Hub**
-    - Create/manage guilds
-    - Guild roster management
-    - Guild bank (shared resources)
-    - Guild event scheduling
-
-15. **Forums / Community**
-    - Discussion boards (or Discord/Reddit integration)
-    - Official announcements
-    - Player-to-player help
-
-16. **Analytics Dashboard**
-    - Account stats (playtime, characters, sessions)
-    - Character progress charts (XP, gold, level timeline)
-    - Combat analytics (win rate, damage dealt)
-
-17. **Support / Help Desk**
-    - Submit support tickets
-    - Track ticket status
-    - FAQ / knowledge base
-    - Bug report submission
-
-**Deliverable:** Mature platform with advanced features
-
----
-
-## Character Creation: Web vs Game Recommendation
-
-**Character creation wizard can exist in BOTH, but prioritize based on your goals:**
-
-### Option 1: Game Client Primary (Recommended)
-
-**Pros:**
-- Better UX (3D character preview, animations, music)
-- Immersive first-time experience
-- Visual customization (face, hair, body type)
-- Immediate transition to gameplay after creation
-
-**Cons:**
-- Requires downloading game client before creating character
-- Can't create characters on mobile (unless Godot exports to mobile)
-
-**When to choose:** If you want character creation to be part of the game experience
-
----
-
-### Option 2: Web Primary (Accessibility)
-
-**Pros:**
-- Accessible from anywhere (phone, tablet, any browser)
-- Can create characters before downloading game
-- Faster load times (no 3D assets)
-- Good for planning builds (skill tree preview)
-
-**Cons:**
-- Less immersive (no 3D preview)
-- Limited visual customization (no character model)
-- Feels more administrative than experiential
-
-**When to choose:** If you want to reduce friction (create character on phone, play on desktop later)
-
----
-
-### Option 3: Both (Best of Both Worlds)
-
-**Implementation:**
-- Web: "Quick Create" - Name, class, origin (minimal wizard)
-- Game: "Full Create" - Visual customization, 3D preview, full immersion
-
-**When to choose:** If you want maximum flexibility
-
-**Recommendation:** Start with game-only (better UX), add web later if needed
-
----
-
-## Mobile Considerations
-
-### Public Web (Mobile-Responsive)
-
-The web frontend should be **fully mobile-responsive** for:
-- Account management (on the go)
-- Character viewing (check stats while away from PC)
-- Marketplace browsing (trading from phone)
-- News and community (read patch notes on commute)
-
-**Implementation:**
-- Responsive CSS (mobile-first design)
-- Touch-friendly UI (large buttons, swipe gestures)
-- Progressive Web App (PWA) support (installable on phone)
-
-### Godot Client (Mobile Export - Future)
-
-Godot supports mobile export (iOS, Android), but:
-- Requires significant UI/UX changes (touch controls)
-- Performance considerations (mobile GPUs)
-- App store submission process
-- Monetization changes (Apple/Google take 30% cut)
-
-**Recommendation:** Start with desktop, add mobile export later if demand exists
-
----
-
-## API Design Considerations
-
-### Endpoint Organization
-
-**Authentication:**
-- `POST /api/v1/auth/register`
-- `POST /api/v1/auth/login`
-- `POST /api/v1/auth/logout`
-- `POST /api/v1/auth/forgot-password`
-- `POST /api/v1/auth/reset-password`
-- `POST /api/v1/auth/verify-email`
-
-**Account Management:**
-- `GET /api/v1/account/profile`
-- `PATCH /api/v1/account/profile`
-- `POST /api/v1/account/change-password`
-- `POST /api/v1/account/change-email`
-- `DELETE /api/v1/account`
-
-**Subscription:**
-- `GET /api/v1/subscription/status`
-- `POST /api/v1/subscription/create-checkout`
-- `POST /api/v1/subscription/create-portal-session`
-- `POST /api/v1/subscription/webhook` (Stripe)
-
-**Marketplace:**
-- `GET /api/v1/marketplace/listings`
-- `GET /api/v1/marketplace/listings/:id`
-- `POST /api/v1/marketplace/listings`
-- `POST /api/v1/marketplace/listings/:id/bid`
-- `POST /api/v1/marketplace/listings/:id/buyout`
-- `DELETE /api/v1/marketplace/listings/:id`
-
-**Leaderboards:**
-- `GET /api/v1/leaderboards/:category`
-- `GET /api/v1/leaderboards/player/:user_id`
-
-**News:**
-- `GET /api/v1/news` (public, no auth required)
-- `GET /api/v1/news/:slug`
-
----
-
-## Technology Stack Summary
-
-### Public Web Frontend
-
-**Core:**
-- Flask (web framework)
-- Jinja2 (templating)
-- HTMX (dynamic interactions)
-- Vanilla CSS (styling)
-
-**Libraries:**
-- Requests (HTTP client for API calls)
-- Structlog (logging)
-- Flask-WTF (CSRF protection)
-
-**Deployment:**
-- Gunicorn (WSGI server)
-- Nginx (reverse proxy)
-- Docker (containerization)
-
-### Godot Game Client
-
-**Core:**
-- Godot 4.5 (game engine)
-- GDScript (scripting language)
-- HTTP client (API calls)
-
-**Deployment:**
-- Desktop exports (Windows, macOS, Linux)
-- Web export (WebAssembly) - future
-- Mobile exports (iOS, Android) - future
-
-### API Backend
-
-**Core:**
-- Flask (REST API framework)
-- Appwrite (database, auth, realtime)
-- RQ + Redis (async task queue)
-- Anthropic API (Claude AI for DM)
-
-**Libraries:**
-- Dataclasses (data modeling)
-- PyYAML (config, game data)
-- Structlog (logging)
-- Requests (external API calls)
-
----
-
-## Conclusion
-
-**Public Web Frontend:**
-- **Purpose:** Account management, character planning, community engagement
-- **Features:** Authentication, subscriptions, marketplace, news, leaderboards, analytics
-- **Security:** Payment processing, password management, 2FA, audit logs
-- **Accessibility:** Mobile-responsive, SEO-friendly, fast load times
-
-**Godot Game Client:**
-- **Purpose:** Immersive gameplay experience
-- **Features:** Combat, quests, story progression, real-time multiplayer, inventory
-- **Experience:** 3D graphics, animations, sound design, music
-- **Performance:** Real-time updates, WebSocket communication, optimized rendering
-
-**Both frontends:**
-- Thin clients (no business logic)
-- Make HTTP requests to API backend
-- API validates everything (security, permissions, business rules)
-- Microservices architecture (independent deployment)
-
-**Next Steps:**
-1. Refactor public_web technical debt (remove stub services)
-2. Implement Phase 1 web features (MVP)
-3. Continue Godot client development (gameplay features)
-4. Phase 2+ based on user feedback and revenue needs
-
----
-
-**Document Version:** 1.0
-**Last Updated:** November 17, 2025
-**Next Review:** After Phase 1 completion

public_web/app/__init__.py

@@ -12,6 +12,7 @@ import structlog
 import yaml
 import os
 from pathlib import Path
+from datetime import datetime, timezone
 
 
 logger = structlog.get_logger(__name__)
@@ -56,10 +57,40 @@ def create_app():
     from .views.auth_views import auth_bp
     from .views.character_views import character_bp
     from .views.game_views import game_bp
+    from .views.pages import pages_bp
 
     app.register_blueprint(auth_bp)
     app.register_blueprint(character_bp)
     app.register_blueprint(game_bp)
+    app.register_blueprint(pages_bp)
+
+    # Register Jinja filters
+    def format_timestamp(iso_string: str) -> str:
+        """Convert ISO timestamp to relative time (e.g., '2 mins ago')"""
+        if not iso_string:
+            return ""
+        try:
+            timestamp = datetime.fromisoformat(iso_string.replace('Z', '+00:00'))
+            now = datetime.now(timezone.utc)
+            diff = now - timestamp
+
+            seconds = diff.total_seconds()
+            if seconds < 60:
+                return "Just now"
+            elif seconds < 3600:
+                mins = int(seconds / 60)
+                return f"{mins} min{'s' if mins != 1 else ''} ago"
+            elif seconds < 86400:
+                hours = int(seconds / 3600)
+                return f"{hours} hr{'s' if hours != 1 else ''} ago"
+            else:
+                days = int(seconds / 86400)
+                return f"{days} day{'s' if days != 1 else ''} ago"
+        except Exception as e:
+            logger.warning("timestamp_format_failed", iso_string=iso_string, error=str(e))
+            return iso_string
+
+    app.jinja_env.filters['format_timestamp'] = format_timestamp
 
     # Register dev blueprint only in development
     env = os.getenv("FLASK_ENV", "development")
@@ -78,6 +109,6 @@ def create_app():
         logger.error("internal_server_error", error=str(error))
         return render_template('errors/500.html'), 500
 
-    logger.info("flask_app_created", blueprints=["auth", "character", "game"])
+    logger.info("flask_app_created", blueprints=["auth", "character", "game", "pages"])
 
     return app

public_web/app/views/auth_views.py

@@ -72,9 +72,9 @@ def login():
             })
 
             # Store user in session
-            if response.get('result'):
-                session['user'] = response['result']
-                logger.info("User logged in successfully", user_id=response['result'].get('id'))
+            if response.get('result') and response['result'].get('user'):
+                session['user'] = response['result']['user']
+                logger.info("User logged in successfully", user_id=response['result']['user'].get('id'))
 
                 # Redirect to next page or character list
                 next_url = session.pop('next', None)

public_web/app/views/character_views.py

@@ -456,6 +456,14 @@ def list_characters():
             char_id = character.get('character_id')
             character['sessions'] = sessions_by_character.get(char_id, [])
 
+        # Fetch usage info for daily turn limits
+        usage_info = {}
+        try:
+            usage_response = api_client.get("/api/v1/usage")
+            usage_info = usage_response.get('result', {})
+        except (APIError, APINotFoundError) as e:
+            logger.debug("Could not fetch usage info", error=str(e))
+
         logger.info(
             "Characters listed",
             user_id=user.get('id'),
@@ -468,18 +476,46 @@ def list_characters():
             characters=characters,
             current_tier=current_tier,
             max_characters=max_characters,
-            can_create=can_create
+            can_create=can_create,
+            # Usage display variables
+            remaining=usage_info.get('remaining', 0),
+            daily_limit=usage_info.get('daily_limit', 0),
+            is_limited=usage_info.get('is_limited', False),
+            is_unlimited=usage_info.get('is_unlimited', False),
+            reset_time=usage_info.get('reset_time', '')
         )
 
     except APITimeoutError:
         logger.error("API timeout while listing characters", user_id=user.get('id'))
         flash('Request timed out. Please try again.', 'error')
-        return render_template('character/list.html', characters=[], can_create=False)
+        return render_template(
+            'character/list.html',
+            characters=[],
+            can_create=False,
+            current_tier='free',
+            max_characters=1,
+            remaining=0,
+            daily_limit=0,
+            is_limited=False,
+            is_unlimited=False,
+            reset_time=''
+        )
 
     except APIError as e:
         logger.error("Failed to list characters", user_id=user.get('id'), error=str(e))
         flash('An error occurred while loading your characters.', 'error')
-        return render_template('character/list.html', characters=[], can_create=False)
+        return render_template(
+            'character/list.html',
+            characters=[],
+            can_create=False,
+            current_tier='free',
+            max_characters=1,
+            remaining=0,
+            daily_limit=0,
+            is_limited=False,
+            is_unlimited=False,
+            reset_time=''
+        )
 
 
 @character_bp.route('/<character_id>')
@@ -613,6 +649,58 @@ def create_session(character_id: str):
         return redirect(url_for('character_views.list_characters'))
 
 
+@character_bp.route('/sessions/<session_id>/delete', methods=['DELETE'])
+@require_auth_web
+def delete_session(session_id: str):
+    """
+    Delete a game session via HTMX.
+
+    This permanently removes the session from the database.
+    Returns a response that triggers page refresh to update UI properly
+    (handles "Continue Playing" button visibility).
+
+    Args:
+        session_id: ID of the session to delete
+    """
+    from flask import make_response
+
+    user = get_current_user()
+    api_client = get_api_client()
+
+    try:
+        api_client.delete(f"/api/v1/sessions/{session_id}")
+
+        logger.info(
+            "Session deleted via web UI",
+            user_id=user.get('id'),
+            session_id=session_id
+        )
+
+        # Return empty response with HX-Refresh to reload the page
+        # This ensures "Continue Playing" button visibility is correct
+        response = make_response('', 200)
+        response.headers['HX-Refresh'] = 'true'
+        return response
+
+    except APINotFoundError:
+        logger.warning(
+            "Session not found for deletion",
+            user_id=user.get('id'),
+            session_id=session_id
+        )
+        # Return error message that HTMX can display
+        return '<span class="error-message">Session not found</span>', 404
+
+    except APIError as e:
+        logger.error(
+            "Failed to delete session",
+            user_id=user.get('id'),
+            session_id=session_id,
+            error=str(e)
+        )
+        return '<span class="error-message">Failed to delete session</span>', 500
+
+
 @character_bp.route('/<character_id>/skills')
 @require_auth_web
 def view_skills(character_id: str):

public_web/app/views/game_views.py

@@ -201,6 +201,14 @@ def play_session(session_id: str):
         # Get user tier
         user_tier = _get_user_tier(client)
 
+        # Fetch usage info for daily turn limits
+        usage_info = {}
+        try:
+            usage_response = client.get("/api/v1/usage")
+            usage_info = usage_response.get('result', {})
+        except (APINotFoundError, APIError) as e:
+            logger.debug("could_not_fetch_usage_info", error=str(e))
+
         # Build session object for template
         session = {
             'session_id': session_id,
@@ -220,7 +228,13 @@ def play_session(session_id: str):
             npcs=npcs,
             discovered_locations=discovered_locations,
             actions=DEFAULT_ACTIONS,
-            user_tier=user_tier
+            user_tier=user_tier,
+            # Usage display variables
+            remaining=usage_info.get('remaining', 0),
+            daily_limit=usage_info.get('daily_limit', 0),
+            is_limited=usage_info.get('is_limited', False),
+            is_unlimited=usage_info.get('is_unlimited', False),
+            reset_time=usage_info.get('reset_time', '')
         )
 
     except APINotFoundError:
@@ -259,13 +273,27 @@ def character_panel(session_id: str):
         character = _build_character_from_api(char_data)
         user_tier = _get_user_tier(client)
 
+        # Fetch usage info for daily turn limits
+        usage_info = {}
+        try:
+            usage_response = client.get("/api/v1/usage")
+            usage_info = usage_response.get('result', {})
+        except (APINotFoundError, APIError) as e:
+            logger.debug("could_not_fetch_usage_info", error=str(e))
+
         return render_template(
             'game/partials/character_panel.html',
             session_id=session_id,
             character=character,
             location=location,
             actions=DEFAULT_ACTIONS,
-            user_tier=user_tier
+            user_tier=user_tier,
+            # Usage display variables
+            remaining=usage_info.get('remaining', 0),
+            daily_limit=usage_info.get('daily_limit', 0),
+            is_limited=usage_info.get('is_limited', False),
+            is_unlimited=usage_info.get('is_unlimited', False),
+            reset_time=usage_info.get('reset_time', '')
         )
     except APIError as e:
         logger.error("failed_to_refresh_character_panel", session_id=session_id, error=str(e))
@@ -506,6 +534,10 @@ def poll_job(session_id: str, job_id: str):
     """Poll job status - returns updated partial."""
     client = get_api_client()
 
+    # Get hx_target and hx_swap from query params (passed through from original request)
+    hx_target = request.args.get('_hx_target')
+    hx_swap = request.args.get('_hx_swap')
+
     try:
         response = client.get(f'/api/v1/jobs/{job_id}/status')
         result = response.get('result', {})
@@ -540,11 +572,14 @@ def poll_job(session_id: str, job_id: str):
 
         else:
             # Still processing - return polling partial to continue
+            # Pass through hx_target and hx_swap to maintain targeting
             return render_template(
                 'game/partials/job_polling.html',
                 session_id=session_id,
                 job_id=job_id,
-                status=status
+                status=status,
+                hx_target=hx_target,
+                hx_swap=hx_swap
             )
 
     except APIError as e:
@@ -683,10 +718,13 @@ def do_travel(session_id: str):
         return f'<div class="error">Travel failed: {e}</div>', 500
 
 
-@game_bp.route('/session/<session_id>/npc/<npc_id>/chat')
+@game_bp.route('/session/<session_id>/npc/<npc_id>')
 @require_auth
-def npc_chat_modal(session_id: str, npc_id: str):
-    """Get NPC chat modal with conversation history."""
+def npc_chat_page(session_id: str, npc_id: str):
+    """
+    Dedicated NPC chat page (mobile-friendly full page view).
+    Used on mobile devices for better UX.
+    """
     client = get_api_client()
 
     try:
@@ -704,7 +742,61 @@ def npc_chat_modal(session_id: str, npc_id: str):
             'name': npc_data.get('name'),
             'role': npc_data.get('role'),
             'appearance': npc_data.get('appearance', {}).get('brief', ''),
-            'tags': npc_data.get('tags', [])
+            'tags': npc_data.get('tags', []),
+            'image_url': npc_data.get('image_url')
+        }
+
+        # Get relationship info
+        interaction_summary = npc_data.get('interaction_summary', {})
+        relationship_level = interaction_summary.get('relationship_level', 50)
+        interaction_count = interaction_summary.get('interaction_count', 0)
+
+        # Conversation history would come from character's npc_interactions
+        # For now, we'll leave it empty - the API returns it in dialogue responses
+        conversation_history = []
+
+        return render_template(
+            'game/npc_chat_page.html',
+            session_id=session_id,
+            npc=npc,
+            conversation_history=conversation_history,
+            relationship_level=relationship_level,
+            interaction_count=interaction_count
+        )
+
+    except APINotFoundError:
+        return render_template('errors/404.html', message="NPC not found"), 404
+    except APIError as e:
+        logger.error("failed_to_load_npc_chat_page", session_id=session_id, npc_id=npc_id, error=str(e))
+        return render_template('errors/500.html', message=f"Failed to load NPC: {e}"), 500
+
+
+@game_bp.route('/session/<session_id>/npc/<npc_id>/chat')
+@require_auth
+def npc_chat_modal(session_id: str, npc_id: str):
+    """
+    Get NPC chat modal with conversation history.
+    Used on desktop for modal overlay experience.
+    """
+    client = get_api_client()
+
+    try:
+        # Get session to find character
+        session_response = client.get(f'/api/v1/sessions/{session_id}')
+        session_data = session_response.get('result', {})
+        character_id = session_data.get('character_id')
+
+        # Get NPC details with relationship info
+        npc_response = client.get(f'/api/v1/npcs/{npc_id}?character_id={character_id}')
+        npc_data = npc_response.get('result', {})
+
+        npc = {
+            'npc_id': npc_data.get('npc_id'),
+            'name': npc_data.get('name'),
+            'role': npc_data.get('role'),
+            'appearance': npc_data.get('appearance', {}).get('brief', ''),
+            'tags': npc_data.get('tags', []),
+            'image_url': npc_data.get('image_url')
         }
 
         # Get relationship info
@@ -740,6 +832,40 @@ def npc_chat_modal(session_id: str, npc_id: str):
         '''
 
 
+@game_bp.route('/session/<session_id>/npc/<npc_id>/history')
+@require_auth
+def npc_chat_history(session_id: str, npc_id: str):
+    """Get last 5 chat messages for history sidebar."""
+    client = get_api_client()
+
+    try:
+        # Get session to find character_id
+        session_response = client.get(f'/api/v1/sessions/{session_id}')
+        session_data = session_response.get('result', {})
+        character_id = session_data.get('character_id')
+
+        # Fetch last 5 messages from chat service
+        # API endpoint: GET /api/v1/characters/{character_id}/chats/{npc_id}?limit=5
+        history_response = client.get(
+            f'/api/v1/characters/{character_id}/chats/{npc_id}',
+            params={'limit': 5, 'offset': 0}
+        )
+        result_data = history_response.get('result', {})
+        messages = result_data.get('messages', [])  # Extract messages array from result
+
+        # Render history partial
+        return render_template(
+            'game/partials/npc_chat_history.html',
+            messages=messages,
+            session_id=session_id,
+            npc_id=npc_id
+        )
+
+    except APIError as e:
+        logger.error("failed_to_load_chat_history", session_id=session_id, npc_id=npc_id, error=str(e))
+        return '<div class="history-empty">Failed to load history</div>', 500
+
+
 @game_bp.route('/session/<session_id>/npc/<npc_id>/talk', methods=['POST'])
 @require_auth
 def talk_to_npc(session_id: str, npc_id: str):
@@ -766,12 +892,15 @@ def talk_to_npc(session_id: str, npc_id: str):
         job_id = result.get('job_id')
         if job_id:
             # Return job polling partial for the chat area
+            # Use hx-target="this" and hx-swap="outerHTML" to replace loading div with response in-place
             return render_template(
                 'game/partials/job_polling.html',
                 job_id=job_id,
                 session_id=session_id,
                 status='queued',
-                is_npc_dialogue=True
+                is_npc_dialogue=True,
+                hx_target='this',       # Target the loading div itself
+                hx_swap='outerHTML'     # Replace entire loading div with response
             )
 
         # Immediate response (if AI is sync or cached)

public_web/app/views/pages.py

@@ -0,0 +1,96 @@
+"""
+Pages Views Blueprint
+
+This module provides web UI routes for static/stub pages:
+- Profile page
+- Sessions page
+- Mechanics page
+- Leaderboard page
+- Settings page
+- Help page
+
+These are currently stub pages that will be implemented in future phases.
+"""
+
+from flask import Blueprint, render_template
+from app.utils.auth import require_auth_web
+from app.utils.logging import get_logger
+
+
+# Initialize logger
+logger = get_logger(__file__)
+
+# Create blueprint
+pages_bp = Blueprint('pages', __name__)
+
+
+@pages_bp.route('/profile')
+@require_auth_web
+def profile():
+    """
+    Display player profile page.
+
+    Currently a stub - will show player stats, achievements, etc.
+    """
+    logger.info("Accessing profile page")
+    return render_template('pages/profile.html')
+
+
+@pages_bp.route('/sessions')
+@require_auth_web
+def sessions():
+    """
+    Display active game sessions page.
+
+    Currently a stub - will show list of active/past sessions.
+    """
+    logger.info("Accessing sessions page")
+    return render_template('pages/sessions.html')
+
+
+@pages_bp.route('/mechanics')
+@require_auth_web
+def mechanics():
+    """
+    Display game mechanics reference page.
+
+    Currently a stub - will explain combat, skills, items, etc.
+    """
+    logger.info("Accessing mechanics page")
+    return render_template('pages/mechanics.html')
+
+
+@pages_bp.route('/leaderboard')
+@require_auth_web
+def leaderboard():
+    """
+    Display leaderboard page.
+
+    Currently a stub - will show top players, achievements, etc.
+    """
+    logger.info("Accessing leaderboard page")
+    return render_template('pages/leaderboard.html')
+
+
+@pages_bp.route('/settings')
+@require_auth_web
+def settings():
+    """
+    Display user settings page.
+
+    Currently a stub - will allow account settings, preferences, etc.
+    """
+    logger.info("Accessing settings page")
+    return render_template('pages/settings.html')
+
+
+@pages_bp.route('/help')
+@require_auth_web
+def help_page():
+    """
+    Display help/guide page.
+
+    Currently a stub - will provide tutorials, FAQs, support info.
+    """
+    logger.info("Accessing help page")
+    return render_template('pages/help.html')

public_web/docs/HTMX_PATTERNS.md

@@ -564,6 +564,8 @@ def create_character():
 <span id="spinner" class="htmx-indicator">⏳</span>
 ```
 
+> **IMPORTANT:** The `htmx-indicator` class is **hidden by default** (opacity: 0) and only shown during active requests. Never put this class on a container that should remain visible - only use it on loading spinners/messages that should appear during requests and disappear after.
+
 ### 4. Debounce Search Inputs
 ```html
 <input hx-get="/search"
@@ -646,6 +648,6 @@ document.body.addEventListener('htmx:responseError', (event) => {
 
 ---
 
-**Document Version:** 1.1
+**Document Version:** 1.2
 **Created:** November 18, 2025
-**Last Updated:** November 21, 2025
+**Last Updated:** November 26, 2025

public_web/docs/RESPONSIVE_MODALS.md

@@ -0,0 +1,380 @@
+# Responsive Modal Pattern
+
+## Overview
+
+This pattern provides an optimal UX for modal-like content by adapting to screen size:
+- **Desktop (>1024px)**: Displays content in modal overlays
+- **Mobile (≤1024px)**: Navigates to dedicated full pages
+
+This addresses common mobile modal UX issues: cramped space, nested scrolling, keyboard conflicts, and lack of native back button support.
+
+---
+
+## When to Use This Pattern
+
+Use this pattern when:
+- Content requires significant interaction (forms, chat, complex data)
+- Mobile users need better scroll/keyboard handling
+- The interaction benefits from full-screen on mobile
+- Desktop users benefit from keeping context visible
+
+**Don't use** for:
+- Simple confirmations/alerts (use standard modals)
+- Very brief interactions (dropdowns, tooltips)
+- Content that must overlay the game state
+
+---
+
+## Implementation Steps
+
+### 1. Create Shared Content Partial
+
+Extract the actual content into a reusable partial template that both the modal and page can use.
+
+**File**: `templates/game/partials/[feature]_content.html`
+
+```html
+{# Shared content partial #}
+<div class="feature-container">
+    <!-- Your content here -->
+    <!-- This will be used by both modal and page -->
+</div>
+```
+
+### 2. Create Two Routes
+
+Create both a modal route and a page route in your view:
+
+**File**: `app/views/game_views.py`
+
+```python
+@game_bp.route('/session/<session_id>/feature/<feature_id>')
+@require_auth
+def feature_page(session_id: str, feature_id: str):
+    """
+    Dedicated page view (mobile-friendly).
+    Used on mobile devices for better UX.
+    """
+    # Fetch data
+    data = get_feature_data(session_id, feature_id)
+
+    return render_template(
+        'game/feature_page.html',
+        session_id=session_id,
+        feature=data
+    )
+
+
+@game_bp.route('/session/<session_id>/feature/<feature_id>/modal')
+@require_auth
+def feature_modal(session_id: str, feature_id: str):
+    """
+    Modal view (desktop overlay).
+    Used on desktop for quick interactions.
+    """
+    # Fetch same data
+    data = get_feature_data(session_id, feature_id)
+
+    return render_template(
+        'game/partials/feature_modal.html',
+        session_id=session_id,
+        feature=data
+    )
+```
+
+### 3. Create Page Template
+
+Create a dedicated page template with header, back button, and shared content.
+
+**File**: `templates/game/feature_page.html`
+
+```html
+{% extends "base.html" %}
+
+{% block title %}{{ feature.name }} - Code of Conquest{% endblock %}
+
+{% block extra_head %}
+<link rel="stylesheet" href="{{ url_for('static', filename='css/play.css') }}">
+{% endblock %}
+
+{% block content %}
+<div class="feature-page">
+    {# Page Header with Back Button #}
+    <div class="feature-header">
+        <a href="{{ url_for('game.play_session', session_id=session_id) }}"
+           class="feature-back-btn">
+            <svg><!-- Back arrow icon --></svg>
+            Back
+        </a>
+        <h1 class="feature-title">{{ feature.name }}</h1>
+    </div>
+
+    {# Include shared content #}
+    {% include 'game/partials/feature_content.html' %}
+</div>
+{% endblock %}
+
+{% block scripts %}
+<script>
+// Add any feature-specific JavaScript here
+</script>
+{% endblock %}
+```
+
+### 4. Update Modal Template
+
+Update your modal template to use the shared content partial.
+
+**File**: `templates/game/partials/feature_modal.html`
+
+```html
+{# Modal wrapper #}
+<div class="modal-overlay" onclick="if(event.target === this) closeModal()">
+    <div class="modal-content modal-content--xl">
+        {# Modal Header #}
+        <div class="modal-header">
+            <h3 class="modal-title">{{ feature.name }}</h3>
+            <button class="modal-close" onclick="closeModal()">&times;</button>
+        </div>
+
+        {# Modal Body - Uses shared content #}
+        <div class="modal-body">
+            {% include 'game/partials/feature_content.html' %}
+        </div>
+
+        {# Modal Footer (optional) #}
+        <div class="modal-footer">
+            <button class="btn btn--secondary" onclick="closeModal()">
+                Close
+            </button>
+        </div>
+    </div>
+</div>
+```
+
+### 5. Add Responsive Navigation
+
+Update the trigger element to use responsive navigation JavaScript.
+
+**File**: `templates/game/partials/sidebar_features.html`
+
+```html
+<div class="feature-item"
+     data-feature-id="{{ feature.id }}"
+     onclick="navigateResponsive(
+         event,
+         '{{ url_for('game.feature_page', session_id=session_id, feature_id=feature.id) }}',
+         '{{ url_for('game.feature_modal', session_id=session_id, feature_id=feature.id) }}'
+     )"
+     style="cursor: pointer;">
+    <div class="feature-name">{{ feature.name }}</div>
+</div>
+```
+
+### 6. Add Mobile-Friendly CSS
+
+Add CSS for the dedicated page with mobile optimizations.
+
+**File**: `static/css/play.css`
+
+```css
+/* Feature Page */
+.feature-page {
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+    background: var(--bg-secondary);
+}
+
+/* Page Header with Back Button */
+.feature-header {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    padding: 1rem;
+    background: var(--bg-primary);
+    border-bottom: 2px solid var(--play-border);
+    position: sticky;
+    top: 0;
+    z-index: 100;
+}
+
+.feature-back-btn {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.5rem 1rem;
+    background: var(--bg-input);
+    color: var(--text-primary);
+    text-decoration: none;
+    border-radius: 4px;
+    border: 1px solid var(--play-border);
+    transition: all 0.2s ease;
+}
+
+.feature-back-btn:hover {
+    background: var(--bg-tertiary);
+    border-color: var(--accent-gold);
+    color: var(--accent-gold);
+}
+
+.feature-title {
+    flex: 1;
+    margin: 0;
+    font-family: var(--font-heading);
+    font-size: 1.5rem;
+    color: var(--accent-gold);
+}
+
+/* Responsive layout */
+@media (min-width: 1025px) {
+    .feature-page .feature-container {
+        max-width: 1400px;
+        margin: 0 auto;
+        padding: 2rem;
+    }
+}
+
+@media (max-width: 1024px) {
+    .feature-page .feature-container {
+        padding: 1rem;
+        flex: 1;
+    }
+}
+```
+
+### 7. Include JavaScript
+
+Ensure the responsive modals JavaScript is included in your play page template.
+
+**File**: `templates/game/play.html`
+
+```html
+{% block scripts %}
+<!-- Existing scripts -->
+<script>
+// Your existing JavaScript
+</script>
+
+<!-- Responsive Modal Navigation -->
+<script src="{{ url_for('static', filename='js/responsive-modals.js') }}"></script>
+{% endblock %}
+```
+
+---
+
+## JavaScript API
+
+The responsive navigation is handled by `responsive-modals.js`:
+
+### Functions
+
+#### `navigateResponsive(event, pageUrl, modalUrl)`
+
+Navigates responsively based on screen size.
+
+**Parameters:**
+- `event` (Event): Click event (will be prevented)
+- `pageUrl` (string): Full page URL for mobile navigation
+- `modalUrl` (string): Modal content URL for desktop HTMX loading
+
+**Example:**
+```javascript
+navigateResponsive(
+    event,
+    '/game/session/123/npc/456',      // Page route
+    '/game/session/123/npc/456/chat'  // Modal route
+)
+```
+
+#### `isMobile()`
+
+Returns true if viewport is ≤1024px.
+
+**Example:**
+```javascript
+if (isMobile()) {
+    // Mobile-specific behavior
+}
+```
+
+---
+
+## Breakpoint
+
+The mobile/desktop breakpoint is **1024px** to match the CSS media query:
+
+```javascript
+const MOBILE_BREAKPOINT = 1024;
+```
+
+This ensures consistent behavior between JavaScript navigation and CSS responsive layouts.
+
+---
+
+## Example: NPC Chat
+
+See the NPC chat implementation for a complete working example:
+
+**Routes:**
+- Page: `/game/session/<session_id>/npc/<npc_id>` (public_web/app/views/game_views.py:695)
+- Modal: `/game/session/<session_id>/npc/<npc_id>/chat` (public_web/app/views/game_views.py:746)
+
+**Templates:**
+- Shared content: `templates/game/partials/npc_chat_content.html`
+- Page: `templates/game/npc_chat_page.html`
+- Modal: `templates/game/partials/npc_chat_modal.html`
+
+**Trigger:**
+- `templates/game/partials/sidebar_npcs.html` (line 11)
+
+**CSS:**
+- Page styles: `static/css/play.css` (lines 1809-1956)
+
+---
+
+## Testing Checklist
+
+When implementing this pattern, test:
+
+- [ ] Desktop (>1024px): Modal opens correctly
+- [ ] Desktop: Modal closes with X button, overlay click, and Escape key
+- [ ] Desktop: Game screen remains visible behind modal
+- [ ] Mobile (≤1024px): Navigates to dedicated page
+- [ ] Mobile: Back button returns to game
+- [ ] Mobile: Content scrolls naturally
+- [ ] Mobile: Keyboard doesn't break layout
+- [ ] Both: Shared content renders identically
+- [ ] Both: HTMX interactions work correctly
+- [ ] Resize: Behavior adapts when crossing breakpoint
+
+---
+
+## Best Practices
+
+1. **Always share content**: Use a partial template to avoid duplication
+2. **Keep routes parallel**: Use consistent URL patterns (`/feature` and `/feature/modal`)
+3. **Test both views**: Ensure feature parity between modal and page
+4. **Mobile-first CSS**: Design for mobile, enhance for desktop
+5. **Consistent breakpoint**: Always use 1024px to match the JavaScript
+6. **Document examples**: Link to working implementations in this doc
+
+---
+
+## Future Improvements
+
+Potential enhancements to this pattern:
+
+- [ ] Add transition animations for modal open/close
+- [ ] Support deep linking to modals on desktop
+- [ ] Add browser back button handling for desktop modals
+- [ ] Support customizable breakpoints per feature
+- [ ] Add analytics tracking for modal vs page usage
+
+---
+
+## Related Documentation
+
+- **HTMX_PATTERNS.md** - HTMX integration patterns
+- **TEMPLATES.md** - Template structure and conventions
+- **TESTING.md** - Manual testing procedures

public_web/static/css/main.css

@@ -130,6 +130,207 @@ body {
     text-shadow: 0 0 8px rgba(243, 156, 18, 0.3);
 }
 
+/* ===== NAVIGATION MENU ===== */
+.nav-menu {
+    display: flex;
+    align-items: center;
+    gap: 0.25rem;
+}
+
+.nav-item {
+    font-family: var(--font-body);
+    font-size: var(--text-sm);
+    color: var(--text-secondary);
+    text-decoration: none;
+    padding: 0.5rem 0.75rem;
+    border-radius: 4px;
+    transition: all 0.3s ease;
+}
+
+.nav-item:hover {
+    color: var(--accent-gold);
+    background: rgba(243, 156, 18, 0.1);
+}
+
+.nav-item.active {
+    color: var(--accent-gold);
+    background: rgba(243, 156, 18, 0.15);
+    font-weight: 600;
+}
+
+/* Header User Section */
+.header-user {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    padding-left: 1rem;
+    border-left: 1px solid var(--border-primary);
+}
+
+/* ===== HAMBURGER MENU (Mobile) ===== */
+.hamburger-btn {
+    display: none;
+    background: none;
+    border: none;
+    cursor: pointer;
+    padding: 0.5rem;
+    z-index: 1001;
+}
+
+.hamburger-icon {
+    display: block;
+    width: 24px;
+    height: 2px;
+    background: var(--text-primary);
+    position: relative;
+    transition: all 0.3s ease;
+}
+
+.hamburger-icon::before,
+.hamburger-icon::after {
+    content: '';
+    position: absolute;
+    width: 24px;
+    height: 2px;
+    background: var(--text-primary);
+    left: 0;
+    transition: all 0.3s ease;
+}
+
+.hamburger-icon::before {
+    top: -8px;
+}
+
+.hamburger-icon::after {
+    bottom: -8px;
+}
+
+/* Hamburger animation when open */
+.hamburger-btn.open .hamburger-icon {
+    background: transparent;
+}
+
+.hamburger-btn.open .hamburger-icon::before {
+    transform: rotate(45deg);
+    top: 0;
+    background: var(--accent-gold);
+}
+
+.hamburger-btn.open .hamburger-icon::after {
+    transform: rotate(-45deg);
+    bottom: 0;
+    background: var(--accent-gold);
+}
+
+/* ===== MOBILE MENU ===== */
+.mobile-menu {
+    display: none;
+    flex-direction: column;
+    background: var(--bg-secondary);
+    border-top: 1px solid var(--border-primary);
+    padding: 1rem;
+    position: absolute;
+    top: 100%;
+    left: 0;
+    right: 0;
+    z-index: 1000;
+    box-shadow: var(--shadow-lg);
+}
+
+.mobile-menu.open {
+    display: flex;
+}
+
+.mobile-nav-item {
+    font-family: var(--font-body);
+    font-size: var(--text-base);
+    color: var(--text-secondary);
+    text-decoration: none;
+    padding: 0.75rem 1rem;
+    border-radius: 4px;
+    transition: all 0.3s ease;
+}
+
+.mobile-nav-item:hover {
+    color: var(--accent-gold);
+    background: rgba(243, 156, 18, 0.1);
+}
+
+.mobile-nav-item.active {
+    color: var(--accent-gold);
+    background: rgba(243, 156, 18, 0.15);
+    font-weight: 600;
+}
+
+.mobile-menu-divider {
+    height: 1px;
+    background: var(--border-primary);
+    margin: 0.75rem 0;
+}
+
+.mobile-user-greeting {
+    font-size: var(--text-sm);
+    color: var(--text-muted);
+    padding: 0.5rem 1rem;
+}
+
+.mobile-logout {
+    color: var(--accent-red-light);
+    background: none;
+    border: none;
+    text-align: left;
+    cursor: pointer;
+    width: 100%;
+}
+
+.mobile-logout:hover {
+    color: var(--accent-red);
+    background: rgba(192, 57, 43, 0.1);
+}
+
+/* ===== RESPONSIVE HEADER ===== */
+@media (max-width: 992px) {
+    .nav-item {
+        padding: 0.4rem 0.5rem;
+        font-size: var(--text-xs);
+    }
+
+    .nav-menu {
+        gap: 0.125rem;
+    }
+
+    .header-user {
+        padding-left: 0.75rem;
+    }
+
+    .user-greeting {
+        display: none;
+    }
+}
+
+@media (max-width: 768px) {
+    .header {
+        position: relative;
+        padding: 1rem;
+    }
+
+    .nav-menu {
+        display: none;
+    }
+
+    .header-user {
+        display: none;
+    }
+
+    .hamburger-btn {
+        display: block;
+    }
+
+    .logo {
+        font-size: var(--text-xl);
+    }
+}
+
 /* ===== MAIN CONTENT ===== */
 main {
     flex: 1;
@@ -606,3 +807,56 @@ main {
 .hidden {
     display: none;
 }
+
+/* ===== PAGE CONTAINER ===== */
+.page-container {
+    width: 100%;
+    max-width: 600px;
+    padding: 2rem;
+}
+
+/* ===== COMING SOON CARD ===== */
+.coming-soon-card {
+    background: var(--bg-secondary);
+    border: 2px solid var(--border-ornate);
+    border-radius: 8px;
+    padding: 3rem 2rem;
+    text-align: center;
+    box-shadow: var(--shadow-lg);
+}
+
+.coming-soon-card .page-title {
+    margin-bottom: 1.5rem;
+}
+
+.coming-soon-icon {
+    color: var(--accent-gold);
+    margin-bottom: 1.5rem;
+    opacity: 0.8;
+}
+
+.coming-soon-icon svg {
+    width: 64px;
+    height: 64px;
+}
+
+.coming-soon-text {
+    font-family: var(--font-heading);
+    font-size: var(--text-2xl);
+    color: var(--text-secondary);
+    text-transform: uppercase;
+    letter-spacing: 3px;
+    margin-bottom: 1rem;
+}
+
+.coming-soon-description {
+    font-size: var(--text-base);
+    color: var(--text-muted);
+    margin-bottom: 2rem;
+    line-height: 1.6;
+}
+
+.coming-soon-card .btn {
+    width: auto;
+    display: inline-block;
+}

public_web/static/css/play.css

@@ -1033,7 +1033,7 @@
 .modal-content--sm { max-width: 400px; }
 .modal-content--md { max-width: 500px; }
 .modal-content--lg { max-width: 700px; }
-.modal-content--xl { max-width: 900px; }
+.modal-content--xl { max-width: 1000px; }  /* Expanded for 3-column NPC chat */
 
 @keyframes slideUp {
     from { transform: translateY(20px); opacity: 0; }
@@ -1434,6 +1434,32 @@
     min-height: 400px;
 }
 
+/* 3-column layout for chat modal with history sidebar */
+.npc-modal-body--three-col {
+    padding: 0;  /* Let container handle padding */
+    max-height: 70vh;
+}
+
+/* Apply grid to the actual container holding the three columns */
+.npc-modal-body--three-col .npc-chat-container {
+    display: grid;
+    grid-template-columns: 200px 1fr 280px;  /* Profile | Chat | History */
+    gap: 1rem;
+    padding: 1rem 1.25rem;
+    height: 100%;
+}
+
+/* Override hardcoded widths for grid children - let grid define sizes */
+.npc-modal-body--three-col .npc-profile {
+    width: auto;
+}
+
+/* Ensure history panel is visible in modal grid */
+.npc-modal-body--three-col .npc-history-panel {
+    min-height: 200px;
+    overflow-y: auto;
+}
+
 /* NPC Profile (Left Column) */
 .npc-profile {
     width: 200px;
@@ -1587,18 +1613,20 @@
     font-weight: 600;
 }
 
-/* NPC Conversation (Right Column) */
+/* NPC Conversation (Middle Column) */
 .npc-conversation {
     flex: 1;
     display: flex;
     flex-direction: column;
     min-width: 0;
+    min-height: 0;  /* Important for grid child to enable scrolling */
 }
 
 .npc-conversation .chat-history {
     flex: 1;
     min-height: 250px;
-    max-height: none;
+    max-height: 500px;  /* Set max height to enable scrolling */
+    overflow-y: auto;  /* Enable vertical scroll */
 }
 
 .chat-empty-state {
@@ -1608,6 +1636,96 @@
     font-style: italic;
 }
 
+/* ===== NPC CHAT HISTORY SIDEBAR ===== */
+.npc-history-panel {
+    display: flex;
+    flex-direction: column;
+    border-left: 1px solid var(--play-border);
+    padding-left: 1rem;
+    overflow-y: auto;
+    max-height: 70vh;
+}
+
+.history-header {
+    font-size: 0.875rem;
+    font-weight: 600;
+    color: var(--text-muted);
+    text-transform: uppercase;
+    margin-bottom: 0.75rem;
+    letter-spacing: 0.05em;
+}
+
+.history-list {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+}
+
+/* Compact history cards */
+.history-card {
+    background: var(--bg-secondary);
+    border: 1px solid var(--play-border);
+    border-radius: 4px;
+    padding: 0.5rem;
+    font-size: 0.8rem;
+    transition: background 0.2s;
+}
+
+.history-card:hover {
+    background: var(--bg-tertiary);
+}
+
+.history-timestamp {
+    font-size: 0.7rem;
+    color: var(--text-muted);
+    margin-bottom: 0.25rem;
+    font-style: italic;
+}
+
+.history-player {
+    color: var(--text-primary);
+    margin-bottom: 0.125rem;
+    line-height: 1.4;
+}
+
+.history-player strong {
+    color: var(--accent-gold);
+}
+
+.history-npc {
+    color: var(--text-primary);
+    line-height: 1.4;
+}
+
+.history-npc strong {
+    color: var(--accent-gold);
+}
+
+.history-empty {
+    text-align: center;
+    color: var(--text-muted);
+    font-size: 0.875rem;
+    padding: 2rem 0;
+    font-style: italic;
+}
+
+.loading-state-small {
+    text-align: center;
+    color: var(--text-muted);
+    font-size: 0.875rem;
+    padding: 1rem 0;
+    font-style: italic;
+}
+
+/* HTMX Loading Indicator - visible by default, replaced by HTMX response */
+.history-loading {
+    text-align: center;
+    color: var(--text-muted);
+    font-size: 0.875rem;
+    padding: 1rem 0;
+    font-style: italic;
+}
+
 /* Responsive NPC Modal */
 @media (max-width: 700px) {
     .npc-modal-body {
@@ -1650,6 +1768,34 @@
     }
 }
 
+/* Responsive: 3-column modal stacks on smaller screens */
+@media (max-width: 1024px) {
+    .npc-modal-body--three-col .npc-chat-container {
+        grid-template-columns: 1fr;  /* Single column */
+        grid-template-rows: auto 1fr auto;
+    }
+
+    .npc-modal-body--three-col .npc-profile {
+        order: 1;
+        width: 100%;
+        flex-direction: row;
+        flex-wrap: wrap;
+    }
+
+    .npc-modal-body--three-col .npc-conversation {
+        order: 2;
+    }
+
+    .npc-modal-body--three-col .npc-history-panel {
+        order: 3;
+        border-left: none;
+        border-top: 1px solid var(--play-border);
+        padding-left: 0;
+        padding-top: 1rem;
+        max-height: 200px;  /* Shorter on mobile */
+    }
+}
+
 /* ===== UTILITY CLASSES FOR PLAY SCREEN ===== */
 .play-hidden {
     display: none !important;
@@ -1689,3 +1835,152 @@
 .chat-history::-webkit-scrollbar-thumb:hover {
     background: var(--text-muted);
 }
+
+/* ===== NPC CHAT DEDICATED PAGE ===== */
+/* Mobile-friendly full page view for NPC conversations */
+
+.npc-chat-page {
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+    background: var(--bg-secondary);
+}
+
+/* Page Header with Back Button */
+.npc-chat-header {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    padding: 1rem;
+    background: var(--bg-primary);
+    border-bottom: 2px solid var(--play-border);
+    position: sticky;
+    top: 0;
+    z-index: 100;
+}
+
+.npc-chat-back-btn {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.5rem 1rem;
+    background: var(--bg-input);
+    color: var(--text-primary);
+    text-decoration: none;
+    border-radius: 4px;
+    border: 1px solid var(--play-border);
+    font-family: var(--font-heading);
+    font-size: 0.9rem;
+    transition: all 0.2s ease;
+}
+
+.npc-chat-back-btn:hover {
+    background: var(--bg-tertiary);
+    border-color: var(--accent-gold);
+    color: var(--accent-gold);
+}
+
+.npc-chat-back-btn svg {
+    width: 20px;
+    height: 20px;
+}
+
+.npc-chat-title {
+    flex: 1;
+    margin: 0;
+    font-family: var(--font-heading);
+    font-size: 1.5rem;
+    color: var(--accent-gold);
+}
+
+/* Chat Container - Full Height Layout */
+.npc-chat-page .npc-chat-container {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    padding: 1rem;
+    gap: 1rem;
+    overflow: hidden;
+}
+
+/* Responsive Layout for NPC Chat Content */
+/* Desktop: 3-column grid */
+@media (min-width: 1025px) {
+    .npc-chat-page .npc-chat-container {
+        display: grid;
+        grid-template-columns: 250px 1fr 300px;
+        gap: 1.5rem;
+        max-width: 1400px;
+        margin: 0 auto;
+        width: 100%;
+    }
+}
+
+/* Mobile: Stacked layout */
+@media (max-width: 1024px) {
+    .npc-chat-page .npc-chat-container {
+        display: flex;
+        flex-direction: column;
+        gap: 1rem;
+    }
+
+    /* Compact profile on mobile */
+    .npc-chat-page .npc-profile {
+        flex-direction: row;
+        flex-wrap: wrap;
+        align-items: flex-start;
+        gap: 1rem;
+    }
+
+    .npc-chat-page .npc-portrait {
+        width: 80px;
+        height: 80px;
+        flex-shrink: 0;
+    }
+
+    .npc-chat-page .npc-profile-info {
+        flex: 1;
+        min-width: 150px;
+    }
+
+    .npc-chat-page .npc-relationship,
+    .npc-chat-page .npc-profile-tags,
+    .npc-chat-page .npc-interaction-stats {
+        width: 100%;
+    }
+
+    /* Conversation takes most of the vertical space */
+    .npc-chat-page .npc-conversation {
+        flex: 1;
+        display: flex;
+        flex-direction: column;
+        min-height: 400px;
+    }
+
+    /* History panel is collapsible on mobile */
+    .npc-chat-page .npc-history-panel {
+        max-height: 200px;
+        overflow-y: auto;
+        border-top: 1px solid var(--play-border);
+        padding-top: 1rem;
+    }
+}
+
+/* Ensure chat history fills available space on page */
+.npc-chat-page .chat-history {
+    flex: 1;
+    overflow-y: auto;
+    min-height: 300px;
+}
+
+/* Fix chat input to bottom on mobile */
+@media (max-width: 1024px) {
+    .npc-chat-page .chat-input-form {
+        position: sticky;
+        bottom: 0;
+        background: var(--bg-secondary);
+        padding: 0.75rem 0;
+        border-top: 1px solid var(--play-border);
+        margin-top: 0.5rem;
+    }
+}