major update to spec based on first round of feedback