verify/update links and polish
update based on @matzew feedback