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.

24.3 KB
Raw Blame
#!/usr/bin/env bash
# papercut-explainer installer. Asks how much you want to set up, then does only that.
#
#   ./install.sh                         interactive (asks for a mode)
#   ./install.sh --mode standard --yes   no questions
#   ./install.sh --doctor                check what is installed
#   ./install.sh --uninstall             remove the skill links this script made
#
# Modes
#   minimal   the skills only. Strategy, hook, script, storyboard and style prompts work; nothing renders.
#   standard  minimal + everything needed to render silent reels: dependency check, Remotion skills,
#             Python tools (numpy + Pillow + soundfile), a self-test render.
#   full      standard + local voiceover: Qwen3-TTS venv (~1.5 GB), model download (2.3-4.2 GB), word-timing ASR.
#   custom    choose each component.
#
# Options
#   --mode M              minimal | standard | full | custom
#   --components a,b,c    with --mode custom: skills,deps,remotion-skills,pytools,tts,verify
#   --target T            which agent harnesses to install for: auto (default: every one found on this machine,
#                         else claude) | all | a comma list, e.g. claude,codex,gemini. Names: see harnesses.sh
#                         (claude opencode codex gemini cursor copilot amp goose cline roo kilo zed droid warp
#                         augment junie openhands crush kiro qwen windsurf, or "agents" for the shared ~/.agents/skills)
#   --skills-dir DIR      where skills go (overrides --target with a single dir);
#                         the subagent goes in the sibling folder DIR/../agents
#   --project DIR         install into DIR (that harness's project folders, e.g. DIR/.claude/skills,
#                         DIR/.agents/skills) instead of user-wide
#   --claude-model M      model for the papercut-scene subagent in Claude Code:
#                         sonnet (default) | opus | haiku | inherit (use the session model) | a full model id
#   --opencode-model M    model for it in opencode: inherit (default) | provider/model-id
#   --agent-model T=M     the same for any other harness with file subagents (codex, gemini), e.g. codex=deepseek-flash
#   --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)
#   --with-clone          also download the voice-cloning model
#   --yes, -y             accept defaults, never prompt
#   --dry-run             print what would happen, change nothing
set -euo pipefail

ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
LIB="$ROOT/library"
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=""; TARGET="auto"; TARGET_EXPLICIT=0; SKILLS_DIR=""; SKILLS_DIR_EXPLICIT=0; PROJECT_DIR=""
COPY=0; YES=0; DRY=0
AGENT_MODELS="claude=sonnet"; MODEL_FLAGS=""
TTS_MODEL=1.7B; WITH_CLONE=0; DOCTOR=0; UNINSTALL=0
while [ $# -gt 0 ]; do
  case "$1" in
    --mode) MODE=${2:?--mode needs a value}; shift 2 ;;
    --components) COMPONENTS=${2:?--components needs a value}; shift 2 ;;
    --target) TARGET=${2:?--target needs auto, all or a comma list of harness names}; TARGET_EXPLICIT=1; shift 2 ;;
    --skills-dir) SKILLS_DIR=${2:?--skills-dir needs a value}; SKILLS_DIR_EXPLICIT=1; shift 2 ;;
    --project) [ -d "${2:?--project needs a folder}" ] || { echo "--project: $2 is not a folder" >&2; exit 2; }
               PROJECT_DIR="$(cd "$2" && pwd)"; shift 2 ;;
    --claude-model) MODEL_FLAGS="$MODEL_FLAGS claude=${2:?--claude-model needs sonnet, opus, haiku, inherit or a model id}"; shift 2 ;;
    --opencode-model) MODEL_FLAGS="$MODEL_FLAGS opencode=${2:?--opencode-model needs inherit or provider/model-id}"; shift 2 ;;
    --agent-model) MODEL_FLAGS="$MODEL_FLAGS ${2:?--agent-model needs NAME=MODEL, e.g. codex=deepseek-flash}"; shift 2 ;;
    --copy) COPY=1; shift ;;
    --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,/^set -euo/p' "$0" | sed '$d'; exit 0 ;;
    *) echo "unknown option: $1 (see --help)" >&2; exit 2 ;;
  esac
