diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ad419d7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,45 @@
+# Zelda Dungeon
+
+A top-down, Legend of Zelda-style dungeon crawler with procedurally generated dungeons. Browser-first (plain Canvas + JS), with an optional Electron wrapper.
+
+> Personal prototype project — functional, but not polished.
+
+## Features
+
+- Procedural dungeon generation (seeded, reproducible) with 100 dungeon definitions
+- Room-based exploration with locked doors, keys, levers, and push-block puzzles
+- 22 enemy types with distinct stats and AI behaviors
+- 12 weapons with different damage, range, and effects
+- Boss encounter per dungeon
+- Items: potions, heart pieces, arrows, bombs
+- Dungeon themes (Forest, Desert, Mountain, and more)
+- Save system (Electron build)
+- Runs in any modern browser — no build step required
+
+## Project Structure
+
+```
+src/
+├── core/        constants, seeded RNG (mulberry32), utilities
+├── data/        dungeons, themes, enemies, bosses, weapons, items
+├── generator/   dungeon, room, and puzzle generation
+├── game/        game state and combat
+├── input/       keyboard handling
+├── rendering/   canvas rendering
+├── menu/        dungeon selection
+└── save/        save/load (Electron)
+```
+
+See `PLAN.md` for the full design document.
+
+## Running
+
+```bash
+npm install
+npx serve .          # browser
+npm start            # Electron
+```
+
+## Status
+
+Working prototype. Built as an experiment in procedural generation and browser game development; not actively maintained.