Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Consolidate demo assets to docs/static/assets/

Maximilian Roos7aba50354278
diff --git a/.gitignore b/.gitignore
index b724353d2..d7eb9fcb5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,4 @@
/target
-docs/demos/out/
docs/static/assets/
# Lychee link checker cache
diff --git a/dev/publish-assets b/dev/publish-assets
index 4b09f6120..9cdb5edcd 100755
--- a/dev/publish-assets
+++ b/dev/publish-assets
@@ -5,7 +5,7 @@ set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(dirname "$SCRIPT_DIR")"
ASSETS_REPO="$REPO_ROOT/../worktrunk-assets"
-DEMOS_DIR="$REPO_ROOT/docs/demos/out"
+DEMOS_DIR="$REPO_ROOT/docs/static/assets"
# Clone assets repo if needed
if [[ ! -d "$ASSETS_REPO/.git" ]]; then
@@ -27,7 +27,7 @@ if ! git pull --ff-only; then
exit 1
fi
-# Copy all GIFs from demos/out
+# Copy all GIFs
echo "Copying assets..."
copied=()
for src in "$DEMOS_DIR"/*.gif; do
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 5d102c31c..c51f918ca 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -257,11 +257,11 @@ This enables precise matching of the outer region.
## Demo GIF workflow
-Demo GIFs (~2MB each) are stored in a separate `worktrunk-assets` repo to avoid bloating git history.
+Demo GIFs (~2MB each) are stored in a separate `worktrunk-assets` repo to avoid bloating git history. Both build and fetch output to `docs/static/assets/` (gitignored), so local builds override fetched assets.
**For local development:**
```bash
-./dev/fetch-assets # Download to docs/static/assets/ (gitignored)
+./dev/fetch-assets # Download published assets
```
**To regenerate demos** (required after CLI output changes):
diff --git a/docs/demos/CLAUDE.md b/docs/demos/CLAUDE.md
index 904f4d8de..4d2b1210b 100644
--- a/docs/demos/CLAUDE.md
+++ b/docs/demos/CLAUDE.md
@@ -6,9 +6,10 @@
docs/demos/
build # Unified build script
tapes/ # All VHS tape files (templated)
- out/ # Output GIFs (gitignored)
shared/ # Python library, themes, fixtures
vhs-keystrokes/ # Custom VHS binary (gitignored, built on demand)
+
+docs/static/assets/ # Output GIFs (gitignored, shared with fetch-assets)
```
Tape files use template variables (`{{FONTSIZE}}`, `{{WIDTH}}`, `{{HEIGHT}}`) so the same tape produces different sizes for docs vs Twitter.
@@ -42,14 +43,16 @@ After building, publish to the assets repo:
./dev/publish-assets
```
-This copies `docs/demos/out/*.gif` to the `worktrunk-assets` repo (sibling directory), commits, and pushes. The script clones the repo via `gh` if missing.
+This copies `docs/static/assets/*.gif` to the `worktrunk-assets` repo (sibling directory), commits, and pushes. The script clones the repo via `gh` if missing.
-For local preview, fetch published assets:
+To fetch published assets (without rebuilding):
```bash
-./dev/fetch-assets # Downloads to docs/static/assets/ (gitignored)
+./dev/fetch-assets
```
+Both build and fetch output to the same location (`docs/static/assets/`), so local builds override fetched assets.
+
## vhs-keystrokes setup (REQUIRED for wt-select demos)
The `wt-select` demos require a custom VHS fork with keystroke overlay. **Claude must build this binary before regenerating demos.**
@@ -70,6 +73,46 @@ cd vhs-keystrokes && go build -o vhs-keystrokes .
The binary is gitignored. Build scripts skip wt-select GIF recording if missing—**always build vhs-keystrokes first** when regenerating demos.
+### Keystroke timing calibration
+
+The keystroke overlay timing is controlled by `keystrokeDelayMS` in `ffmpeg.go`:
+
+```go
+keystrokeDelayMS = 500.0 // Delay to sync with terminal rendering
+```
+
+**How this was calibrated:**
+1. The overlay must appear synchronized with when the terminal responds to the keystroke
+2. Initial value (600ms) showed keystrokes appearing ~240ms LATE (after terminal changed)
+3. Frame-by-frame GIF analysis (25fps = 40ms/frame) revealed the exact offset
+4. Reduced to 500ms achieves perfect sync—keystroke and terminal change on same frame
+
+**To recalibrate if needed:**
+```bash
+# Extract frames from GIF
+ffmpeg -i demo.gif -vsync 0 /tmp/gif-frames/frame_%04d.png
+
+# Compare frames to find when terminal changes vs when keystroke appears
+# Adjust keystrokeDelayMS: increase if keystroke appears too early, decrease if too late
+```
+
+## wt-select demo goals
+
+The wt-select demo showcases **realistic variety in all columns**:
+
+| Column | Demonstration |
+|--------|---------------|
+| CI | Hollow ○ (branch CI) vs filled ● (PR CI) vs none |
+| HEAD± | Large staged diff (+54), small unstaged (+8), none |
+| Status | Staged changes (+), unstaged (!), ahead/behind (↕) |
+| main↕ | Some branches ahead-only, some ahead-and-behind |
+| main…± | Meaningful merge-base diffstats (small to 300+ lines) |
+
+Branch setup (from shared infrastructure):
+- **alpha** — Large working tree changes, unpushed commits, PR CI
+- **beta** — Staged changes, behind main, branch CI
+- **hooks** — Staged+unstaged changes, no remote
+
## Light/dark theme variants
The docs build generates both light and dark GIF variants:
@@ -138,11 +181,24 @@ Key fields in `.claude.json` for suppressing notifications:
- `numStartups: 100` - makes Claude think it's been run many times
- `hasCompletedOnboarding: true` - skips onboarding
+## Viewing GIF results
+
+**Do NOT use `open` on the GIF** — that's for the user to do manually.
+
+Inline viewing options:
+```bash
+# Quick Look (macOS)
+qlmanage -p docs/static/assets/wt-select.gif
+
+# iTerm2 inline images
+imgcat docs/static/assets/wt-select.gif
+```
+
## Extracting frames from a GIF for inspection
```bash
mkdir -p /tmp/frames
-magick docs/demos/out/wt-switch.gif -coalesce /tmp/frames/frame_%03d.png
+magick docs/static/assets/wt-switch.gif -coalesce /tmp/frames/frame_%03d.png
# View a specific frame
open /tmp/frames/frame_200.png
diff --git a/docs/demos/build b/docs/demos/build
index cfb44c997..c0e87f686 100755
--- a/docs/demos/build
+++ b/docs/demos/build
@@ -27,7 +27,7 @@ from shared import (
)
REPO_ROOT = SCRIPT_DIR.parent.parent
-OUT_DIR = SCRIPT_DIR / "out"
+OUT_DIR = SCRIPT_DIR.parent / "static" / "assets"
TAPES_DIR = SCRIPT_DIR / "tapes"
# Sizes
diff --git a/docs/demos/shared/CLAUDE.md b/docs/demos/shared/CLAUDE.md
deleted file mode 100644
index 3d2777e7e..000000000
--- a/docs/demos/shared/CLAUDE.md
+++ /dev/null
@@ -1,106 +0,0 @@
-# wt select Demo Recording
-
-## Running the Demo
-
-```bash
-./docs/demos/wt-select/build
-```
-
-Creates:
-- `docs/demos/wt-select/out/wt-select.gif` - Light theme demo
-- `docs/demos/wt-select/out/wt-select-dark.gif` - Dark theme demo
-- Demo repo at `docs/demos/wt-select/out/.demo-select/` (gitignored)
-
-Theme colors are defined in `docs/demos/shared/themes.py` to match the doc site's CSS variables.
-
-## Demo Goals
-
-The demo showcases `wt select` with **realistic variety in all columns**:
-
-```
-Branch Status HEAD± main↕ main…± Remote⇅ CI Age
-@ main ^ ○ now
-+ streaming + +54 -5 ● now
-+ doctor ↕ ↑1 ↓1 +320 -14 ● 2d
-+ llm-templates ! ↕ +8 ↑1 ↓1 +263 -192 3d
-```
-
-Key demonstration points:
-- **CI column**: hollow ○ (branch CI) vs filled ● (PR CI) vs none
-- **HEAD± column**: Large staged diff (+54), small unstaged (+8), none
-- **Status column**: Staged changes (+), unstaged (!), ahead/behind (↕)
-- **main↕ column**: Some branches ahead-only, some ahead-and-behind
-- **main…± column**: Meaningful merge-base diffstats (small to 300+ lines)
-
-## How It Works
-
-Uses the **unified demo infrastructure** (`prepare_demo_repo()` from `shared/lib.py`), same as wt-core and wt-merge demos. The repo is a synthetic "acme" Rust project with alpha/beta/hooks branches designed to showcase column variety.
-
-Branch setup (from shared infrastructure):
-- **alpha** - Large working tree changes, unpushed commits, PR CI
-- **beta** - Staged changes, behind main, branch CI
-- **hooks** - Staged+unstaged changes, no remote
-
-The demo navigates to alpha to show the large committed diff in the main…± panel.
-
-## Viewing Results
-
-**Do NOT use `open` on the GIF** - that's for the user to do manually.
-
-Inline viewing options:
-- Quick Look: `qlmanage -p docs/demos/wt-select/out/wt-select.gif`
-- iTerm2: `imgcat docs/demos/wt-select/out/wt-select.gif`
-
-## Prerequisites
-
-- `wt` (worktrunk) installed and in PATH
-- `starship` for prompt
-- **Custom VHS fork** with keystroke overlay (**required** - standard VHS won't work)
-
-### Building the VHS Fork
-
-The demo requires a custom VHS fork that displays keystroke overlays. **You must build this before running the demo:**
-
-```bash
-cd docs/demos
-git clone -b keypress-overlay https://github.com/max-sixty/vhs.git vhs-keystrokes
-cd vhs-keystrokes
-go build -o vhs-keystrokes .
-```
-
-The build scripts look for the binary at `docs/demos/vhs-keystrokes/vhs-keystrokes`.
-
-**Why custom VHS?** The fork adds a large keystroke overlay in the center of the screen, showing what keys are being pressed. This is essential for demo GIFs where viewers need to see navigation keys (↓, Ctrl+D, etc.).
-
-Override path with: `VHS_KEYSTROKES=/path/to/binary ./build`
-
-### Keystroke Timing Calibration
-
-The keystroke overlay timing is controlled by `keystrokeDelayMS` in `ffmpeg.go`:
-
-```go
-keystrokeDelayMS = 500.0 // Delay to sync with terminal rendering
-```
-
-**How this was calibrated:**
-1. The overlay must appear synchronized with when the terminal responds to the keystroke
-2. Initial value (600ms) showed keystrokes appearing ~240ms LATE (after terminal changed)
-3. Frame-by-frame GIF analysis (25fps = 40ms/frame) revealed the exact offset
-4. Reduced to 500ms achieves perfect sync - keystroke and terminal change on same frame
-
-**To recalibrate if needed:**
-```bash
-# Extract frames from GIF
-ffmpeg -i demo.gif -vsync 0 /tmp/gif-frames/frame_%04d.png
-
-# Compare frames to find when terminal changes vs when keystroke appears
-# Adjust keystrokeDelayMS: increase if keystroke appears too early, decrease if too late
-```
-
-## Files
-
-- `build` - Main build script (uses shared infrastructure from `docs/demos/shared/`)
-- `demo.tape` - VHS tape file with recording script
-- `out/` - Output directory (gitignored)
-
-Starship config comes from shared `docs/demos/shared/fixtures/`.