The existing README linked to out-of-date test and code coverage and
documentation which was no-longer being built.

Remove most of the README and replace its contents. Note that this
README is "forward-looking". It describes functionality which is added
in later commits but it didn't seem worth writing a README for old-world
and then immediately re-writing it.