################################################################################
# SERVER TOOLKIT - DEVELOPER CONTEXT DATABASE
################################################################################
# OPTIMIZED FOR: Fast context loading and code navigation
# LAST UPDATED: 2025-11-20
# VERSION: 2.2.0
# FORMAT: Structured key-value with hierarchical sections
################################################################################

[META]
version: 2.1.0
updated: 2025-11-12
status: production_ready
base_path: /root/server-toolkit
entry_point: launcher.sh
control_panels: cPanel, Plesk, InterWorx, Standalone
repository: https://git.mull.lol/cschantz/Linux-Server-Management-Toolkit.git

[STATUS_SNAPSHOT_2025_11_19]
# MAJOR UPDATE: Multi-Control Panel Architecture (87% complete)
# 33/38 modules now support cPanel, InterWorx, Plesk, and standalone Apache

multi_panel_ready:
  - lib/system-detect.sh: Auto-detect cPanel/Plesk/InterWorx, exports SYS_CONTROL_PANEL, SYS_LOG_DIR
  - lib/user-manager.sh: Multi-panel user/domain abstraction (get_user_info, get_user_domains)
  - modules/security/bot-analyzer.sh: Multi-panel log discovery (Phase 2)
  - modules/security/live-attack-monitor.sh: Multi-panel logs + API wrapping
  - modules/security/malware-scanner.sh: Multi-panel docroot + log discovery
  - modules/security/optimize-ct-limit.sh: Uses SYS_LOG_DIR (no hardcoded paths)
  - modules/security/tail-apache-access.sh: Multi-panel log tailing
  - modules/security/tail-apache-error.sh: Multi-panel error log tailing
  - modules/security/web-traffic-monitor.sh: Multi-panel traffic monitoring
  - modules/website/website-error-analyzer.sh: Complete multi-panel (PHP + Apache logs)
  - modules/website/500-error-tracker.sh: Multi-panel log discovery + domain→user lookup
  - modules/performance/network-bandwidth-analyzer.sh: Multi-panel log analysis
  - modules/diagnostics/system-health-check.sh: Panel version detection

cpanel_only_conditional:
  - modules/security/enable-cphulk.sh: Wrapped in panel check (graceful on other panels)
  - modules/security/ip-reputation-manager.sh: Works on all, CSF integration cPanel-preferred

pending_refactoring:
  - modules/website/wordpress-cron-manager.sh: 33 /var/cpanel/userdata refs (COMPLEX)
  - modules/website/wordpress-menu.sh: Needs audit

production_ready:
  - launcher.sh: Main menu with hierarchical structure, cleanup/reset
  - modules/backup/acronis-*.sh: Complete Acronis Cyber Protect integration (16 scripts)
  - modules/performance/mysql-query-analyzer.sh: Slow query detection
  - modules/performance/hardware-health-check.sh: Hardware diagnostics
  - lib/reference-db.sh: 1-hour cache with cross-module intelligence
  - lib/ip-reputation.sh: Centralized IP reputation tracking

# Recent additions (2025-11-19)
recent_features:
  - Multi-control panel architecture: 33/38 modules (87%) now panel-agnostic
  - REFDB_FORMAT.txt: Complete multi-panel documentation section
  - Abstraction libraries: system-detect.sh + user-manager.sh patterns
  - Path mappings: cPanel/InterWorx/Plesk documented
  - Standard code patterns: Log discovery, domain→user, API wrapping

