cleanup: documentation and more informative errors