fix weirdly broken test
add some TODO notes on possible format changes
start at docs