sigilco · espetro · Jul 1, 2026 · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026
diff --git a/.agents/docs/demo-gif-creation.md b/.agents/docs/demo-gif-creation.md
@@ -0,0 +1,65 @@
+# Demo GIF creation
+
+Source-of-truth process for the `docs/public/demo.gif` shown in the README and used in Show HN / social-media posts.
+
+## Why manual, not CI
+
+We considered a GitHub Action that re-renders `demo.gif` whenever `packages/cli/src/**` changes. Rejected for HN launch: it adds a moving part to the repo before the launch story is settled, and stale screenshots rarely block users more than a 5-minute manual re-render. Reconsider in v0.6.x if the GIF goes stale visibly more than twice.
+
+## Tool
+
+[VHS](https://github.com/charmbracelet/vhs) — declarative `.tape` files, real pixel output, regenerable by anyone with VHS installed. [gum](https://github.com/charmbracelet/gum) drives the fake-agent HUD (Frame 3).
+
+```bash
+mise install     # picks up vhs + aqua:charmbracelet/gum from mise.toml
+```
+
+## Files
+
+```
+docs/public/demo.tape           # source of truth (declarative script)
+docs/public/demo-agent-hud.sh   # scripted fake-agent HUD (gum banner/spinner/tool-call lines)
+docs/public/demo.gif            # rendered artifact (committed, referenced in README)
+docs/public/demo.mp4            # rendered artifact (committed, for social posts)
+```
+
+## Render locally
+
+```bash
+cd docs/public
+vhs demo.tape            # produces demo.gif + demo.mp4
+```
+
+Re-render whenever any of these change:
+
+- The CLI's `add` command output (installer text)
+- The Tier-1 harness list (Claude Code, Codex, OpenCode, Pi)
+- The plugin name featured in the storyboard (`agentplugins-conventional-commits`)
+
+## Storyboard (current)
+
+| Frame | Duration | What happens |
+| --- | --- | --- |
+| 1 | 0–1s | `cd` into a pre-warmed demo folder |
+| 2 | 1–2s | User's natural-language ask typed live (shell comment, cosmetic only) |
+| 3 | 2–6s | Scripted fake-agent HUD runs (`docs/public/demo-agent-hud.sh`), prints `Plugin is ready` |
+| 4 | 6–7s | `clear` |
+| 5 | 7–12s | Real `agentplugins add sigilco/agentplugins-conventional-commits -y`, waits for `Installed to:` (the punchline) |
+
+Total budget: 15–30s, width 1200, height 700, font size 18.
+
+## Agent HUD (Frame 3) — why scripted
+
+A live capture of the agent scaffolding the plugin is more authentic, but brittle and slow: any agent behavior change breaks the tape, and a real `claude` run takes 5–15 minutes to render. Instead `docs/public/demo-agent-hud.sh` drives [`gum`](https://github.com/charmbracelet/gum) (mise tool `aqua:charmbracelet/gum`) to render a real bordered banner, a real animated spinner, and boxed tool-call lines — deterministic, no network/API calls, runs in ~3s. The install segment stays a real, live `agentplugins add` call; it's already fast and deterministic, and is the visual punchline.
+
+## Plumbing
+
+- VHS pulls `ttyd` and `ffmpeg` automatically on macOS.
+- The `.tape` uses `Output docs/public/demo.gif` and `Output docs/public/demo.mp4` so a single run produces both.
+- Screenshots reference `./docs/public/img/logo-light.png` and `./docs/public/img/logo-dark.png` if any frame embeds the logo.
+
+## What is NOT in scope
+
+- Auto-rendering on PR / CLI change (deferred to v0.6.x).
+- GIF hosting on a CDN (the file is small and GitHub renders it natively).
+- git-lfs (the GIF stays under 5 MB; if it ever blows past, switch then).
diff --git a/.gitignore b/.gitignore
@@ -59,6 +59,9 @@ docs/public/*
 !docs/public/img/
 !docs/public/img/logo-dark.png
 !docs/public/img/logo-light.png
+!docs/public/demo.tape
+!docs/public/demo.gif
+!docs/public/demo.mp4
 
 # Misc
 *.local

diff --git a/README.md b/README.md
@@ -1,30 +1,67 @@
-# AgentPlugins
-
-<p align="left">
+<p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="./docs/public/img/logo-dark.png" />
     <img src="./docs/public/img/logo-light.png" alt="AgentPlugins" height="96" />
   </picture>
 </p>
 
-> Write AI agent plugins once, ship to any harness.
+<h1 align="center">AgentPlugins</h1>
+
+<p align="center">
+  <strong>Write AI agent plugins once, ship to any harness.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/sigilco/agentplugins/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/sigilco/agentplugins?style=flat-square"/></a>
+  <a href="https://www.npmjs.com/package/@agentplugins/cli"><img alt="npm version" src="https://img.shields.io/npm/v/@agentplugins/cli?style=flat-square"/></a>
+  <a href="https://www.npmjs.com/package/@agentplugins/cli"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@agentplugins/cli?style=flat-square"/></a>
+  <a href="https://github.com/sigilco/agentplugins/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/sigilco/agentplugins/ci.yml?branch=main&style=flat-square"/></a>
+  <a href="https://buy.polar.sh/polar_cl_Mv1gdlG7bw3I70EC9IHtfeSHJj4PEKvA7JAUz23CFhj"><img alt="Sponsor" src="https://img.shields.io/badge/Sponsor-❤️-ff69b4?style=flat-square"/></a>
+</p>
+
+## Why
+
+- **Write once, run everywhere** — one manifest compiles to Claude Code, Codex, OpenCode, Pi Mono, Copilot, Gemini, and Kimi
+- **Universal codegen first, per-harness fallback second** — Tier-1 harnesses get full parity; Tier-2 gets skills + commands + a subset of hooks
+- **No runtime proxy** — every adapter emits the harness's native output format; no shim layer, no lock-in
+- **Honest capability matrix** — capability gaps emit `WARN` at compile time and surface on the [capability matrix page](https://agentplugins.pages.dev/guide/capability-matrix)
+- **Plays nicely with what you already have** — install a plugin into a harness that already has its own plugins; they coexist
 
-Install any plugin into every supported AI agent — **Tier-1:** Claude Code, Codex, OpenCode, Pi Mono. **Tier-2:** Copilot, Gemini, Kimi.
+## Install
 
-[**Sponsor development →**](https://buy.polar.sh/polar_cl_Mv1gdlG7bw3I70EC9IHtfeSHJj4PEKvA7JAUz23CFhj)
+Install the CLI, then add any plugin to every supported AI agent — **Tier-1:** Claude Code, Codex, OpenCode, Pi Mono. **Tier-2:** Copilot, Gemini, Kimi.
 
 ```bash
-npx @agentplugins/cli add user/awesome-plugin
+curl -fsSL https://agentplugins.pages.dev/install.sh | bash
+agentplugins add user/awesome-plugin
 ```
 
+Or skip the install and use `npx`:
+
 ```bash
-agentplugins add sigilco/agentplugins-ponytail
+npx @agentplugins/cli add user/awesome-plugin
 ```
 
-Or install the CLI globally first:
+Full guide → [agentplugins.pages.dev/guide/install](https://agentplugins.pages.dev/guide/install)
+
+<p align="center">
+  <img src="./docs/public/demo.gif" width="100%" alt="AgentPlugins demo: build once, install everywhere" />
+</p>
+
+## Quick start
+
+From zero to a working plugin in any supported harness:
 
 ```bash
-curl -fsSL https://agentplugins.pages.dev/install.sh | bash
+# Scaffold a new plugin from the official template
+npx @agentplugins/cli init my-plugin
+cd my-plugin
+
+# Install it into every supported harness (writes to ~/.claude, ~/.codex, etc.)
+npx @agentplugins/cli add .
+
+# Verify the install landed where you expect
+npx @agentplugins/cli doctor
 ```
 
 ## Create a plugin
@@ -60,6 +97,10 @@ Full docs → [agentplugins.pages.dev](https://agentplugins.pages.dev)
 
 LLMs.txt for AI agents → [agentplugins.pages.dev/llms.txt](https://agentplugins.pages.dev/llms.txt)
 
+## Contributing
+
+PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md), file issues, and join the conversation in [Discussions](https://github.com/sigilco/agentplugins/discussions).
+
 ---
 
 Apache-2.0 · [GitHub](https://github.com/sigilco/agentplugins) · [Sponsor](https://buy.polar.sh/polar_cl_Mv1gdlG7bw3I70EC9IHtfeSHJj4PEKvA7JAUz23CFhj)
diff --git a/docs/public/demo.gif b/docs/public/demo.gif
diff --git a/docs/public/demo.mp4 b/docs/public/demo.mp4
diff --git a/docs/public/demo.tape b/docs/public/demo.tape
@@ -0,0 +1,83 @@
+# AgentPlugins demo GIF — VHS source of truth (scripted fake-agent HUD + real install)
+#
+# Render: vhs docs/public/demo.tape
+# Produces: docs/public/demo.gif + docs/public/demo.mp4 (canonical, <5 MB)
+#
+# Higher-res render for social media: render with docs/public/demo-hq.tape at
+# 1920x1080 — see .agents/docs/demo-gif-creation.md.
+#
+# This tape types a natural prompt live (real VHS typing animation), then runs
+# a scripted fake-agent HUD (docs/public/demo-agent-hud.sh, gum-driven: real
+# bordered banner + real animated spinner + boxed tool-call lines) that prints
+# `Plugin is ready` deterministically in ~3s — no live `claude` call, no
+# network, no flakiness. The install segment (`agentplugins add ...`) is real
+# and is the visual punchline; it runs with HOME pointed at a throwaway /tmp
+# dir so the printed install paths and on-disk writes don't leak the
+# operator's real home directory/username into a publicly shared asset.
+#
+# Fallback: if demo.gif > 5 MB, use demo-print.tape (the claude -p flow).
+
+Output docs/public/demo.gif
+Output docs/public/demo.mp4
+
+Set Shell bash
+Set FontSize 18
+Set Width 1200
+Set Height 700
+Set Padding 20
+Set Theme Dracula
+Set TypingSpeed 50ms
+Set WaitTimeout 30s
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Frame 1 — cd into a pre-warmed demo folder (git-init'd so the agent doesn't
+# stall on a repo-create prompt). Capture the HUD script's absolute path
+# before cd'ing away (hidden from the recording — pure setup, not part of the
+# story) so the render works regardless of repo checkout location.
+# ─────────────────────────────────────────────────────────────────────────────
+Hide
+Type "HUD=$PWD/docs/public/demo-agent-hud.sh"
+Enter
+Type "DEMO_HOME=/tmp/agentplugins-demo-home"
+Enter
+Type "mkdir -p $DEMO_HOME"
+Enter
+Type "clear"
+Enter
+Show
+
+Type "cd /tmp/agentplugins-demo"
+Enter
+Sleep 500ms
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Frame 2 — type the prompt live (typed at the shell, read by the fake-HUD
+# script below — purely for the visual of a natural-language ask).
+# ─────────────────────────────────────────────────────────────────────────────
+Type "# Read the agentplugins docs, scaffold a conventional-commits plugin, build it, push it, print Plugin is ready when done"
+Enter
+Sleep 500ms
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Frame 3 — run the scripted fake-agent HUD (gum banner + spinner + boxed
+# tool-call lines), block on its marker (no Sleep-guessing).
+# ─────────────────────────────────────────────────────────────────────────────
+Type "bash $HUD"
+Enter
+Wait+Screen /Plugin is ready/
+Sleep 1s
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Frame 4 — clear before the install frame.
+# ─────────────────────────────────────────────────────────────────────────────
+Type "clear"
+Enter
+Sleep 500ms
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Frame 5 — install the plugin into the system.
+# ─────────────────────────────────────────────────────────────────────────────
+Type "HOME=$DEMO_HOME agentplugins add sigilco/agentplugins-conventional-commits -y"
+Enter
+Wait+Screen /Installed to:/
+Sleep 2s
diff --git a/mise.toml b/mise.toml
@@ -1,3 +1,4 @@
 [tools]
 pnpm = "11"
 node = "24"
+"aqua:charmbracelet/gum" = "0.17.0"