lots of updates to readme & doc. new cli flags