updating the README to include all the latest API details

This needed some updating with the redesign and some 3rd-party
engines being developed.

@jcredding I'm gonna go ahead and merge this.  I want to reference it in the 3rd-party engine gems I'm writing.  I have "TODO" placeholders for things that will come or need further additions.