diff --git a/doc/lex/lexer-states.txt b/doc/lex/lexer-states.txt
new file mode 100644
index 0000000..99a90b5
--- /dev/null
+++ b/doc/lex/lexer-states.txt
@@ -0,0 +1,14 @@
+possible lexer states:
+	STATE_NORMAL
+	STATE_STRING
+	STATE_FSTRING
+	STATE_INTERPOLATION
+
+
+state transitions:
+	STATE_NORMAL + " -> push STATE_STRING
+	STATE_NORMAL + ' -> push STATE_FSTRING
+	STATE_STRING + " -> pop
+	STATE_FSTRING + { -> push STATE_INTERPOLATION, record brace depth
+	STATE_FSTRING + ' -> pop
+	STATE_INTERPOLATION + } (at recorded brace depth) -> pop
\ No newline at end of file