diff --git a/KiteStacks Forgejo Automation – Watcher Script Documentation b/KiteStacks Forgejo Automation – Watcher Script Documentation
new file mode 100644
index 0000000..492929f
--- /dev/null
+++ b/KiteStacks Forgejo Automation – Watcher Script Documentation	
@@ -0,0 +1,80 @@
+KiteStacks Forgejo Automation – Watcher Script Documentation
+Overview
+
+The kitestacks-watcher.sh script is a systemd-compatible file watcher for the KiteStacks Homelab. Its main responsibilities:
+
+Watch configured directories for file changes.
+Sync changes to the correct apps/ or clusters/ folder in the repo.
+Automatically bump version in README.md.
+Update versioned documentation and CHANGELOG.md.
+Commit and push changes to either test or main repository.
+Throttle updates to prevent frequent commits when changes are rapid.
+Key Features Added in This Setup
+1. 20-Minute Conditional Throttling
+The script now tracks the last successful push.
+Commits/pushes only happen once every 20 minutes.
+If changes occur multiple times within 20 minutes, they are batched into a single update.
+Logs indicate skipped pushes during throttle:
+[autosync] 2026-06-06 12:50:10 INFO  Throttling active, skipping commit/push for 1190s
+2. Initial Setup Steps
+Navigate to the scripts folder:
+cd ~/kitestacks-homelab-autosync-test/scripts
+Make the watcher script executable:
+chmod +x kitestacks-watcher.sh
+Run manually to test:
+./kitestacks-watcher.sh
+Observe logs for startup confirmation.
+Make a small change in a watched directory (e.g., apps/forgejo/README.md) to trigger the watcher.
+Run in background (detach from terminal):
+mkdir -p ~/logs
+nohup ./kitestacks-watcher.sh > ~/logs/kitestacks-watcher.log 2>&1 &
+Verify process is running:
+ps aux | grep kitestacks-watcher
+tail -f ~/logs/kitestacks-watcher.log
+3. Optional: systemd Service
+
+Create /etc/systemd/system/kitestacks-watcher.service:
+
+[Unit]
+Description=KiteStacks AutoSync Watcher
+After=network.target
+
+[Service]
+Type=simple
+User=kenpat
+WorkingDirectory=/home/kenpat/kitestacks-homelab-autosync-test/scripts
+ExecStart=/home/kenpat/kitestacks-homelab-autosync-test/scripts/kitestacks-watcher.sh
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+
+Enable and start:
+
+sudo systemctl daemon-reload
+sudo systemctl enable kitestacks-watcher.service
+sudo systemctl start kitestacks-watcher.service
+sudo systemctl status kitestacks-watcher.service
+
+View logs:
+
+journalctl -u kitestacks-watcher.service -f
+4. Script Behavior Summary
+Watches directories listed in $WATCH_DIRS.
+Debounce period defined in $DEBOUNCE_SECONDS (default 15s) to batch rapid changes.
+Maps filesystem paths to repo folders (apps/ for Docker apps, clusters/assassin/ for cluster configs).
+Updates README.md version tags and generates versioned docs in docs/.
+Maintains a CHANGELOG.md with automated entries.
+Pushes updates to either test or main repo based on $STATE_FILE.
+Throttle ensures that frequent changes do not flood the repository with commits.
+5. Verification
+Make a change to a file in the watched directories.
+Confirm logs show sync, doc creation, and commit/push.
+Multiple changes within 20 minutes are batched.
+Watch for throttling messages confirming 20-minute delay between pushes.
+6. Notes / Recommendations
+Keep $WATCH_DIRS and $EXCLUDE_PATTERNS properly configured in settings.conf.
+Use logs (~/logs/kitestacks-watcher.log) for debugging.
+Manual testing is recommended after any config changes.
+systemd integration ensures the watcher starts automatically on reboot.
\ No newline at end of file