add docs to state machine. fix miscellanea.