diff --git a/README.md b/README.md
index fee624a..321275c 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,48 @@
-# town-launcher
+This is an implementation of an idea we discussed a while ago; a launcher for town-specific
+commands.
 
-A launcher for tilde.town commands both official and community-supported
\ No newline at end of file
+The idea is to put town commands in one of three places:
+
+/town/launcher/core
+/town/launcher/contrib
+/town/launcher/admin
+
+and pair each command with a corresponding .yml file.
+
+For example, the `aup` command is a simple wrapper around elinks that opens our code of conduct. I
+put the executable `aup` in /town/launcher/core and matched it with /town/launcher/aup.yml. The
+purpose of the yaml file is to provide documentation for your executable, so `aup.yml` looks like:
+
+    shortDesc: View the town's Acceptable Use Policy
+    longDesc: |
+      This command will open our code of conduct, a type of document that evokes the Acceptable Use
+      Policies that governed servers like this in the past. It will open the elinks browser to a
+      page on the wiki.
+    examples: |
+      $ aup           # open the aup
+      $ aup --rainbow # open the aup with rainbow colors
+
+
+ and using the launcher is like:
+
+     $ town aup
+     $ town aup --rainbow
+     $ town contrib writo
+     $ town admin ban vilmibm
+
+You can see all the commands with `town help` as well as their descriptions; `town help
+aup` would show you the docs from `aup.yml`.
+
+I'd love feedback on this approach while I wrap up this implementation. I can put it up on
+git.tilde.town if anyone desires to collaborate (and let me know if you want a git.tilde.town
+account).
+
+Remaining TODOs:
+
+- [ ] fix arg passing
+- [ ] make tab completion available for common shells
+- [ ] test with a command that makes use of stdin/stdout
+- [ ] document / script submitting a tool for inclusion in contrib
+- [ ] add all existing commands to the buckets
+- [ ] make little wrappers for things like `mail` and `chat`
+- [ ] add to users' paths