From 93d3df74364454ef6d58f637362291b5efc47def Mon Sep 17 00:00:00 2001
From: uprightbass360 <uprightbass360@gmail.com>
Date: Sat, 3 Jan 2026 02:19:01 -0500
Subject: [PATCH] chore: docs update

---
 docs/ADVANCED.md        | 20 +++++++++++++
 docs/SCRIPTS.md         | 45 ++++++++++++++++++++++++++++
 scripts/hooks/README.md | 65 +++++++++++++++++++++++++++++++++++++++--
 3 files changed, 127 insertions(+), 3 deletions(-)

diff --git a/docs/ADVANCED.md b/docs/ADVANCED.md
index 8ac3144..99cf8b9 100644
--- a/docs/ADVANCED.md
+++ b/docs/ADVANCED.md
@@ -190,6 +190,26 @@ The build system is optimized for development and production deployments with Do
 - Build artifact caching for faster rebuilds
 - Support for custom patches and modifications
 
+### Module Build Source Path
+
+**`MODULES_REBUILD_SOURCE_PATH`** - Path to AzerothCore source used for C++ module compilation.
+
+**Default:** `${STORAGE_PATH_LOCAL}/source/azerothcore`
+
+Auto-selects the appropriate fork:
+- Playerbots enabled → `./local-storage/source/azerothcore-playerbots`
+- Standard build → `./local-storage/source/azerothcore`
+
+**Custom Override:**
+```bash
+MODULES_REBUILD_SOURCE_PATH=/path/to/custom/azerothcore
+```
+
+**Notes:**
+- Must be a valid AzerothCore git repository
+- Cannot be inside `STORAGE_PATH` (performance)
+- Auto-managed by `setup-source.sh` and `rebuild-with-modules.sh`
+
 ## Custom Configuration
 Advanced customization options for specialized deployments and development environments.
 
diff --git a/docs/SCRIPTS.md b/docs/SCRIPTS.md
index 722ee2c..7168085 100644
--- a/docs/SCRIPTS.md
+++ b/docs/SCRIPTS.md
@@ -415,6 +415,51 @@ Comprehensive deployment verification with health checks and service validation.
 ./scripts/bash/verify-deployment.sh --quick               # Quick health check only
 ```
 
+#### `scripts/bash/validate-env.sh` - Environment Configuration Validator
+Validates `.env` configuration for required and optional variables with detailed reporting.
+
+```bash
+./scripts/bash/validate-env.sh                    # Basic validation (required vars only)
+./scripts/bash/validate-env.sh --strict           # Validate required + optional vars
+./scripts/bash/validate-env.sh --quiet            # Errors only, suppress success messages
+```
+
+**Exit Codes:**
+- `0` - All required variables present (and optional if --strict)
+- `1` - Missing required variables
+- `2` - Missing optional variables (only in --strict mode)
+
+**Validates:**
+- **Project Configuration:** `COMPOSE_PROJECT_NAME`, `NETWORK_NAME`
+- **Repository URLs:** Standard and playerbots AzerothCore repositories
+- **Storage Paths:** `STORAGE_PATH`, `STORAGE_PATH_LOCAL`, `MODULES_REBUILD_SOURCE_PATH`
+- **Database Settings:** MySQL credentials, ports, database names
+- **Container Config:** Container names and user permissions
+- **Build Paths:** Module rebuild source paths (optional)
+- **Performance Tuning:** MySQL buffer pool, InnoDB settings (optional)
+- **Image References:** Docker image tags (optional)
+
+**Use Cases:**
+- Pre-deployment validation
+- Troubleshooting configuration issues
+- CI/CD pipeline checks
+- Documentation of environment requirements
+
+**Example Output:**
+```
+ℹ️  Validating environment configuration...
+✅ Loaded environment from /path/to/.env
+
+ℹ️  Checking required variables...
+✅ COMPOSE_PROJECT_NAME=azerothcore-realmmaster
+✅ NETWORK_NAME=azerothcore
+✅ STORAGE_PATH=./storage
+✅ MYSQL_ROOT_PASSWORD=********
+✅ All required variables are set
+
+✅ Environment validation passed ✨
+```
+
 ### Backup System Scripts
 
 #### `scripts/bash/backup-scheduler.sh` - Automated Backup Service
diff --git a/scripts/hooks/README.md b/scripts/hooks/README.md
index 6170149..3d23214 100755
--- a/scripts/hooks/README.md
+++ b/scripts/hooks/README.md
@@ -41,9 +41,68 @@ Reads patch definitions from module metadata.
 
 ## Module-Specific Hooks
 
-Module-specific hooks are named after their primary module:
-- `mod-ale-patches` - Apply mod-ale compatibility fixes
-- `black-market-setup` - Black Market specific setup
+Module-specific hooks are named after their primary module and handle unique setup requirements.
+
+### `mod-ale-patches`
+Applies compatibility patches for mod-ale (Eluna Lua scripting engine) when building with the AzerothCore playerbots fork.
+
+**Auto-Detection:**
+The hook automatically detects if you're building with the playerbots fork by checking:
+1. `STACK_SOURCE_VARIANT=playerbots` environment variable
+2. `MODULES_REBUILD_SOURCE_PATH` contains "azerothcore-playerbots"
+
+**Patches Applied:**
+
+#### SendTrainerList Compatibility Fix
+**When Applied:** Automatically for playerbots fork (or when `APPLY_SENDTRAINERLIST_PATCH=1`)
+**What it fixes:** Adds missing `GetGUID()` call to fix trainer list display
+**File:** `src/LuaEngine/methods/PlayerMethods.h`
+**Change:**
+```cpp
+// Before (broken)
+player->GetSession()->SendTrainerList(obj);
+
+// After (fixed)
+player->GetSession()->SendTrainerList(obj->GetGUID());
+```
+
+#### MovePath Compatibility Fix
+**When Applied:** Only when explicitly enabled with `APPLY_MOVEPATH_PATCH=1` (disabled by default)
+**What it fixes:** Updates deprecated waypoint movement API
+**File:** `src/LuaEngine/methods/CreatureMethods.h`
+**Change:**
+```cpp
+// Before (deprecated)
+MoveWaypoint(creature->GetWaypointPath(), true);
+
+// After (updated API)
+MovePath(creature->GetWaypointPath(), FORCED_MOVEMENT_RUN);
+```
+**Note:** Currently disabled by default as testing shows it's not required for normal operation.
+
+**Feature Flags:**
+```bash
+# Automatically set for playerbots fork
+APPLY_SENDTRAINERLIST_PATCH=1
+
+# Disabled by default - enable if needed
+APPLY_MOVEPATH_PATCH=0
+```
+
+**Debug Output:**
+The hook provides detailed debug information during builds:
+```
+🔧 mod-ale-patches: Applying playerbots fork compatibility fixes to mod-ale
+   ✅ Playerbots detected via MODULES_REBUILD_SOURCE_PATH
+   ✅ Applied SendTrainerList compatibility fix
+   ✅ Applied 1 compatibility patch(es)
+```
+
+**Why This Exists:**
+The playerbots fork has slightly different API signatures in certain WorldSession methods. These patches ensure mod-ale (Eluna) compiles and functions correctly with both standard AzerothCore and the playerbots fork.
+
+### `black-market-setup`
+Black Market specific setup tasks.
 
 ## Usage in Manifest