done

. "$ROOT/harnesses.sh"
resolve_targets "$TARGET"

# Models for the scene agent. Defaults: Claude Code sonnet, everything else inherits the session model.
for kv in $MODEL_FLAGS; do
  case "$kv" in *=*) ;; *) echo "--agent-model needs NAME=MODEL (got: $kv)" >&2; exit 2 ;; esac
  h_known "${kv%%=*}" || { echo "--agent-model: unknown harness '${kv%%=*}'" >&2; exit 2; }
  valid_model "${kv%%=*}" "${kv#*=}" || { echo "bad model '${kv#*=}' for ${kv%%=*} (opencode needs provider/model-id; others a plain id or inherit)" >&2; exit 2; }
  AGENT_MODELS="$AGENT_MODELS $kv"
done

# Destinations: skills folders and subagent jobs, de-duplicated (many harnesses share ~/.agents/skills).
# --skills-dir overrides everything with one folder (legacy); --project uses each harness's project folders.
SKILLS_DIRS=(); AGENT_JOBS=()   # a job is "kind|dir|harness"
if [ "$SKILLS_DIR_EXPLICIT" = 1 ]; then
  SKILLS_DIRS=("$SKILLS_DIR")
  case "$SKILLS_DIR" in */.opencode/skills|*/opencode/skills) AGENT_JOBS=("opencode|$(dirname "$SKILLS_DIR")/agents|opencode") ;;
                        *) AGENT_JOBS=("claude|$(dirname "$SKILLS_DIR")/agents|claude") ;; esac
else
  for h in "${TARGET_LIST[@]}"; do
    if [ -n "$PROJECT_DIR" ]; then sd="$PROJECT_DIR/$(h_row "$h" | cut -d'|' -f3)"; ad="$(h_row "$h" | cut -d'|' -f6)"; [ -n "$ad" ] && [ "$ad" != "-" ] && ad="$PROJECT_DIR/$ad"
    else sd="$(h_field "$h" 2)"; ad="$(h_field "$h" 5)"; fi
    in_array "$sd" "${SKILLS_DIRS[@]+"${SKILLS_DIRS[@]}"}" || SKILLS_DIRS+=("$sd")
    kind="$(h_field "$h" 4)"
    if [ "$kind" != none ] && [ -n "$ad" ] && [ "$ad" != "-" ]; then
      job="$kind|$ad|$h"; in_array "$job" "${AGENT_JOBS[@]+"${AGENT_JOBS[@]}"}" || AGENT_JOBS+=("$job")
    fi
  done
fi

if [ -t 1 ]; then B=$'\033[1m'; G=$'\033[32m'; Y=$'\033[33m'; R=$'\033[31m'; N=$'\033[0m'; else B=""; G=""; Y=""; R=""; N=""; fi
say()  { printf '%s==>%s %s\n' "$B" "$N" "$*"; }
ok()   { printf '  %s[ok]%s %s\n' "$G" "$N" "$*"; }
miss() { printf '  %s[--]%s %s\n' "$Y" "$N" "$*"; }
bad()  { printf '  %s[!!]%s %s\n' "$R" "$N" "$*"; }
run()  { if [ "$DRY" = 1 ]; then printf '  (dry run) %s\n' "$*"; else "$@"; fi; }
interactive() { [ "$YES" = 0 ] && [ -t 0 ]; }
confirm() {  # confirm "question" default(y|n)
  interactive || { [ "$2" = y ]; return; }
  local hint="[Y/n]"; [ "$2" = n ] && hint="[y/N]"
  printf '%s %s ' "$1" "$hint"; read -r a
  case "$(printf '%s' "$a" | tr 'A-Z' 'a-z')" in y|yes) return 0 ;; n|no) return 1 ;; *) [ "$2" = y ] ;; esac
}

