docs: demo gifs, a stats section, and CONTRIBUTING.md #12

Merged

jwarykowski merged 3 commits from docs/demo-gif into master

2026-07-29 23:49:19 +00:00

jwarykowski commented

2026-07-29 13:07:09 +00:00

(Migrated from github.com)

The README described the commands but never showed them, and carried its development detail inline.

gifs

Both scripted with vhs rather than screen-captured, so they can be regenerated whenever the commands, the picker or the statusline change:

assets/demo.gif (1320x800, ~45s, 616K) — above ## requirements
assets/stats.gif (1500x1160, ~11s, 164K) — in a new ## stats section

vhs assets/demo.tape
vhs assets/stats.tape

Demo shot list: the statusline count · :ShepherdCapture on a -- TODO: comment, prompt pre-filled with the marker stripped · :ShepherdList → edit with its pre-filled quick-add line · :ShepherdList → done, count drops · :Shepherd opening the board in the floating terminal with the captured item in it.

The recording runs with mouse empty, so it is keyboard-driven throughout.

CONTRIBUTING.md

Takes the development detail out of the README: the module layout (init.lua / board.lua / health.lua, all of it over the CLI — the plugin never parses a board file), what the specs cover and why logic belongs in pure helpers on _internal, the stylua/luacheck conventions, and how to re-record the gifs. The README's ## development is now the four make targets plus a pointer.

It also records the trap I hit while testing: named boards live under $XDG_CONFIG_HOME/shepherd/boards/, not wherever $SHEPHERD_TODO_FILE points, so a scratch tree for board commands needs XDG_CONFIG_HOME set too.

The README described the commands but never showed them, and carried its development detail inline. ## gifs Both scripted with [vhs](https://github.com/charmbracelet/vhs) rather than screen-captured, so they can be regenerated whenever the commands, the picker or the statusline change: - `assets/demo.gif` (1320x800, ~45s, 616K) — above `## requirements` - `assets/stats.gif` (1500x1160, ~11s, 164K) — in a new `## stats` section ```sh vhs assets/demo.tape vhs assets/stats.tape ``` Demo shot list: the statusline count · `:ShepherdCapture` on a `-- TODO:` comment, prompt pre-filled with the marker stripped · `:ShepherdList` → **edit** with its pre-filled quick-add line · `:ShepherdList` → **done**, count drops · `:Shepherd` opening the board in the floating terminal with the captured item in it. The recording runs with `mouse` empty, so it is keyboard-driven throughout. ## CONTRIBUTING.md Takes the development detail out of the README: the module layout (`init.lua` / `board.lua` / `health.lua`, all of it over the CLI — the plugin never parses a board file), what the specs cover and why logic belongs in pure helpers on `_internal`, the stylua/luacheck conventions, and how to re-record the gifs. The README's `## development` is now the four `make` targets plus a pointer. It also records the trap I hit while testing: named boards live under `$XDG_CONFIG_HOME/shepherd/boards/`, not wherever `$SHEPHERD_TODO_FILE` points, so a scratch tree for board commands needs `XDG_CONFIG_HOME` set too.