finish up #288, tested & documented