Create terminal GIF for README

[skokaina]

Why

A 15-second terminal GIF is the single highest-ROI item for GitHub README conversion. On HN/Reddit, people scroll past text but stop at a visual demo. Every successful CLI tool has one (starship, mise, zoxide, fig).

What to record

The 5-minute AHA moment in ~15 seconds:

agentspec init --yes
agentspec validate agent.yaml
agentspec audit agent.yaml        # show the grade + score
agentspec generate agent.yaml --framework langgraph --output ./agent/
ls ./agent/                        # show generated files

Recommended tool

vhs — scriptable terminal GIF recorder by Charm. Write a .tape file, run vhs < demo.tape, get a deterministic GIF every time. Alternatively: asciinema + agg for GIF conversion.

Placement

• README.md — below the logo, above "What you can do"
• docs/index.md — hero section
• Blog post — embedded

Acceptance criteria

• GIF is < 5 MB (GitHub renders inline up to 10 MB but smaller loads faster)
• Shows the full init → validate → audit → generate flow
• Audit output shows a grade (the visual "wow" moment)
• Committed to docs/graphics/ or similar
• Embedded in README.md and docs/index.md