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/.gitignoreindex b724353d2..d7eb9fcb5 100644--- a/.gitignore+++ b/.gitignore@@ -1,5 +1,4 @@/target-docs/demos/out/docs/static/assets/# Lychee link checker cachediff --git a/dev/publish-assets b/dev/publish-assetsindex 4b09f6120..9cdb5edcd 100755--- a/dev/publish-assets+++ b/dev/publish-assets@@ -5,7 +5,7 @@ set -euo pipefailSCRIPT_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 neededif [[ ! -d "$ASSETS_REPO/.git" ]]; then@@ -27,7 +27,7 @@ if ! git pull --ff-only; thenexit 1fi-# Copy all GIFs from demos/out+# Copy all GIFsecho "Copying assets..."copied=()for src in "$DEMOS_DIR"/*.gif; dodiff --git a/docs/CLAUDE.md b/docs/CLAUDE.mdindex 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.mdindex 904f4d8de..4d2b1210b 100644--- a/docs/demos/CLAUDE.md+++ b/docs/demos/CLAUDE.md@@ -6,9 +6,10 @@docs/demos/build # Unified build scripttapes/ # All VHS tape files (templated)- out/ # Output GIFs (gitignored)shared/ # Python library, themes, fixturesvhs-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 variantsThe 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```bashmkdir -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 frameopen /tmp/frames/frame_200.pngdiff --git a/docs/demos/build b/docs/demos/buildindex 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"# Sizesdiff --git a/docs/demos/shared/CLAUDE.md b/docs/demos/shared/CLAUDE.mddeleted file mode 100644index 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/`.