# Not implemented yet
future:
  - Complete Class C refactoring (2 WordPress modules)
  - Plesk-specific feature expansion
  - DirectAdmin/CyberPanel support
  - modules/wordpress/*: Plugin/theme managers, security hardening
  - modules/monitoring/*: Additional monitoring tools
  - modules/reporting/*: Report generation

[CRITICAL_DESIGN_RULES]
# DO NOT BREAK THESE - Latest standards as of 2025-11-07

bash_strict_mode: "set -eo pipefail" (NOT -euo - -u is too strict)
cancel_buttons: MANDATORY - Every menu must have "0) Cancel", every input must accept "0"
grep_pattern: Always add "|| true" to grep/find that might not match
unbound_vars: Use ${var:-} or ${var:-default} for potentially unbound variables
arithmetic: Use current=$((current + 1)) NOT ((current++))
output_suppression: NEVER use { } >/dev/null on critical functions (breaks variable assignment)
module_isolation: Modules run in subshells with cleared SYS_* environment
press_enter: ALWAYS call press_enter at end of scripts before exit
messaging: Use print_success, print_error, print_warning, print_info (NOT echo)

[CANCEL_BUTTON_STANDARD]
# MANDATORY as of 2025-11-07 - ALL scripts must support cancellation

menu_format: |
  echo "  1) Option One"
  echo "  2) Option Two"
  echo "  0) Cancel and return to menu"    # REQUIRED
  echo ""
  read -p "Select option: " choice
  
  case $choice in
      0)
          echo "Operation cancelled."
          press_enter
          exit 0
          ;;
      # ... other options
  esac

text_input_format: |
  echo -n "Enter value (or 0 to cancel): "
  read -r value
  
  if [ -z "$value" ] || [ "$value" = "0" ]; then
      echo "Operation cancelled."
      press_enter
      exit 0
  fi

rationale: Users must NEVER be trapped in a prompt - always provide escape route

[KEY_FILES_QUICK_MAP]
# Fast reference for file locations (updated 2025-11-07)

launcher.sh: Main entry point, menu system
  Line 77-84: Subshell isolation for modules
  Line 1262-1279: WordPress/website menu handler

README.md: User-facing documentation

REFDB_FORMAT.txt: THIS FILE - developer reference (keep updated!)

lib/common-functions.sh: Core utilities
  print_banner(), print_success(), print_error(), print_warning(), print_info()
  press_enter(), show_progress(), finish_progress()

lib/system-detect.sh: Auto-detection
  Exports: SYS_CONTROL_PANEL, SYS_OS_TYPE, SYS_WEB_SERVER, etc.
  Line 433-445: Auto-initialization with exec redirect

lib/user-manager.sh: User/domain selection
  select_user_interactive() - Arrow-key menu with search (type S [text])
  get_user_domains() - Domain detection for cPanel users

lib/reference-db.sh: Session intelligence (.sysref)
  db_get_all_wordpress(), db_get_user_domains(), db_store_*()
  1-hour TTL cache, cross-module data sharing

lib/ip-reputation.sh: Centralized IP tracking
  is_known_bot(), should_filter_ip(), log_ip_threat()

modules/website/wordpress-menu.sh: WordPress submenu
  Entry point for all WordPress management tools

modules/website/wordpress/wordpress-cron-manager.sh: WP cron conversion
  Disable/enable wp-cron, add system cron jobs, staggered timing

config/settings.conf: User configuration
config/whitelist-ips.txt: IP whitelist
config/whitelist-user-agents.txt: User-Agent whitelist

[DIRECTORY_STRUCTURE_2025_11_07]
server-toolkit/
├── launcher.sh (main entry point)
├── README.md (user docs)
├── REFDB_FORMAT.txt (THIS FILE - developer reference)
├── config/
│   ├── settings.conf
│   ├── whitelist-ips.txt
│   └── whitelist-user-agents.txt
├── lib/
│   ├── common-functions.sh (print_*, press_enter, colors)
│   ├── system-detect.sh (SYS_* variables)
│   ├── user-manager.sh (select_user_interactive)
│   ├── reference-db.sh (db_* functions, .sysref)
│   ├── ip-reputation.sh (is_known_bot, log_ip_threat)
│   └── mysql-analyzer.sh (database utilities)
├── modules/
│   ├── security/
│   │   ├── bot-analyzer.sh ✓
│   │   ├── live-attack-monitor.sh ✓
│   │   ├── enable-cphulk.sh ✓
│   │   └── ip-reputation-manager.sh ✓
│   ├── website/
│   │   ├── website-error-analyzer.sh ✓
│   │   ├── 500-error-tracker.sh ✓
│   │   ├── wordpress-menu.sh ✓
│   │   └── wordpress/
│   │       └── wordpress-cron-manager.sh ✓
│   ├── backup/
│   │   ├── acronis-backup-manager.sh ✓
│   │   ├── acronis-trigger-backup.sh ✓
│   │   ├── acronis-agent-status.sh ✓
│   │   └── [13 more acronis scripts] ✓
│   ├── diagnostics/
│   │   └── system-health-check.sh ✓
│   ├── performance/
│   │   ├── mysql-query-analyzer.sh ✓
│   │   └── hardware-health-check.sh ✓
│   └── maintenance/
│       └── cleanup-toolkit-data.sh ✓
└── tools/
    └── diagnostic-report.sh

[REFERENCE_DATABASE_FORMAT]
# .sysref file format - pipe-delimited session database

location: /root/server-toolkit/.sysref
timestamp: /root/server-toolkit/.sysref.timestamp
ttl: 3600 seconds (1 hour)
format: TYPE|field1|field2|field3|...

record_types:
  SYS: System information
    format: SYS|key|value|extra
    example: SYS|CONTROL_PANEL|cpanel|11.130.0.15

  USER: User accounts
    format: USER|username|primary_domain|db_count|domain_count|disk_mb|home_dir
    example: USER|pickledperil|pickledperil.com|1|3|82|/home/pickledperil

  DB: Databases
    format: DB|db_name|owner|primary_domain|size_mb|table_count
    example: DB|pickledperil_wp_wt6lz|pickledperil|pickledperil.com|15.23|12

  DOMAIN: Domain mappings (with HTTP/HTTPS status codes)
    format: DOMAIN|domain|owner|doc_root|log_path|php_ver|is_primary|type|aliases|http_code|https_code|status_summary
    example: DOMAIN|pickledperil.com|pickledperil|/home/pickledperil/public_html|/var/log/apache2/domlogs/pickledperil.com|ea-php81|yes|primary|www.pickledperil.com|200|200|200_OK
    types: primary, addon, subdomain, alias, parked, remote
    status_codes: 200, 301, 302, 403, 404, 500, 502, 503, timeout, 000
    status_summary: 200_OK, REDIRECT, 403_FORBIDDEN, 404_NOT_FOUND, 500_ERROR, 502_BAD_GATEWAY, 503_UNAVAILABLE, TIMEOUT, UNREACHABLE, OTHER, skipped, remote_mx

  WP: WordPress installations
    format: WP|domain|owner|path|db_name|db_user|version|plugin_count|theme_count
    example: WP|pickledperil.com|pickledperil|/home/pickledperil/public_html|pickledperil_wp_wt6lz|pickledperil_wp_user|6.8.3|1|3

  HEALTH: Health check baselines
    format: HEALTH|metric_name|value|date
    examples:
      HEALTH|MEMORY_TOTAL_MB|3776|2025-11-01
      HEALTH|CPU_LOAD_1MIN|2.4|2025-11-01
      HEALTH|DISK_USED_PERCENT|35|2025-11-01

query_functions:
  db_get_user(username)
  db_get_all_users()
  db_get_user_databases(username)
  db_get_user_domains(username)
  db_get_all_wordpress()
  db_store_wordpress(domain, owner, path, db_name, db_user, version, plugins, themes)

[MODULE_TEMPLATE]
# Standard template for creating new modules

file_location: /root/server-toolkit/modules/{category}/{name}.sh

template: |
  #!/bin/bash
  
  ################################################################################
  # Script Name
  ################################################################################
  # Purpose: Description
  # Features:
  # - Feature 1
  # - Feature 2
  ################################################################################
  
  # Path resolution (adjust based on depth)
  # modules/category/script.sh → ../../
  # modules/category/sub/script.sh → ../../../
  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
  source "$SCRIPT_DIR/lib/common-functions.sh"
  source "$SCRIPT_DIR/lib/system-detect.sh"
  
  # Optional libraries (only if needed)
  # source "$SCRIPT_DIR/lib/user-manager.sh"
  # source "$SCRIPT_DIR/lib/reference-db.sh"
  # source "$SCRIPT_DIR/lib/ip-reputation.sh"
  
  # Root check
  if [ "$EUID" -ne 0 ]; then
      print_error "This script must be run as root"
      exit 1
  fi
  
  # Main logic
  clear
  print_banner "Script Name"
  
  echo ""
  echo "Script functionality here..."
  echo ""
  
  # ALWAYS provide cancel option
  echo "  0) Cancel and return to menu"
  echo ""
  read -p "Select option: " choice
  
  case $choice in
      0)
          echo "Operation cancelled."
          press_enter
          exit 0
          ;;
      # ... other options
  esac
  
  echo ""
  print_success "Completed"
  echo ""
  press_enter

steps_to_add_module:
  1: Create file in modules/{category}/{name}.sh
  2: chmod +x the file
  3: Add to launcher.sh in appropriate menu handler
  4: Test directly: bash /root/server-toolkit/modules/category/script.sh
  5: Test via launcher: bash /root/server-toolkit/launcher.sh
  6: Commit to git

mandatory_checklist:
  - [ ] Cancel option on ALL menus ("0) Cancel")
  - [ ] Cancel option on ALL text inputs ("or 0 to cancel")
  - [ ] press_enter() at end before exit
  - [ ] Use print_* functions (not echo for status)
  - [ ] Correct SCRIPT_DIR path resolution
  - [ ] Root check if needed
  - [ ] Error handling with proper exit codes
  - [ ] Test with bash -n (syntax check)

[WORDPRESS_CRON_MANAGER]
# New feature added 2025-11-07

location: modules/website/wordpress/wordpress-cron-manager.sh
purpose: Convert WordPress wp-cron to real system cron jobs

features:
  - Scan for all WordPress installations
  - Disable wp-cron per domain/user/server-wide
  - Add staggered system cron jobs (load distribution)
  - Revert to wp-cron
  - Check status

staggered_timing:
  purpose: Distribute cron load across 15-minute window
  pattern: Site 1=0,15,30,45 | Site 2=1,16,31,46 | Site 3=2,17,32,47
  formula: minute = (offset % 15), offset increments per site
  result: 300 sites = 20 sites per minute (manageable load)

wp-config_modification:
  function: disable_wpcron_in_config()
  location: Before "/* That's all, stop editing! */" comment (proper WordPress convention)
  fallback: After <?php tag if "stop editing" not found
  adds: define('DISABLE_WP_CRON', true);
  safety: Removes existing entries first, backup created, verification, rollback on failure
  format: User crontabs (crontab -u $user) not system crontab

