This is good stuff, but it's really developer docs.  Maybe a separate file under docs? Maybe in the github wiki?

Read me should simply get you started...this is how you build this is how you use.  I reckon more folks are going to use, rather than develop against.