# aiterm Demo GIFs

Terminal recordings for aiterm documentation using [VHS](https://github.com/charmbracelet/vhs).

## Requirements

```bash
brew install vhs gifsicle
```

## Generate GIFs

```bash
# Generate all demos
cd docs/demos
for tape in *.tape; do
  vhs "$tape"
done

# Or generate specific demo
vhs feature-workflow.tape
```

## Optimize GIFs

Use `gifsicle` for ~30% smaller file sizes:

```bash
# Install gifsicle
brew install gifsicle

# Optimize all GIFs (lossy compression)
for gif in *.gif; do
  gifsicle -O3 --lossy=80 "$gif" -o "${gif%.gif}-opt.gif"
  mv "${gif%.gif}-opt.gif" "$gif"
done
```

**Optimization results:**
- `-O3` - Maximum optimization level
- `--lossy=80` - Lossy compression (good quality/size balance)
- Typical savings: 25-35% smaller files

## Available Demos

| Demo | Description | Duration | Used In |
|------|-------------|----------|---------|
| `feature-workflow.tape` | Feature branch commands (status, start, cleanup) | ~30s | Feature Workflow |
| `context-detection.tape` | Context detection and profile switching | ~25s | Feature Tutorial |
| `worktree-setup.tape` | Creating worktrees with craft + aiterm | ~20s | Git Worktrees Guide |
| `craft-finish.tape` | AI-assisted feature completion workflow | ~30s | Feature Tutorial |
| `worktree-complete.tape` | Full worktree lifecycle (create → work → cleanup) | ~35s | - |
| `sessions.tape` | Session coordination (live, current, conflicts) | ~25s | Sessions Guide |

## Customization

Edit tape files to adjust:

- `Set FontSize` - Text size (default: 18)
- `Set Width/Height` - GIF dimensions (800x500)
- `Set Theme` - Color scheme (Dracula)
- `Set TypingSpeed` - How fast text appears (40ms)
- `Sleep` - Pause duration between commands

## Embedding in Docs

```markdown
![Feature Workflow](./demos/feature-workflow.gif)
```

## Tape File Template

```tape
# Demo Title
# Brief description

Output demo-name.gif

Set Shell "zsh"
Set FontSize 18
Set Width 800
Set Height 500
Set Theme "Dracula"
Set Padding 15
Set TypingSpeed 40ms

# Command 1
Type "command here"
Enter
Sleep 2s

# Command 2
Type "another command"
Enter
Sleep 2s
```

## CI/CD Generation

GIFs are automatically regenerated by GitHub Actions when tape files change.

**Workflow:** `.github/workflows/demos.yml`

**Features:**
- Validates tape file syntax
- Generates GIFs on macOS runner
- Optimizes with gifsicle (~30% smaller)
- Posts PR comment with file sizes
- Auto-commits to main/dev

**Triggers:**
- Push to main/dev with tape changes
- PRs with tape changes
- Manual: Actions → Demo GIFs → Run workflow

## Tips

- Keep demos under 30 seconds
- Use `Sleep` to let viewers read output
- Add comments in tape files for context
- Test with `vhs --preview` before generating