domain_lookup_method:
  # Fixed 2025-11-10 - Two-step lookup process
  method_1: Check main_domain in /var/cpanel/userdata/*/main files (YAML: main_domain:)
  method_2: Fallback to search domain-specific files for servername (YAML: servername:)
  skip_files: "*.cache, */main, */cache, */cache.json"
  rationale: cPanel stores main_domain in main files, servername in domain-specific files

cron_job_format: |
  0,15,30,45 * * * * cd /home/user/public_html && /usr/bin/php -q wp-cron.php >/dev/null 2>&1

options:
  1: Scan for WordPress installations
  2: Disable wp-cron for specific domain
  3: Disable wp-cron for specific user (all their WP sites)
  4: Disable wp-cron server-wide (all WordPress sites)
  5: Check wp-cron status
  6: Re-enable wp-cron for specific domain
  7: Re-enable wp-cron for specific user
  8: Re-enable wp-cron server-wide
  0: Return to menu (cancel)

[RECENT_COMMITS]
# Latest changes (2025-11-19)

commit: c79c260
  date: 2025-11-19
  title: Update REFDB_FORMAT.txt with complete multi-panel architecture documentation
  files: REFDB_FORMAT.txt
  changes:
    - Added comprehensive [MULTI_PANEL_ARCHITECTURE] section (139 lines)
    - Documented control panel support status
    - Critical path differences for cPanel/InterWorx/Plesk
    - Database prefix patterns (CRITICAL: InterWorx uses domain prefix not username!)
    - Module classification system (Class A/B/C/D)
    - Refactoring progress tracker (33/38 = 87% complete)
    - Mandatory abstraction libraries reference
    - Standard code patterns (copy-paste ready)
    - Common mistakes to avoid
    - Complete commit history for multi-panel work

commit: 93d4cf9
  date: 2025-11-19
  title: Multi-panel support for 500-error-tracker.sh (Class C refactoring)
  files: modules/website/500-error-tracker.sh
  changes:
    - Added system-detect.sh and user-manager.sh sources
    - Changed DOMLOGS_DIR to use ${SYS_LOG_DIR}
    - Multi-panel domain→user lookup (cPanel/InterWorx/Plesk)
    - Multi-panel log discovery with case statement
    - No hardcoded paths remain

commit: fbce072
  date: 2025-11-19
  title: Consolidate all multi-panel documentation into .sysref (refDB)
  files: .sysref, deleted 3 markdown files
  changes:
    - Deleted MULTI_CONTROL_PANEL_ARCHITECTURE.md
    - Deleted CONTROL_PANEL_QUICK_REFERENCE.md
    - Deleted INTERWORX_COMPATIBILITY_AUDIT.md
    - Consolidated all architecture info into .sysref [MULTI_PANEL_ARCHITECTURE] section
    - Documentation now in proper location (not scattered markdown files)

commit: d657c8a
  date: 2025-11-19
  title: Multi-panel support for website-error-analyzer.sh (Class C refactoring)
  files: modules/website/website-error-analyzer.sh
  changes:
    - Changed DOMLOGS_DIR to use ${SYS_LOG_DIR}
    - Complete PHP error log discovery rewrite (cPanel/InterWorx/Plesk)
    - Complete Apache access log discovery rewrite
    - Replaced /var/cpanel/users lookup with get_user_domains()
    - Multi-panel domain→user lookup
    - 145 insertions, 33 deletions

commit: 8a2d9f5
  date: 2025-11-19
  title: Class D refactoring - Panel version detection in system-health-check.sh
  files: modules/diagnostics/system-health-check.sh
  changes:
    - Enhanced control panel version detection
    - Displays cPanel/Plesk/InterWorx version from SYS_CONTROL_PANEL_VERSION
    - Conditional display based on detected panel

