diff --git a/README.md b/README.md
index 7a24617..7931d97 100644
--- a/README.md
+++ b/README.md
@@ -64,12 +64,26 @@ or
 
     $ make
 
-### visit `localhost:8080` in web browser
+Visit `localhost:8080` in web browser
 
 ### start watcher
 
     $ docker exec -it container_name sitegen watch
 
+### lint moonscript
+
+    $ make lint
+
+## gotchas
+
+### What is `cosmo failed: [string "..."]:62: cannot resume dead coroutine`?
+
+If you call `cosmo.yield`, your function **must** return `nil`! If you forget
+to return `nil`, you will see this cryptic error:
+
+    Error: index.html -> html/index.html: cosmo failed: [string "..."]:62: cannot resume dead coroutine
+    make: *** [Makefile:6: build] Error 1`
+
 ## todo
 
 * draft documents