updated: readme with clearer examples and notes