Papercut Setup

Papercut setup

A guided wrapper around install.sh. It checks what is installed, asks how much the user wants, runs the installer non-interactively and reports. Use it whenever another papercut skill finds something missing.

Preflight

• Find the repo root (where install.sh lives): readlink on the installed skill folder ends in <root>/skills/papercut-setup. Look in each harness's skills folder in turn (the table is harnesses.sh; typically ~/.claude/skills, ~/.agents/skills, ~/.config/opencode/skills, or the same under <project>/). Failing that, PAPERCUT_HOME= in ${XDG_CONFIG_HOME:-~/.config}/papercut-explainer/config.env. If neither exists, the skills probably came from npx skills add (skills only, no library). Ask where to clone the repo (default ~/papercut-explainer), run git clone https://github.com/0xS4N4TG/papercut-explainer <dir>, and use that as the root. The installer then replaces the copied skill folders with links into the checkout (it backs up real folders first). Never guess a path.
• Run every install.sh command from that root. It needs bash, and macOS or Linux (Windows: use WSL).
• The installer's own prompts need a terminal, which the agent's shell tool lacks. Always pass --yes and the answers as flags. Tell the user they can run ./install.sh themselves for the interactive menu.

1. Doctor

Copy code
./install.sh --doctor

Add --project DIR, --skills-dir DIR or --target <names> if the skills went somewhere other than the detected defaults; the doctor only looks where you point it, and with no --target one complete install location is enough. It prints [ok], [--] (missing) or [!!] (wrong). Summarise it in plain words:

• skills installed, config file and PAPERCUT_LIB
• node 20+, npm, ffmpeg, python3
• Remotion agent skills, Python tools (numpy + Pillow)
• voice: qwen_tts importable, a CustomVoice model in the Hugging Face cache
• library files present

Then say which install mode that adds up to (see papercut-explainer, Install modes).

2. Ask

Ask only what is still open, in one call (your agent's question tool, for example AskUserQuestion in Claude Code). Run ./install.sh --dry-run --mode minimal --yes first if you need to know which harnesses it detected (--target auto, the default):

Confirm before any multi-GB download. On a machine with no GPU (not Apple Silicon, no NVIDIA), TTS generation takes minutes per line; suggest recording the voiceover or the placeholder voice instead.

3. Install

Copy code
./install.sh --mode <minimal|standard|full> --yes [--target auto|all|claude,codex,...] [--claude-model M] [--opencode-model M] [--agent-model NAME=M] [--skills-dir DIR | --project DIR] [--copy] [--tts-model 1.7B|0.6B] [--with-clone]
./install.sh --mode custom --components skills,deps,remotion-skills,pytools,tts,verify --yes

• Add --dry-run first if the user wants to see the plan; it changes nothing.
• The scene-builder agent is written as a copy per harness, in that harness's own format (Claude and OpenCode markdown, Codex TOML, Gemini markdown), with the chosen model line or none for Inherit. Harnesses without file subagents get none; papercut-build then builds scenes itself or uses the harness's own parallel tasks. Skills stay symlinks. To change a model later: ./install.sh --mode custom --components skills --target codex --agent-model codex=<id> --yes (or --claude-model, --opencode-model).
• 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 (into each selected harness's skills and agents folders). Standard adds a dependency check, the Remotion agent skills (npx skills add remotion-dev/skills -g -y -a <harness id> once per selected harness, 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

Run ./install.sh --doctor again with the same --project, --skills-dir or --target. Report what is installed, which scene-agent model each agent got, what failed (the installer prints needs attention: with component names), and the fix. A new Claude Code, Codex or Gemini CLI session picks up newly linked skills (restart it); opencode reloads configuration automatically. Then suggest: "make a papercut explainer about ", or one stage at a time ("write a hook for...", "storyboard this script", "set up the voice").

Troubleshooting

Hand-off

Return to the skill that sent you here, or to papercut-explainer for the stage table. Files hold the state: config.env carries the library path, so the other skills resolve it without asking again.