diff --git a/README.md b/README.md
index 7ca125d..66fdc52 100644
--- a/README.md
+++ b/README.md
@@ -8,57 +8,12 @@ Bowtie is designed to support a WIP [book](http://lambdakit.com/), but those are
 
 # In this repo
 
-## [./bowtie](./bowtie)
-
 ![modules](./bowtie/misc/generated/modules.svg)
 
-![sloc-bowtie](./bowtie/misc/generated/sloc-bowtie.svg)
-
-Reference implementation. Parser, typechecker, and tree-walking evaluator (WIP).
-
-## [./spec](./spec)
-
-Informal specification with a description of the language and test examples (WIP).
-
-## [./example-lib](./example-lib)
-
-Bowtie code!
-
-## [./example-app](./example-app)
-
-Bowtie programs!
-
-```sh
-stack install
-# installs bowtie, bowtie-js, bowtie-blueprint, and bowtie-visualize
-
-bowtie ./example-app/lunar-lander.bowtie
--- this evaluates lunar-lander and prints the result to the screen.
--- to get this into a webpage and actually play it see ./bowtie-js
-```
-
-## [./bowtie-js](./bowtie-js)
-
-![sloc-bowtie-js](./bowtie/misc/generated/sloc-bowtie-js.svg)
-
-JavaScript transpiler (WIP).
-
-```sh
-stack install
-
-bowtie-js example-app/lunar-lander.bowtie > bowtie-js/main.js
-
-firefox ./bowtie-js/index.html
-```
-
-## [./bowtie-blueprint](./bowtie-blueprint)
-
-![sloc-bowtie-blueprint](./bowtie/misc/generated/sloc-bowtie-blueprint.svg)
-
-Linter for a types-only variant of the language (WIP).
++ [./bowtie](./bowtie): Reference implementation
 
-## [./bowtie-visualize](./bowtie-visualize)
++ [./spec](./spec): Description of the language
 
-![sloc-bowtie-visualize](./bowtie/misc/generated/sloc-bowtie-visualize.svg)
++ [./example-app](./example-app) and [./example-lib](./example-lib): Bowtie code
 
-Tool to illustrate type inference or term evaluation (WIP).
++ [./bowtie-js](./bowtie-js): JavaScript transpiler
diff --git a/bowtie-blueprint/README.md b/bowtie-blueprint/README.md
new file mode 100644
index 0000000..04e1801
--- /dev/null
+++ b/bowtie-blueprint/README.md
@@ -0,0 +1,3 @@
+![sloc-bowtie-blueprint](./bowtie/misc/generated/sloc-bowtie-blueprint.svg)
+
+Linter for a types-only variant of the language (WIP).
diff --git a/bowtie-js/README.md b/bowtie-js/README.md
new file mode 100644
index 0000000..23808b9
--- /dev/null
+++ b/bowtie-js/README.md
@@ -0,0 +1,11 @@
+![sloc-bowtie-js](./bowtie/misc/generated/sloc-bowtie-js.svg)
+
+JavaScript transpiler (WIP)
+
+```sh
+stack install bowtie-js # all these command from the root of the repo
+
+bowtie-js example-app/lunar-lander.bowtie > bowtie-js/main.js
+
+firefox ./bowtie-js/index.html
+```
diff --git a/bowtie-visualize/README.md b/bowtie-visualize/README.md
index f5f76f7..97da385 100644
--- a/bowtie-visualize/README.md
+++ b/bowtie-visualize/README.md
@@ -1,3 +1,5 @@
-WIP
+![sloc-bowtie-visualize](./bowtie/misc/generated/sloc-bowtie-visualize.svg)
+
+Tool to illustrate type inference or term evaluation (WIP)
 
 Be careful, this will write a ton of files out to the current directory.
diff --git a/bowtie/README.md b/bowtie/README.md
index 437fac0..2b2141a 100644
--- a/bowtie/README.md
+++ b/bowtie/README.md
@@ -7,3 +7,11 @@ Module layout:
 ![modules](./misc/generated/modules.svg)
 
 Legend: `---->` means "imports".
+
+```sh
+stack install bowtie # all these command from the root of the repo
+
+bowtie ./example-app/lunar-lander.bowtie
+-- this evaluates lunar-lander and prints the result to the screen.
+-- to get this into a webpage and actually play it see ../bowtie-js
+```