minor notes and tweaks as the api refactor design takes shape