chore(scripts): parallel + filterable cli_interactive gif rendering

`scripts/gen_cli_interactive_gifs.py` now renders tapes through a
ThreadPoolExecutor (CPU-aware default capped at 4) and accepts optional
tape names as CLI args, so contributors can iterate on a single tape
without re-rendering all five.

Make `shared/base.tape` and `shared/cleanup.tape` use a per-tape
`mktemp -d` workdir instead of the hardcoded `/tmp/commitizen-example`,
so concurrent vhs runs do not race on the same directory.

Generated-by: GitHub Copilot CLI (claude-opus-4.7-1m-internal)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: bearomorphism

docs/contributing/contributing.md

@@ -71,6 +71,8 @@ If you're a first-time contributor, please check out issues labeled [good first
 5. **Documentation**
     - Update `docs/README.md` if needed
     - For CLI help screenshots: `uv run poe doc:screenshots`
+        - To re-render a single interactive tape, e.g. `commit`:
+          `python scripts/gen_cli_interactive_gifs.py commit`
     - Prefer [Google style documentation](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings), which works well with editors like VSCode and PyCharm
     - **DO NOT** update `CHANGELOG.md` (automatically generated)
     - **DO NOT** update version numbers (automatically handled)

docs/images/shared/base.tape

@@ -40,6 +40,6 @@ Type "PS1='$ '"
 Enter
 Sleep 300ms
 
-Type "rm -rf /tmp/commitizen-example && mkdir -p /tmp/commitizen-example && cd /tmp/commitizen-example"
+Type `WORKDIR=$(mktemp -d "${TMPDIR:-/tmp}/commitizen-example.XXXXXX") && cd "$WORKDIR"`
 Enter
 Sleep 500ms

docs/images/shared/cleanup.tape

@@ -1,4 +1,4 @@
 Hide
-Type "cd /tmp && rm -rf /tmp/commitizen-example"
+Type `cd "${TMPDIR:-/tmp}" && rm -rf "$WORKDIR"`
 Enter
 Sleep 200ms

scripts/gen_cli_interactive_gifs.py

@@ -1,39 +1,108 @@
+"""Render docs/images/*.tape with VHS, optionally in parallel.
+
+Usage:
+    uv run poe doc:screenshots                              # all tapes
+    python scripts/gen_cli_interactive_gifs.py              # all tapes
+    python scripts/gen_cli_interactive_gifs.py commit init  # subset
+    python scripts/gen_cli_interactive_gifs.py -j 1         # serial
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
 import subprocess
+import sys
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 
+VHS_DIR = Path(__file__).parent.parent / "docs" / "images"
+OUTPUT_DIR = VHS_DIR / "cli_interactive"
 
-def gen_cli_interactive_gifs() -> None:
-    """Generate GIF screenshots for interactive commands using VHS."""
-    vhs_dir = Path(__file__).parent.parent / "docs" / "images"
-    output_dir = Path(__file__).parent.parent / "docs" / "images" / "cli_interactive"
-    output_dir.mkdir(parents=True, exist_ok=True)
 
-    vhs_files = list(vhs_dir.glob("*.tape"))
+def gen_cli_interactive_gifs(
+    tape_names: list[str] | None = None,
+    max_workers: int | None = None,
+) -> None:
+    """Render VHS tapes in parallel.
 
-    if not vhs_files:
+    ``tape_names`` filters by stem or filename (``None`` renders all).
+    ``max_workers`` defaults to ``min(len(tapes), 4)``; pass ``1`` for serial.
+    """
+    if shutil.which("vhs") is None:
+        raise SystemExit(
+            "VHS is not installed. Please install it from: "
+            "https://github.com/charmbracelet/vhs"
+        )
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    all_tapes = sorted(VHS_DIR.glob("*.tape"))
+    if not all_tapes:
         print("No VHS tape files found in docs/images/, skipping")
         return
 
-    for vhs_file in vhs_files:
-        print(f"Processing: {vhs_file.name}")
-        try:
-            subprocess.run(
-                ["vhs", vhs_file.name],
-                check=True,
-                cwd=vhs_dir,
-            )
-            gif_name = vhs_file.stem + ".gif"
-            print(f"✓ Generated {gif_name}")
-        except FileNotFoundError:
-            print(
-                "✗ VHS is not installed. Please install it from: "
-                "https://github.com/charmbracelet/vhs"
-            )
-            raise
-        except subprocess.CalledProcessError as e:
-            print(f"✗ Error processing {vhs_file.name}: {e}")
-            raise
+    if tape_names:
+        by_stem = {t.stem: t for t in all_tapes}
+        tapes: list[Path] = []
+        seen: set[str] = set()
+        for name in tape_names:
+            stem = Path(name).stem
+            if stem in seen:
+                continue
+            if stem not in by_stem:
+                raise SystemExit(
+                    f"Unknown tape: {name}. Available: {', '.join(sorted(by_stem))}"
+                )
+            seen.add(stem)
+            tapes.append(by_stem[stem])
+    else:
+        tapes = all_tapes
+
+    workers = max(1, max_workers if max_workers is not None else min(len(tapes), 4))
+    print(f"Rendering {len(tapes)} tape(s) with up to {workers} worker(s)")
+
+    def _render(tape: Path) -> None:
+        subprocess.run(
+            ["vhs", tape.name],
+            check=True,
+            cwd=VHS_DIR,
+            capture_output=True,
+            text=True,
+        )
+
+    errors: list[Path] = []
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        futures = {pool.submit(_render, t): t for t in tapes}
+        for fut in as_completed(futures):
+            tape = futures[fut]
+            try:
+                fut.result()
+            except subprocess.CalledProcessError as exc:
+                print(f"✗ {tape.name}", file=sys.stderr)
+                if exc.stdout:
+                    print(exc.stdout, file=sys.stderr)
+                if exc.stderr:
+                    print(exc.stderr, file=sys.stderr)
+                errors.append(tape)
+            else:
+                print(f"✓ {tape.stem}.gif")
+
+    if errors:
+        raise SystemExit("vhs failed for: " + ", ".join(t.name for t in errors))
 
 
 if __name__ == "__main__":
-    gen_cli_interactive_gifs()
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "tapes",
+        nargs="*",
+        help="Tape stems or filenames (e.g. 'commit' or 'commit.tape'). Default: all.",
+    )
+    parser.add_argument(
+        "-j",
+        "--max-workers",
+        type=int,
+        default=None,
+        help="Max parallel vhs invocations. Default: min(len(tapes), 4). Use 1 for serial.",
+    )
+    args = parser.parse_args()
+    gen_cli_interactive_gifs(args.tapes or None, args.max_workers)