more pedagogy and bug fixes