diff --git a/build-instructions.md b/build-instructions.md
new file mode 100644
index 0000000..ab5cd15
--- /dev/null
+++ b/build-instructions.md
@@ -0,0 +1,64 @@
+# NOXOS Build Instructions
+
+**DISCLAIMER:** To build this project you need a linux system (WSL could work for Windows users, but I haven't tested it).
+
+## Workspace setup
+First create a directory and name it something like `noxos`.
+Then clone at least the following repositories into that directory:
+
+```bash
+git clone https://git.nerdcult.net/noxos/kernel
+git clone https://git.nerdcult.net/noxos/libraries
+git clone https://git.nerdcult.net/noxos/userspace
+git clone https://git.nerdcult.net/noxos/drivers
+```
+
+After that `cd` into the `kernel` directory.
+
+There are a few tools required, that need to be installed:
+* **gcc** - compiler
+* **ld** - linker
+* **nasm** - assembler
+* **cmake** - build system
+* **xorriso** - ISO creation tools
+* **qemu** - emulator
+* **ovmf** - UEFI firmware
+
+you can check if you have all tools installed, with `./build.sh check`.
+
+# Compiling NOXOS
+The build system is based on CMake and uses a bash script to automate the kernel, libraries and drivers compilation and image creation process.
+
+You can run the script with the following command:
+```bash
+./build.sh
+```
+
+All temporary data will be written into a directory called `build`.
+
+If the Bootloader ([limine](https://github.com/limine-bootloader/limine)) isn't downloaded yet, the script will download it.
+
+The final ISO file will be written to the `build` directory.
+
+# Running NOXOS
+After compiling, you can run NOXOS using `/run.sh`.
+
+## BIOS Emulation
+To emulate a BIOS system, you can run `./run.sh bios`.
+
+# Debugging
+## Logs
+When running through the script, qemu is configured to write the kernels logs to *STDOUT* and a file called *noxos.log*.
+
+## GDB
+You can connect GDB to qemu.
+To achieve this, run `./run.sh debug`.
+QEMU will wait until you connect GDB to it as a 'remote' target on `localhost:1234`.
+```bash
+gdb build/cmake/kernel/kernel
+target remote localhost:1234
+c
+```
+(note, that the last to commands have to be 'executed' in gdb not in your shell)
+
+**Warning:** QEMU + GDB debugging seems to be kinda broken after an update.
\ No newline at end of file
diff --git a/kernel/build-instructions.md b/kernel/build-instructions.md
deleted file mode 100644
index 46fc75a..0000000
--- a/kernel/build-instructions.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# Build Instructions
-
-**DISCLAIMER:** To build this project you need a linux system (WSL could work for windows users, but I haven't tested it)
-
-First you need to clone the repository:
-
-`git clone https://git.nerdcult.net/noxos/kernel`
-
-then there are a few tools required, that need to be installed:
-* **gcc** - compiler
-* **ld** - linker
-* **nasm** - assembler
-* **cmake** - build system
-* **xorriso** - ISO creation tools
-* **qemu** - emulator
-* **ovmf** - UEFI firmware
-
-you can check if you have all tools installed, with `./build.sh check`.
-
-There is a shell script to setup the workspace and compile.
-Just run it using the following commands:
-```bash
-cd noxos
-./build.sh
-```
-If the Bootloader ([limine](https://github.com/limine-bootloader/limine)) isn't downloaded yet, the script will download it.
-
-The final ISO file will be written to the *build* directory.
-
-To launch the ISO, run the `run.sh` script.
-
-# BIOS Emulation
-To emulate a BIOS system, you can run `./run.sh bios`.
-
-# Debugging
-## Logs
-When running through the script, qemu is configured to write the kernels logs to *STDOUT* and a file called *noxos.log*.
-
-## GDB
-You can connect GDB to qemu.
-To achieve this, run `./run.sh debug`.
-QEMU will wait until you connect GDB to it as a 'remote' target on `localhost:1234`.
-```bash
-gdb build/cmake/kernel/kernel
-target remote localhost:1234
-c
-```
-(note, that the last to commands have to be 'executed' in gdb not in your shell)