some docs, better error messages, improved gitignore