tweak perms and doc clarifications