diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0b298ed
--- /dev/null
+++ b/README.md
@@ -0,0 +1,36 @@
+# GhostHunt
+
+[![Build](https://git.softwarerat.com/zlaura/ghosthunt/actions/workflows/build.yml/badge.svg)](https://git.softwarerat.com/zlaura/ghosthunt/actions)
+
+A Paper minigame plugin inspired by the classic "Ghosthouse" mode: a small team of **Ghosts** — limited vision (Darkness effect), each spawning with one of several colored keys — hides from a larger team of **Ghost Hunters**, who must find and open the matching key-colored blocks scattered around the map before the ghosts escape or run out the clock.
+
+Built on [GameAPI](https://git.softwarerat.com/zlaura/GameAPI) and [KitAPI](https://git.softwarerat.com/zlaura/KitAPI). Designed with [ItemsAdder](https://www.spigotmc.org/resources/73355/) custom textures in mind; map-specific key-block placement is intended to be handled by a separate map-design tool (not yet implemented).
+
+See [gamedesign.md](gamedesign.md) for the full design notes (German).
+
+## Requirements
+
+- Java 21
+- Maven
+- Spigot API 1.21.11
+
+## Dependencies
+
+- [GameAPI](https://git.softwarerat.com/zlaura/GameAPI)
+- [KitAPI](https://git.softwarerat.com/zlaura/KitAPI)
+
+Both resolved from the private Maven registry at `https://git.softwarerat.com/api/packages/zlaura/maven`.
+
+## Building
+
+```bash
+mvn -B package
+```
+
+## Known issue
+
+This project pins `GameAPI` to `1.6.7-SNAPSHOT`, a version that predates the version now published (`1.6.4-SNAPSHOT` is what actually gets built from the `GameAPI` repo's current source). CI cannot resolve this until the pinned version is reconciled with what's actually available.
+
+## Status
+
+Early development — several game-state classes are still stubs.