populate README.md

some fixes as issues were found by exercising the API
described in the documentation.