spec, sample docs and bug fixes