revise sec 3 + a bunch of small infrastructure improvements