diff --git a/README.md b/README.md
index 2f6fc9d..f95fde6 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,8 @@
-# dotGit ::: 🪄 dotfiles +  🧸 bare git repo + 🐚 shell aliases
+# dotGit ::: 🪄 dotfiles + 🧸 bare git repo + 🐚 shell aliases
 
-There are a lot of ways to manage your dotfiles. dotGit implements an idea that has been floating around on the internet for a while: a bare git repo for storing your dotfiles. A quick search finds [this post](https://news.ycombinator.com/item?id=11070797), but there may be older sources. dotGit combines this with some convenient shell aliases, a couple of functions, and FZF's matching magic to track your dotfiles files with ease.
-
-dotGit has modest aims:
-- 🏡 keep configuration files where tools expect them in `$HOME`
-- 🐚 stay as light and close to git and the shell as possible
-- 🚀 reduce friction and make configuration changes quick and convenient
+Your dotfiles are scattered across `$HOME`. You can't remember which file sets `PATH`, or where you defined that alias three months ago. `.gg PATH` greps across every tracked dotfile and drops you straight to the line. `.ge` fuzzy-finds any file by name with a live preview. Under the hood it's a [bare git repo](https://news.ycombinator.com/item?id=11070797), so files stay exactly where tools expect them and everything else is standard git.
 
+![dotGit demo](demo/demo.gif)
 
 ## TL;DR
 
@@ -32,11 +28,27 @@ source /path/to/dotgit.sh
 
 ## usage
 
-Most of dotGit is just some aliases that point to the `--git-dir` and `--work-tree`.
+### .ge — fuzzy find and edit
 
-The real daily winners for me are the "edit" (`.ge`) and "grep" (`.gg`) aliases. They get me to where I need to be fast.
+`.ge` opens a fuzzy file finder across all tracked dotfiles. Type to narrow by filename, and get a live syntax-highlighted preview of each file on the right. Select one or more files and they open in `$EDITOR`.
 
-### a normal workflow for making configuration changes 
+```
+.ge            # browse all dotfiles
+.ge zsh        # pre-filter to files with "zsh" in the name
+```
+
+### .gg — grep and jump
+
+`.gg` runs `git grep` across all tracked dotfile contents and presents the matches interactively. Select a result and your editor opens directly at that line.
+
+```
+.gg PATH       # find every place PATH is set or referenced
+.gg 'alias g'  # find all git aliases
+```
+
+Everything else is a standard git alias pointed at the dotfiles repo.
+
+### a normal workflow for making configuration changes
 
 1. `.gl` - pull changes from origin
 2. make some changes. Try:
@@ -57,8 +69,8 @@ The real daily winners for me are the "edit" (`.ge`) and "grep" (`.gg`) aliases.
 | .gco | `.git checkout`  | |
 | .gd | `.git diff` | |
 | .gds | `.git diff --stat` | |
-| .ge | calls the `_dotgit_ge` helper function | the dotGit edit feature [^fzf] |
-| .gg | calls the `_dotgit_gg` helper function (falls back to `.git grep` without fzf) | grep your dotfiles and open at the matched line [^line] |
+| .ge | fuzzy find and edit dotfiles [^fzf] | |
+| .gg | grep dotfiles and open at the matched line [^line] [^fzf] | falls back to `.git grep` without fzf |
 | .gss | `.git status --short` | |
 | .glo | `.git log --oneline --decorate`  | |
 | .glg | `.git log --stat`  | |
@@ -84,7 +96,7 @@ The real daily winners for me are the "edit" (`.ge`) and "grep" (`.gg`) aliases.
 | .gclone | `git clone --bare "${DOT_ORIGIN}" "${DOT_REPO}"; .git config --local status.showUntrackedFiles no` | [^untracked] |
 | .ginit | `git init --bare "${DOT_REPO}"; .git config --local status.showUntrackedFiles no`   |   |
 
-[^line]: Opens the editor with `+line file` arguments. Works with vi, emacs, nano, micro, and any editor that accepts a line number via `+N`.
+[^line]: Opens the editor with `+line file` arguments. Works with vi, emacs, nano, micro, and any editor that accepts `+N`. For vim/nvim multi-file line jumping set `DOTGIT_OPEN_FMT='+e {file}|{line}'` (note: literal `|`, not `\|`).
 [^untracked]: Also set git's `status.showUntrackedFiles` to `no`. This prevents every file in `$DOT_HOME` from showing as "untracked" by git.
 [^fzf]: requires [FZF](https://github.com/junegunn/fzf)
 
diff --git a/demo/demo-note.sh b/demo/demo-note.sh
new file mode 100755
index 0000000..d5f48fb
--- /dev/null
+++ b/demo/demo-note.sh
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+clear
+gum style --bold --foreground 6 --border rounded --border-foreground 8 "$*"
diff --git a/demo/demo.gif b/demo/demo.gif
new file mode 100644
index 0000000..b0ba4c8
Binary files /dev/null and b/demo/demo.gif differ
diff --git a/demo/demo.tape b/demo/demo.tape
new file mode 100644
index 0000000..f4eb2cc
--- /dev/null
+++ b/demo/demo.tape
@@ -0,0 +1,81 @@
+# dotGit — .gg and .ge demo
+
+Output demo/demo.gif
+
+Set Shell zsh
+Set Width 1200
+Set Height 450
+Set FontSize 16
+Set TypingSpeed 100ms
+
+Sleep 1s
+
+Hide
+Type "export DOT_REPO=$HOME/.dotfiles DOT_HOME=$HOME && source /home/matthias/Code/dotGit/dotgit.sh"
+Enter
+Sleep 500ms
+Show
+
+# .gg — grep your dotfiles and jump to the line
+Hide
+Type "./demo/demo-note.sh 'Search your dotfiles for PATH'"
+Enter
+Sleep 500ms
+Show
+Sleep 3s
+
+Type "EDITOR=nano .gg PATH"
+Sleep 1500ms
+Enter
+Sleep 3000ms
+
+Screenshot screenshot.png
+Sleep 1500ms
+
+Down
+Sleep 1500ms
+Down
+Sleep 1500ms
+Down
+Sleep 1500ms
+Down
+Sleep 1500ms
+Up
+Sleep 1200ms
+Up
+Sleep 1200ms
+Enter
+Sleep 2000ms
+
+Ctrl+X
+Sleep 2500ms
+
+# .ge — fuzzy find and edit
+Hide
+Type "./demo/demo-note.sh 'Fuzzy find and edit your dotfiles'"
+Enter
+Sleep 500ms
+Show
+Sleep 3s
+
+Type "EDITOR=nano .ge"
+Sleep 1500ms
+Enter
+Sleep 3000ms
+Down
+Sleep 1200ms
+Down
+Sleep 1200ms
+Down
+Sleep 1200ms
+Up
+Sleep 1000ms
+Type "zshrc"
+Sleep 2000ms
+Down
+Sleep 1200ms
+Enter
+Sleep 2000ms
+
+Ctrl+X
+Sleep 1500ms
diff --git a/demo/screenshot.png b/demo/screenshot.png
new file mode 100644
index 0000000..50d8efc
Binary files /dev/null and b/demo/screenshot.png differ
diff --git a/screenshot.png b/screenshot.png
new file mode 100644
index 0000000..50d8efc
Binary files /dev/null and b/screenshot.png differ