docs: go over design docs and fix things