add updated README and specs from working-branch