improve README
improve spec
create package in a clean dir
add javadoc.  demote a method
improve javadoc