follow on doc updates
update specs (in progress)