add specs for top level API
align README with implementation