docs: add README screenshots section + VHS tape scripts

README.md

@@ -7,6 +7,22 @@
 
 ---
 
+## Screenshots
+
+Recorded with [charmbracelet/vhs](https://github.com/charmbracelet/vhs). The `.tape`
+source scripts live in [`docs/tapes/`](docs/tapes/); see [`docs/tapes/README.md`](docs/tapes/README.md)
+for regeneration instructions. If the
+GIFs below appear broken, that means the tapes have not been rendered yet against a
+tenant — the tape scripts are the source of truth.
+
+| Users list, filter, detail | System Logs tail |
+|---|---|
+| ![Users list](docs/images/users_list.gif) | ![Logs tail](docs/images/logs_tail.gif) |
+| **Edit form (SCR-012)** | **Status picker** |
+| ![Edit form](docs/images/edit_form.gif) | ![Status picker](docs/images/status_picker.gif) |
+
+---
+
 ## Why ota
 
 Okta's Admin Console requires many clicks to correlate a user's group membership with their recent login events, and shared `curl + jq` snippets lose context fast. ota brings the same keyboard-first, "press `:`, type a resource, drill down" workflow that k9s established for Kubernetes — applied to Okta's identity model.

docs/tapes/README.md

@@ -0,0 +1,41 @@
+# VHS tape scripts
+
+These `.tape` files drive [charmbracelet/vhs](https://github.com/charmbracelet/vhs)
+to render the animated GIFs referenced from the top-level [`README.md`](../../README.md#screenshots).
+They are **scripts of the boot flow only** — no real Okta tenant data is baked in.
+
+## Regenerate
+
+```bash
+brew install vhs                              # or: go install github.com/charmbracelet/vhs@latest
+export OKTA_ORG_URL="https://dev-XXXXXX.okta.com"
+export OKTA_API_TOKEN="…read-only token…"
+go build -o ota ./cmd/ota
+
+for f in docs/tapes/*.tape; do
+  vhs "$f"
+done
+```
+
+Each tape writes its `.gif` to `docs/images/<name>.gif`, matching the paths embedded
+in the top-level README's Screenshots section.
+
+## Tape catalogue
+
+| Tape | Demonstrates |
+|---|---|
+| `users_list.tape` | Boot → Users list → `/` incremental filter → `d` detail |
+| `logs_tail.tape` | `:logs` command palette route → `s` tail toggle |
+| `edit_form.tape` | Groups list → `e` edit modal (SCR-012) |
+| `status_picker.tape` | Group Rules list → `s` status picker |
+
+## Recording tips
+
+- Use a Developer Free tenant with a handful of seeded users — enough to make filter
+  animations look alive but nothing PII-sensitive.
+- The `Theme` directive uses `Catppuccin Mocha` for consistency; swap freely if you
+  prefer another dark theme.
+- Keep the terminal size at 1200×720 so the GIFs sit at a readable width in GitHub's
+  README render.
+- If a tape stalls, bump the `Sleep` after `Enter` — first API calls can take longer
+  on cold caches.

docs/tapes/edit_form.tape

@@ -0,0 +1,39 @@
+# edit_form.tape — SCR-012 edit modal (e opens edit form on a Group).
+#
+# Regenerate with:
+#   vhs docs/tapes/edit_form.tape
+
+Output docs/images/edit_form.gif
+
+Set Shell "bash"
+Set FontSize 14
+Set Width 1200
+Set Height 720
+Set Padding 20
+Set Theme "Catppuccin Mocha"
+
+Type "./ota"
+Enter
+Sleep 2s
+
+# Jump to Groups.
+Type ":"
+Sleep 300ms
+Type "groups"
+Sleep 300ms
+Enter
+Sleep 2s
+
+# Open edit modal.
+Type "e"
+Sleep 2500ms
+
+# Discard and exit.
+Escape
+Sleep 800ms
+
+# Quit.
+Type "q"
+Sleep 500ms
+Enter
+Sleep 1s

docs/tapes/logs_tail.tape

@@ -0,0 +1,39 @@
+# logs_tail.tape — Jump to System Logs and toggle tail mode.
+#
+# Regenerate with:
+#   vhs docs/tapes/logs_tail.tape
+
+Output docs/images/logs_tail.gif
+
+Set Shell "bash"
+Set FontSize 14
+Set Width 1200
+Set Height 720
+Set Padding 20
+Set Theme "Catppuccin Mocha"
+
+Type "./ota"
+Enter
+Sleep 2s
+
+# Command palette -> :logs
+Type ":"
+Sleep 500ms
+Type "logs"
+Sleep 500ms
+Enter
+Sleep 2s
+
+# Toggle tail mode.
+Type "s"
+Sleep 3s
+Type "s"
+Sleep 1s
+
+# Return + quit.
+Escape
+Sleep 500ms
+Type "q"
+Sleep 500ms
+Enter
+Sleep 1s

docs/tapes/status_picker.tape

@@ -0,0 +1,39 @@
+# status_picker.tape — s opens the status picker on Group Rules.
+#
+# Regenerate with:
+#   vhs docs/tapes/status_picker.tape
+
+Output docs/images/status_picker.gif
+
+Set Shell "bash"
+Set FontSize 14
+Set Width 1200
+Set Height 720
+Set Padding 20
+Set Theme "Catppuccin Mocha"
+
+Type "./ota"
+Enter
+Sleep 2s
+
+# Jump to Group Rules.
+Type ":"
+Sleep 300ms
+Type "grouprules"
+Sleep 300ms
+Enter
+Sleep 2s
+
+# Open the status picker.
+Type "s"
+Sleep 2500ms
+
+# Cancel out.
+Escape
+Sleep 800ms
+
+# Quit.
+Type "q"
+Sleep 500ms
+Enter
+Sleep 1s

docs/tapes/users_list.tape

@@ -0,0 +1,43 @@
+# users_list.tape — Users list, incremental filter, open detail.
+#
+# Regenerate with:
+#   vhs docs/tapes/users_list.tape
+#
+# Requires OKTA_ORG_URL / OKTA_API_TOKEN in the shell that runs vhs
+# (recommend a Developer tenant with a few seeded users).
+
+Output docs/images/users_list.gif
+
+Set Shell "bash"
+Set FontSize 14
+Set Width 1200
+Set Height 720
+Set Padding 20
+Set Theme "Catppuccin Mocha"
+
+Type "./ota"
+Enter
+Sleep 2s
+
+# Land on Users list (SCR-010).
+Sleep 1s
+
+# Incremental filter demo.
+Type "/"
+Sleep 500ms
+Type "al"
+Sleep 1s
+Escape
+Sleep 500ms
+
+# Open detail (d) then return.
+Type "d"
+Sleep 2s
+Escape
+Sleep 500ms
+
+# Quit.
+Type "q"
+Sleep 500ms
+Enter
+Sleep 1s