Clarify spec

This is PR an attempt to clarify some of the questions that came up when designing the client.