Rev4 update

This is in sync with https://docs.google.com/document/d/1m7Cep2U5eCe5M62Y6a_4CNGF7QM4UgJtmMFq2FrRo3s/edit?usp=sharing

and implements the proposals there. Please carefully review (in particular removed messages). This will go soon in master after another community review round. Criticism now or never 8).
No code-level changes in the message below, but urgently needed clarifications about the API / docs.