Skip to content

Short vertical cut-paper explainer reels, made by your coding agent. Nine Agent Skills plus a Remotion library. Works with Claude Code, OpenCode, Codex, Gemini CLI, Cursor, Copilot and more.

Smoother install: fix skill backups, stale config, zsh, venv and re-run failures

sanatd3a80b17d0a6
diff --git a/README.md b/README.md
index 10c8d26..eea6601 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,7 @@ You describe the video ("explain this repo in 25 seconds"). The skills research
| Cuts | `whip`, `zoomThrough`, `pageTurn`, `tearAway`, `tapePull`, `stampCut`, `infiniteZoom`, `popUpBook`, `keyhole`, `burnAway`, chained with `CutSeries` |
| Film look | gate weave and flicker, moving felt fibre, lens dirt, lamp flicker, halftone, graph paper |
| Overlays | taped headline banner, word-by-word torn caption tags, hook title, real-screenshot proof card with marker circles |
-| Kit | 212 exports in `library/papercut/kit`: paper primitives (`Paper`, `Slab`, `Disc`, `Pill`, `Card`), a base critter with accessories, prop sets, rough UI rebuilds, a comment-keyword CTA scene |
+| Kit | 188 exports in `library/papercut/kit`: paper primitives (`Paper`, `Slab`, `Disc`, `Pill`, `Card`), a base critter with accessories, prop sets, rough UI rebuilds, a comment-keyword CTA scene |
| Sound | 79 synthesised SFX and 8 music beds, picked by name, rendered with Web Audio (no audio files to license) |
| Tools | scaffold, cue sheets, cached renders, QA contact sheets, catalog generator, placeholder narration, optional local TTS setup |
@@ -79,7 +79,7 @@ Non-interactive and scoped installs:
./install.sh --uninstall # remove the links it made
```
-By default skills are symlinked into `~/.claude/skills` and the subagent into `~/.claude/agents`, so a `git pull` updates them. The installer writes `~/.config/papercut-explainer/config.env` with `PAPERCUT_LIB` and the Python paths it created; the library scripts and the skills read it. It never installs system packages (it prints the `brew` or `apt` line instead), asks before replacing an existing skill folder, and does not touch your shell profile.
+By default skills are symlinked into `~/.claude/skills` and the subagent into `~/.claude/agents`, so a `git pull` updates them. The installer writes `~/.config/papercut-explainer/config.env` with `PAPERCUT_LIB` and the Python paths it created; the library scripts and the skills read it. It never installs system packages (it prints the `brew` or `apt` line instead), replaces an identical existing skill folder (such as one from `npx skills add`) and moves a different one to `~/.config/papercut-explainer/backups/` instead of the skills folder, and does not touch your shell profile.
Prefer to let Claude do it? Open Claude Code in this folder and say **"set up papercut-explainer"**. The `papercut-setup` skill asks which mode you want, confirms any large download, runs the installer with the right flags and checks the result.
@@ -214,6 +214,7 @@ Projects keep a snapshot of the kit in `src/lib/`, so an old episode renders the
| OS | macOS (tested) or Linux (scripts are bash; not run end to end). Windows: use WSL. |
| Node, npm | Node 20+ |
| ffmpeg | on `PATH` |
+| rubberband | only if you set a voice `tempo` other than 1.0 (`brew install rubberband`) |
| rsync | on `PATH` (kit sync) |
| Python | 3.9+ for the tools; 3.10–3.12 for the voice venv (the installer uses `uv` if you have it, else `python3.12`/`3.11`/`3.10`) |
| Chrome or Chromium | for the SFX and music render only (`CHROME_PATH` to override). Video renders use Remotion's own headless browser, downloaded on first render. |
diff --git a/install.sh b/install.sh
index 5d040c3..30788b6 100755
--- a/install.sh
+++ b/install.sh
@@ -16,7 +16,7 @@
# Options
# --mode M minimal | standard | full | custom
# --components a,b,c with --mode custom: skills,deps,remotion-skills,pytools,tts,verify
-# --skills-dir DIR where skills go (default ~/.claude/skills)
+# --skills-dir DIR where skills go (default ~/.claude/skills); the subagent goes in the sibling folder DIR/../agents
# --project DIR install skills into DIR/.claude/skills instead (one project only)
# --copy copy the skills instead of symlinking them (no live updates from this checkout)
# --tts-model 1.7B|0.6B model size for the voice step (default 1.7B)
@@ -31,23 +31,25 @@ CFG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/papercut-explainer"
DATA_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/papercut-explainer"
export PAPERCUT_CONFIG="$CFG_DIR/config.env"
. "$LIB/env.sh"
+export PAPERCUT_LIB="$LIB" # this checkout wins over a stale path left in an older config file
MODE=""; COMPONENTS=""; SKILLS_DIR="$HOME/.claude/skills"; COPY=0; YES=0; DRY=0
TTS_MODEL=1.7B; WITH_CLONE=0; DOCTOR=0; UNINSTALL=0
while [ $# -gt 0 ]; do
case "$1" in
- --mode) MODE=$2; shift 2 ;;
- --components) COMPONENTS=$2; shift 2 ;;
- --skills-dir) SKILLS_DIR=$2; shift 2 ;;
- --project) SKILLS_DIR="$(cd "$2" && pwd)/.claude/skills"; shift 2 ;;
+ --mode) MODE=${2:?--mode needs a value}; shift 2 ;;
+ --components) COMPONENTS=${2:?--components needs a value}; shift 2 ;;
+ --skills-dir) SKILLS_DIR=${2:?--skills-dir needs a value}; shift 2 ;;
+ --project) [ -d "${2:?--project needs a folder}" ] || { echo "--project: $2 is not a folder" >&2; exit 2; }
+ SKILLS_DIR="$(cd "$2" && pwd)/.claude/skills"; shift 2 ;;
--copy) COPY=1; shift ;;
- --tts-model) TTS_MODEL=$2; shift 2 ;;
+ --tts-model) TTS_MODEL=${2:?--tts-model needs 1.7B or 0.6B}; shift 2 ;;
--with-clone) WITH_CLONE=1; shift ;;
--yes|-y) YES=1; shift ;;
--dry-run) DRY=1; shift ;;
--doctor) DOCTOR=1; shift ;;
--uninstall) UNINSTALL=1; shift ;;
- -h|--help) sed -n '2,32p' "$0"; exit 0 ;;
+ -h|--help) sed -n '2,/^set -euo/p' "$0" | sed '$d'; exit 0 ;;
*) echo "unknown option: $1 (see --help)" >&2; exit 2 ;;
esac
done
@@ -198,14 +200,17 @@ step_config() {
step_skills() {
say "skills -> $SKILLS_DIR"
run mkdir -p "$SKILLS_DIR" "$CFG_DIR"
- local ts; ts="$(date +%Y%m%d-%H%M%S)"
+ local ts bak; ts="$(date +%Y%m%d-%H%M%S)"; bak="$CFG_DIR/backups"
for s in $(SKILL_NAMES); do
local src="$ROOT/skills/$s" dst="$SKILLS_DIR/$s"
if [ -L "$dst" ]; then
run rm "$dst"
elif [ -e "$dst" ]; then
- if confirm "$dst exists and is not a link from this installer. Back it up and replace?" y; then
- run mv "$dst" "$dst.bak-$ts"; miss "backed up to $dst.bak-$ts"
+ if [ -f "$dst/.papercut-installed" ] || diff -rq "$src" "$dst" >/dev/null 2>&1; then
+ run rm -rf "$dst" # an earlier --copy install or an identical copy (npx skills add): refresh it
+ elif confirm "$dst exists and differs from this checkout. Back it up and replace?" y; then
+ # backups live outside the skills folder, so Claude Code does not load them as duplicate skills
+ run mkdir -p "$bak"; run mv "$dst" "$bak/$s.$ts"; miss "backed up to $bak/$s.$ts"
else miss "kept existing $s"; continue; fi
fi
if [ "$COPY" = 1 ]; then run cp -R "$src" "$dst"; [ "$DRY" = 1 ] || touch "$dst/.papercut-installed"; else run ln -s "$src" "$dst"; fi
@@ -218,13 +223,18 @@ step_skills() {
for a in "$ROOT"/agents/*.md; do
[ -f "$a" ] || continue
local adst="$adir/$(basename "$a")"
- if [ -e "$adst" ] && [ ! -L "$adst" ]; then miss "kept existing agent $(basename "$a")"; continue; fi
- [ -L "$adst" ] && run rm "$adst"
+ if [ -L "$adst" ]; then run rm "$adst"
+ elif [ -e "$adst" ]; then
+ if cmp -s "$a" "$adst"; then run rm "$adst" # identical copy: refresh it
+ elif confirm "$adst exists and differs from this checkout. Back it up and replace?" y; then
+ run mkdir -p "$CFG_DIR/backups"; run mv "$adst" "$CFG_DIR/backups/$(basename "$a" .md).$ts.md"; miss "backed up to $CFG_DIR/backups"
+ else miss "kept existing agent $(basename "$a")"; continue; fi
+ fi
if [ "$COPY" = 1 ]; then run cp "$a" "$adst"; else run ln -s "$a" "$adst"; fi
[ "$DRY" = 1 ] || echo "$adst" >> "$CFG_DIR/installed.txt"
ok "agent $(basename "$a" .md)"
done
- [ "$DRY" = 1 ] || { sort -u "$CFG_DIR/installed.txt" -o "$CFG_DIR/installed.txt"; }
+ [ "$DRY" = 1 ] || [ ! -f "$CFG_DIR/installed.txt" ] || sort -u "$CFG_DIR/installed.txt" -o "$CFG_DIR/installed.txt"
}
step_deps() {
@@ -246,7 +256,7 @@ step_remotion() {
say "Remotion agent skills"
if [ -f "$HOME/.claude/skills/remotion-best-practices/SKILL.md" ]; then ok "already installed"; return; fi
command -v npx >/dev/null 2>&1 || { note_fail remotion-skills "npx not found"; return 1; }
- run npx -y skills@latest add remotion-dev/skills -g -y || note_fail remotion-skills "npx skills add failed; run it by hand"
+ run npx -y skills@latest add remotion-dev/skills -g -y -a claude-code || note_fail remotion-skills "npx skills add failed; run it by hand"
}
step_pytools() {
@@ -254,7 +264,9 @@ step_pytools() {
local V="$DATA_DIR/tools-venv"
command -v python3 >/dev/null 2>&1 || { note_fail pytools "python3 missing"; return 1; }
run mkdir -p "$DATA_DIR"
- [ -x "$V/bin/python" ] || run python3 -m venv "$V"
+ if [ ! -x "$V/bin/python" ]; then
+ run python3 -m venv "$V" || { rm -rf "$V"; note_fail pytools "could not create a venv (on Debian/Ubuntu: apt install python3-venv, then rerun with --mode custom --components pytools,verify)"; return 1; }
+ fi
run "$V/bin/python" -m pip install -q -U pip numpy pillow soundfile || { note_fail pytools "pip install failed"; return 1; }
[ "$DRY" = 1 ] || papercut_config_set PAPERCUT_PY "$V/bin/python"
ok "PAPERCUT_PY=$V/bin/python"
@@ -283,7 +295,7 @@ if [ $C_DEPS = 1 ]; then step_deps || C_VERIFY=0; fi
# ---------------------------------------------------------------- summary
echo
say "Done ($MODE)"
-[ -n "$FAILED" ] && bad "needs attention:$FAILED"
+if [ -n "$FAILED" ]; then bad "needs attention:$FAILED"; echo "After fixing, rerun the failed part with --mode custom --components <names>, or check everything with ./install.sh --doctor."; exit 1; fi
cat <<EOF
Next: open Claude Code and say
@@ -292,4 +304,3 @@ or run one stage on its own: "write a hook for ...", "storyboard this script", "
Check the setup any time: ./install.sh --doctor
EOF
-[ -z "$FAILED" ]
diff --git a/library/env.sh b/library/env.sh
index 9cdc491..db4f0ab 100644
--- a/library/env.sh
+++ b/library/env.sh
@@ -14,12 +14,15 @@ _pc_cfg="${PAPERCUT_CONFIG:-${XDG_CONFIG_HOME:-$HOME/.config}/papercut-explainer
if [ -f "$_pc_cfg" ]; then
while IFS='=' read -r _k _v || [ -n "$_k" ]; do
- case "$_k" in ''|'#'*) continue ;; esac
- [ -n "${!_k:-}" ] || export "$_k=$_v"
+ case "$_k" in ''|'#'*|*[!A-Za-z0-9_]*) continue ;; esac
+ eval "_cur=\"\${$_k:-}\"" # indirect lookup that works in bash 3.2 and zsh
+ [ -n "$_cur" ] || export "$_k=$_v"
done < "$_pc_cfg"
fi
-if [ -z "${PAPERCUT_LIB:-}" ]; then
+# a PAPERCUT_LIB from the config file that no longer exists (moved or deleted checkout) is ignored
+if [ -n "${PAPERCUT_LIB:-}" ] && [ ! -d "$PAPERCUT_LIB" ]; then unset PAPERCUT_LIB; fi
+if [ -z "${PAPERCUT_LIB:-}" ] && [ -n "${BASH_SOURCE[0]:-}" ]; then
PAPERCUT_LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
fi
export PAPERCUT_LIB
diff --git a/library/new_episode.sh b/library/new_episode.sh
index 1829c89..a39c89b 100755
--- a/library/new_episode.sh
+++ b/library/new_episode.sh
@@ -16,15 +16,18 @@ if [ $# -lt 3 ]; then echo "usage: $0 <series dir> <NN-slug> <CompositionId> [ou
L=$(dirname "$(rp "${BASH_SOURCE[0]}")")
CH=$(rp "$1"); SLUG=$2; COMP=$3; OUTN=${4:-${SLUG#*-}-papercut}
E=$CH/episodes/$SLUG; P=$E/papercut
-if [ -e "$P/package.json" ]; then echo "already scaffolded: $P" >&2; exit 1; fi
+# SYNCED.txt is written last (by sync_kit.sh), so a run that died halfway can be repeated
+if [ -e "$P/src/lib/SYNCED.txt" ]; then echo "already scaffolded: $P" >&2; exit 1; fi
mkdir -p "$E/research" "$E/narration/voice" "$P"
-cp -cRn "$L/papercut/template/." "$P/" 2>/dev/null || cp -Rn "$L/papercut/template/." "$P/"
+rsync -a --ignore-existing "$L/papercut/template/" "$P/" # never overwrites; rsync is a required dependency
DONOR=${DONOR:-}
if [ -z "$DONOR" ]; then
DONOR=$(ls -td "$CH"/episodes/*/papercut/node_modules 2>/dev/null | head -1 || true)
fi
-if [ -n "$DONOR" ] && [ -d "$DONOR" ]; then
+if [ -d "$P/node_modules" ]; then
+ : # left by an earlier run that stopped after the install
+elif [ -n "$DONOR" ] && [ -d "$DONOR" ]; then
cp -cR "$DONOR" "$P/node_modules" 2>/dev/null || { rm -rf "$P/node_modules"; cp -R "$DONOR" "$P/node_modules"; }
else
(cd "$P" && npm i --no-audit --no-fund)
@@ -40,7 +43,7 @@ python3 - "$P/episode.json" "$COMP" "$OUTN" <<'PY'
import json, sys
p, comp, out = sys.argv[1:]; e = json.load(open(p)); e["comp"], e["out"] = comp, out; json.dump(e, open(p, "w"), indent=1)
PY
-cp -n "$L/voice/build_timing.py" "$E/narration/"
+[ -e "$E/narration/build_timing.py" ] || cp "$L/voice/build_timing.py" "$E/narration/"
[ -e "$E/narration/script.json" ] || echo "[]" > "$E/narration/script.json"
echo "new episode: $E (comp $COMP -> out/$OUTN.mp4)"
echo "next: research/facts.md -> narration/script.json -> voice/narrate.sh -> voice/finalize.sh -> episode.json scenes+banners -> papercut/stubs.py -> tools/build_vo.py"
diff --git a/library/papercut/backdrops-src/render_backdrops.sh b/library/papercut/backdrops-src/render_backdrops.sh
index 43c1f5a..f80cd0f 100755
--- a/library/papercut/backdrops-src/render_backdrops.sh
+++ b/library/papercut/backdrops-src/render_backdrops.sh
@@ -1,4 +1,4 @@
-#!/bin/zsh
+#!/usr/bin/env bash
# Render code-drawn library backdrops to out/backdrops/<name>.jpg (1080x1920, q92). usage: ./render_backdrops.sh [name ...]
set -e
cd ${0:A:h}
diff --git a/library/tools/catalog.py b/library/tools/catalog.py
index 814af72..28bcbf1 100644
--- a/library/tools/catalog.py
+++ b/library/tools/catalog.py
@@ -72,6 +72,6 @@ if os.path.exists(bdj):
"Optional `tint` (multiply colour) and `dim` (0-1 darkening) shift a set's mood. No people or text are baked in.", "",
"| name | floorY | mood | desc | bestFor |", "|---|---|---|---|---|"]
for b in bd: out.append(f"| `{b['name']}` | {b['floorY']} | {b['mood']} | {b['desc']} | {b['bestFor']} |")
- out.append(""); count += len(bd)
+ out.append("")
open(f"{LIB}/papercut/CATALOG.md", "w", encoding="utf-8").write("\n".join(out) + "\n")
print("papercut:", count, "exports")
diff --git a/library/tools/qa.sh b/library/tools/qa.sh
index ebf950c..c0737a3 100755
--- a/library/tools/qa.sh
+++ b/library/tools/qa.sh
@@ -9,6 +9,7 @@ rp() { python3 -c 'import os,sys;print(os.path.realpath(sys.argv[1]))' "$1"; }
LIB=$(dirname "$(rp "${BASH_SOURCE[0]}")")
NAME=${1:?usage: qa.sh NAME [FROM-TO] [NTH=12] [SCALE=0.3] [COLS=9]}
+case "$NAME" in */*|.*) echo "qa.sh: NAME must be a plain folder name, got '$NAME'" >&2; exit 2 ;; esac
RANGE=${2:-}; NTH=${3:-12}; SCALE=${4:-0.3}; COLS=${5:-9}
if [ -f "$LIB/../env.sh" ]; then . "$LIB/../env.sh"; fi # fills PAPERCUT_PY from the config file, if any
PY=${PAPERCUT_PY:-python3}
diff --git a/library/tools/selftest.sh b/library/tools/selftest.sh
index 1550d28..333dd52 100755
--- a/library/tools/selftest.sh
+++ b/library/tools/selftest.sh
@@ -6,7 +6,7 @@
set -euo pipefail
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
. "$HERE/../env.sh"
-KEEP=1; W="${1:-}"; if [ -z "$W" ]; then W="$(mktemp -d)"; KEEP=0; fi
+KEEP=1; W="${1:-}"; if [ -z "$W" ]; then W="$(mktemp -d)"; KEEP=0; trap 'rm -rf "$W"' EXIT; fi # temp dir goes away on failure too
say() { printf ' selftest: %s\n' "$*"; }
EX="$PAPERCUT_LIB/../examples/hello-reel"
@@ -39,4 +39,4 @@ say "render one still"
( cd "$P" && npx remotion still Example out/selftest.png --frame=40 --log=error )
[ "$(wc -c < "$P/out/selftest.png")" -gt 50000 ] || { echo "selftest: still is empty or tiny" >&2; exit 1; }
-if [ "$KEEP" = 1 ]; then say "ok, still at $P/out/selftest.png"; else rm -rf "$W"; say "ok"; fi
+if [ "$KEEP" = 1 ]; then say "ok, still at $P/out/selftest.png"; else say "ok"; fi
diff --git a/skills/papercut-explainer/SKILL.md b/skills/papercut-explainer/SKILL.md
index 04e3e0e..831ed39 100644
--- a/skills/papercut-explainer/SKILL.md
+++ b/skills/papercut-explainer/SKILL.md
@@ -84,10 +84,10 @@ Reuse before writing: a kit component, a props set or a scene template beats new
Probe (read-only):
```
-grep '^PAPERCUT_' "${XDG_CONFIG_HOME:-$HOME/.config}/papercut-explainer/config.env"
+. "$(grep '^PAPERCUT_LIB=' "${XDG_CONFIG_HOME:-$HOME/.config}/papercut-explainer/config.env" | cut -d= -f2-)/env.sh" # fills PAPERCUT_PY, QWEN_TTS_PY
node -v; ffmpeg -version | head -1
-"${PAPERCUT_PY:-python3}" -c 'import numpy, PIL, soundfile'
-"${QWEN_TTS_PY:-python3}" -c 'import qwen_tts'
+"$PAPERCUT_PY" -c 'import numpy, PIL, soundfile'
+"$QWEN_TTS_PY" -c 'import qwen_tts'
```
The first three lines passing means Standard. The `qwen_tts` import passing as well means Full. If a stage needs more than the install provides, say so in one line, run `./install.sh --doctor` from the repo root, and hand over to `papercut-setup` instead of improvising. Find the root with `readlink` on the installed skill folder, or `PAPERCUT_HOME` in the config file.
diff --git a/skills/papercut-setup/SKILL.md b/skills/papercut-setup/SKILL.md
index ee959f3..39fe1e4 100644
--- a/skills/papercut-setup/SKILL.md
+++ b/skills/papercut-setup/SKILL.md
@@ -1,6 +1,6 @@
---
name: papercut-setup
-description: Install, check or upgrade the papercut toolchain. Runs the doctor, asks how much to set up (Minimal, Standard, Full), then runs install.sh with flags and fixes dependency errors. Use for "check my papercut install", "set up the voice", "why won't it render".
+description: Install, check or upgrade the papercut toolchain. Runs the doctor, asks how much to set up (Minimal, Standard, Full), then runs install.sh with flags and fixes dependency errors. Use for "set up papercut-explainer", "install papercut", "check my papercut install", "set up the voice", "why won't it render".
---
# Papercut setup
@@ -51,8 +51,8 @@ Confirm before any multi-GB download. On a machine with no GPU (not Apple Silico
- Add `--dry-run` first if the user wants to see the plan; it changes nothing.
- Standard and Full take minutes (npm install, Remotion's Chrome, venvs, model download). Run them in the background and check the output; do not hold a foreground call.
-- What each mode does: Minimal links the skills and the scene-builder agent. Standard adds a dependency check, the Remotion agent skills (`npx skills add remotion-dev/skills -g`), a Python venv with numpy, Pillow and soundfile, and a self-test render. Full adds `library/voice/setup_tts.sh`: a voice venv with Qwen3-TTS, an ASR backend (mlx-whisper on Apple Silicon, faster-whisper elsewhere), the model download and a one-line smoke test.
-- The installer writes `PAPERCUT_HOME`, `PAPERCUT_LIB`, `PAPERCUT_PY`, `QWEN_TTS_PY` and `ASR_PY` into `~/.config/papercut-explainer/config.env`. An existing skill folder is backed up as `<name>.bak-<timestamp>`.
+- What each mode does: Minimal links the skills and the scene-builder agent. Standard adds a dependency check, the Remotion agent skills (`npx skills add remotion-dev/skills -g -a claude-code`, installed user-wide, so say so when you confirm the plan), a Python venv with numpy, Pillow and soundfile, and a self-test render. Full adds `library/voice/setup_tts.sh`: a voice venv with Qwen3-TTS, an ASR backend (mlx-whisper on Apple Silicon, faster-whisper elsewhere), the model download and a one-line smoke test.
+- The installer writes `PAPERCUT_HOME`, `PAPERCUT_LIB`, `PAPERCUT_PY`, `QWEN_TTS_PY` and `ASR_PY` into `~/.config/papercut-explainer/config.env`. An existing skill folder that differs from this checkout is backed up to `~/.config/papercut-explainer/backups/` (not into the skills folder, so it is not loaded twice); an identical copy, such as one from `npx skills add`, is just replaced.
## 4. Verify and report