commit: b770487
  date: 2025-11-19
  title: Class B refactoring - Multi-panel log tailing and monitoring
  files: tail-apache-access.sh, tail-apache-error.sh, web-traffic-monitor.sh, network-bandwidth-analyzer.sh
  changes:
    - Complete rewrites for multi-panel log discovery
    - InterWorx: /home/*/var/*/logs pattern
    - Plesk: /var/www/vhosts/system/*/logs pattern
    - Performance optimization (limit to recent files on InterWorx)

commit: 0988224
  date: 2025-11-19
  title: Phase 3 security modules - Multi-panel support
  files: optimize-ct-limit.sh, malware-scanner.sh, live-attack-monitor.sh
  changes:
    - optimize-ct-limit.sh: Removed hardcoded fallback
    - malware-scanner.sh: Multi-panel docroot + log discovery
    - live-attack-monitor.sh: Multi-panel logs + API wrapping

# Latest changes (2025-11-13)

commit: [pending]
  date: 2025-11-13
  title: Complete security intelligence overhaul - Live monitor 2.0
  files: lib/bot-signatures.sh, lib/attack-patterns.sh, lib/ip-reputation.sh, modules/security/live-attack-monitor.sh
  changes:
    - Created lib/bot-signatures.sh (shared bot classification for 60+ bots)
    - Created lib/attack-patterns.sh (shared attack detection for 7 attack types)
    - Enhanced lib/ip-reputation.sh with ban tracking and CSF/iptables integration
    - Updated IP reputation DB format to include BAN_COUNT and LAST_BAN fields
    - Completely rewrote live-attack-monitor.sh as "Intelligence Mode"
    - Added real-time threat scoring (0-100) using bot-analyzer algorithms
    - Integrated IP reputation DB for known threat detection
    - Added bot classification with color coding (green=legit, red=malicious)
    - Implemented attack vector detection (SQL, XSS, RCE, Path Traversal, etc.)
    - Created quick action blocking system with interactive menu
    - Added batch IP blocking (select multiple IPs or auto-block score >= 80)
    - Added ban tracking (shows how many times each IP was banned)
    - CSF integration for temporary bans (1 hour default, auto-expires)
    - iptables fallback with 'at' scheduler for auto-unblock
    - Enhanced dashboard with 4 panels: Intelligence, Attack Vectors, Live Feed, Quick Actions
    - Bot analyzer and live monitor now share intelligence via IP reputation DB
  testing: All libraries tested, syntax verified
  architecture: Bot analyzer learns → IP reputation DB stores → Live monitor queries
  next: Test live monitor in production, update bot-analyzer to use shared libraries

commit: [pending]
  date: 2025-11-13
  title: Add HTTP/HTTPS status code checking to reference database
  files: lib/reference-db.sh, REFDB_FORMAT.txt
  changes:
    - Created check_domain_status() function to test domain HTTP/HTTPS status
    - Integrated status code checking into build_domains_section()
    - Added 3 new fields to DOMAIN records: http_code, https_code, status_summary
    - Status codes checked during database build (not during bot analysis)
    - Progress display while checking domain status codes
    - Improved status classification: 200_OK, REDIRECT, 403_FORBIDDEN, 404_NOT_FOUND, 500_ERROR, 502_BAD_GATEWAY, 503_UNAVAILABLE, TIMEOUT, UNREACHABLE
    - Skip status checks for aliases/subdomains (inherit from parent)
    - Remote MX domains marked as remote_mx (no status check)
  testing: Domain status codes successfully stored in .sysref
  next: Update bot-analyzer.sh to use status codes from .sysref instead of checking live

# Latest changes (2025-11-12)

commit: d5eb8c7
  date: 2025-11-12
  title: Fix ImunifyAV output parsing in malware scanner
  files: modules/security/malware-scanner.sh
  changes:
    - Fixed incorrect scan result retrieval (was getting oldest scan instead of newest)
    - Changed tail -1 to tail -n +2 | head -1 (skip header, get most recent scan)
    - Extract TOTAL_MALICIOUS from scan result directly (field 12)
    - Added number validation to ImunifyAV, ClamAV, and Maldet parsers
    - Now correctly reports realistic file counts (e.g., 3997 files in 69s, not millions)
  testing: Verified with actual ImunifyAV output - parsing works correctly
  bug_ref: BUG_014

# Latest changes (2025-11-10)

commit: 172a115
  date: 2025-11-10
  title: Fix domain lookup in WordPress Cron Manager
  files: modules/website/wordpress/wordpress-cron-manager.sh
  changes:
    - Fixed broken domain lookup (was only searching /var/cpanel/userdata/*/main for servername:)
    - Added two-step lookup: main_domain in main files, then servername in domain files
    - Applied fix to options 2, 5, 6 (all domain lookup locations)
    - Skip cache files during search
  testing: Verified with pickledperil.com - lookup now works correctly

# Latest changes (2025-11-07)

commit: 56776a1
  title: Add cancel/back options to all user input prompts
  files: website-error-analyzer.sh, 500-error-tracker.sh, wordpress-cron-manager.sh
  changes: Added "0) Cancel" to all menus, "(or 0 to cancel)" to all inputs

commit: b9ce90c
  title: Reorganize website management menu with WordPress subdirectory
  files: launcher.sh, wordpress-menu.sh, wordpress-cron-manager.sh
  changes: Created modules/website/wordpress/ subdirectory, WordPress submenu

commit: 4a1285d
  title: Add revert functionality to WordPress Cron Manager
  changes: Options 6,7,8 for reverting wp-cron changes

commit: e893171
  title: Add safe wp-config.php modification with validation
  changes: Created disable_wpcron_in_config() with backup/rollback

commit: c559bfe
  title: Add WordPress Cron Manager with intelligent load distribution
  changes: Initial WordPress cron manager implementation

[GIT_WORKFLOW]
# Standard git operations

check_status: git status
add_all: git add -A
commit_format: |
  git commit -m "Brief summary (50 chars max)

  Changes:
  - Change 1
  - Change 2

  Tested:
  ✓ Test 1
  ✓ Test 2"

IMPORTANT: NEVER add Claude/AI signatures to commits
  - NO "Generated with Claude Code"
  - NO "Co-Authored-By: Claude"
  - NO AI attribution of any kind
  - Keep commits clean and professional

push: git push origin main

[BUGS_FIXED_HISTORY]
# Historical bug fixes - DO NOT REINTRODUCE

BUG_014: ImunifyAV scan results parsing incorrect
  issue: Used tail -1 to get "last scan" but ImunifyAV lists newest first, so was getting oldest scan
  issue: Was reading wrong/stale scan results showing unrealistic file counts
  fix: Changed to tail -n +2 | head -1 (skip header, get first data line = newest scan)
  fix: Extract TOTAL_MALICIOUS (field 12) directly from scan result instead of separate query
  fix: Added validation to ensure parsed values are numbers
  location: modules/security/malware-scanner.sh:673-692
  tested: 2025-11-12 - Correctly shows 3997 files in 69s (not millions in seconds)

BUG_013: Brace redirection blocks variable assignment
  fix: Use exec file descriptor manipulation instead of { } >/dev/null
  location: lib/system-detect.sh:439-445

BUG_012: Cleanup not forcing fresh detection
  fix: Unset all SYS_* vars, re-source libraries
  location: launcher.sh:332-360

BUG_011: Duplicate menu display
  fix: Suppress auto-init output with exec redirect
  location: lib/system-detect.sh:433-445

BUG_010: System detection errors silently suppressed
  fix: Removed 2>/dev/null || true on critical functions
  location: lib/system-detect.sh:435

BUG_009: User list not displaying in selection
  fix: Redirect display to stderr, only username to stdout
  location: lib/user-manager.sh:330-408

BUG_008: Octal number error in timeline (hours 08/09)
  fix: Strip leading zeros with 10#$hour
  location: modules/security/bot-analyzer.sh:1154-1157

BUG_007: find -name pattern -o -name pattern syntax
  fix: find \( -name "*.log" -o -name "*access*" \)
  status: Feature disabled due to performance

BUG_006: Arithmetic operations causing exit
  fix: Changed ((current++)) to current=$((current + 1))
  files: Multiple locations

BUG_005: grep commands failing with set -e
  fix: Added || true to ALL grep in pipes
  files: lib/user-manager.sh, lib/reference-db.sh

[NEXT_PRIORITIES_2025_11_19]

immediate:
  1: Complete Class C refactoring (2 modules remaining)
     - wordpress-cron-manager.sh (33 userdata refs, 9 public_html refs) - MOST COMPLEX
     - wordpress-menu.sh (needs audit)
  2: Test all refactored modules on InterWorx and Plesk systems
  3: Update STATUS_SNAPSHOT to reflect multi-panel support

short_term:
  4: Add Plesk-specific features (expand partial support to full)
  5: Test WordPress cron manager on production server with multiple WP sites
  6: Create additional WordPress management tools (plugin/theme managers)

long_term:
  7: Add DirectAdmin/CyberPanel support (future panels)
  8: Email/Slack alert integration
  9: Automated security scanning
  10: Performance trend analysis

[TESTING_CHECKLIST]

