readme and improved api