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.
TypeScript agent-skillsagents-mdclaude-codeclaude-code-skillscodexexplainer-videosgemini-cliopencodepapercutremotiontext-to-speechvideo-generation
Install for any coding agent: harness table, Codex and Gemini agent files, AGENTS.md
sanatff8223abc813
diff --git a/.agents/skills b/.agents/skillsnew file mode 120000index 0000000..42c5394--- /dev/null+++ b/.agents/skills@@ -0,0 +1 @@+../skills\ No newline at end of filediff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 0000000..f760753--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,23 @@+# papercut-explainer: notes for coding agents++This repo makes short vertical explainer reels that look like layered construction paper. It is nine Agent Skills plus a+Remotion library. If your harness loads skills from `.agents/skills` or `skills/` (most do), they are already available here.+If it does not, read the matching `skills/<name>/SKILL.md` yourself when a request fits its description.++| Skill | Use it when the user wants to |+|---|---|+| `papercut-explainer` | make a reel end to end, or does not say which stage; it routes to the rest |+| `papercut-strategy` | decide what the reel should be: topic, format, audience, funnel, competitor study |+| `papercut-hook` | write or fix the hook (five scored variants, frame-0 cover) |+| `papercut-script` | turn a link into a researched script (75-95 words on a fixed spine) |+| `papercut-storyboard` | storyboard a script: camera and cut table, scene by scene, before any code |+| `papercut-voice` | voice the reel and time it to the picture |+| `papercut-build` | build and render the episode from a storyboard with the library |+| `papercut-qa` | check stills and the cut against the style and the storyboard |+| `papercut-setup` | install or repair this repo's setup (`./install.sh --doctor` first) |++- Library path: `$PAPERCUT_LIB`, else `PAPERCUT_LIB=` in `~/.config/papercut-explainer/config.env`, else `./library` here.+- Each skill reads the files the stage before it wrote, so you can stop after any stage.+- Scene-building agent: `papercut-scene` (installed per harness by `install.sh`). With no subagent support, build the scenes yourself, one at a time.+- Aider and other agents without skills support: `aider --read AGENTS.md`, then read the `SKILL.md` that fits.+- Harness folders and models: `harnesses.sh` and the README's *Works with* section.diff --git a/README.md b/README.mdindex 83223b7..50a5796 100644--- a/README.md+++ b/README.md@@ -1,6 +1,6 @@# papercut-explainer-Make short vertical explainer reels that look like layered construction paper, with Claude Code or opencode doing the work.+Make short vertical explainer reels that look like layered construction paper, with the coding agent you already use doing the work: Claude Code, OpenCode, Codex, Gemini CLI, Cursor, Copilot and any other tool that reads Agent Skills.@@ -8,7 +8,7 @@ Make short vertical explainer reels that look like layered construction paper, wThis repo is two things that work together:-- **Nine agent skills** (Claude Code and opencode) that run the whole pipeline: strategy, hook, script, storyboard, voice, build, QA, and an installer. Ask for a reel, or run one stage on its own.+- **Nine agent skills** (the open `SKILL.md` format, so they load in most coding agents; see [Works with](#works-with)) that run the whole pipeline: strategy, hook, script, storyboard, voice, build, QA, and an installer. Ask for a reel, or run one stage on its own.- **A Remotion library** the skills build on: a paper-cut component kit, 24 backdrops, 17 camera moves, 10 scene transitions, film-look layers, 79 sound effects and 8 music beds, plus the scripts that tie them into an episode.You describe the video ("explain this repo in 25 seconds"). The skills research it, write a script on a fixed spoken spine, plan every camera move and cut, make or fake the voiceover, and build the scenes in Remotion. You review stills and the final cut.@@ -38,7 +38,7 @@ Each camera move and cut, with its props and when to use it, is in [`library/pap## Install-You need Node 20+, npm, ffmpeg, rsync and Python 3. Claude Code or opencode is the front end.+You need Node 20+, npm, ffmpeg, rsync and Python 3. Any coding agent in [Works with](#works-with) is the front end.**With `npx skills`** (skills only, fastest):@@ -46,7 +46,7 @@ You need Node 20+, npm, ffmpeg, rsync and Python 3. Claude Code or opencode is tnpx skills add 0xS4N4TG/papercut-explainer```-This installs the nine skills into your agents' skill folders (Claude Code and the others the CLI supports). It does not fetch the Remotion library or the scripts. Open Claude Code and say "set up papercut-explainer": `papercut-setup` clones the repo, asks how much you want (Minimal, Standard, Full) and installs it. Add `-g` for a user-wide install, `--skill papercut-hook` to take one skill.+This installs the nine skills into your agents' skill folders (the CLI supports about 80 agents). It does not fetch the Remotion library or the scripts. Open your agent and say "set up papercut-explainer": `papercut-setup` clones the repo, asks how much you want (Minimal, Standard, Full) and installs it. Add `-g` for a user-wide install, `--skill papercut-hook` to take one skill.**With git** (everything, including the library):@@ -79,23 +79,57 @@ Non-interactive and scoped installs:./install.sh --uninstall # remove the links it made```-By default skills are symlinked into `~/.claude/skills` and `~/.config/opencode/skills` (pass `--target claude` or `--target opencode` for only one) and the subagent into the sibling `agents` folders (`~/.claude/agents`, `~/.config/opencode/agents`; opencode also discovers the `.claude` paths), 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.+By default the installer looks for coding agents on your machine (`--target auto`; Claude Code if it finds none) and symlinks the skills into each one's skills folder, so a `git pull` updates them. Pick harnesses yourself with `--target claude,codex,gemini` (names in [Works with](#works-with)), or `--target all`. 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.-The scene-builder subagent is written as a copy (not a link) with the model you pick: `--claude-model sonnet|opus|haiku|inherit|<id>` (default `sonnet`) and `--opencode-model inherit|<provider/model-id>` (default `inherit`, the session's model). Rerun the installer to change it; `papercut-setup` asks.--Opencode-only minimal install:+**The scene-builder subagent** (`papercut-scene`, which builds the scenes in parallel) is written as a copy per harness, in that harness's own format, with the model you choose. Rerun the installer to change it; `papercut-setup` asks.```bash-./install.sh --mode minimal --target opencode --yes+./install.sh --mode minimal --target claude,opencode,codex --yes # defaults: Claude sonnet, others inherit the session model+./install.sh --mode minimal --target claude --claude-model opus --yes # opus | sonnet | haiku | inherit | a model id+./install.sh --mode minimal --target opencode --opencode-model anthropic/claude-sonnet-5-5 --yes+./install.sh --mode minimal --target codex --agent-model codex=<model-id> --yes # any harness with file subagents```-Prefer to let the agent do it? Open Claude Code or opencode 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.+Prefer to let the agent do it? Open your agent in this folder and say **"set up papercut-explainer"**. The `papercut-setup` skill detects your agents, asks which mode and which scene-agent model you want, confirms any large download, runs the installer with the right flags and checks the result.++Install by hand: symlink or copy each folder in `skills/` into your agent's skills folder, then `export PAPERCUT_LIB="$PWD/library"`. For a subagent file, copy `agents/papercut-scene.md` (Claude Code) or `agents/opencode/papercut-scene.md` (OpenCode) and add the `model:` line yourself; Codex and Gemini files are generated by the installer.++## Works with++The skills are Agent Skills (`SKILL.md` folders with only `name` and `description` in the frontmatter, checked against the spec), so any agent that loads them works. The installer knows where each one looks:++| Harness | `--target` | Skills folder | Scene subagent file | Status |+|---|---|---|---|---|+| Claude Code | `claude` | `~/.claude/skills` | `~/.claude/agents/*.md` | In daily use |+| OpenCode | `opencode` | `~/.config/opencode/skills` | `~/.config/opencode/agents/*.md` | Skills, agent file and model line checked on 1.18; 2.x checked by the contributor who added it |+| Codex CLI | `codex` | `~/.agents/skills` | `~/.codex/agents/*.toml` | Paths and fields from OpenAI's docs; the TOML parses; not run in Codex |+| Gemini CLI | `gemini` | `~/.agents/skills` | `~/.gemini/agents/*.md` | Paths and fields from Google's docs; not run in Gemini CLI |+| Cursor, GitHub Copilot, Amp, Goose, Cline, Roo Code, Kilo Code, Zed, Factory Droid, Warp, Augment, Junie, OpenHands, Crush | `cursor` `copilot` `amp` `goose` `cline` `roo` `kilo` `zed` `droid` `warp` `augment` `junie` `openhands` `crush` | `~/.agents/skills` | none (Cursor, Copilot in VS Code and Goose read `~/.claude/agents` themselves) | Paths from each vendor's docs; not run |+| Kiro, Qwen Code, Windsurf | `kiro` `qwen` `windsurf` | `~/.kiro/skills`, `~/.qwen/skills`, `~/.codeium/windsurf/skills` | none | Paths from the vendors' docs or the `skills` CLI; not run |+| Anything else that reads `~/.agents/skills` | `agents` | `~/.agents/skills` | none | |+| Aider (no skills support) | none | | | Run `aider --read AGENTS.md`; the file points at the skills |++"Not run" means the folder and file format follow the vendor's documentation as of 17 Oct 2026 and the installer's output was checked for shape, but the agent itself wasn't started. If one breaks, [open an issue](../../issues) with the harness version. The table lives in [`harnesses.sh`](harnesses.sh): adding a harness is one line.++Harnesses without file subagents build the scenes themselves, one after another, or through their own parallel-task feature. The output is the same; it takes longer.++Opening this checkout in OpenCode finds the skills and the scene agent with no install (checked on 1.18; `.opencode/` and `opencode.jsonc` point at `skills/` and `agents/opencode/`). Agents that read a project's `.agents/skills` should find them through the `.agents/skills` link, which is untested. [`AGENTS.md`](AGENTS.md) covers agents that read that file instead.++## Models other than Claude (DeepSeek and others)++The skills are plain instructions, so any model that can call tools, read the QA stills (image input) and follow a long brief can run them. Weaker models cost more QA rounds. Nothing here has been run end to end on a non-Anthropic model by the maintainer, so treat these as starting points; DeepSeek's page for each agent is the authority: [api-docs.deepseek.com/quick_start/agent_integrations](https://api-docs.deepseek.com/quick_start/agent_integrations).++| Agent | What to do (DeepSeek model ids as of 17 Oct 2026: `deepseek-flash`, `deepseek-v4-pro`) |+|---|---|+| OpenCode | `/connect`, choose `deepseek`, paste your key. Then `./install.sh --target opencode --opencode-model deepseek/deepseek-flash --yes`. |+| Codex CLI | Add DeepSeek's `[model_providers.deepseek]` block to `~/.codex/config.toml` (their Codex page has it; prefer an env var for the key over a literal token). Then `./install.sh --target codex --agent-model codex=deepseek-flash --yes`. |+| Claude Code | Point it at DeepSeek's Anthropic-compatible endpoint with `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` and the `ANTHROPIC_DEFAULT_*_MODEL` variables from their Claude Code page. The scene agent's `model: sonnet` then resolves through `ANTHROPIC_DEFAULT_SONNET_MODEL`, so leave `--claude-model` alone. |-Install by hand: symlink or copy each folder in `skills/` into `~/.claude/skills/` and `~/.config/opencode/skills/`, `agents/papercut-scene.md` into `~/.claude/agents/` and `~/.config/opencode/agents/`, then `export PAPERCUT_LIB="$PWD/library"`.+The same pattern works for any provider your agent supports: connect it in the agent, then pass its model id to `--opencode-model` or `--agent-model`.## Use it-Open Claude Code or opencode in any folder you want the episode to live in and ask for a reel:+Open your agent in any folder you want the episode to live in and ask for a reel:> Make a papercut explainer about https://github.com/example/echolark. 25 seconds, comment keyword PAPER.@@ -227,7 +261,7 @@ Projects keep a snapshot of the kit in `src/lib/`, so an old episode renders the| 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. || Disk | about 0.7 GB per project for `node_modules` (shared by APFS cloning on macOS; plain copy elsewhere, or set `DONOR`); 4–6 GB for local voice |-| Claude Code / opencode | the skills and subagent target both (see `--target`) |+| A coding agent | any in [Works with](#works-with); the installer finds the ones you have (`--target`) |## Cost@@ -255,7 +289,8 @@ What moves the cost, largest first:| Model download stalls | Rerun `library/voice/setup_tts.sh`; finished files are kept. It already sets `HF_HUB_DISABLE_XET=1`. || First render is slow | Remotion downloads its headless browser (about 200 MB) once. || `--gl=angle` rejected | Edit the flag in `library/tools/render.py` and `qa.sh` for your Chrome build. |-| A skill does not trigger | Check `ls ~/.claude/skills` and `ls ~/.config/opencode/skills`; restart Claude Code after installing (opencode reloads automatically). |+| A skill does not trigger | Check the harness's skills folder (table in [Works with](#works-with)); `./install.sh --doctor` lists what it found. Restart Claude Code, Codex and Gemini CLI after installing; opencode reloads on its own. |+| opencode: "Configuration is invalid ... tools" | You have an old copy of the Claude agent file in an opencode folder. Rerun `./install.sh --target opencode`; it writes the opencode version. |## Limitsdiff --git a/examples/prompts.md b/examples/prompts.mdindex 346ba6f..6fa40b3 100644--- a/examples/prompts.md+++ b/examples/prompts.md@@ -2,7 +2,7 @@Copy-paste prompts for each skill, in the order of the workflow, with what to expect. Replace anything in `<angle brackets>`.-Claude Code or opencode picks a skill from your wording. If the wrong one loads, or none does, name it: "use papercut-hook to write 5 hooks for this fact list". Each skill reads the files the stage before it wrote, so you can stop after any stage and pick up in a new session. `examples/paper-trail/` shows what every stage writes.+Your agent picks a skill from your wording. If the wrong one loads, or none does, name it: "use papercut-hook to write 5 hooks for this fact list". Each skill reads the files the stage before it wrote, so you can stop after any stage and pick up in a new session. `examples/paper-trail/` shows what every stage writes.## End to end@@ -32,7 +32,7 @@ Set up papercut-explainer, partial install- Loads `papercut-setup`. It runs `./install.sh --doctor` from the repo root and tells you in plain words what is installed and which mode that adds up to.- Asks, in one question: how much (Minimal, Standard, Full or Custom), skills for every project or one, symlink or copy. "Partial" usually means Minimal, or Custom with the components you name (`skills,deps,pytools,verify`). It asks again before any multi-GB download.-- Runs `install.sh --yes` with the matching flags and writes `~/.config/papercut-explainer/config.env`, which every later skill reads for the library path. A new Claude Code session picks up the linked skills (restart it); opencode reloads them automatically.+- Runs `install.sh --yes` with the matching flags and writes `~/.config/papercut-explainer/config.env`, which every later skill reads for the library path. A new Claude Code, Codex or Gemini CLI session picks up the linked skills (restart it); opencode reloads them automatically.## 2. Strategydiff --git a/harnesses.sh b/harnesses.shnew file mode 100644index 0000000..f1f6697--- /dev/null+++ b/harnesses.sh@@ -0,0 +1,92 @@+# Harness table for install.sh. Sourced, not run. Bash 3.2 safe (macOS default): no associative arrays.+#+# One line per harness:+# name | user skills dir | project skills dir | agent kind | user agents dir | project agents dir+# | `npx skills` agent id | detect command | detect dir+#+# Skills: most harnesses read the shared ~/.agents/skills (project: .agents/skills). Claude Code, Kiro, Qwen Code,+# Windsurf and OpenCode v1 have their own folders, so they get their own rows. Paths follow each vendor's docs+# (checked 2026-10-17); only Claude Code and OpenCode 1.x have been run against this installer.+#+# Agent kind is the file format of the papercut-scene subagent:+# claude markdown, Claude Code frontmatter (also read by Cursor, Copilot in VS Code and Goose from .claude/agents)+# opencode markdown, opencode frontmatter (no `tools:`: opencode 1.x rejects Claude's comma list)+# codex TOML (name, description, developer_instructions, model, model_reasoning_effort)+# gemini markdown, strict frontmatter (name, description, model)+# none no file-defined subagents; papercut-build falls back to a general agent or builds the scenes itself+#+# To add a harness: add a line. Nothing else needs to change.+HARNESS_TABLE='+claude|~/.claude/skills|.claude/skills|claude|~/.claude/agents|.claude/agents|claude-code|claude|~/.claude+opencode|~/.config/opencode/skills|.opencode/skills|opencode|~/.config/opencode/agents|.opencode/agents|opencode|opencode|~/.config/opencode+codex|~/.agents/skills|.agents/skills|codex|~/.codex/agents|.codex/agents|codex|codex|~/.codex+gemini|~/.agents/skills|.agents/skills|gemini|~/.gemini/agents|.gemini/agents|gemini-cli|gemini|~/.gemini+cursor|~/.agents/skills|.agents/skills|none|-|-|cursor|cursor-agent|~/.cursor+copilot|~/.agents/skills|.agents/skills|none|-|-|github-copilot|copilot|~/.copilot+amp|~/.agents/skills|.agents/skills|none|-|-|amp|amp|~/.config/amp+goose|~/.agents/skills|.agents/skills|none|-|-|goose|goose|~/.config/goose+cline|~/.agents/skills|.agents/skills|none|-|-|cline|cline|~/.cline+roo|~/.agents/skills|.agents/skills|none|-|-|roo|-|~/.roo+kilo|~/.agents/skills|.agents/skills|none|-|-|kilo|kilo|~/.kilo+zed|~/.agents/skills|.agents/skills|none|-|-|zed|zed|-+droid|~/.agents/skills|.agents/skills|none|-|-|droid|droid|~/.factory+warp|~/.agents/skills|.agents/skills|none|-|-|warp|-|~/.warp+augment|~/.agents/skills|.agents/skills|none|-|-|augment|auggie|~/.augment+junie|~/.agents/skills|.agents/skills|none|-|-|junie|junie|~/.junie+openhands|~/.agents/skills|.agents/skills|none|-|-|openhands|openhands|~/.openhands+crush|~/.agents/skills|.agents/skills|none|-|-|crush|crush|~/.config/crush+kiro|~/.kiro/skills|.kiro/skills|none|-|-|kiro-cli|kiro-cli|~/.kiro+qwen|~/.qwen/skills|.qwen/skills|none|-|-|qwen-code|qwen|~/.qwen+windsurf|~/.codeium/windsurf/skills|.windsurf/skills|none|-|-|windsurf|windsurf|~/.codeium/windsurf+agents|~/.agents/skills|.agents/skills|none|-|-|universal|-|-+'++h_names() { printf '%s\n' "$HARNESS_TABLE" | awk -F'|' 'NF > 1 { print $1 }'; }+h_known() { h_names | grep -qx "$1"; }+h_row() { printf '%s\n' "$HARNESS_TABLE" | awk -F'|' -v n="$1" '$1 == n { print; exit }'; }+h_field() { # h_field NAME COLUMN (1-based); expands a leading ~ to $HOME; "-" becomes empty+ local v; v="$(h_row "$1" | awk -F'|' -v c="$2" '{ print $c }')"+ case "$v" in "~/"*) v="$HOME/${v#\~/}" ;; "-") v="" ;; esac+ printf '%s' "$v"+}+h_detected() { # does this harness look installed? (command on PATH or its config folder exists)+ local cmd dir; cmd="$(h_field "$1" 8)"; dir="$(h_field "$1" 9)"+ [ -n "$cmd" ] && command -v "$cmd" >/dev/null 2>&1 && return 0+ [ -n "$dir" ] && [ -d "$dir" ] && return 0+ return 1+}++# resolve_targets SPEC -> TARGET_LIST (array of harness names)+# auto (the default): every harness that looks installed, else claude+# all: every harness in the table a,b,c: exactly those+resolve_targets() {+ local spec="$1" n; TARGET_LIST=()+ case "$spec" in+ auto) for n in $(h_names); do [ "$n" = agents ] && continue; h_detected "$n" && TARGET_LIST+=("$n"); done+ [ "${#TARGET_LIST[@]}" -gt 0 ] || TARGET_LIST=(claude) ;;+ all) for n in $(h_names); do TARGET_LIST+=("$n"); done ;;+ *) for n in $(printf '%s' "$spec" | tr ',' ' '); do+ h_known "$n" || { echo "unknown --target '$n'. Known: $(h_names | tr '\n' ' ')| auto | all" >&2; exit 2; }+ TARGET_LIST+=("$n")+ done ;;+ esac+}++in_array() { # in_array VALUE ITEM... (call with "${ARR[@]+"${ARR[@]}"}" so an empty array is fine under set -u)+ local v="$1" x; shift+ for x in "$@"; do [ "$x" = "$v" ] && return 0; done+ return 1+}++# Per-harness model for the scene agent. AGENT_MODELS is a space-separated list of name=model; the last entry wins.+agent_model() { # agent_model NAME -> model string, "inherit" when none was set+ local kv m=inherit+ for kv in $AGENT_MODELS; do [ "${kv%%=*}" = "$1" ] && m="${kv#*=}"; done+ printf '%s' "$m"+}+valid_model() { # valid_model NAME MODEL -> 0 if the string is acceptable for that harness+ case "$2" in ""|*[!A-Za-z0-9._:/#\[\]-]*) return 1 ;; esac+ [ "$2" = inherit ] && return 0+ [ "$1" = opencode ] && { case "$2" in */*) case "$2" in /*|*/) return 1 ;; esac ;; *) return 1 ;; esac; }+ return 0+}diff --git a/install.sh b/install.shindex 4ee317e..6b4c8dc 100755--- a/install.sh+++ b/install.sh@@ -16,14 +16,18 @@# Options# --mode M minimal | standard | full | custom# --components a,b,c with --mode custom: skills,deps,remotion-skills,pytools,tts,verify-# --target T claude | opencode | all (default all: install for both agents)+# --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 skills into DIR/.claude/skills and DIR/.opencode/skills-# instead (one project only; --target filters which of the two)+# --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, session model) | provider/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@@ -39,20 +43,21 @@ 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="all"; TARGET_EXPLICIT=0; SKILLS_DIR=""; SKILLS_DIR_EXPLICIT=0; PROJECT_DIR=""+MODE=""; COMPONENTS=""; TARGET="auto"; TARGET_EXPLICIT=0; SKILLS_DIR=""; SKILLS_DIR_EXPLICIT=0; PROJECT_DIR=""COPY=0; YES=0; DRY=0-CLAUDE_MODEL=sonnet; OPENCODE_MODEL=inherit+AGENT_MODELS="claude=sonnet"; MODEL_FLAGS=""TTS_MODEL=1.7B; WITH_CLONE=0; DOCTOR=0; UNINSTALL=0while [ $# -gt 0 ]; docase "$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 claude, opencode or all}; TARGET_EXPLICIT=1; 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) CLAUDE_MODEL=${2:?--claude-model needs sonnet, opus, haiku, inherit or a model id}; shift 2 ;;- --opencode-model) OPENCODE_MODEL=${2:?--opencode-model needs inherit or provider/model-id}; 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 ;;@@ -65,42 +70,34 @@ while [ $# -gt 0 ]; doesacdone-case "$TARGET" in- claude|opencode|all) ;;- *) echo "--target needs claude, opencode or all (got: $TARGET)" >&2; exit 2 ;;-esac+. "$ROOT/harnesses.sh"+resolve_targets "$TARGET"-case "$CLAUDE_MODEL" in- ""|*[!A-Za-z0-9._:-]*) echo "--claude-model needs sonnet, opus, haiku, inherit or a model id (got: $CLAUDE_MODEL)" >&2; exit 2 ;;-esac-case "$OPENCODE_MODEL" in- inherit) ;;- */*) case "$OPENCODE_MODEL" in *[!A-Za-z0-9._:/-]*|/*|*/) echo "--opencode-model needs inherit or provider/model-id (got: $OPENCODE_MODEL)" >&2; exit 2 ;; esac ;;- *) echo "--opencode-model needs inherit or provider/model-id, e.g. anthropic/claude-sonnet-5-5 (got: $OPENCODE_MODEL)" >&2; exit 2 ;;-esac+# 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-# Skill destinations. One entry per agent target, so both Claude Code and-# opencode pick the skills up (opencode also reads ~/.claude/skills, but the-# native path keeps discovery explicit and survives config changes).-# --skills-dir overrides the list with a single dir (legacy behaviour);-# --project scopes the install to one project folder instead of user-wide.-SKILLS_DIRS=()+# 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 ]; thenSKILLS_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") ;; esacelse- if [ -n "$PROJECT_DIR" ]; then- case "$TARGET" in- claude) SKILLS_DIRS=("$PROJECT_DIR/.claude/skills") ;;- opencode) SKILLS_DIRS=("$PROJECT_DIR/.opencode/skills") ;;- all) SKILLS_DIRS=("$PROJECT_DIR/.claude/skills" "$PROJECT_DIR/.opencode/skills") ;;- esac- else- case "$TARGET" in- claude) SKILLS_DIRS=("$HOME/.claude/skills") ;;- opencode) SKILLS_DIRS=("$HOME/.config/opencode/skills") ;;- all) SKILLS_DIRS=("$HOME/.claude/skills" "$HOME/.config/opencode/skills") ;;- esac- fi+ 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+ donefiif [ -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@@ -120,21 +117,55 @@ confirm() { # confirm "question" default(y|n)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 so the model is the user's choice. Claude Code and opencode name-# models differently, so the source file carries no model line; this adds one (or none for "inherit").-agent_with_model() { # agent_with_model SRC MODEL- awk -v model="$2" '+# 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 "<!-- papercut-explainer install.sh (generated): rerun the installer to change the 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+}# ---------------------------------------------------------------- doctordoctor() {- say "papercut-explainer: status (target: $TARGET)"+ say "papercut-explainer: status (target: $TARGET = ${TARGET_LIST[*]})"local n=0 t=0 L_SKILLS=0 L_STD=1 L_FULL=0local best=0 dir_n nskills misses=() complete=()for dir in "${SKILLS_DIRS[@]}"; do@@ -159,7 +190,7 @@ doctor() {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"; do+ 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=1doneif [ $remo_found = 1 ]; then ok "remotion skills"; else miss "remotion skills (npx skills add remotion-dev/skills, see step_remotion)"; L_STD=0; fi@@ -185,7 +216,7 @@ uninstall() {if [ -L "$p" ]; thencase "$(readlink "$p")" in "$ROOT"/*) run rm "$p"; ok "removed $p" ;; *) miss "kept $p (link points elsewhere)" ;; esacelif [ -d "$p" ] && [ -f "$p/.papercut-installed" ]; then run rm -rf "$p"; ok "removed $p"- elif [ -f "$p" ] && [ -f "$ROOT/agents/$(basename "$p")" ] && { cmp -s "$p" "$ROOT/agents/$(basename "$p")" || grep -q 'papercut-explainer install.sh (generated)' "$p"; }; then run rm "$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)"; fidone < "$rec"run rm -f "$rec"@@ -249,7 +280,7 @@ esacif [ "$MODE" != custom ] && interactive; thensay "Plan ($MODE)"- [ $C_SKILLS = 1 ] && echo " - link the skills into ${SKILLS_DIRS[*]} (target: $TARGET)"+ [ $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"@@ -273,8 +304,36 @@ step_config() {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 adir+ local onedirfor onedir in "${SKILLS_DIRS[@]}"; dosay "skills -> $onedir"run mkdir -p "$onedir" "$CFG_DIR"@@ -295,30 +354,8 @@ step_skills() {[ "$DRY" = 1 ] || echo "$dst" >> "$CFG_DIR/installed.txt"ok "$s ($onedir)"done- # the scene-builder subagent sits next to the skills dir:- # ~/.claude/agents, ~/.config/opencode/agents, or <project>/.claude|opencode/agents- adir="$(dirname "$onedir")/agents"- run mkdir -p "$adir"- local akind=claude amodel="$CLAUDE_MODEL" agen- case "$onedir" in */.opencode/skills|*/opencode/skills) akind=opencode; amodel="$OPENCODE_MODEL" ;; esac- local asrc="$ROOT/agents"; [ "$akind" = opencode ] && asrc="$ROOT/agents/opencode"- for a in "$asrc"/*.md; do- [ -f "$a" ] || continue- local adst="$adir/$(basename "$a")"- agen="$(mktemp)"; agent_with_model "$a" "$amodel" > "$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 'papercut-explainer install.sh (generated)' "$adst" 2>/dev/null; then run rm "$adst" # an earlier run 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 "$a" .md).$ts.md"; miss "backed up to $CFG_DIR/backups"- else miss "kept existing agent $(basename "$a")"; 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) ($akind, model: $amodel) -> $adir"- donedone+ install_agents[ "$DRY" = 1 ] || [ ! -f "$CFG_DIR/installed.txt" ] || sort -u "$CFG_DIR/installed.txt" -o "$CFG_DIR/installed.txt"}@@ -338,25 +375,19 @@ step_deps() {}step_remotion() {- say "Remotion agent skills (target: $TARGET)"- local need_cc=0 need_oc=0- case "$TARGET" in- claude) need_cc=1 ;;- opencode) need_oc=1 ;;- all) need_cc=1; need_oc=1 ;;- esac- [ -f "$HOME/.claude/skills/remotion-best-practices/SKILL.md" ] && need_cc=0- [ -f "$HOME/.config/opencode/skills/remotion-best-practices/SKILL.md" ] && need_oc=0- # opencode also discovers ~/.claude/skills, so a Claude-side install covers both;- # the native opencode install below just makes it explicit.- if [ $need_cc = 0 ] && [ $need_oc = 0 ]; then ok "already installed"; return; fi+ say "Remotion agent skills (${TARGET_LIST[*]})"command -v npx >/dev/null 2>&1 || { note_fail remotion-skills "npx not found"; return 1; }- if [ $need_cc = 1 ]; then- if ! run npx -y skills@latest add remotion-dev/skills -g -y -a claude-code; then note_fail remotion-skills "npx skills add failed for claude-code; run it by hand"; fi- fi- if [ $need_oc = 1 ]; then- if ! run npx -y skills@latest add remotion-dev/skills -g -y -a opencode; then note_fail remotion-skills "npx skills add failed for opencode; run it by hand"; fi- fi+ # `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() {@@ -398,9 +429,9 @@ 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; ficat <<EOF-Next: open Claude Code or opencode and say+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 claude|opencode|all]+Check the setup any time: ./install.sh --doctor [--target auto|all|claude,codex,...]EOFdiff --git a/skills/papercut-build/SKILL.md b/skills/papercut-build/SKILL.mdindex 4a88aff..19acdab 100644--- a/skills/papercut-build/SKILL.md+++ b/skills/papercut-build/SKILL.md@@ -11,7 +11,7 @@ Build every episode on the library instead of writing a Remotion project from sc- Install: **Standard** or Full. Needs the library, node 20+, npm, ffmpeg, Python tools (numpy, Pillow, soundfile) and Chrome or Chromium for the audio render. Probe with the commands in `papercut-explainer`; if something is missing, run `./install.sh --doctor` and hand over to `papercut-setup`.- Library: `$PAPERCUT_LIB`, else the `PAPERCUT_LIB=` line in `~/.config/papercut-explainer/config.env`, else ask once. With no library at all, build from the sketches in `../papercut-explainer/references/remotion-recipes.md`.-- Load the Remotion best-practices skill first (`remotion-best-practices`, from the Remotion plugin or `npx skills add remotion-dev/skills -g -y -a claude-code` plus `-a opencode` for opencode) and follow its routing for markup, captions and the Studio.+- Load the Remotion best-practices skill first (`remotion-best-practices`, from the Remotion plugin, or `npx skills add remotion-dev/skills -g -y -a <your harness id>`; `install.sh --mode standard` does this) and follow its routing for markup, captions and the Studio.- Needs `papercut/STORYBOARD.md` and `narration/script.json` from the earlier stages.- Smoke test of the whole toolchain: `library/tools/selftest.sh` builds `examples/hello-reel/` in a throwaway folder and renders one still.@@ -48,7 +48,7 @@ Follow `../papercut-explainer/references/asset-prompts.md`: an image tool (anyth## 4. Scenes1. Build `S01Hook` yourself first, from the HOOK block. It is the reference scene the agents match (cue constants, the camera, clamped `interpolate`).-2. Hand the rest to scene agents in parallel, grouped by scene (2-3 scenes each; more agents cost more startup context). Use the `papercut-scene` agent that `install.sh` links into the agents folder (`~/.claude/agents` for Claude Code, `~/.config/opencode/agents` for opencode; a general agent also works). Spawn via the Task tool in Claude Code or the subagent tool in opencode. The brief is `library/papercut/AGENT_BRIEF.md`. The spawn message gives the project path, each agent's scenes with absolute frame ranges, a QA folder name and the value of `$PAPERCUT_LIB`.+2. Hand the rest to scene agents in parallel, grouped by scene (2-3 scenes each; more agents cost more startup context). Use the `papercut-scene` agent that `install.sh` wrote for your harness (Claude Code `~/.claude/agents`, OpenCode `~/.config/opencode/agents`, Codex `~/.codex/agents`, Gemini CLI `~/.gemini/agents`); a general agent also works. Spawn it with your harness's own mechanism (the Task tool in Claude Code, the subagent tool in opencode, Codex's subagents, Gemini's agent tool). **If your harness has no subagents, build the scenes yourself one at a time**, in the same order and with the same brief; it is slower, not different. The brief is `library/papercut/AGENT_BRIEF.md`. The spawn message gives the project path, each agent's scenes with absolute frame ranges, a QA folder name and the value of `$PAPERCUT_LIB`.3. File ownership: an agent writes only `src/scenes/<Scene>.tsx`, an optional `<Scene>.parts.tsx` and `tools/cue_sheet.d/<Scene>.json`. Never `src/lib/**`, other scenes, `index.ts`, `plan.json`, `episode.json` or the storyboard.4. Agents read `library/papercut/CATALOG.md` and `library/audio/CATALOG.md`, not the kit source, and reuse components, prop sets and scene templates (`kit/scenes/`, for example `CtaPhoneDM` for the CTA) before drawing anything new.diff --git a/skills/papercut-explainer/SKILL.md b/skills/papercut-explainer/SKILL.mdindex 939fa07..fc1ae70 100644--- a/skills/papercut-explainer/SKILL.md+++ b/skills/papercut-explainer/SKILL.md@@ -90,7 +90,7 @@ node -v; ffmpeg -version | head -1"$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 (under `.claude/skills` or `.config/opencode/skills`), or `PAPERCUT_HOME` in the config file.+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 (under `.claude/skills`, `.agents/skills`, `.config/opencode/skills` or another harness's skills folder), or `PAPERCUT_HOME` in the config file.## Rules across stagesdiff --git a/skills/papercut-setup/SKILL.md b/skills/papercut-setup/SKILL.mdindex 77e314a..8086182 100644--- a/skills/papercut-setup/SKILL.md+++ b/skills/papercut-setup/SKILL.md@@ -9,7 +9,7 @@ A guided wrapper around `install.sh`. It checks what is installed, asks how much## Preflight-- Find the repo root (where `install.sh` lives): `readlink` on the installed skill folder ends in `<root>/skills/papercut-setup`. Check each agent's location in turn: `~/.claude/skills/papercut-setup` (or `<project>/.claude/skills`), then `~/.config/opencode/skills/papercut-setup` (or `<project>/.opencode/skills`; opencode also discovers the `.claude` paths). 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.+- 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.@@ -19,7 +19,7 @@ A guided wrapper around `install.sh`. It checks what is installed, asks how much./install.sh --doctor```-Add `--project DIR`, `--skills-dir DIR` or `--target claude|opencode|all` if the skills went somewhere other than the defaults (`~/.claude/skills` + `~/.config/opencode/skills`); the doctor only looks where you point it. It prints `[ok]`, `[--]` (missing) or `[!!]` (wrong). Summarise it in plain words:+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)@@ -30,16 +30,16 @@ Then say which install mode that adds up to (see `papercut-explainer`, Install m## 2. Ask-Ask only what is still open, in one call (AskUserQuestion in Claude Code, the question tool in opencode):+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):| Question | Options ||---|---|| How much? | **Minimal**: skills only, seconds. **Standard**: render with a placeholder voice, ~0.7 GB and a few minutes. **Full**: Standard + local voiceover, +4-6 GB (a 1.5 GB venv plus a 2.3 or 4.2 GB model) and a 2-minute smoke test. **Custom**: pick components. |-| Which agent? | Both (default, `--target all`), Claude Code only (`--target claude`) or opencode only (`--target opencode`). |+| Which agents? | **Detected on this machine** (default, `--target auto`; Claude Code if none), a list such as `--target claude,codex,gemini`, or `--target all`. Names are in `harnesses.sh`; the README's *Works with* table says which are tested. || Where do the skills go? | User-wide (the default) or one project (`--project DIR`). || Copy or link? | Symlink (default, updates with `git pull`) or `--copy` (a snapshot). |-| Scene-agent model, Claude Code? (skip if `--target opencode`) | **Sonnet** (default: cheapest, what the scene agents were tuned on) · **Opus** (strongest; every parallel scene agent bills at Opus rates) · **Haiku** (cheapest, weakest) · **Inherit** (whatever model the session runs). Maps to `--claude-model sonnet\|opus\|haiku\|inherit\|<model id>`. |-| Scene-agent model, opencode? (skip if `--target claude`) | **Inherit** (default: the session's model) or a specific `provider/model-id` in the form opencode's model picker shows, for example `anthropic/claude-sonnet-5-5`. Maps to `--opencode-model inherit\|<provider/model-id>`. Free open-source models work but are untested here; a weaker model costs QA rounds. |+| Scene-agent model, per agent with file subagents (`claude`, `opencode`, `codex`, `gemini`; skip the rest)? | One question per selected agent, each with **Inherit** (use the session model) as an option. Claude Code: **Sonnet** (default: cheapest, what the scene agents were tuned on) · **Opus** (strongest; every parallel scene agent bills at Opus rates) · **Haiku** · Inherit. Maps to `--claude-model sonnet\|opus\|haiku\|inherit\|<id>`. Other agents: default **Inherit**, or a model id in that agent's own format (opencode `provider/model-id`, for example `anthropic/claude-sonnet-5-5`; Codex and Gemini plain ids). Maps to `--opencode-model M` or `--agent-model codex=M`. |+| Another provider's model (DeepSeek and others)? | Only if the user asks. Connect the provider inside the agent first (OpenCode `/connect`; Codex `config.toml` provider; Claude Code's `ANTHROPIC_*` variables), then pass its model id as above. The README's *Models other than Claude* section has the steps and the DeepSeek ids. Say plainly that it is untested end to end and that weaker models cost more QA rounds. || TTS model size (Full) | 1.7B, better prosody, ~4.2 GB (default). 0.6B, lighter and faster, ~2.3 GB. || Voice-clone model (Full) | No (default), or `--with-clone`: the Base model of the same size again. |@@ -48,19 +48,19 @@ Confirm before any multi-GB download. On a machine with no GPU (not Apple Silico## 3. Install```-./install.sh --mode <minimal|standard|full> --yes [--target claude|opencode|all] [--claude-model M] [--opencode-model M] [--skills-dir DIR | --project DIR] [--copy] [--tts-model 1.7B|0.6B] [--with-clone]+./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 agent folder with the chosen `model:` line (Claude Code and opencode name models differently, so the repo's file carries none). Skills stay symlinks. To change the model later: `./install.sh --mode custom --components skills --claude-model opus --yes` (or `--opencode-model ...`).+- 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 the Claude and opencode skill/agent folders, unless `--target` says otherwise). Standard adds a dependency check, the Remotion agent skills (`npx skills add remotion-dev/skills -g -y -a claude-code` plus `-a opencode`, 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.+- 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 session picks up newly linked skills (restart it); opencode reloads configuration automatically. Then suggest: "make a papercut explainer about <link>", or one stage at a time ("write a hook for...", "storyboard this script", "set up the voice").+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 <link>", or one stage at a time ("write a hook for...", "storyboard this script", "set up the voice").## Troubleshooting@@ -72,8 +72,8 @@ Run `./install.sh --doctor` again with the same `--project`, `--skills-dir` or `| Hugging Face download stalls or fails | Rerun; finished files are kept and the script retries 3 times. It sets `HF_HUB_DISABLE_XET=1`; set it yourself for manual downloads. || First render is slow | Remotion downloads its headless Chrome once. The audio render and `capture.mjs` use your own Chrome; set `CHROME_PATH` if it isn't in a usual place. || Self-test fails | Run `library/tools/selftest.sh` directly to see the failing step. |-| Skills don't show (Claude Code) | Start a new session. Check `ls ~/.claude/skills` (or `<project>/.claude/skills`). |-| Skills don't show (opencode) | Config reloads automatically. Check `ls ~/.config/opencode/skills` (or `<project>/.opencode/skills`); opencode also reads the `.claude` paths. |+| Skills don't show | Restart Claude Code, Codex or Gemini CLI (opencode reloads). Check the harness's folder (`harnesses.sh`; `~/.agents/skills` for most) and run `./install.sh --doctor`. |+| opencode: "Configuration is invalid ... tools" | An old copy of the Claude agent file sits in an opencode agents folder. Rerun `./install.sh --target opencode`; it writes the opencode version. || Scene agents cost too much, or run on the wrong model | Rerun the skills step with another model: `./install.sh --mode custom --components skills --claude-model sonnet --yes` (or `--opencode-model inherit`). `inherit` means the session model. || Move from Minimal to Standard | `./install.sh --mode custom --components deps,remotion-skills,pytools,verify --yes` || Add the voice later | `./install.sh --mode custom --components tts --yes [--tts-model 0.6B] [--with-clone]` |