diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dbd0392
--- /dev/null
+++ b/README.md
@@ -0,0 +1,36 @@
+# Io calculator
+
+## what?
+
+a small, stack-based calculator/programming language inspired by forth.
+
+## why?
+
+i wanted to learn a little bit about the [Io](https://iolanguage.org/index.html) language. also, i wanted to practice programming in general.
+
+## how?
+
+install the Io interpreter from the linked site. then, run `io main.io`. if you want to check out one of the demo programs, say for instance `program.txt`, run `io main.io program.txt` instead.
+
+running the program will put you into a REPL. you can enter words (whitespace-separated strings) here, and they will be executed in order. here are some of the things you can do:
+
+| word                     | meaning                                                                                                  |
+| -                        | -                                                                                                        |
+| any number               | push the number onto the stack.                                                                          |
+| `+`                      | pop `a`, then `b`, then push `a+b`.                                                                      |
+| `-`                      | pop `a`, then `b`, then push `b-a`.                                                                      |
+| `*`                      | pop `a`, then `b`, then push `a*b`.                                                                      |
+| `:`                      | duplicate the stack top item.                                                                            |
+| `~`                      | swap the two top stack items.                                                                            |
+| `_`                      | pop the stack.                                                                                           |
+| `quit`                   | exit the REPL.                                                                                           |
+| `defun`                  | pop `name`, then turn the entire current stack into a function, and associate `name` with said function. |
+| `clear`                  | empty the stack.                                                                                         |
+| any word prefixed by `'` | push the word without executing it (this is stackable).                                                  |
+| `exec`                   | pop the stack, and execute the popped value as a word.                                                   |
+
+you can read the source code for more info on what builtin words are available, or the example programs to get an idea of how programming this calculator works.
+
+## ideas
+
+- expose the `doword` internal function to the calculator. this would let programs modify its behaviour, for instance to make it possible to declare functions without quoting everything that you don't want to execute at function-construction-time.