i'm sure there is more to document yet but this gets us started
also docs + tests for what we have so far