fleshing out the README with proposed API