add some black magic docs