diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f0341b9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,13 @@
+# hello
+
+this is my attempt at managing a common configuration between multiple machines, including my main study (mini)pc as well as my old laptop and perhaps later my gaming pc.
+
+i have purposefully removed and avoided home-manager, because i never ended up utilizing it much. so here is my way to version control and handle my dot files across multiple machines, by deploying a little scripting and some symlinks. let's see how this works. 
+
+# overview
+
+- `hosts/` contains the machine-specific configurations
+- `dotfiles/` contains various configuration files to be placed in `~/.config` on a fresh install.
+- `modules/` contains nixos modules to be imported by machines for a modular configuration with all the shared config found in `modules/base.nix`
+- `install-dotfiles.nu` is a shell script that adds symlinks to `.config/<subdir>/<configfile>` for all `dotfiles/<subdir>/<configfile>`
+