diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ed084f9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,44 @@
+# mudlib
+
+A telnet MUD engine. No client needed — just `telnet` and you're in.
+
+Built on telnetlib3, Python 3.12+, managed with uv.
+
+## Quickstart
+
+```
+uv sync
+just run
+```
+
+Then connect: `telnet localhost 6789`
+
+## Commands
+
+```
+just check   # lint + typecheck + test
+just run     # start the server
+just debug   # start with debug logging
+just render  # generate world map HTML
+```
+
+## What's in here
+
+- `src/mudlib/` — the engine (commands, world, combat, rendering, storage)
+- `tests/` — pytest tests
+- `worlds/` — world definitions (yaml/toml)
+- `docs/` — internal knowledge base
+- `DREAMBOOK.md` — vision and wild ideas
+
+## How it works
+
+The world is a toroidal 2D grid of terrain tiles, not discrete rooms. Players
+see a viewport centered on their position. Terrain types have mechanics —
+shallow water slows you, mountains block you, forests hide you.
+
+Combat is timing-based with telegraphed moves and cooldown management, not
+turn-based.
+
+The server runs a tick-based async game loop alongside the telnet server.
+SQLite handles persistence. Session mode stacks filter what reaches the player
+depending on context (exploring, fighting, composing, solving puzzles).