diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e1f468c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,61 @@
+# Spigot Chat Sync
+
+Sync chat messages and death events across Minecraft servers using NATS.
+
+## Features
+- Chat sync across servers
+- Death message sync across servers
+- Per-server display name
+- Legacy color code formatting
+- Loop prevention by server id
+
+## Requirements
+- Spigot 1.21.1+ (Java 21)
+- NATS server
+
+## Configuration
+Edit `src/main/resources/config.yml` or the generated `plugins/SpigotChatSync/config.yml`.
+
+```yml
+server:
+  id: "server-1"
+  name: "Server 1"
+
+nats:
+  url: "nats://localhost:4222"
+
+subjects:
+  chat: "mc.chat.sync"
+  death: "mc.death.sync"
+
+format:
+  chat: "&7[&b{server}&7] &f{player}&7: &f{message}"
+  death: "&7[&b{server}&7] &f{message}"
+```
+
+Only remote messages are formatted; local chat/death output stays unchanged.
+
+## Build
+
+```bash
+mvn package
+```
+
+Or via Docker:
+
+```bash
+make docker-jar
+```
+
+The shaded jar will be in `target/`.
+
+## Usage
+1. Install the jar on each server.
+2. Set a unique `server.id` and a friendly `server.name` on each server.
+3. Point all servers to the same NATS instance.
+
+## Message Placeholders
+- `{server}`: configured server name
+- `{player}`: player name
+- `{message}`: chat or death text
+- `{time}`: local server time in HH:mm