diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7a6beca
--- /dev/null
+++ b/README.md
@@ -0,0 +1,33 @@
+an operating system made in nasm assembly and (in the future) zig, using the zig build system.
+this project is based on [this video series](https://www.youtube.com/playlist?list=PLFjM7v6KGMpiH2G-kT781ByCNC_0pKpPN) by [nanobyte](https://www.youtube.com/@nanobyte-dev)
+
+# HOWTO
+
+## dependencies
+
+this project requires the nasm assembler, mtools for floppy disk generation and zig to build.
+this project uses qemu as the default emulator, but this is optional
+
+## building
+
+```bash
+git clone https://dario48.site/git/Dario48/zos.git
+cd zos
+zig build
+```
+
+## running
+
+- with the default emulator
+
+```bash
+cd zos
+zig build run
+```
+
+- with a different emulator
+
+```bash
+cd zos
+emulator_cmd zig-out/bin/main_floppy.img
+```