improved docs and various fixes