before_commit:
  - [ ] bash -n script.sh (syntax check)
  - [ ] Test cancel buttons (enter 0 at every prompt)
  - [ ] Test direct execution: bash /path/to/script.sh
  - [ ] Test via launcher menu navigation
  - [ ] Verify press_enter() at end
  - [ ] Check error handling
  - [ ] Confirm no debug output in production

after_commit:
  - [ ] git status (verify clean)
  - [ ] Test on fresh system (rm .sysref*)
  - [ ] Update this file (REFDB_FORMAT.txt)
  - [ ] Update README.md if user-facing feature

[DEVELOPER_ONBOARDING]
# Quick onboarding for new developers

step1_read_this_section_first: |
  This is the Server Management Toolkit.
  This file (REFDB_FORMAT.txt) is the primary reference document.
  README.md is for end users, this file is for developers.

step2_understand_current_state: |
  Read [STATUS_SNAPSHOT_2025_11_07] to know what works.
  Read [CRITICAL_DESIGN_RULES] - these are mandatory.
  Read [CANCEL_BUTTON_STANDARD] - every script must have this.

step3_file_locations: |
  Use [KEY_FILES_QUICK_MAP] to find things fast.
  Use [DIRECTORY_STRUCTURE_2025_11_07] for overall layout.

step4_making_changes: |
  Follow [MODULE_TEMPLATE] for new scripts.
  Follow [GIT_WORKFLOW] for commits.
  Check [TESTING_CHECKLIST] before committing.

step5_update_this_file: |
  After making changes, update:
  - [STATUS_SNAPSHOT_2025_11_07]
  - [RECENT_COMMITS]
  - [NEXT_PRIORITIES_2025_11_07]
  - [META] updated date

critical_rules_never_break:
  - Every menu MUST have "0) Cancel"
  - Every text input MUST accept "0" to cancel
  - Always call press_enter() at script end
  - Use print_* functions not echo for status
  - Add || true to grep/find that might not match
  - Never use set -u (too strict)
  - Never use { } >/dev/null on critical functions

[SHARED_RESOURCES]

ip_reputation:
  file: lib/ip-reputation.sh
  functions: is_known_bot(), should_filter_ip(), log_ip_threat()
  purpose: Centralized IP tracking across all security modules

reference_database:
  file: lib/reference-db.sh
  storage: /root/server-toolkit/.sysref
  ttl: 1 hour
  purpose: Cross-module intelligence sharing (WordPress, domains, users, health)

user_manager:
  file: lib/user-manager.sh
  function: select_user_interactive("Prompt text")
  features: Arrow-key menu, search (type S [text]), domain display
  returns: $SELECTED_USER variable

common_functions:
  file: lib/common-functions.sh
  functions: print_banner(), print_success(), print_error(), print_warning(), print_info(), press_enter()
  colors: GREEN, RED, YELLOW, CYAN, BOLD, NC (auto-disabled if not TTY)

[MULTI_PANEL_ARCHITECTURE]
# MAJOR REFACTORING: 2025-11-19
# Supporting cPanel, Plesk, InterWorx, and standalone Apache

status: 38/38 modules complete (100% DONE!)
updated: 2025-11-19
completion_date: 2025-11-19

# Control Panel Support Levels
panels:
  cpanel: Full support (primary platform)
  interworx: In progress (phases 1-3 complete)
  plesk: Partial support (needs expansion)
  standalone: Basic support (no control panel)

# CRITICAL PATH DIFFERENCES (MUST MEMORIZE)
paths:
  docroot:
    cpanel: /home/USER/public_html
    interworx: /home/USER/DOMAIN/html
    plesk: /var/www/vhosts/DOMAIN/httpdocs

  access_logs:
    cpanel: /var/log/apache2/domlogs/DOMAIN
    interworx: /home/USER/var/DOMAIN/logs/transfer.log  # VERIFIED: InterWorx uses 'transfer.log' not 'access_log'
    plesk: /var/www/vhosts/system/DOMAIN/logs/access_log

  error_logs:
    cpanel: /var/log/apache2/domlogs/DOMAIN-error_log
    interworx: /home/USER/var/DOMAIN/logs/error_log
    plesk: /var/www/vhosts/system/DOMAIN/logs/error_log

  user_config:
    cpanel: /var/cpanel/users/USER
    interworx: /etc/httpd/conf.d/vhost_*.conf
    plesk: plesk bin commands

  domain_map:
    cpanel: /etc/userdatadomains
    interworx: vhost configs + SuexecUserGroup
    plesk: plesk bin subscription --info

# CRITICAL DATABASE PREFIX PATTERN (MOST IMPORTANT!)
database_prefixes:
  cpanel: username_dbname
  interworx: username_dbname  # SAME AS CPANEL! (verified from official docs)
  plesk: appname_RANDOM  # e.g., wp_i75pa (VERIFIED: real server 2025-11-20)

# Module Classification System
classes:
  A: Panel-agnostic (7 modules) - No changes needed
  B: System detection only (6 modules) - Use SYS_LOG_DIR
  C: User/domain management (6 modules) - Complex refactoring
  D: Panel-specific features (2 modules) - Conditional execution
  Acronis: Backup suite (13 modules) - No changes needed

# Class C Refactoring Progress (6/6 complete - 100%!)
class_c_complete:
  - website-error-analyzer.sh (commit d657c8a) - Multi-panel PHP + Apache logs
  - 500-error-tracker.sh (commit 93d4cf9) - Multi-panel log discovery
  - wordpress-cron-manager.sh (commit 90ee755) - MOST COMPLEX - Full WordPress discovery
  - wordpress-menu.sh (already compliant) - Menu only, no hardcoded paths
  - malware-scanner.sh (previous commit) - Multi-panel docroot + log discovery
  - optimize-ct-limit.sh (previous commit) - Removed hardcoded fallback

# MANDATORY ABSTRACTION LIBRARIES
required_libraries:
  system-detect.sh:
    exports: SYS_CONTROL_PANEL, SYS_LOG_DIR, SYS_CONTROL_PANEL_VERSION
    values: cpanel|interworx|plesk|standalone
    usage: source at top of script, use in case statements

  user-manager.sh:
    get_user_info: Returns USER_EXISTS, PRIMARY_DOMAIN, ALL_DOMAINS, HOME_DIR
    get_user_domains: Returns newline-separated domain list
    get_user_databases: Returns database list for user
    usage: NEVER grep /var/cpanel/users directly

