diff --git a/docs/images/TOTEM_logo_bright.svg b/docs/images/TOTEM_logo_bright.svg
new file mode 100644
index 0000000..52505a4
--- /dev/null
+++ b/docs/images/TOTEM_logo_bright.svg
@@ -0,0 +1,21 @@
+
+
\ No newline at end of file
diff --git a/docs/images/TOTEM_logo_dark.svg b/docs/images/TOTEM_logo_dark.svg
new file mode 100644
index 0000000..62922b0
--- /dev/null
+++ b/docs/images/TOTEM_logo_dark.svg
@@ -0,0 +1,21 @@
+
+
\ No newline at end of file
diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..129f572
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,28 @@
+
+
+
+
+
+
+
+# ZMK CONFIG FOR THE TOTEM SPLIT KEYBOARD
+
+[Here](https://github.com/GEIGEIGEIST/totem) you can find the hardware files and build guide for the TOTEM.
+
+TOTEM is 38 keys column-staggered split keyboard running [ZMK](https://zmk.dev/). It's meant to be used with a SEEED XIAO BLE or RP2040.
+
+
+
+
+## HOW TO USE
+
+- fork this repo
+- `git clone` your repo, to create a local copy on your PC (you can use the [command line](https://www.atlassian.com/git/tutorials) or [github desktop](https://desktop.github.com/))
+- adjust the totem.keymap file (find all the keycodes on [the zmk docs pages](https://zmk.dev/docs/codes/))
+- `git push` your repo to your fork
+- on the GitHub page of your fork navigate to "Actions"
+- scroll down and unzip the `firmware.zip` archive that contains the latest firmware
+- connect the left half of the TOTEM to your PC, press reset twice
+- the keyboard should now appear as a mass storage device
+- drag'n'drop the `totem_left-seeeduino_xiao_ble-zmk.uf2` file from the archive onto the storage device
+- repeat this process with the right half and the `totem_right-seeeduino_xiao_ble-zmk.uf2` file.
\ No newline at end of file
+