docs & associated bugfixes