fleshed out the spec + updated README