From e2052b4b45e25c345c908ba63480876a1e0faec6 Mon Sep 17 00:00:00 2001
From: Developer <dev@localhost>
Date: Fri, 20 Mar 2026 02:01:52 -0400
Subject: [PATCH] Docs: Clarify cache clearing workflow and what 'total
 entries' means

- Add 'Fresh Deployment' section with git clean -fd command
- Update 'After Git Pull' section to include git clean for safety
- Clarify that 'total entries' in cache is line count, not WordPress count
- Helps users avoid confusion with stale cache on fresh deployments
---
 CACHE_MANAGEMENT.md | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/CACHE_MANAGEMENT.md b/CACHE_MANAGEMENT.md
index 3dfc48d..95e7151 100644
--- a/CACHE_MANAGEMENT.md
+++ b/CACHE_MANAGEMENT.md
@@ -129,6 +129,11 @@ cat .sysref.beta | head -20
 
 # Count records by type
 awk -F'|' '{print $1}' .sysref.beta | sort | uniq -c
+
+# Count total lines (includes headers and all records)
+wc -l .sysref.beta
+# Note: This total includes system records, user records, headers, and blank lines
+# NOT the count of WordPress sites
 ```
 
 ---
@@ -192,16 +197,31 @@ Now when you pull:
 
 ## Recommended Workflow
 
+### Fresh Deployment (First Clone or Migration)
+```bash
+# 1. Clone or navigate to toolkit directory
+cd /root/server-toolkit-beta
+
+# 2. Remove any old untracked files (including stale cache)
+git clean -fd
+
+# 3. Verify no cache files exist
+ls -la .sysref* 2>&1
+
+# 4. Run fresh - cache will be built automatically
+bash launcher.sh --detect-only
+```
+
 ### 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
+# 2. Remove any untracked files from previous versions
+git clean -fd
 
-# 3. Verify detection works
+# 3. Verify detection works (cache auto-clears if launcher.sh changed)
 bash launcher.sh --detect-only
 
 # 4. Run normally