diff --git a/preview.png b/preview.png
new file mode 100644
index 0000000..dafd999
Binary files /dev/null and b/preview.png differ
diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..fc35d21
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,40 @@
+### dotfiles
+
+![preview](preview.png)
+
+these are my dotfiles, custom desktop entries, and scripts for my personal machine
+to use these verbatim, clone the repo and merge it onto root with rsync, like below.
+
+please note that these are provided without guarantee or warranty of any kind.
+please back up all your files before using these!
+
+```
+git clone https://gitea.bubbletea.dev/shibao/dotfiles.git
+rsync -a dotfiles/* /
+```
+
+thank you!
+
+### requirements
+
+this isn't an exhaustive list.
+please let me know if i've forgotten one!
+
+- sway (de)
+- waybar (topbar)
+- swayidle (idle daemon)
+- swaylock (lockscreen)
+- alacritty (terminal)
+- rofi (launcher)
+- moki (notification daemon)
+- kanshi (screen config manager)
+- lxpolkit (auth helper)
+- nm-applet (network gui manager)
+- playerctl (music controller)
+- materia-dark (gtk theme)
+- papirus-dark (icon theme)
+- fctix (intl. keyboard input)
+- grim (screenshots on wayland)
+- neovim (editor)
+- direnv (per-directory environment variables)
+- asdf (language agnostic dependency management)