documented api and schema; updated readme