README.md is a mess

The README.md file is presently a mess.
The only thing it should contain is the statement of what it is and brief instructions on using it.
However since the code base is in flux the instructions on use belong elsewhere in a docs folder.

We need to refactor and we also need to document what the API for this looks like (or at least will look like) for users of the system.