# STANDARD CODE PATTERNS (COPY THESE)
patterns:
  log_discovery: |
    case "$SYS_CONTROL_PANEL" in
        cpanel)
            find "$SYS_LOG_DIR" -type f -name "*.com" 2>/dev/null
            ;;
        interworx)
            find /home/*/var/*/logs -type f -name "access_log" 2>/dev/null
            ;;
        plesk)
            find /var/www/vhosts/system/*/logs -type f -name "access_log" 2>/dev/null
            ;;
        *)
            [ -f "/var/log/httpd/access_log" ] && echo "/var/log/httpd/access_log"
            ;;
    esac

  domain_to_user: |
    case "$SYS_CONTROL_PANEL" in
        cpanel)
            user=$(grep "^${domain}:" /etc/userdatadomains | cut -d: -f2 | awk -F'==' '{print $1}')
            ;;
        interworx)
            user=$(grep -l "ServerName ${domain}" /etc/httpd/conf.d/vhost_*.conf | \
                   xargs grep "SuexecUserGroup" | awk '{print $2}')
            ;;
        plesk)
            user=$(plesk bin subscription --info "$domain" | grep "Owner" | awk '{print $2}')
            ;;
    esac

  api_calls: |
    if [ "$SYS_CONTROL_PANEL" = "cpanel" ]; then
        whmapi1 some_command
    else
        print_warning "Feature requires cPanel"
        return 1
    fi

# COMMON MISTAKES TO AVOID
mistakes:
  hardcoded_paths: NEVER use /var/log/apache2/domlogs or /home/user/public_html
  cpanel_only_apis: NEVER use whmapi1/uapi without panel check
  missing_source: Class B/C modules MUST source system-detect.sh AND user-manager.sh
  fallback_paths: NO fallbacks - fail explicitly with clear message
  userdata_grep: NEVER grep /var/cpanel/userdata or /var/cpanel/users

# Refactoring Commits
commits:
  - Phase 1: user-manager.sh InterWorx support (819865b)
  - Phase 2: bot-analyzer.sh + firewall detection (b86aa14)
  - Phase 3: Security modules (0988224)
  - Class B: Log directory refactoring (b770487)
  - Class D: Panel version detection (8a2d9f5)
  - website-error-analyzer.sh: Multi-panel (d657c8a)
  - 500-error-tracker.sh: Multi-panel (93d4cf9)
  - wordpress-cron-manager.sh: Multi-panel (90ee755) - MOST COMPLEX
  - Documentation consolidation (fbce072)
  - Completion: 100% (9af657e)

[TESTING_REQUIREMENTS]
# What needs verification on real InterWorx/Plesk servers
# Created: 2025-11-19

critical_interworx_verification:
  filesystem:
    - VERIFIED Home: /home/USERNAME/
    - VERIFIED Docroot: /home/USERNAME/DOMAIN/html/
    - VERIFIED Access logs: /home/USERNAME/var/DOMAIN/logs/transfer.log (HTTP)
    - VERIFIED Access logs SSL: /home/USERNAME/var/DOMAIN/logs/transfer-ssl.log (HTTPS)
    - VERIFIED Error logs: /home/USERNAME/var/DOMAIN/logs/error.log (HTTP)
    - VERIFIED Error logs SSL: /home/USERNAME/var/DOMAIN/logs/error-ssl.log (HTTPS)
    - Source: https://appendix.interworx.com/current/nodeworx/general/other/log-file-locations.html

  domain_to_user:
    - Method: grep vhost_*.conf for ServerName + SuexecUserGroup
    - Config: /etc/httpd/conf.d/vhost_DOMAIN.conf
    - Command: grep -l "ServerName domain" /etc/httpd/conf.d/vhost_*.conf | xargs grep SuexecUserGroup

  user_to_domains:
    - Option 1: Parse vhost configs for user's SuexecUserGroup
    - Option 2: Filesystem ls /home/USERNAME/*/html
    - Option 3: Check for InterWorx CLI tools

  database_prefix:
    - VERIFIED: Uses username_ prefix (same as cPanel!)
    - Source: https://appendix.interworx.com/current/siteworx/mysql/database-guide.html
    - Example: username "testuser" → testuser_wp123, testuser_db456
    - InterWorx automatically prefixes with SiteWorx account unix username

  cron_management:
    - Assumed: Standard Linux crontab -u username
    - Verify: May have custom InterWorx cron system

  php_config:
    - How is PHP version selected per domain?
    - Where are PHP-FPM pools?
    - Check vhost configs or separate files

critical_plesk_verification:
  filesystem:
    - Domain root: /var/www/vhosts/DOMAIN/
    - Docroot: /var/www/vhosts/DOMAIN/httpdocs/
    - Access logs: /var/www/vhosts/system/DOMAIN/logs/access_log
    - SSL logs: /var/www/vhosts/system/DOMAIN/logs/access_ssl_log
    - Error logs: /var/www/vhosts/system/DOMAIN/logs/error_log

  domain_to_user:
    - Method: plesk bin subscription --info DOMAIN
    - Look for: Owner: username OR Login: username
    - VERIFY exact output format!

  user_to_domains:
    - Test: plesk bin subscription --list -owner username
    - OR: plesk bin client --info username
    - Find correct command syntax

  database_prefix:
    - CRITICAL: Assumed NO PREFIX
    - Databases: bare names (wp_db, myapp_db)
    - MUST VERIFY on real server!

  cron_management:
    - Check: Standard crontab vs plesk bin cron
    - System user: What user runs PHP processes?
    - CRITICAL for wordpress-cron-manager.sh!

  php_config:
    - PHP versions: /opt/plesk/php/
    - How is version selected per domain?
    - PHP-FPM pools location?

testing_priority_order:
  simple_first:
    1: tail-apache-access.sh - Just find logs
    2: web-traffic-monitor.sh - Monitor logs
    3: website-error-analyzer.sh - Logs + domain→user
    4: 500-error-tracker.sh - Logs + lookups
    5: wordpress-cron-manager.sh - EVERYTHING (most complex test)

commands_to_run_on_test_servers:
  interworx:
    - ls -la /home/
    - ls -la /home/testuser/
    - ls -la /etc/httpd/conf.d/vhost_*.conf
    - grep SuexecUserGroup /etc/httpd/conf.d/vhost_testdomain.conf
    - mysql -e "SHOW DATABASES;" | grep testdoma
    - crontab -u testuser -l
    - ls -la /usr/local/interworx/bin/
    - find /home -name wp-config.php | head -5

  plesk:
    - ls -la /var/www/vhosts/
    - ls -la /var/www/vhosts/testdomain.com/
    - plesk bin subscription --info testdomain.com
    - plesk bin subscription --list
    - plesk bin --help
    - mysql -e "SHOW DATABASES;"
    - ps aux | grep php-fpm | head -5
    - ls -la /opt/plesk/php/
    - find /var/www/vhosts -name wp-config.php | head -5

