feat: add terminal-gif skill to gitmem-hooks plugin

New skill for the blog publishing pipeline — guides agents through creating
animated terminal GIFs from synthetic asciinema v3 cast files. Includes:
- SKILL.md with full pipeline (cast authoring → agg rendering → OG compositing)
- Claude Code 16-color palette reference with correct orange (#DA7756)
- Sharp OG image compositing recipe
- Working example: session start ceremony generator
- agg binary installer script

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

hooks/skills/terminal-gif/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: Terminal GIF
+description: >
+  This skill should be used when the user asks to "create a terminal GIF",
+  "record a terminal animation", "make a terminal screenshot for the blog",
+  "generate a cast file", "create an asciinema recording", "animate a CLI demo",
+  or needs animated terminal visuals for blog posts, documentation, or social media.
+  Covers the full pipeline: synthetic cast file authoring, GIF rendering with agg,
+  and optional OG image compositing with Sharp.
+---
+
+# Terminal GIF — Animated Terminal Recordings for Content
+
+Generate animated terminal GIFs from synthetic asciinema v3 cast files. The
+pipeline produces pixel-perfect terminal animations without requiring screen
+recording — content is authored programmatically with full control over timing,
+colors, and text.
+
+## When to Use
+
+- Blog posts that need a terminal demo (session start, CLI output, etc.)
+- OG/feature images that embed a mini terminal screenshot
+- Documentation showing CLI workflows
+- Social media content with terminal visuals
+
+## Pipeline Overview
+
+```
+1. Author content  →  Node.js script generates .cast file (ANSI escape sequences)
+2. Render GIF      →  agg binary converts .cast → .gif with terminal fonts
+3. (Optional)      →  Sharp composites GIF frame onto OG image
+```
+
+## Step 1: Create the Cast Generator Script
+
+Create a Node.js script that builds an asciinema v3 cast file. The cast format
+is JSONL — a JSON header line followed by event lines: `[delta_seconds, "o", "data"]`.
+
+### Cast File Structure
+
+```jsonl
+{"version":3,"term":{"cols":80,"rows":36,"type":"xterm","theme":{...}},"timestamp":1234567890}
+[0.5,"o","$ "]
+[0.1,"o","c"]
+[0.08,"o","l"]
+```
+
+- **Header**: version, terminal dimensions, color theme
+- **Events**: `[delay_from_previous, "o", "output_text"]`
+- **ANSI escapes**: Use standard escape sequences for color/formatting
+
+### Claude Code Color Palette (CRITICAL)
+
+Use the exact Claude Code terminal theme. See `references/claude-code-palette.md` for
+the full 16-color palette and ANSI escape code mapping.
+
+Key colors:
+- **Background**: `#30302d` (warm dark gray)
+- **Foreground**: `#a1a1a1` (medium gray)
+- **Claude logo**: Palette index 1 = `#DA7756` (orange/terracotta, NOT red)
+- **Bright red** (scar HIGH): Palette index 9 = `#e65535`
+
+### Timing Guidelines
+
+| Element | Delay | Notes |
+|---------|-------|-------|
+| Typing each character | 0.06-0.14s | Randomize for natural feel |
+| Enter key | 0.3-0.4s | Slight pause before submit |
+| Section transitions | 0.6-1.2s | Simulates processing |
+| Final hold | 2-3s | Let viewer read the result |
+
+### Working Example
+
+See `examples/generate-ceremony-cast.mjs` for a complete cast generator that produces
+the GitMem session start ceremony animation. Key patterns:
+
+- `out(delay, text)` / `outln(delay, text)` helper functions
+- Character-by-character typing with randomized delays
+- Multi-color ANSI sequences for styled output
+- Claude Code block-art logo rendering
+
+## Step 2: Render with agg
+
+[agg](https://github.com/asciinema/agg) is the asciinema GIF generator. It renders
+`.cast` files to `.gif` with proper terminal fonts and anti-aliasing.
+
+### Install agg
+
+```bash
+# Download pre-built binary (no compiler needed)
+# Detect architecture
+ARCH=$(uname -m)
+if [ "$ARCH" = "aarch64" ]; then
+  AGG_BIN="agg-aarch64-unknown-linux-gnu"
+elif [ "$ARCH" = "x86_64" ]; then
+  AGG_BIN="agg-x86_64-unknown-linux-gnu"
+fi
+
+curl -L "https://github.com/asciinema/agg/releases/download/v1.7.0/${AGG_BIN}" -o /tmp/agg
+chmod +x /tmp/agg
+```
+
+### Render Command
+
+```bash
+/tmp/agg input.cast output.gif --speed 1 --font-size 14 --line-height 1.4
+```
+
+Options:
+- `--speed 1`: Real-time playback (increase to speed up)
+- `--font-size 14`: Good for blog embeds (12-16 range)
+- `--line-height 1.4`: Comfortable reading spacing
+- `--cols 80 --rows 36`: Override terminal dimensions
+
+### Verify Output
+
+The GIF will typically be 100-200KB for a 10-15 second animation. Check the
+last frame visually — the Read tool only shows the first frame of animated GIFs.
+Extract the last frame with Sharp to verify:
+
+```javascript
+await sharp('output.gif', { page: -1 }).png().toFile('/tmp/last-frame.png');
+```
+
+## Step 3: Composite into OG Image (Optional)
+
+To embed a mini terminal screenshot in a feature/OG image:
+
+1. Extract the best frame from the GIF (usually the last)
+2. Crop to the relevant content area
+3. Resize to fit (~400-500px wide)
+4. Apply rounded corners
+5. Composite onto the base OG image with Sharp
+
+See `references/og-compositing.md` for the Sharp compositing recipe.
+
+### Key Dimensions
+
+| Context | Terminal Width | Position |
+|---------|--------------|----------|
+| OG image (1200x630) | 440-480px | Right side, vertically centered |
+| Blog embed | 600px max | Centered, `.terminal-frame` CSS class |
+| X/Twitter card | 400px | Right side |
+
+## Blog Integration
+
+### CSS for Terminal Frames
+
+Add to the blog build if not already present:
+
+```css
+.terminal-frame {
+  margin: 32px auto;
+  max-width: 600px;
+  border-radius: 8px;
+  overflow: hidden;
+  border: 2px solid var(--color-primary);
+  box-shadow: 0 8px 32px rgba(0,0,0,0.15);
+}
+.terminal-frame img { width: 100%; height: auto; display: block; }
+```
+
+### Markdown Embed
+
+```html
+<div class="terminal-frame">
+  <img src="/blog/images/my-animation.gif" alt="Description" loading="lazy" />
+</div>
+```
+
+### MIME Type
+
+Ensure the serving layer handles `.gif`:
+
+```javascript
+'.gif': 'image/gif'  // Add to mime type map
+```
+
+## Common Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Logo renders red, not orange | Wrong palette index 1 | Set to `#DA7756` |
+| GIF clipped at bottom | Terminal rows too small | Increase `rows` in header |
+| Block characters garbled | Wrong font in renderer | Use agg (has built-in fonts) |
+| Read tool shows blank frame | Shows frame 1, which may be empty | Extract last frame with Sharp |
+| SVG rendering looks bad | Unicode blocks render poorly in SVG | Use agg — do not attempt SVG-based rendering |
+
+## Additional Resources
+
+### Reference Files
+
+- **`references/claude-code-palette.md`** — Full 16-color palette, ANSI codes, theme JSON
+- **`references/og-compositing.md`** — Sharp recipe for OG image compositing
+
+### Examples
+
+- **`examples/generate-ceremony-cast.mjs`** — Complete session start ceremony generator
+
+### Scripts
+
+- **`scripts/install-agg.sh`** — Download and install the agg binary

hooks/skills/terminal-gif/examples/generate-ceremony-cast.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * Generate a synthetic .cast (asciinema v3) file showing a GitMem session start.
+ * Content is anonymized. Then render it to GIF with `agg`.
+ */
+
+import { writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ANSI escape helpers
+const ESC = '\x1b';
+const RESET    = `${ESC}[0m`;
+const BOLD     = `${ESC}[1m`;
+const DIM      = `${ESC}[2m`;
+const NORMAL   = `${ESC}[22m`;
+const RED      = `${ESC}[31m`;     // palette 1: #DA7756 (Claude orange)
+const GREEN    = `${ESC}[32m`;     // palette 2: #00a600
+const YELLOW   = `${ESC}[33m`;     // palette 3: #999900
+const CYAN     = `${ESC}[36m`;     // palette 6: #00a6b3
+const WHITE    = `${ESC}[37m`;     // palette 7: #bfbfbf
+const BG_BLK   = `${ESC}[40m`;    // black bg (for logo blocks)
+const BG_DEF   = `${ESC}[49m`;    // default bg
+const FG_DEF   = `${ESC}[39m`;    // default fg
+const BR_RED   = `${ESC}[91m`;    // bright red: #e65535
+const BR_GREEN = `${ESC}[92m`;    // bright green: #00d900
+const BR_YELLOW= `${ESC}[93m`;    // bright yellow: #e6e600
+const BR_CYAN  = `${ESC}[96m`;    // bright cyan: #00e6e6
+const BR_WHITE = `${ESC}[97m`;    // bright white: #e6e6e6
+const BR_MAG   = `${ESC}[95m`;    // bright magenta: #e600e6
+
+// Build the cast file events: [delta_seconds, "o", "data"]
+const events = [];
+let t = 0;
+
+function out(delay, text) {
+  events.push([delay, 'o', text]);
+  t += delay;
+}
+
+function outln(delay, text) {
+  out(delay, text + '\r\n');
+}
+
+// --- Scene 1: Shell prompt + type "claude" ---
+out(0.5, '$ ');
+// Type "claude" character by character
+for (const ch of 'claude') {
+  out(0.08 + Math.random() * 0.06, ch);
+}
+out(0.3, '\r\n');
+
+// --- Scene 2: Claude Code header (actual layout from recordings) ---
+out(1.2, '');
+
+// Line 1: logo + Claude Code
+outln(0.0, ` ${RED}▐${BG_BLK}▛███▜${BG_DEF}▌${FG_DEF}   ${BOLD}Claude Code${NORMAL} ${WHITE}v2.1.32${FG_DEF}`);
+
+// Line 2: logo + model
+outln(0.0, `${RED}▝▜${BG_BLK}█████${BG_DEF}▛▘${FG_DEF}  ${WHITE}Sonnet 4.5 · API key${FG_DEF}`);
+
+// Line 3: logo feet + path
+outln(0.0, `${RED}  ▘▘ ▝▝${FG_DEF}    ${WHITE}~/my-project${FG_DEF}`);
+
+outln(0.0, '');
+
+// Horizontal rule
+outln(0.0, `${DIM}${WHITE}${'─'.repeat(76)}${FG_DEF}${NORMAL}`);
+
+// Prompt hint
+outln(0.0, `${DIM}❯ ${NORMAL}Try "how does <filepath> work?"${RESET}`);
+
+// Horizontal rule
+outln(0.0, `${DIM}${WHITE}${'─'.repeat(76)}${FG_DEF}${NORMAL}`);
+
+// Status bar
+outln(0.0, `  ${BR_MAG}⏵⏵ bypass permissions on${FG_DEF}`);
+
+// --- Scene 3: User types "lets start" ---
+out(1.5, '');
+
+// Replace prompt area
+outln(0.0, '');
+out(0.0, `${BR_WHITE}❯ ${RESET}`);
+for (const ch of 'lets start') {
+  out(0.06 + Math.random() * 0.05, `${BR_WHITE}${ch}${RESET}`);
+}
+out(0.4, '\r\n');
+
+// --- Scene 4: Frosting spinner ---
+outln(0.3, `${RED}· Frosting…${FG_DEF}`);
+outln(0.8, `  ${BR_YELLOW}SessionStart hook firing...${FG_DEF}`);
+
+// --- Scene 5: GitMem session start ---
+out(1.0, '\r\n');
+outln(0.0, `  ${BR_GREEN}${BOLD}gitmem ── session started${NORMAL}${FG_DEF}`);
+outln(0.1, `  ${DIM}a3f8b291 · cli · my-project${NORMAL}`);
+outln(0.1, '');
+
+// --- Scene 6: Threads ---
+out(0.8, '');
+outln(0.0, `  ${BR_CYAN}${BOLD}Threads (5)${NORMAL}${FG_DEF}`);
+outln(0.15, `    Fix auth token refresh — stale JWT after 24h`);
+outln(0.1, `    Migrate user table to use UUID primary keys`);
+outln(0.1, `    Add rate limiting to /api/search endpoint`);
+outln(0.1, `    Investigate Docker build cache misses on CI`);
+outln(0.1, `    ${DIM}+1 more${NORMAL}`);
+outln(0.0, '');
+
+// --- Scene 7: Decisions ---
+out(0.8, '');
+outln(0.0, `  ${BR_YELLOW}${BOLD}Decisions (3)${NORMAL}${FG_DEF}`);
+outln(0.15, `    Use Zod for API validation, not Joi    ${DIM}· Feb 18${NORMAL}`);
+outln(0.1, `    Keep Postgres — no migration to Mongo  ${DIM}· Feb 17${NORMAL}`);
+outln(0.1, `    Rate limit: token bucket, not sliding  ${DIM}· Feb 16${NORMAL}`);
+outln(0.0, '');
+
+// --- Scene 8: Summary ---
+out(0.6, '');
+outln(0.0, `  ${DIM}${'─'.repeat(50)}${NORMAL}`);
+outln(0.2, `  ${BR_GREEN}3 scars recalled · 5 threads open · ready${FG_DEF}`);
+outln(0.0, '');
+
+// --- Scene 9: Agent response with scars ---
+out(1.2, '');
+outln(0.0, `  ${BR_WHITE}Loaded institutional memory. 3 scars surfaced:${FG_DEF}`);
+outln(0.3, `    [${BR_RED}HIGH${FG_DEF}] JWT refresh tokens expire silently after rotation`);
+outln(0.2, `    [${BR_YELLOW}MED${FG_DEF}]  Docker layer caching requires consistent COPY order`);
+outln(0.2, `    [${DIM}LOW${NORMAL}]  Rate limit headers must include X-RateLimit-Reset`);
+outln(0.0, '');
+outln(0.5, `  ${BR_GREEN}Acknowledging scars before proceeding...${FG_DEF}`);
+
+// Hold at end
+out(3.0, '');
+
+// --- Write .cast file ---
+const header = {
+  version: 3,
+  term: {
+    cols: 80,
+    rows: 36,
+    type: 'xterm',
+    theme: {
+      fg: '#a1a1a1',
+      bg: '#30302d',
+      palette: '#000000:#DA7756:#00a600:#999900:#0000b3:#b300b3:#00a6b3:#bfbfbf:#262624:#e65535:#00d900:#e6e600:#0000ff:#e600e6:#00e6e6:#e6e6e6'
+    }
+  },
+  timestamp: Math.floor(Date.now() / 1000),
+  idle_time_limit: 5.0,
+};
+
+const castPath = join(__dirname, 'images', 'session-start-ceremony.cast');
+const gifPath = join(__dirname, 'images', 'session-start-ceremony.gif');
+
+let castContent = JSON.stringify(header) + '\n';
+for (const [delay, type, data] of events) {
+  castContent += JSON.stringify([delay, type, data]) + '\n';
+}
+
+writeFileSync(castPath, castContent);
+console.log(`Cast file: ${castPath} (${events.length} events, ${Math.round(t)}s total)`);
+
+// --- Render with agg ---
+try {
+  execSync(`/tmp/agg ${castPath} ${gifPath} --speed 1 --font-size 14 --line-height 1.4`, {
+    stdio: 'inherit',
+  });
+  console.log(`GIF: ${gifPath}`);
+} catch (e) {
+  console.error('agg render failed:', e.message);
+  console.log('Cast file written — render manually with: agg', castPath, gifPath);
+}