doc tweaks
better X/Y/Z; role handling