clarity update + documentation