fixed nits. more polite, better error handling, docs