diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4a2182c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+# Server Modpack Repository
+
+This repository contains the automated modpack synchronization system for the Minecraft server hosted at jianfgit.xyz.
+
+## Overview
+
+This system automatically:
+1. Monitors the server's mod list (`/tmp/server_mods.txt`)
+2. Creates a minimal client modpack in Modrinth format
+3. Packs the modpack with corresponding TACZ gun packs
+4. Commits and pushes updates to this git repository when changes are detected
+5. Increments version numbers using decimal versioning (0.0.1, 0.0.2, etc.)
+6. Runs every 12 hours via systemd timer
+
+## Files
+
+- `sync_modpack.sh` - Main synchronization script
+- `modpack/modrinth.index.json` - Modrinth format modpack index
+- `state/mods.json` - Current list of required mods (for change detection)
+- `state/gunpacks.json` - Current list of TACZ gun packs (for change detection)
+- `VERSION` - Current version number of the modpack
+- `README.md` - This file
+
+## Modrinth Format
+
+The modpack follows the [Modrinth index format](https://docs.modrinth.com/docs/getting-started/index-format/) with:
+- Format version: 1
+- Game: Forge 1.20.1
+- Environment: Client required, Server unsupported
+- Files: All mods and gunpacks with SHA1 hashes
+
+## Installation & Setup
+
+The system is already configured and running on the server. To manually trigger a sync:
+
+```bash
+/tmp/mod_repo/sync_modpack.sh
+```
+
+## Versioning
+
+- Version format: Major.Minor.Patch (e.g., 0.0.1)
+- Only the patch number is incremented on each change (0.0.1 → 0.0.2 → 0.0.3)
+- This ensures that even small mod changes trigger a new version, preventing version conflicts
+- Critical: Mod versions must match exactly for clients to connect to the server
+
+## TACZ Gun Packs
+
+TACZ gun packs are stored in the `tacz/` directory and included in the modpack index.
+The system automatically detects new gun packs added to this directory.
+
+## Monitoring
+
+Check the status of the automated sync:
+
+```bash
+# Check timer status
+systemctl list-timers --all | grep modpack
+
+# Check service logs
+journalctl -u modpack-sync.service -f
+
+# Check current version
+cat /tmp/mod_repo/VERSION
+```
+
+## Manual Mod Addition
+
+To add a new mod to the server:
+1. Place the mod `.jar` file in `/home/minecraft/mods/`
+2. Add the mod name (without version) to `/tmp/server_mods.txt`
+3. The next sync cycle (or manual run) will detect the change and update the modpack
+
+## Troubleshooting
+
+If the sync fails:
+1. Check the service logs: `journalctl -u modpack-sync.service`
+2. Verify git connectivity: `ssh -T -p 220 git@jianfgit.xyz`
+3. Ensure the script is executable: `ls -l /tmp/mod_repo/sync_modpack.sh`
+4. Check disk space: `df -h /tmp`
+
+## License
+
+This system is internal to the jianfgit.xyz Minecraft server infrastructure.
\ No newline at end of file