better docs (but still poor), bug squash