simplify README and document newer concepts