because @indiebrain is a neckbeard
keep the client concerns in the client spec
add documentation for example responses