From 92cbd7172a891e8c373e5409f3e7b5aef41ee663 Mon Sep 17 00:00:00 2001
From: Timo <6156589+Shik3i@users.noreply.github.com>
Date: Wed, 22 Apr 2026 11:00:39 +0200
Subject: [PATCH] Add SYNC_GUIDE.md for protocol synchronization documentation

---
 SYNC_GUIDE.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 SYNC_GUIDE.md

diff --git a/SYNC_GUIDE.md b/SYNC_GUIDE.md
new file mode 100644
index 0000000..dad511e
--- /dev/null
+++ b/SYNC_GUIDE.md
@@ -0,0 +1,36 @@
+# KoalaSync Protocol Synchronization Guide (SYNC_GUIDE.md)
+
+## Why do we need to sync?
+KoalaSync uses a "Single Source of Truth" for its communication protocol constants located in the `shared/` directory. However, Chrome Extensions (Manifest V3) are strictly sandboxed and **cannot load or import files from outside their root directory**.
+
+To ensure that the extension and the relay server are always using the exact same event names and protocol versions, we must maintain a mirrored copy of the shared files within the extension folder.
+
+## When should you run the sync script?
+You MUST run the synchronization script in any of the following scenarios:
+1. **After modifying** `shared/constants.js`.
+2. **After modifying** `shared/blacklist.js`.
+3. **Before committing** changes to the repository if any protocol-related files were touched.
+4. **Before deploying** the server or releasing the extension.
+
+## How to sync
+
+### On Windows
+Run the batch script from the repository root:
+```powershell
+.\scripts\sync-constants.bat
+```
+
+### On macOS / Linux
+Run the shell script from the repository root:
+```bash
+./scripts/sync-constants.sh
+```
+
+## What does it do?
+The script performs the following actions:
+1. Ensures the `extension/shared/` directory exists.
+2. Copies `shared/constants.js` to `extension/shared/constants.js`.
+3. Copies `shared/blacklist.js` to `extension/shared/blacklist.js`.
+
+> [!CAUTION]
+> **NEVER** edit the files inside `extension/shared/` directly. They will be overwritten the next time the sync script is run. Always edit the files in the root `shared/` directory and then run the sync script.