Document SCRIPT_DIR variable collision bug fix in REFDB_FORMAT.txt

Added [UPDATE_2025_12_03_SCRIPT_DIR_BUG_FIX] section documenting:
- Root cause analysis: Multiple libraries redefining SCRIPT_DIR
- Sourcing chain that triggered the bug
- Solution: Unique variable names (PHP_TOOLKIT_DIR, _LIB_SRCDIR)
- Architectural note for future refactoring
- All 6 libraries that set SCRIPT_DIR identified

REFDB_FORMAT.txt

@@ -1228,9 +1228,55 @@ git_commit_policy:
   clear_messages: "Use clear, descriptive commit messages"
   technical_details: "Include technical details and impact"
 
+[UPDATE_2025_12_03_SCRIPT_DIR_BUG_FIX]
+# Critical bug fix for PHP optimizer runtime failure
+
+problem_identified:
+  symptom: "ERROR: php-config-manager.sh not found (file exists at correct path)"
+  error_trace: "Trying to source /root/server-toolkit/lib/lib/php-analyzer.sh (double /lib/lib/)"
+  root_cause: "SCRIPT_DIR variable collision - multiple sourced libraries redefining SCRIPT_DIR"
+
+libraries_setting_script_dir:
+  - "lib/php-detector.sh (line 14, conditional)"
+  - "lib/php-analyzer.sh (line 7)"
+  - "lib/user-manager.sh (line 10)"
+  - "lib/system-detect.sh (line 11)"
+  - "lib/mysql-analyzer.sh (line 10)"
+  - "lib/reference-db.sh (line 11)"
+
+sourcing_chain:
+  php-optimizer.sh: "sources php-detector.sh + php-analyzer.sh + system-detect.sh + user-manager.sh"
+  php-detector.sh: "sources system-detect.sh + user-manager.sh (if SYS_CONTROL_PANEL undefined)"
+  php-analyzer.sh: "sources php-detector.sh + system-detect.sh"
+  issue: "Each sourced library overwrites parent's SCRIPT_DIR → /lib/lib/ double paths"
+
+solution_implemented:
+  php-optimizer.sh: "Renamed SCRIPT_DIR → PHP_TOOLKIT_DIR (unique variable name)"
+  user-manager.sh: "Renamed SCRIPT_DIR → _LIB_SRCDIR (avoid collision)"
+  php-optimizer.sh: "Fixed detect_system() → initialize_system_detection()"
+  debugging: "Removed 2>/dev/null error suppression to see actual errors"
+
+result:
+  status: "FIXED - Script loads all libraries successfully"
+  menu_display: "Working - Shows all 9 options correctly"
+  system_detection: "Working - Detects cPanel, AlmaLinux, Apache, MariaDB, PHP versions"
+  ready_for: "Live testing on production system"
+
+architectural_note:
+  global_issue: "SCRIPT_DIR used by multiple libraries creates collision risk"
+  current_fix: "Each module uses unique variable (PHP_TOOLKIT_DIR, etc.)"
+  better_solution: "Libraries should NEVER set SCRIPT_DIR, only modules"
+  status: "Documented for future refactoring"
+
+files_modified:
+  - "lib/user-manager.sh (3 lines changed)"
+  - "modules/performance/php-optimizer.sh (10 lines changed)"
+
+commit: "0cfbba2"
+
 [END]
 # This file is the primary developer reference document.
 # README.md is for end users, this file is for developers.
 # Keep this updated after every significant change.
-# Last updated: 2025-12-03 (PHP optimizer complete, documentation cleanup)
+# Last updated: 2025-12-03 (PHP optimizer SCRIPT_DIR bug fix - now runs successfully)
 ################################################################################