updates readme.
adds html region (which induced some restructuring for the markdown region)
general cleanup and specs.