migrate docs to yard

conflated a reworking of the client initialization in there as well, but it made for much less doc writing.