automation: changes, fixes and documentation