diff --git a/README.md b/README.md
new file mode 100644
index 00000000..bb75b2c0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,77 @@
+# Dynmap — NeoForge 1.21.1 Port
+
+Port of [Dynmap](https://github.com/webbukkit/dynmap) to **NeoForge 21.1.219 / Minecraft 1.21.1**.
+
+This standalone build is used for deployment on an ATM10 server. The goal is to eventually submit this as a PR back to the upstream `webbukkit/dynmap` repository.
+
+- **Upstream:** https://github.com/webbukkit/dynmap (branch: `neoforge`)
+- **Fork (for PR):** https://github.com/Cobbert/dynmap
+- **Gitea (this repo):** `Sulkta-Coop/dynmap-neoforge`, branch `neoforge-1.21.1`
+
+---
+
+## Building
+
+Requires Java 21 and Docker (build container: `dynmap-neoforge-build`).
+
+```bash
+# Inside build container
+cd /workspace
+./gradlew shadowJar --no-daemon
+```
+
+Output: `build/libs/Dynmap-neoforge-1.21.1-3.7-SNAPSHOT-Dev-all.jar`
+
+### Memory notes
+- Gradle daemon heap: capped at `-Xmx2g` (see `gradle.properties`)
+- forked javac: capped at `-Xmx3g` (see `build.gradle`)
+- Without these caps, JVM defaults to 25% of host RAM — causes OOM on high-RAM hosts
+
+---
+
+## Changes from upstream `neoforge-1.20.6`
+
+See [CHANGES.md](./CHANGES.md) for the full changelog.
+
+---
+
+## Test status
+
+| Environment | Result |
+|---|---|
+| Vanilla NeoForge 1.21.1 (clean server) | ✅ Passes |
+| ATM10 5.5 (445 mods, NeoForge 21.1.219) | ✅ Passes |
+
+---
+
+## Deployment
+
+Copy the fat jar into the server's `mods/` directory. Remove any old `Dynmap*.jar` first.
+
+```bash
+docker cp build/libs/Dynmap-neoforge-1.21.1-3.7-SNAPSHOT-Dev-all.jar <container>:/data/mods/
+```
+
+> **Note:** Always remove old jars before copying a new one. The container data volume may retain old versions.
+
+---
+
+## Containers (internal, Lucy/Unraid)
+
+| Container | Purpose | Ports |
+|---|---|---|
+| `dynmap-neoforge-build` | Gradle build environment | — |
+| `neoforge-test` | Vanilla NeoForge 1.21.1 test server | 25566 (MC), 8124 (web) |
+| `atm10-55-test` | ATM10 5.5 test server, 445 mods | — |
+| `a6860a8008ed` (prod) | **Production ATM10 — DO NOT TOUCH** | — |
+
+---
+
+## PR Plan
+
+Once ATM10 testing is confirmed:
+1. Mirror all changes to monorepo (`dynmap-upstream/neoforge-1.21.1/`)
+2. Push to `Cobbert/dynmap` fork on GitHub
+3. Open PR: `Cobbert/dynmap:neoforge-1.21.1` → `webbukkit/dynmap:neoforge`
+
+PR description draft is in [DYNMAP.md](https://github.com/Cobbert/dynmap) (workspace copy).