demo-gif

Turns "add a demo GIF to this README" into a repeatable pipeline: pick the right recording method for the project, generate a reproducible recording script, render it, optimize the file size, and embed it in the README correctly.

Don't screen-record by hand and drop a 40 MB file in the repo. Every step here is scripted so the demo can be regenerated later when the tool changes.

Step 1 — Detect what kind of demo fits

Look at the repo before picking a method.

Signal	Demo type	Method
`bin/`, a CLI entry point, `package.json` with a `bin` field, argparse/click/cobra code, a Dockerfile that runs a command	CLI tool	Terminal recording (vhs)
A TUI framework (bubbletea, ratatui, textual, blessed, ink)	TUI	Terminal recording (vhs), larger window
`package.json` with a frontend framework, a dev server script, `index.html`	Web app	Browser recording (Playwright + ffmpeg)
A library/SDK with no standalone entry point — README shows import + usage snippets	Library	REPL or a short example script, recorded as a terminal session

If it's ambiguous, ask which surface the demo should show (the CLI, a specific screen, a code example) rather than guessing.