diff --git a/edn/README.md b/edn/README.md
index 5c05a67d..360886b6 100644
--- a/edn/README.md
+++ b/edn/README.md
@@ -1,4 +1,99 @@
-# `tek_edn`
+# `ket`
 
-parser and bindings for tek's configuration language,
-which is based on edn.
+**ket** is the configuration language of **tek**.
+it's based on [edn](https://en.wikipedia.org/wiki/Clojure#Extensible_Data_Notation)
+but without all the features.
+
+## usage
+
+### with `tek_output`
+
+this is a `tek_output` view layout defined using ket:
+
+```edn
+(bsp/s (fixed/y 2 :toolbar)
+  (fill/x (align/c (bsp/w :pool
+    (bsp/s :outputs (bsp/s :inputs (bsp/s :tracks :scenes)))))))
+```
+
+### with `tek_input`
+
+this is a `tek_input` keymap defined using ket:
+
+```edn
+(@u       undo 1)
+(@shift-u redo 1)
+(@e       editor show :pool-clip)
+(@ctrl-a  scene add)
+(@ctrl-t  track add)
+(@tab     pool toggle)
+```
+
+## tokens
+
+ket has 5 "types":
+
+* nil
+* numeric literal
+* symbol
+* key
+* group
+
+### nil
+
+this does nothing.
+
+### numeric literal
+
+numbers are passed through as is. only non-negative integers are supported.
+
+```edn
+0
+123456
+```
+
+### keys
+
+keys are the names of available operations. they look like this:
+
+```edn
+simple-key
+multi-part/key
+```
+
+keys are implemented by the underlying subsystem:
+
+* in `tek_output`, keys are names of layout primitives
+* in `tek_input`, keys are names of commands
+
+### symbols
+
+symbols that start with `:` represent the names of variables
+provided by the `EdnProvide` trait - such as command parameters,
+or entire layout components:
+
+```edn
+:symbol-name
+```
+
+symbols that start with `@` represent keybindings.
+they are parsed in `tek_tui` and look like this:
+
+```edn
+@ctrl-alt-shift-space
+```
+
+### groups
+
+groups represent things like expressions or configuration statements,
+and look like this:
+
+```edn
+(some-key :symbol (some/other-key @another-symbol 123) 456)
+```
+
+## goals
+
+* [ ] const parse
+* [ ] live reload
+* [ ] serialize modified code back to original indentation
diff --git a/tek/src/keys.edn b/tek/src/keys.edn
index bd5aa985..512c4f49 100644
--- a/tek/src/keys.edn
+++ b/tek/src/keys.edn
@@ -2,7 +2,7 @@
 (@shift-u     redo 1)
 (@space       play/toggle)
 (@shift-space play/start-toggle)
-(@e           editor/show :pool-phrase)
+(@e           editor show :pool-clip)
 (@ctrl-a      scene add)
 (@ctrl-t      track add)
-(@tab         pool/toggle)
+(@tab         pool toggle)