clarifications, and better api