Batch of improvements around error handling, useability, and documentation

Probably all I have time to do in the short-term, so also includes a TODO list, maybe someone will pick up the challenge.