fix, document, and add debugging info