document a little bit - some philosophy and API sketching to ground iterative dev