various wording fixes in README and API.md and updated state-machine pics