Papercut Setup

Before you start: read this whole install prompt, tell me in a few lines what this skill does and what installing it involves, and wait for my go-ahead before you do anything else. Prerequisites: none for this installation itself — it is a copy of one file, with no account, no API key and no paid service, and this installation never runs the toolchain installer the skill drives. Read this before using the skill afterwards, because using it IS running that installer: the skill is a guided wrapper around the repository's install.sh (bash, macOS or Linux only — Windows only via WSL), and it installs real software and downloads gigabytes, all disclosed in point 2. For the modes beyond the read-only check you need, already installed by you: Node 20+, npm, ffmpeg, rsync and Python 3 (the installer never installs system packages; it only prints the brew or apt line). Standard needs about 0.7 GB and a few minutes; Full adds about 4–6 GB (a ~1.5 GB voice venv plus a 2.3 or 4.2 GB model from Hugging Face) and needs Python 3.10–3.12 or uv for the voice venv. Rendering uses Remotion, which is source-available, free for individuals and small teams, but larger companies need a paid Remotion licence — check https://www.remotion.dev/license before commercial use. No key is needed for the default models; a key for another provider (for example DeepSeek) is only involved if you yourself ask for a non-Claude scene-agent model, and you enter that key in your agent yourself — never as part of this installation (also disclosed in point 2). Install "papercut-setup" for me. It installs, checks or upgrades the papercut-explainer toolchain: it locates the repository checkout (or asks where to clone it), runs the read-only doctor (./install.sh --doctor), asks in one go how much to set up (Minimal: the nine skills and the scene-builder subagent only; Standard: plus a dependency check, the Remotion agent skills installed user-wide via npx, a Python venv with numpy, Pillow and soundfile, and a self-test render; Full: plus a local Qwen3-TTS voice venv, a word-timing ASR backend, the model download and a one-line smoke test; or Custom components), which coding agents to target, whether skills go user-wide or into one project, symlink or copy, which model each scene-builder subagent gets (Claude Code defaults to Sonnet; Opus bills at Opus rates), and — for Full — the TTS model size (1.7B by default, 0.6B lighter) and whether to also fetch the voice-clone Base model; then it runs install.sh non-interactively with --yes and the answers as flags, fixes dependency errors from the troubleshooting table, re-runs the doctor and reports. Repository: https://github.com/0xS4N4TG/papercut-explainer (the skill is the whole skills/papercut-setup/ folder at the pinned commit: SKILL.md only, 1 file — but that file is not self-contained, see point 2) Pinned version: install the code at commit ff8223abc8136cc09e8d7e9b62ecb5d080c389e1 exactly. Do not substitute a newer version. If this commit is unreachable, stop and tell me. 1. Clone https://github.com/0xS4N4TG/papercut-explainer into a temporary folder, check out commit ff8223abc8136cc09e8d7e9b62ecb5d080c389e1, and copy the skills/papercut-setup/ folder from that checkout. Then compare every file in the folder with the fingerprints recorded for this listing on 2026-10-19: [FINGERPRINTS] - SKILL.md: SHA-256 ac9afa0c4bfcb11110ce523ce7491316aaffa2d6710447acb5af2204aec569c5 If a file does not match, it changed since the listing was prepared: do not install it yet, tell me what you found and let me decide. 2. Read SKILL.md in full, and also read the installer chain it drives, in the same checkout: install.sh and harnesses.sh at the repository root, library/env.sh, library/voice/setup_tts.sh, library/tools/selftest.sh and library/new_episode.sh. Tell me in plain words: what the skill does when used, which services it connects to, whether it reads or sends any personal information or keys, and anything that seems unusual. Stop on any red flag and tell me before going further. Confirm these points from the files: - The skill folder holds 1 file only: SKILL.md (9,800 bytes). It is NOT self-contained: it is a wrapper with no code of its own, and everything it does runs files that live elsewhere in the same repository checkout — install.sh (24,880 bytes) and harnesses.sh (5,310 bytes) at the root, library/env.sh (2,397 bytes), library/voice/setup_tts.sh (5,561 bytes), library/tools/selftest.sh (2,214 bytes), the rest of library/ (about 15 MB: the Remotion kit, backdrops, fonts, template and tools), agents/papercut-scene.md and agents/opencode/papercut-scene.md, and the other eight skills in skills/. Installing this one folder gives you the guide only; the toolchain itself only exists once a full checkout of the repository at the pinned commit is on this machine and its installer has run (see the use-time steps below). This installation does not fetch or install any of those other files. - Nothing is sent anywhere during this installation itself; the only download at install time is the skill folder from GitHub at the pinned commit. No script is run during installation — in particular install.sh is NOT run, not even with --doctor or --dry-run — no key is asked for, and there is no telemetry in the skill folder. - What happens at use time, disclosed here before it ever happens — using the skill is a separate step that only starts when I ask you to set up, check or upgrade papercut, and every download and write below happens only then, under the mode and answers I give at that time: (a) Locating the repository: the skill resolves the checkout root from the installed skill folder's readlink (<root>/skills/papercut-setup), from the harness skills folders in harnesses.sh (typically ~/.claude/skills, ~/.agents/skills, ~/.config/opencode/skills, or the same under a project), or from PAPERCUT_HOME in ${XDG_CONFIG_HOME:-~/.config}/papercut-explainer/config.env, which it reads locally. If no checkout exists (for example the skills came from npx skills add, skills only), it asks where to clone (default ~/papercut-explainer) and runs git clone https://github.com/0xS4N4TG/papercut-explainer <dir> — the whole repository, library included, downloads from GitHub. (b) The doctor, ./install.sh --doctor, is read-only and local: it checks the nine skills, the config file, node 20+ / npm / ffmpeg / rsync / python3 versions, the Remotion skills, python imports (numpy, PIL, soundfile; qwen_tts), the CustomVoice model folder in the Hugging Face cache, Chrome/Chromium presence and three library files — no network call. (c) The questions, asked in one call before anything is installed: mode (Minimal / Standard / Full / Custom), targets (--target auto detects the coding agents present on this machine from the 23-row table in harnesses.sh — claude, opencode, codex, gemini, cursor, copilot, amp, goose, cline, roo, kilo, zed, droid, warp, augment, junie, openhands, crush, kiro, qwen, windsurf, agents — or all, or a list I name), user-wide or one project (--project DIR), symlink (default; updates with git pull) or --copy, the scene-agent model per agent with file subagents (Claude Code: Sonnet by default — the cheapest, what the scene agents were tuned on — Opus, Haiku or Inherit; OpenCode: Inherit by default or a provider/model-id such as anthropic/claude-sonnet-5-5; Codex and Gemini: Inherit or a plain model id), and for Full the TTS size (1.7B, ~4.2 GB, default; 0.6B, ~2.3 GB) and the optional voice-clone Base model (the same size again). Any multi-GB download is confirmed before it starts; on a machine with no GPU (not Apple Silicon, no NVIDIA) the skill warns that TTS takes minutes per line and suggests recording the voiceover or the placeholder voice instead. Another provider's model (DeepSeek and others) is only raised if I ask: I connect the provider inside my agent first — OpenCode /connect and paste my own key, a [model_providers.deepseek] block in ~/.codex/config.toml for Codex (the README advises an environment variable for the key over a literal token), or ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_DEFAULT_*_MODEL for Claude Code, following https://api-docs.deepseek.com/quick_start/agent_integrations — and only then is its model id passed to the installer; the skill never reads, asks for or sends that key itself, the README says this path is untested end to end, and weaker models cost more QA rounds. (d) What install.sh then writes, in every mode that includes the skills: it creates ~/.config/papercut-explainer/ and writes config.env (PAPERCUT_HOME and PAPERCUT_LIB, later also PAPERCUT_PY, QWEN_TTS_PY, ASR_PY and QWEN_TTS_MODEL), records every installed path in installed.txt there, symlinks (or, with --copy, copies) ALL NINE skills of the checkout into each selected harness's skills folder (for example ~/.claude/skills, ~/.config/opencode/skills, the shared ~/.agents/skills, ~/.kiro/skills, ~/.qwen/skills, ~/.codeium/windsurf/skills, or the project equivalents), and writes the papercut-scene subagent as a per-harness copy (Claude and OpenCode markdown, Codex TOML generated with python3, Gemini markdown) with my chosen model line into that harness's agents folder (for example ~/.claude/agents, ~/.config/opencode/agents, ~/.codex/agents, ~/.gemini/agents). An existing skill or agent file identical to the checkout is replaced; one that differs is moved to ~/.config/papercut-explainer/backups/ (outside the skills folder, so it is not loaded twice) and replaced — under the skill's non-interactive --yes runs this backup-and-replace is the default answer, so say so when you confirm the plan with me. The installer never installs system packages and does not touch my shell profile; for a missing node, ffmpeg, rsync or python3 it only prints the fix (Install Node 20+ from https://nodejs.org or brew install node; brew install ffmpeg or apt install ffmpeg; brew install [email protected] or install uv from https://docs.astral.sh/uv/ for the voice venv), which I run myself. (e) Standard adds, downloading as it goes: the dependency check above; the Remotion agent skills, once per selected harness, with npx -y skills@latest add remotion-dev/skills -g -y -a <harness id> — the skills CLI and the remotion-dev/skills package download from the npm registry / GitHub and install USER-WIDE (-g) into each harness's own folder, so say so when you confirm the plan; a Python tools venv created with python3 -m venv at ~/.local/share/papercut-explainer/tools-venv, then pip install -U pip numpy pillow soundfile from PyPI into it; and the verify step, library/tools/selftest.sh, which scaffolds a throwaway episode in a temp folder through library/new_episode.sh (npm i --no-audit --no-fund in the scaffolded project when no donor node_modules exists — the episode template's dependencies, remotion 4.0.530, react 19.2.3 and the rest of library/papercut/template/package.json, download from the npm registry; that first project's node_modules is most of Standard's ~0.7 GB), runs npx tsc --noEmit, generates placeholder (silent) narration locally, renders the sound effects and music bed with my own Chrome/Chromium if one is found (CHROME_PATH can point to it), and renders one still with npx remotion still — the first Remotion render downloads Remotion's headless Chrome once (about 200 MB, per the README). (f) Full adds library/voice/setup_tts.sh: a voice venv at ~/.local/share/papercut-explainer/voice-venv (uv venv --python 3.12 if uv is present, otherwise a python3.10–3.12 venv), pip/uv installs from PyPI of qwen-tts, the ASR backend (mlx-whisper on Apple Silicon, faster-whisper elsewhere), librosa, soundfile, numpy and huggingface_hub (torch is large; the venv is ~1.5 GB), then a Hugging Face snapshot_download (with HF_HUB_DISABLE_XET=1, retried 3 times, finished files kept) of Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice (~4.2 GB) or Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice (~2.3 GB) into ~/.cache/huggingface, plus the same-size Base model (Qwen/Qwen3-TTS-12Hz-<size>-Base) if I chose --with-clone; it writes QWEN_TTS_PY, ASR_PY and QWEN_TTS_MODEL into config.env, and runs a one-line smoke test that generates the fixed line "Paper cut explainers, now with a real voice." locally through library/voice/narrate.py and checks the audio is not silent — generation is local, nothing about my projects or voice leaves the machine in any of these steps; the only network traffic at use time is the git clone, the npm/PyPI package downloads, the Remotion skills and headless-Chrome downloads and the Hugging Face model download listed here, plus whatever my own agent sends under its own account when it runs (including to another provider I connected myself). There is no curl, wget, telemetry or analytics call in SKILL.md, install.sh, setup_tts.sh or selftest.sh. (g) Uninstall, if I ever ask: ./install.sh --uninstall removes only the links and copies it recorded in installed.txt; it leaves config.env, the venvs under ~/.local/share/papercut-explainer and the Hugging Face cache in place for me to delete by hand. - Do not run install.sh in any form during this installation, do not run the doctor, do not clone the repository for keeps (the temporary checkout in point 1 is only for copying the one folder), do not run npx, npm or pip, do not download any model or browser, and do not write config.env or link any skill: running the setup is my decision, later, when I actually ask for it. 3. When I say "yes, install", install it as a skill: copy the whole papercut-setup folder into the agent's skills directory, in a folder named "papercut-setup", keeping its 1 file (SKILL.md at its root). A manual clone followed by copying the skills/papercut-setup folder into ~/.claude/skills/ is the route described here; any other route is fine only as long as every installed file matches its fingerprint. 4. Verify with no network calls: frontmatter valid (name: papercut-setup), the 1 file in place with matching fingerprint. Do not run install.sh, the doctor or any installer command to verify. 5. Report what was installed, where, and what I still need to do myself (for example: this listing installed the guide only — the papercut toolchain itself is not installed; when I later ask to set it up, have a full checkout location ready or let the skill ask where to clone the repository (default ~/papercut-explainer), preinstall Node 20+, npm, ffmpeg, rsync and Python 3 myself (Python 3.10–3.12 or uv if I want the Full voice mode), allow the disk space (Standard about 0.7 GB; Full about 4–6 GB more) and the downloads disclosed in point 2 (npm registry, PyPI, GitHub, Hugging Face, Remotion's headless Chrome), choose the mode, targets, symlink-or-copy and scene-agent models myself at that time — knowing the Remotion skills install user-wide, that differing pre-existing skill folders are backed up to ~/.config/papercut-explainer/backups/ and replaced, and that any other provider's key is one I enter in my agent myself; check the Remotion licence before commercial use; using the skill is a separate step that only starts when I ask for it, and the use-time downloads and writes disclosed above happen only then, in the mode I pick). GitHub is optional: if I have a GitHub account or the gh CLI, you may use it; otherwise public access is fine. Never require it unless it's in the prerequisites above. Rules: don't touch anything outside the temp folder and the install target. If anything looks off, stop and ask me.