enhancements to `README` and more code cleanup