update README and examples for new functionality