diff --git a/CACHE_MANAGEMENT.md b/CACHE_MANAGEMENT.md
new file mode 100644
index 0000000..3dfc48d
--- /dev/null
+++ b/CACHE_MANAGEMENT.md
@@ -0,0 +1,339 @@
+# Cache Management Guide
+
+## Overview
+
+The Server Toolkit uses caching to avoid repeatedly scanning your system for:
+- WordPress installations
+- Database listings
+- User and domain information
+- System configuration
+- Firewall status
+
+This document explains how caching works and how to manage it.
+
+---
+
+## Cache Basics
+
+### What Gets Cached
+
+The system maintains a **Reference Database** (`.sysref.beta`) containing:
+- **USER records** - All user accounts on server
+- **DOMAIN records** - All domains and their owners
+- **DB records** - All databases and their owners
+- **WP records** - All WordPress installations
+- **SYS records** - System configuration (detected once)
+- **HEALTH records** - Hardware baselines
+
+### Cache Location
+
+**Production:** `.sysref` (for `/root/server-toolkit/`)
+**Development:** `.sysref.beta` (for `/root/server-toolkit-beta/`)
+
+Timestamps: `.sysref.timestamp` and `.sysref.beta.timestamp`
+
+### Cache Lifetime
+
+**TTL (Time To Live): 1 Hour**
+- Cache auto-rebuilds after 1 hour
+- Prevents stale data from being used too long
+- Balances performance vs. freshness
+
+---
+
+## Why You Need to Clear Cache
+
+### Scenario 1: After Git Pull
+```bash
+# You pull the latest dev changes
+cd /root/server-toolkit-beta
+git pull origin dev
+
+# But old cache is still present with stale data:
+# - 29 WordPress sites (from previous system)
+# - Old user list
+# - Outdated domain information
+```
+
+**Solution:**
+```bash
+bash launcher.sh --clear-cache
+```
+
+### Scenario 2: System Configuration Changed
+```bash
+# You added a new WordPress site
+# You installed a new domain
+# You created new databases
+# But cache still shows old data
+```
+
+**Solution:**
+```bash
+bash launcher.sh --clear-cache
+bash launcher.sh --detect-only    # Verify new config detected
+```
+
+### Scenario 3: Moved Between Servers
+```bash
+# You cloned dev branch to a different server
+# But cache contains data from the original server
+```
+
+**Solution:**
+```bash
+bash launcher.sh --clear-cache
+```
+
+---
+
+## Cache Commands
+
+### Clear All Cache
+```bash
+bash launcher.sh --clear-cache
+```
+
+Clears:
+- `.sysref.beta` and `.sysref.beta.timestamp`
+- All temporary files in `tmp/`
+- Next run will auto-rebuild cache
+
+### Force Fresh Detection & Rebuild
+```bash
+bash launcher.sh --detect-only
+```
+
+This command:
+1. Clears detection cache
+2. Re-detects system configuration
+3. Shows detected components
+4. Rebuilds reference database
+
+### Check Cache Status
+```bash
+# See when cache was last built
+ls -la .sysref.beta*
+
+# Check cache age
+stat .sysref.beta.timestamp
+
+# See how much data is in cache
+wc -l .sysref.beta
+```
+
+### View Cache Contents
+```bash
+# See what's in the cache
+cat .sysref.beta | head -20
+
+# Count records by type
+awk -F'|' '{print $1}' .sysref.beta | sort | uniq -c
+```
+
+---
+
+## Automatic Cache Behavior
+
+### On First Run
+1. No cache exists
+2. System detection runs (httpd, MySQL, etc.)
+3. Reference database is built
+4. Cache is created: `.sysref.beta`
+5. Timestamp is recorded: `.sysref.beta.timestamp`
+
+### On Subsequent Runs (Within 1 Hour)
+1. Cache exists and is fresh
+2. No detection runs (uses cached SYS_* variables)
+3. Reference database is read from cache
+4. Data is immediately available
+5. Menu opens instantly
+
+### After 1 Hour
+1. Cache TTL expires
+2. Next run detects system changes
+3. Reference database is rebuilt
+4. New cache is written
+
+---
+
+## Git & Cache Interaction
+
+### Problem: Cache Files in Git
+❌ **Before Fix:**
+```
+.sysref.beta          <- COMMITTED TO GIT
+.sysref.beta.timestamp <- COMMITTED TO GIT
+data/*.dat            <- COMMITTED TO GIT
+```
+
+When you pulled, you got:
+- Old cache with 0 WordPress sites
+- Old database listings
+- Wrong data for your system
+
+### Solution: Proper .gitignore
+✅ **After Fix:**
+```
+.gitignore includes:
+  .sysref.beta          ← NOT committed
+  .sysref.beta.timestamp ← NOT committed
+  /data/                ← NOT committed
+  /tmp/                 ← NOT committed
+  /logs/                ← NOT committed
+```
+
+Now when you pull:
+- No cache files are pulled
+- Fresh system detection runs
+- Your server's actual data is used
+
+---
+
+## Recommended Workflow
+
+### After Git Pull
+```bash
+# 1. Update code from git
+cd /root/server-toolkit-beta
+git pull origin dev
+
+# 2. Clear old cache
+bash launcher.sh --clear-cache
+
+# 3. Verify detection works
+bash launcher.sh --detect-only
+
+# 4. Run normally
+bash launcher.sh
+```
+
+### After System Changes
+```bash
+# 1. Made changes (added domain, installed WordPress, etc.)
+
+# 2. Clear cache
+bash launcher.sh --clear-cache
+
+# 3. Verify changes are detected
+bash launcher.sh --detect-only
+
+# 4. Run normally
+bash launcher.sh
+```
+
+### Daily Operation
+```bash
+# Just run normally - cache auto-expires after 1 hour
+bash launcher.sh
+```
+
+---
+
+## Troubleshooting Cache Issues
+
+### Issue: Data Shows Stale Information
+```bash
+# Step 1: Clear cache
+bash launcher.sh --clear-cache
+
+# Step 2: Verify fresh data
+bash launcher.sh --detect-only
+```
+
+### Issue: WordPress Sites Count is Wrong
+```bash
+# Clear cache and rebuild
+bash launcher.sh --clear-cache
+
+# Check count
+bash launcher.sh --detect-only | grep "WordPress"
+```
+
+### Issue: User/Domain List is Old
+```bash
+# Force complete rebuild
+bash launcher.sh --clear-cache
+
+# Wait for rebuild (takes a few seconds)
+# Then check:
+bash launcher.sh --detect-only
+```
+
+### Issue: Cache File Corrupted
+```bash
+# Remove both cache files
+rm -f .sysref.beta .sysref.beta.timestamp
+
+# Rebuild on next run
+bash launcher.sh --detect-only
+```
+
+---
+
+## Cache Implementation Details
+
+### How Cache Rebuilds
+
+```bash
+# When cache is stale or missing:
+1. initialize_system_detection()      # Detect httpd, MySQL, PHP, etc.
+2. db_ensure_fresh()                  # Check/rebuild reference database
+3. build_reference_database()         # Scan for users, domains, WordPress
+4. Save to .sysref.beta               # Write cache file
+5. Touch .sysref.beta.timestamp       # Record timestamp
+```
+
+Takes 3-10 seconds depending on:
+- Number of users
+- Number of domains
+- Number of WordPress installations
+- System I/O speed
+
+### Cache Size
+
+Typical cache sizes:
+- **10 users, 50 domains, 5 WP sites:** ~5 KB
+- **50 users, 500 domains, 50 WP sites:** ~50 KB
+- **500 users, 5000 domains, 500 WP sites:** ~500 KB
+
+Cache is **text-based** for readability and easy debugging.
+
+---
+
+## Best Practices
+
+### ✅ DO
+
+- Clear cache after system configuration changes
+- Clear cache after pulling git updates
+- Let cache auto-expire naturally (1 hour)
+- Use `--detect-only` to verify after clearing
+- Check cache age if data seems wrong
+
+### ❌ DON'T
+
+- Edit `.sysref.beta` manually (use clear instead)
+- Commit cache files to git (now impossible with .gitignore)
+- Rely on cache being more than 1 hour old
+- Delete cache during active operations
+- Copy cache between different servers (rebuild instead)
+
+---
+
+## Summary
+
+| Task | Command |
+|------|---------|
+| **Clear all cache** | `bash launcher.sh --clear-cache` |
+| **Check detection** | `bash launcher.sh --detect-only` |
+| **See cache age** | `stat .sysref.beta.timestamp` |
+| **View cache contents** | `cat .sysref.beta` |
+| **Count cache entries** | `wc -l .sysref.beta` |
+
+---
+
+**Last Updated:** 2026-03-20
+**Cache Version:** 1.0
+**TTL:** 1 hour
+**Last Clear:** After git pull or major system changes