some API notes added to README; gotta make these better
more doc spew