SKILL_NAMES() { for d in "$ROOT"/skills/*/; do [ -f "${d}SKILL.md" ] && basename "$d"; done; }
ver_ge() { [ "$(printf '%s\n%s\n' "$2" "$1" | sort -V | head -1)" = "$2" ]; }   # ver_ge have need

# The scene agent is written as a copy per harness, so the model is the user's choice and each format is right.
# Claude Code, opencode, Codex and Gemini name models and tools differently; the repo keeps one source per format
# family (agents/papercut-scene.md for Claude, agents/opencode/ for opencode) and derives the Codex and Gemini files.
AGENT_MARK='papercut-explainer install.sh (generated)'
agent_with_model() {  # agent_with_model SRC MODEL: markdown, model line after name: (none for "inherit")
  awk -v model="$2" -v mark="$AGENT_MARK" '
    NR == 1 && $0 == "---" { fm = 1; print; next }
    fm == 1 && /^model:/ { next }
    fm == 1 && /^name:/ { print; if (model != "inherit") print "model: " model; next }
    fm == 1 && $0 == "---" { fm = 2; print; print "<!-- " mark ": rerun the installer to change the model -->"; next }
    { print }
  ' "$1"
}
agent_for_gemini() {  # Gemini validates frontmatter strictly: name, description, model only (no Claude tools:/effort:)
  awk -v model="$2" -v mark="$AGENT_MARK" '
    NR == 1 && $0 == "---" { fm = 1; print; next }
    fm == 1 && /^(name|description):/ { print; next }
    fm == 1 && $0 == "---" { if (model != "inherit") print "model: " model; fm = 2; print; print "<!-- " mark ": rerun the installer to change the model -->"; next }
    fm == 1 { next }
    { print }
  ' "$1"
}
agent_for_codex() {  # Codex subagents are TOML: name, description, developer_instructions (+ model, model_reasoning_effort)
  python3 -B - "$1" "$2" "$AGENT_MARK" <<'PY'
import json, re, sys
src, model, mark = sys.argv[1:4]
fm, body = re.match(r'---\n(.*?)\n---\n(.*)', open(src).read(), re.S).groups()
field = lambda k: (re.search(r'^%s:\s*(.+)$' % k, fm, re.M) or [None, None])[1]
instr = body.strip()
assert "'''" not in instr
out = ["# " + mark + ": rerun the installer to change the model",
       "name = " + json.dumps(field("name")), "description = " + json.dumps(field("description"))]
if model != "inherit": out.append("model = " + json.dumps(model))
if field("effort"): out.append("model_reasoning_effort = " + json.dumps(field("effort").strip()))
out.append("developer_instructions = '''\n" + instr + "\n'''")
print("\n".join(out))
PY
}
agent_render() {  # agent_render KIND SRC MODEL
  case "$1" in
    gemini) agent_for_gemini "$2" "$3" ;;
    codex)  agent_for_codex "$2" "$3" ;;
    *)      agent_with_model "$2" "$3" ;;
  esac
}

# ---------------------------------------------------------------- doctor
doctor() {
  say "papercut-explainer: status (target: $TARGET = ${TARGET_LIST[*]})"
  local n=0 t=0 L_SKILLS=0 L_STD=1 L_FULL=0
  local best=0 dir_n nskills misses=() complete=()
  for dir in "${SKILLS_DIRS[@]}"; do
    dir_n=0
    for s in $(SKILL_NAMES); do
      if [ -e "$dir/$s/SKILL.md" ]; then dir_n=$((dir_n+1)); else misses+=("skill $s not in $dir"); fi
    done
    n=$((n+dir_n)); t=$((t+$(SKILL_NAMES | wc -w)))
    [ "$dir_n" -gt "$best" ] && best=$dir_n
    if [ "$dir_n" = "$(SKILL_NAMES | wc -w | tr -d " ")" ]; then complete+=("$dir"); fi
  done
  nskills=$(SKILL_NAMES | wc -w | tr -d " ")
  # No explicit --target: Claude-only and opencode-only installs are both fine, so one complete location passes.
  if [ "$TARGET_EXPLICIT" = 0 ] && [ "$SKILLS_DIR_EXPLICIT" = 0 ] && [ "${#complete[@]}" -gt 0 ]; then
    ok "skills: $nskills/$nskills in ${complete[*]}"; L_SKILLS=1
  elif [ "$n" = "$t" ] && [ "$t" -gt 0 ]; then ok "skills: $n/$t in ${SKILLS_DIRS[*]}"; L_SKILLS=1
  else for m in "${misses[@]}"; do miss "$m"; done; bad "skills: $n/$t installed"; fi
  [ -f "$PAPERCUT_CONFIG" ] && ok "config: $PAPERCUT_CONFIG (PAPERCUT_LIB=$PAPERCUT_LIB)" || miss "config file missing ($PAPERCUT_CONFIG)"
  if command -v node >/dev/null 2>&1; then v="$(node -v | sed 's/^v//')"; if ver_ge "$v" 20; then ok "node $v"; else bad "node $v (need 20+)"; L_STD=0; fi; else miss "node (need 20+)"; L_STD=0; fi
  command -v npm >/dev/null 2>&1 && ok "npm" || { miss "npm"; L_STD=0; }
  command -v ffmpeg >/dev/null 2>&1 && ok "ffmpeg" || { miss "ffmpeg"; L_STD=0; }
  command -v rsync >/dev/null 2>&1 && ok "rsync" || { miss "rsync"; L_STD=0; }
  command -v python3 >/dev/null 2>&1 && ok "python3 $(python3 -c 'import platform;print(platform.python_version())')" || { miss "python3"; L_STD=0; }
  local remo_found=0 d
  for d in "${SKILLS_DIRS[@]}" "$HOME/.claude/skills" "$HOME/.config/opencode/skills" "$HOME/.agents/skills" "$HOME/.gemini/skills" "$HOME/.cursor/skills"; do
    [ -f "$d/remotion-best-practices/SKILL.md" ] && remo_found=1
  done
  if [ $remo_found = 1 ]; then ok "remotion skills"; else miss "remotion skills (npx skills add remotion-dev/skills, see step_remotion)"; L_STD=0; fi
  if "$PAPERCUT_PY" -c 'import numpy, PIL, soundfile' >/dev/null 2>&1; then ok "python tools: numpy + Pillow + soundfile ($PAPERCUT_PY)"; else miss "python tools (numpy + Pillow + soundfile)"; L_STD=0; fi
  if papercut_find_chrome >/dev/null; then ok "Chrome or Chromium (sound effects and music render)"; else miss "Chrome/Chromium (only the SFX and music render needs it)"; fi
  if "$QWEN_TTS_PY" -c 'import qwen_tts' >/dev/null 2>&1; then
    ok "voice: qwen-tts importable ($QWEN_TTS_PY)"
    if ls -d "$HOME"/.cache/huggingface/hub/models--Qwen--Qwen3-TTS-12Hz-*-CustomVoice >/dev/null 2>&1; then ok "voice: CustomVoice model cached"; L_FULL=1; else miss "voice: no CustomVoice model in the Hugging Face cache"; fi
  else miss "voice: qwen-tts not installed (optional; ./install.sh --mode custom --components tts)"; fi
  for f in kit/paper/camera.tsx public/bg/backdrops/backdrops.json public/bg/textures/felt-fibre.mp4; do
    [ -e "$LIB/papercut/$f" ] && ok "library: $f" || { bad "library file missing: $f"; L_STD=0; }
  done
  local level="none (skills not installed)"
  if [ $L_SKILLS = 1 ]; then level="Minimal"; [ $L_STD = 1 ] && level="Standard" && [ $L_FULL = 1 ] && level="Full"; fi
  say "Install level: $level"
}

uninstall() {
  say "removing skill links made by this installer"
  local rec="$CFG_DIR/installed.txt"; [ -f "$rec" ] || { echo "nothing recorded in $rec"; return; }
  while IFS= read -r p; do
    [ -n "$p" ] || continue
    if [ -L "$p" ]; then
      case "$(readlink "$p")" in "$ROOT"/*) run rm "$p"; ok "removed $p" ;; *) miss "kept $p (link points elsewhere)" ;; esac
    elif [ -d "$p" ] && [ -f "$p/.papercut-installed" ]; then run rm -rf "$p"; ok "removed $p"
    elif [ -f "$p" ] && { grep -q "$AGENT_MARK" "$p" 2>/dev/null || cmp -s "$p" "$ROOT/agents/$(basename "$p")" 2>/dev/null; }; then run rm "$p"; ok "removed $p"
    elif [ -e "$p" ]; then miss "kept $p (not an unmodified copy from this installer)"; fi
  done < "$rec"
  run rm -f "$rec"
  echo "Left in place: $CFG_DIR/config.env, venvs under $DATA_DIR, Hugging Face model cache. Delete them by hand if you want the space back."
}

[ "$DOCTOR" = 1 ] && { doctor; exit 0; }
[ "$UNINSTALL" = 1 ] && { uninstall; exit 0; }

# ---------------------------------------------------------------- mode
if [ -z "$MODE" ]; then
  if interactive; then
    cat <<EOF
${B}papercut-explainer setup${N}

How much do you want to set up?

  1) Minimal   The skills only (hook, script, storyboard, strategy, style prompts).
               Nothing renders. Takes seconds.
  2) Standard  Minimal + render silent reels: dependency check, Remotion skills,
               Python tools, a self-test render.             ~0.7 GB, a few minutes.
  3) Full      Standard + local voiceover: Qwen3-TTS + word-timing ASR.
                                                              +4-6 GB (1.5 GB venv + model).
  4) Custom    Pick each component.

EOF
    printf 'Choose 1-4 [2]: '; read -r c
    case "${c:-2}" in 1) MODE=minimal ;; 2) MODE=standard ;; 3) MODE=full ;; 4) MODE=custom ;; *) echo "pick 1-4" >&2; exit 2 ;; esac
  else
    echo "no terminal to ask on: pass --mode minimal|standard|full|custom (and --yes)" >&2; exit 2
  fi
fi

C_SKILLS=0; C_DEPS=0; C_REMO=0; C_PY=0; C_TTS=0; C_VERIFY=0
case "$MODE" in
  minimal)  C_SKILLS=1 ;;
  standard) C_SKILLS=1; C_DEPS=1; C_REMO=1; C_PY=1; C_VERIFY=1 ;;
  full)     C_SKILLS=1; C_DEPS=1; C_REMO=1; C_PY=1; C_TTS=1; C_VERIFY=1 ;;
  custom)
    if [ -n "$COMPONENTS" ]; then
      for c in $(printf '%s' "$COMPONENTS" | tr ',' ' '); do
        case "$c" in skills) C_SKILLS=1 ;; deps) C_DEPS=1 ;; remotion-skills) C_REMO=1 ;; pytools) C_PY=1 ;; tts) C_TTS=1 ;; verify) C_VERIFY=1 ;;
          *) echo "unknown component: $c" >&2; exit 2 ;; esac
      done
    else
      interactive || { echo "--mode custom needs --components or a terminal" >&2; exit 2; }
      confirm "Install the skills (links into ${SKILLS_DIRS[*]})?" y && C_SKILLS=1
      confirm "Check dependencies (node 20+, npm, ffmpeg, python3)?" y && C_DEPS=1
      confirm "Install the Remotion agent skills (npx skills add remotion-dev/skills)?" y && C_REMO=1
      confirm "Set up Python tools (venv with numpy + Pillow, for QA contact sheets)?" y && C_PY=1
      if confirm "Set up local voiceover (Qwen3-TTS + ASR; 4-6 GB of disk)?" n; then
        C_TTS=1
        printf 'Model size: 1) 1.7B better, 4.2 GB   2) 0.6B lighter, 2.3 GB  [1]: '; read -r m
        [ "$m" = 2 ] && TTS_MODEL=0.6B
        confirm "Also download the voice-cloning model (same size again)?" n && WITH_CLONE=1
      fi
      confirm "Run a self-test render at the end?" y && C_VERIFY=1
    fi ;;
  *) echo "unknown mode: $MODE" >&2; exit 2 ;;
esac

if [ "$MODE" != custom ] && interactive; then
  say "Plan ($MODE)"
  [ $C_SKILLS = 1 ] && echo "  - link the skills into ${SKILLS_DIRS[*]} (${TARGET_LIST[*]})"
  [ $C_DEPS = 1 ]   && echo "  - check node, npm, ffmpeg, python3"
  [ $C_REMO = 1 ]   && echo "  - install the Remotion agent skills (global)"
  [ $C_PY = 1 ]     && echo "  - create a Python venv with numpy + Pillow"
  [ $C_TTS = 1 ]    && echo "  - build a voice venv and download Qwen3-TTS $TTS_MODEL (~$([ "$TTS_MODEL" = 1.7B ] && echo 4.2 || echo 2.3) GB)"
  [ $C_VERIFY = 1 ] && echo "  - scaffold a throwaway project and render one still (npm install runs once)"
  confirm "Go?" y || { echo "cancelled"; exit 0; }
fi
[ "$MODE" = full ] && interactive && ! confirm "Full mode asks for a multi-GB model download. Keep model size $TTS_MODEL?" y && { echo "rerun with --tts-model 0.6B or --mode standard"; exit 0; }

# ---------------------------------------------------------------- steps
FAILED=""; SKIPPED=""; DONE=""
note_fail() { FAILED="$FAILED $1"; bad "$1 failed: $2"; }

step_config() {
  say "config"
  run mkdir -p "$CFG_DIR"
  if [ "$DRY" = 0 ]; then
    papercut_config_set PAPERCUT_HOME "$ROOT"
    papercut_config_set PAPERCUT_LIB "$LIB"
  fi
  ok "$PAPERCUT_CONFIG"
}

# The scene-builder subagent, one file per (format, folder) job from the harness table.
install_agents() {
  local job kind adir harness model asrc a ext adst agen ts; ts="$(date +%Y%m%d-%H%M%S)"
  for job in "${AGENT_JOBS[@]+"${AGENT_JOBS[@]}"}"; do
    kind="${job%%|*}"; adir="${job#*|}"; harness="${adir##*|}"; adir="${adir%|*}"
    model="$(agent_model "$harness")"; asrc="$ROOT/agents"; [ "$kind" = opencode ] && asrc="$ROOT/agents/opencode"
    ext=md; [ "$kind" = codex ] && ext=toml
    run mkdir -p "$adir"
    for a in "$asrc"/*.md; do
      [ -f "$a" ] || continue
      adst="$adir/$(basename "$a" .md).$ext"
      if [ "$kind" = codex ] && ! command -v python3 >/dev/null 2>&1; then miss "skipped the Codex agent file: python3 not found"; continue; fi
      agen="$(mktemp)"; agent_render "$kind" "$a" "$model" > "$agen"
      if [ -L "$adst" ]; then run rm "$adst"
      elif [ -e "$adst" ]; then
        if cmp -s "$agen" "$adst" || cmp -s "$a" "$adst"; then run rm "$adst"   # identical copy: refresh it
        elif grep -q "$AGENT_MARK" "$adst" 2>/dev/null; then run rm "$adst"   # an earlier run, maybe with another model
        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 "$adst" ".$ext").$ts.$ext"; miss "backed up to $CFG_DIR/backups"
        else miss "kept existing agent $(basename "$adst")"; rm -f "$agen"; continue; fi
      fi
      run cp "$agen" "$adst"; rm -f "$agen"
      [ "$DRY" = 1 ] || echo "$adst" >> "$CFG_DIR/installed.txt"
      ok "agent $(basename "$a" .md) ($kind, model: $model) -> $adir"
    done
  done
}

step_skills() {
  local onedir
  for onedir in "${SKILLS_DIRS[@]}"; do
    say "skills -> $onedir"
    run mkdir -p "$onedir" "$CFG_DIR"
    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="$onedir/$s"
      if [ -L "$dst" ]; then
        run rm "$dst"
      elif [ -e "$dst" ]; then
        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 agents do 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
      [ "$DRY" = 1 ] || echo "$dst" >> "$CFG_DIR/installed.txt"
      ok "$s ($onedir)"
    done
  done
  install_agents
  [ "$DRY" = 1 ] || [ ! -f "$CFG_DIR/installed.txt" ] || sort -u "$CFG_DIR/installed.txt" -o "$CFG_DIR/installed.txt"
}

step_deps() {
  say "dependencies"
  local miss_any=0
  if command -v node >/dev/null 2>&1; then v="$(node -v | sed 's/^v//')"; if ver_ge "$v" 20; then ok "node $v"; else bad "node $v, need 20+"; miss_any=1; fi
  else bad "node not found. Install Node 20+: https://nodejs.org or 'brew install node'"; miss_any=1; fi
  command -v npm >/dev/null 2>&1 && ok "npm" || { bad "npm not found (ships with node)"; miss_any=1; }
  command -v ffmpeg >/dev/null 2>&1 && ok "ffmpeg" || { bad "ffmpeg not found: 'brew install ffmpeg' or 'apt install ffmpeg'"; miss_any=1; }
  command -v rsync >/dev/null 2>&1 && ok "rsync" || { bad "rsync not found (the kit sync uses it): 'brew install rsync' or 'apt install rsync'"; miss_any=1; }
  if papercut_find_chrome >/dev/null; then
    ok "Chrome or Chromium (sound effects and music render)"
  else miss "Chrome/Chromium not found: only the SFX and music render needs it (set CHROME_PATH or install Chrome); video renders do not"; fi
  command -v python3 >/dev/null 2>&1 && ok "python3" || { bad "python3 not found"; miss_any=1; }
  if [ $miss_any = 1 ]; then note_fail deps "install the items above, then rerun with --mode custom --components deps,verify"; return 1; fi
}

step_remotion() {
  say "Remotion agent skills (${TARGET_LIST[*]})"
  command -v npx >/dev/null 2>&1 || { note_fail remotion-skills "npx not found"; return 1; }
  # `npx skills` installs into each harness's own folder. Skip a harness that already has the skill where it reads skills.
  local h id udir done_ids=()
  for h in "${TARGET_LIST[@]}"; do
    id="$(h_field "$h" 7)"; udir="$(h_field "$h" 2)"
    [ -f "$udir/remotion-best-practices/SKILL.md" ] && continue
    [ -f "$HOME/.claude/skills/remotion-best-practices/SKILL.md" ] && [ "$h" = claude ] && continue
    in_array "$id" "${done_ids[@]+"${done_ids[@]}"}" && continue
    done_ids+=("$id")
    run npx -y skills@latest add remotion-dev/skills -g -y -a "$id" || note_fail remotion-skills "npx skills add failed for $id; run it by hand"
  done
  [ "${#done_ids[@]}" -gt 0 ] || ok "already installed"
}

step_pytools() {
  say "Python tools (numpy + Pillow + soundfile)"
  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"
  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"
}

step_tts() {
  say "local voiceover"
  local args="--model $TTS_MODEL --yes"; [ "$WITH_CLONE" = 1 ] && args="$args --with-clone"
  # shellcheck disable=SC2086
  run bash "$LIB/voice/setup_tts.sh" $args || note_fail tts "see the output above; rerun: library/voice/setup_tts.sh"
}

step_verify() {
  say "self-test render"
  run bash "$LIB/tools/selftest.sh" || note_fail verify "self-test failed; run library/tools/selftest.sh to see why"
}

step_config
[ $C_SKILLS = 1 ] && step_skills
if [ $C_DEPS = 1 ]; then step_deps || C_VERIFY=0; fi
[ $C_REMO = 1 ] && step_remotion
[ $C_PY = 1 ] && step_pytools
[ $C_TTS = 1 ] && step_tts
[ $C_VERIFY = 1 ] && step_verify

# ---------------------------------------------------------------- summary
echo
say "Done ($MODE)"
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 your coding agent (Claude Code, opencode, Codex, Gemini CLI, Cursor ...) and say
  "make a papercut explainer about <link>"
or run one stage on its own: "write a hook for ...", "storyboard this script", "set up the voice".

Check the setup any time: ./install.sh --doctor [--target auto|all|claude,codex,...]
EOF