diff --git a/README.md b/README.md
index b0c35c5..17762cb 100644
--- a/README.md
+++ b/README.md
@@ -4,19 +4,37 @@
 
 It would be great to put a link in my notes to the directory I working in on a project, and it opens a terminal right to there.
 
+Something simple like a [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) to the directory you had a terminal open.
+
 ## install
 
 ```shell
+git clone https://github.com/vbatts/terminal-url-handler
+cd terminal-url-handler
 make user-install
 ```
 
+## examples
+
+Say you keep a notebook/journal/whatever in an app that allows hyperlinks (markdown, html, etc.).
+
+Create a link:
+
+```markdown
+[terminal-url-handler](terminal://~/src/terminal-url-handler)
+```
+i.e. [terminal-url-handler](terminal://~/src/terminal-url-handler)
+
+```html
+<a href="terminal://~/src/terminal-url-handler">terminal-url-handler</a>
+```
+
 ## development
 
 happy to take contributions or enhancements.
 
 This seems like something that ought to be built-in for most desktops. 
 
-
 ### lint
 
 ```shell
@@ -32,6 +50,10 @@ Whatever.
 
 https://portland.freedesktop.org/doc/xdg-settings.html
 
+### Future improvements?
+
+- [ ] if a `user@host` is included, then ssh to the host
+
 ## LICENSE
 
 See [LICENSE](./LICENSE)