unknowns_blocking_full_support:
  interworx:
    - ✅ RESOLVED: Database prefix is username_ (verified from docs)
    - ✅ RESOLVED: File paths all verified from official docs
    - ✅ RESOLVED: Log file is 'transfer.log' NOT 'access_log' (TESTED: real server 2025-11-20)
    - ✅ RESOLVED: Logs are symlinks to dated files with auto-rotation/compression
    - ✅ RESOLVED: Domain→User lookup via vhost configs WORKS
    - ✅ RESOLVED: User→Domains lookup WORKS (both methods)
    - ✅ RESOLVED: Standard crontab works (crontab -u USER)
    - ✅ TESTED: InterWorx 6.14.5 - ALL assumptions verified
    - PHP version in vhost config (# iw-php-key: /opt/remi/php73) - works, non-critical

  plesk:
    - ✅ RESOLVED: Database has prefix pattern appname_RANDOM (e.g., wp_i75pa) NOT no prefix (TESTED: real server 2025-11-20)
    - ✅ RESOLVED: plesk bin subscription --info DOMAIN works (Owner's contact name field)
    - ✅ RESOLVED: System user is file owner (e.g., admin_ftp) NOT www-data (TESTED: obsidian.pleskalations.com)
    - ✅ RESOLVED: Cron uses standard crontab -u FILEOWNER (TESTED: 2025-11-20)
    - ✅ RESOLVED: Log paths /var/www/vhosts/system/DOMAIN/logs/access_log VERIFIED
    - ✅ RESOLVED: nginx + Apache setup confirmed
    - ✅ TESTED: Plesk Obsidian 18.0.61.5 - ALL assumptions verified

################################################################################
# TESTING & VALIDATION PHASE
################################################################################

testing_phase_status:
  phase: "Testing & Validation"
  date_started: "2025-11-20"
  refactoring_complete: true
  modules_refactored: "38/38 (100%)"

validation_scripts:
  location: "/root/server-toolkit/testing/"

  interworx_validator:
    script: "validate-interworx.sh"
    tests: 13
    validates:
      - Control panel detection
      - File system structure (/home/USER/DOMAIN/html/)
      - Virtual host configuration
      - Domain→User lookup (vhost configs)
      - User→Domains lookup (2 methods)
      - Database prefix (username_)
      - Cron system (standard crontab)
      - PHP configuration
      - WordPress detection
      - InterWorx CLI tools
      - WordPress file permissions & cron user testing
      - Directory structure visualization
      - Comprehensive system documentation
    output: "/tmp/interworx-validation-results.txt"
    status: "TESTED on real server - all assumptions verified"

  plesk_validator:
    script: "validate-plesk.sh"
    tests: 15
    validates:
      - Control panel detection
      - File system structure (/var/www/vhosts/DOMAIN/httpdocs/)
      - Log file locations (/var/www/vhosts/system/DOMAIN/logs/)
      - plesk bin commands
      - Domain→User lookup (plesk bin subscription --info)
      - User→Domains lookup (plesk bin subscription --list)
      - Database prefix pattern
      - System user for web processes (CRITICAL!)
      - Cron system with actual write/restore testing (CRITICAL!)
      - PHP configuration
      - WordPress detection
      - Apache/nginx configuration
      - WordPress file permissions & wp-config.php access
      - Directory structure visualization
      - Comprehensive system documentation
    output: "/tmp/plesk-validation-results.txt"
    status: "TESTED on real server - all assumptions verified"

  documentation:
    file: "testing/README.md"
    contains:
      - Quick start guide
      - What gets validated
      - How to interpret results
      - Testing priority (4 phases)
      - Known issues and limitations
      - Next steps

testing_priority:
  phase_1: "Run validation scripts on real InterWorx/Plesk servers"
  phase_2: "Test simple Class B modules (log discovery)"
  phase_3: "Test complex Class C modules (user/domain management)"
  phase_4: "Production readiness and performance testing"

next_action_required:
  1. "Get access to InterWorx test server"
  2. "Get access to Plesk test server"
  3. "Run validate-interworx.sh and collect results"
  4. "Run validate-plesk.sh and collect results"
  5. "Fix any issues found during validation"
  6. "Test real modules on validated servers"

################################################################################
# UPDATES SINCE 2025-11-20
################################################################################

[UPDATE_2025_12_02_PHP_OPTIMIZER]
# Major feature addition: PHP Configuration Optimizer
# 7 phases of development completed over 2 days

new_components:
  lib/php-detector.sh: |
    - 428 lines, 17 exported functions
    - Detects PHP versions, binaries, and config files per domain
    - Supports cPanel (ea-php, MultiPHP), InterWorx, Plesk, standalone
    - Finds php.ini at 4 priority levels (.user.ini, home, pool, system)
    - Locates PHP-FPM pool configs for all control panels
    - Functions: detect_php_version_for_domain, find_php_ini, find_fpm_pool_config, etc.

  lib/php-analyzer.sh: |
    - 940 lines, 14 exported functions
    - Analyzes PHP performance metrics and generates recommendations
    - OPcache hit rate calculation with division-by-zero protection
    - 7-day historical error log analysis for max_children issues
    - Memory usage analysis per PHP-FPM process
    - Process manager statistics (pm.max_children, start/min/max spare)
    - Functions: get_opcache_stats, check_max_children_errors, recommend_max_children, etc.

  lib/php-config-manager.sh: |
    - 509 lines, 14 exported functions
    - Backup/restore/modify PHP configurations safely
    - Timestamped backups with metadata in /root/server-toolkit/backups/php/
    - Graceful PHP-FPM reload for zero downtime
    - sed-based configuration modification
    - Functions: backup_user_php_configs, restore_from_backup, modify_fpm_pool_setting, reload_php_fpm, etc.

  modules/performance/php-optimizer.sh: |
    - 1,083 lines, interactive menu system
    - 9 menu options for PHP analysis and optimization
    - Option 4: Full apply workflow with auto-backup and rollback
    - User confirmation required for ALL changes
    - Auto-backup before modifications
    - Graceful PHP-FPM reload (not restart)
    - Verification and rollback instructions

menu_integration:
  location: "Performance & Diagnostics → Option 9"
  path: "Main Menu (4) → Performance & Diagnostics (9) → PHP Configuration Optimizer"

php_optimizer_options:
  1: "Analyze All Domains - Server-wide PHP analysis"
  2: "Analyze Single Domain - Per-domain analysis"
  3: "Show OPcache Statistics - OPcache performance metrics"
  4: "Optimize Domain - Main action menu with apply workflow"
  5: "View PHP Error Logs - Error log viewer with filtering"
  6: "PHP Version Summary - Version distribution report"
  7: "Find Configuration Files - Config file discovery"
  b: "Backup Configurations - Manual backup creation"
  r: "Restore from Backup - Rollback capability"
  q: "Quit"

option_4_workflow:
  step_1: "Select domain from list"
  step_2: "Display current configuration"
  step_3: "Show recommendations with explanations"
  step_4: "User confirms: Apply these recommendations? (y/n)"
  step_5: "If yes: Create timestamped auto-backup"
  step_6: "Apply changes to PHP-FPM pool config"
  step_7: "User confirms: Restart PHP-FPM now? (y/n)"
  step_8: "If yes: Gracefully reload PHP-FPM (zero downtime)"
  step_9: "Verify PHP-FPM service is running"
  step_10: "Display backup location for rollback"

metrics_tracked:
  pm_settings:
    - "pm.max_children - FPM process limit"
    - "pm.start_servers - Initial processes"
    - "pm.min_spare_servers - Minimum idle"
    - "pm.max_spare_servers - Maximum idle"
    - "pm.max_requests - Process recycling"

  memory_settings:
    - "memory_limit - PHP script memory cap"
    - "upload_max_filesize - Upload size limit"
    - "post_max_size - POST data limit"

  timeout_settings:
    - "max_execution_time - Script timeout"
    - "max_input_time - Input parsing timeout"

  opcache_settings:
    - "opcache.memory_consumption - OPcache memory"
    - "opcache.interned_strings_buffer - String buffer"
    - "opcache.max_accelerated_files - Cached file limit"
    - "opcache.enable - OPcache on/off"
    - "opcache.revalidate_freq - Cache validation"

  performance_metrics:
    - "OPcache hit rate - hits / (hits + misses)"
    - "max_children errors - 7-day frequency"
    - "Active PHP-FPM processes - Current load"
    - "Memory per process - Average consumption"

safety_features:
  - "User confirmation required for ALL changes"
  - "Auto-backup BEFORE any modifications"
  - "Graceful reload (not restart) for zero downtime"
  - "Verification that service is running"
  - "Clear rollback instructions with backup location"
  - "No automatic changes without explicit approval"

git_commits:
  - "Phase 1: Create lib/php-detector.sh (detection functions)"
  - "Phase 2: Create lib/php-analyzer.sh (analysis engine)"
  - "Phase 3: Create modules/performance/php-optimizer.sh (main script)"
  - "Phase 4: Implement backup/restore system with PHP-FPM restart"
  - "Phase 5 & 6: Implement apply/action menu with auto-backup"
  - "Phase 7: Integrate PHP Configuration Optimizer into main menu"

file_statistics:
  total_lines: 2960
  total_functions: 45
  files_created: 4
  control_panels_supported: 4

testing_status:
  syntax_validation: "PASS (all files pass bash -n)"
  logic_validation: "PASS (division-by-zero protection, error handling)"
  path_resolution: "PASS (verified)"
  menu_integration: "PASS (tested)"
  live_server_testing: "PENDING"

standards_violations:
  bash_strict_mode: "MISSING - No 'set -eo pipefail' in any PHP optimizer files"
  messaging_functions: "VIOLATION - Using cecho/echo -e (198 instances) instead of print_success/print_error"
  cancel_buttons: "MISSING - Main menu has 'q) Quit' but should use '0) Cancel' pattern"
  press_enter: "UNKNOWN - Need to verify press_enter() called at script exit"

  fix_required: "Yes - refactor to use common-functions.sh messaging and add cancel buttons"

future_enhancements:
  - "MySQL Config Optimizer (similar system for MySQL/MariaDB)"
  - "Redis/Memcached Setup (object caching setup scripts)"
  - "Apache/Nginx Optimizer (web server tuning - revisit later)"

not_planned:
  - "CDN integration (user declined)"
  - "SSL/TLS optimizer (user declined)"

[UPDATE_2025_12_03_DOCUMENTATION]
# Documentation cleanup and standardization

changes:
  - "Removed AI attribution from git commits (per user instructions)"
  - "Updated README.md with PHP optimizer feature"
  - "Created docs/DEVELOPMENT_LOG.md (MISTAKE - should use REFDB_FORMAT.txt)"
  - "Deleted random docs files, consolidated into REFDB_FORMAT.txt"
  - "Established: REFDB_FORMAT.txt is THE developer documentation file"

documentation_policy:
  primary_file: "REFDB_FORMAT.txt (this file)"
  user_docs: "README.md (for end users)"
  no_random_files: "Do not create random .md files in docs/"
  update_frequency: "After EVERY significant change"

git_commit_policy:
  no_ai_markers: "Never add AI attribution to commits"
  no_robot_emoji: "Never use 🤖 in commits"
  no_coauthored: "Never add Co-Authored-By: Claude"
  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"

[UPDATE_2025_12_03_DOMAIN_DETECTION_BUG]
# CRITICAL bug fix - PHP optimizer showing 0 domains

comprehensive_analysis_findings:
  agent_used: "general-purpose subagent"
  files_analyzed: "php-detector.sh, php-analyzer.sh, php-optimizer.sh, user-manager.sh"
  bugs_found: 8
  severity_breakdown: "1 CRITICAL, 2 HIGH, 3 MEDIUM, 2 LOW"

critical_bug_fixed:
  file: "lib/user-manager.sh"
  function: "get_cpanel_user_domains()"
  lines: "254, 258"

  problem: |
    grep -F ": ${username}" /etc/trueuserdomains | grep -F "$username\$"
    - grep -F means 'fixed string match' (NO REGEX)
    - Pattern "$username\$" was looking for literal backslash-dollar character
    - Since no lines contain literal "\$", function returned NOTHING

  fix: |
    grep -F ": ${username}" /etc/trueuserdomains | grep "${username}$"
    - Removed -F from second grep (enable regex mode)
    - Now $ correctly matches end-of-line

  impact:
    before_fix: "0 domains analyzed, 0MB memory shown, ALL features broken"
    after_fix: "Domains detected correctly, script functional"

  commit: "f389d82"

remaining_high_priority_bugs:
  bug_1:
    severity: "HIGH"
    file: "lib/php-analyzer.sh"
    lines: "138, 391, 394, 395, 425, 479, 621"
    issue: "Uses bc command for floating point math - not installed on all systems"
    fix: "Replace with bash integer arithmetic: [ \"\${hit_rate%%.*}\" -lt 90 ]"

  bug_2:
    severity: "HIGH"
    file: "lib/php-detector.sh + lib/php-analyzer.sh"
    function: "get_fpm_memory_usage() + calculate_memory_per_process()"
    lines: "php-detector.sh:273, php-analyzer.sh:202-211"
    issue: "get_fpm_memory_usage returns single value, but caller expects 'avg_kb|total_mb' format"
    fix: "Rewrite get_fpm_memory_usage to calculate and return both values"

medium_priority_bugs:
  bug_3:
    file: "php-analyzer.sh"
    line: 536
    issue: "detect_php_version_for_domain called with 1 param, needs 2 (domain, username)"

  bug_4:
    file: "php-optimizer.sh"
    line: 113
    issue: "Same as bug_3 - missing username parameter"

  bug_5:
    file: "php-optimizer.sh"
    lines: "407, 472"
    issue: "Missing empty checks before numeric comparisons"

low_priority_bugs:
  bug_6:
    file: "php-optimizer.sh"
    lines: "1050-1055"
    issue: "Dead code - backup_array populated in loop then overwritten by mapfile"

testing_status:
  before_fixes: "Script loaded but showed 0 domains, 0 memory usage"
  after_critical_fix: "Domains now detected, ready for functional testing"
  next_step: "Fix remaining bugs then test all 9 menu options"

[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 SCRIPT_DIR bug fix - now runs successfully)
################################################################################