update readme with examples, reasoning, and other rambling.
actual code