playrig 0.0.0-stage → 0.1.0

package/editions/ae/skills/create-ae-video/references/templates.md

@@ -0,0 +1,90 @@
+# Templates for Create AE Video
+
+Copy, fill, and reprint compactly. Keep each to what fits on a screen.
+
+## Question bank (pick ≤ 5; defaults in brackets)
+
+| Topic | Question | Default if not answered |
+|---|---|---|
+| Purpose | What is this for and who watches it? (launch promo, explainer, social ad, title/opener, internal) | promo / explainer |
+| Length & format | How long, what shape? (15 s, 30 s; 16:9, 9:16, 1:1) | 15 s, 1920×1080, 24 fps |
+| Content | What should it say? (script, key lines, labels, a CTA) | ask for the 1-3 key lines; draft the rest and confirm |
+| Look | Light & clean, or dark & technical? Brand colours? Font? | light for friendly, dark for technical; Inter |
+| References | Any video/images to match? | none |
+| Must-haves | Anything that must appear / must not appear? | none |
+| Music/VO | Does motion need to hit beats? | no audio sync |
+
+Choice-style questions work best with 2-4 options and a recommended default.
+
+## Brief block
+
+```
+BRIEF
+Goal:      <one sentence>
+Audience:  <who>
+Format:    <WxH, fps, length>
+Look:      <light|dark>, <palette>, <font>
+Content:   <key lines / labels / CTA>
+Reference: <none | path>
+Assumed:   <what you decided without asking>
+```
+
+## Coverage map
+
+| Need | Recipe(s) | Status | Note / fallback |
+|---|---|---|---|
+| Light background with depth | `<background recipe id>` | ready | |
+| Headline word-by-word | `<text recipe id>` | ready | |
+| Logo build | `<logo recipe id>` | missing | substitute a fade-in, or create one |
+| ... | | | |
+
+Status: `ready` (runs now), `planned` (documented, no script), `missing` (nothing in the library).
+
+## Storyboard
+
+| # | Scene | Time | Background | Content | Recipe chain | Out |
+|---|---|---|---|---|---|---|
+| 1 | Hook | 0-3.5 s | radial light | "…" bold "…" + 6 chips | <background> → <headline> → <chips> → <exit> | hard cut |
+| 2 | … | | | | | |
+
+Total: <sum> s (target <n> s). Comps will be named `S1 Hook`, `S2 …`, master `MAIN`.
+
+## Status board (reprint at each milestone)
+
+```
+VIDEO: <name>   <WxH> @ <fps>   target <n>s
+Preflight: ready        Library gaps: <n> to create
+
+S1 Hook        built      approved
+S2 Proof       building   -
+S3 CTA         planned    -
+MAIN           planned    -
+
+Recipes to create: <id> (in progress), <id> (queued)
+Next: <one line>
+```
+
+## Polish checklist
+
+- Pacing: is every line readable for its full hold (≈ 3 words/s)? Any dead air?
+- Legibility: contrast, size, nothing clipped or off-screen, fonts are the intended ones.
+- Consistency: one typeface, one palette, same motion language (stagger/ease) across scenes.
+- Transitions: each cut is hidden behind motion or softened; no accidental flashes.
+- First and last frame: the opener starts clean; the end card holds long enough.
+
+## Handover
+
+```
+DONE: <name>
+Comps:      S1 Hook (3.5 s), S2 … , MAIN (15.0 s)  in <project name | unsaved project>
+Rebuild:    per-scene command chains (below), re-runnable with different --param values
+Tweak first: <3-5 parameters that change the feel most, with what they do>
+New recipes added to the library: <ids | none>
+Not covered / approximated: <list, incl. planned recipes>
+Reminders:  the project is UNSAVED and NOT RENDERED; render via the Render Queue / Media Encoder.
+Next:       <2-3 offers: variations, vertical cut, new recipes for planned items>
+
+S1 Hook
+  playrig ae lib run … --param …
+  …
+```

package/editions/ae/skills/create-ae-video/scripts/preflight.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+'use strict';
+// Readiness report for making an After Effects video: toolchain, library, After Effects + Playrig panel, fonts.
+// Usage: node .claude/skills/create-ae-video/scripts/preflight.js [--root <Playrig inbox>] [--wait 15]
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const cp = require('child_process');
+
+// The Playrig CLI: `playrig` on the PATH (npm install -g playrig), else the one next to this edition in the monorepo.
+const projectDir = path.resolve(__dirname, '..', '..', '..', '..'); // where the skills were installed (.claude/skills/<skill>/scripts/..)
+const repo = projectDir;
+const monoCli = path.resolve(__dirname, '..', '..', '..', '..', 'cli', 'bin', 'playrig.js');
+const onPath = cp.spawnSync(process.platform === 'win32' ? 'where' : 'which', ['playrig'], { encoding: 'utf8' }).status === 0;
+const cli = onPath ? ['playrig'] : fs.existsSync(monoCli) ? [process.execPath, monoCli] : null;
+const runCli = (args, o) => cp.spawnSync(cli[0], [...cli.slice(1), 'ae', ...args], o);
+const args = process.argv.slice(2);
+const opt = (k, d) => { const i = args.indexOf(`--${k}`); return i >= 0 ? args[i + 1] : d; };
+const rootOpt = opt('root', null) ? path.resolve(opt('root')) : null; // otherwise the CLI picks the inbox (PLAYRIG_ROOT, ~/Documents/Playrig/ae)
+const waitSec = Number(opt('wait', 15));
+const root = rootOpt || (cli ? cp.spawnSync(cli[0], [...cli.slice(1), 'where', 'inbox:ae'], { encoding: 'utf8' }).stdout.trim() : null);
+
+const rows = [];
+const add = (status, name, detail, fix) => rows.push({ status, name, detail, fix });
+const which = (t) => cp.spawnSync(process.platform === 'win32' ? 'where' : 'which', [t], { encoding: 'utf8' }).status === 0;
+
+// 1. Node + Playrig CLI
+const major = Number(process.versions.node.split('.')[0]);
+add(major >= 18 ? 'ok' : 'fail', 'Node.js', `v${process.versions.node}`, 'Install Node 18 or newer');
+add(cli ? 'ok' : 'fail', 'Playrig CLI', cli ? cli.join(' ') : 'playrig not found', 'Install it: npm install -g playrig');
+if (!cli) { rows.forEach((r) => console.log(`${r.status.toUpperCase().padEnd(4)} ${r.name}: ${r.detail}${r.fix ? `  -> ${r.fix}` : ''}`)); process.exit(1); }
+
+// 2. Library
+let lib = null;
+const chk = runCli(['lib', 'check'], { encoding: 'utf8' });
+const m = /(\d+) recipes checked: (\d+) errors, (\d+) warnings/.exec(chk.stdout || '');
+const libDir = cp.spawnSync(cli[0], [...cli.slice(1), 'where', 'library'], { encoding: 'utf8' }).stdout.trim();
+const idx = path.join(libDir, 'index.json');
+if (m && fs.existsSync(idx)) {
+  const j = JSON.parse(fs.readFileSync(idx, 'utf8'));
+  lib = { ready: j.filter((x) => x.status !== 'planned').length, planned: j.filter((x) => x.status === 'planned').length };
+  add(Number(m[2]) !== 0 ? 'fail' : lib.ready === 0 ? 'warn' : 'ok', 'Motion library', `${lib.ready} usable recipes, ${lib.planned} planned; lint: ${m[2]} errors, ${m[3]} warnings`, lib.ready === 0 ? 'The library is empty: add recipes with the create-ae-recipe skill, or build scenes with plain job scripts' : 'Run: playrig ae lib check, and fix the errors');
+} else add('warn', 'Motion library', 'no recipe library yet', 'Run: playrig ae lib init (creates a starter you can add recipes to)');
+
+// 3. Media tools (needed by create-ae-recipe and for contact sheets)
+const venvPy = path.join(repo, '.claude', 'skills', 'create-ae-recipe', '.venv', 'bin', 'python');
+const haveFf = which('ffmpeg') && which('ffprobe');
+const havePil = fs.existsSync(venvPy);
+add(haveFf && havePil ? 'ok' : 'warn', 'Media tools (ffmpeg + Pillow)', `ffmpeg ${haveFf ? 'yes' : 'NO'}, Pillow venv ${havePil ? 'yes' : 'NO'}`, 'Run: .claude/skills/create-ae-recipe/scripts/setup.sh (needed for contact sheets and video analysis)');
+
+// 4. Sibling skills
+const skills = ['create-ae-recipe', 'use-ae-recipes'].filter((s) => !fs.existsSync(path.join(repo, '.claude', 'skills', s, 'SKILL.md')));
+add(skills.length ? 'warn' : 'ok', 'Sibling skills', skills.length ? `missing: ${skills.join(', ')}` : 'create-ae-recipe, use-ae-recipes present', 'Restore .claude/skills/<name>/');
+
+// 5. After Effects + bridge round trip
+const id = `preflight-${Date.now().toString(36)}`;
+const jobFile = path.join(os.tmpdir(), `${id}.jsx`);
+fs.writeFileSync(jobFile, `
+var want = ["Inter-Regular", "Inter-Medium", "Inter-Bold", "Inter-ExtraBold"], fonts = {}, i, names = [], comps = 0, it;
+for (i = 0; i < want.length; i++) { try { fonts[want[i]] = app.fonts.getFontsByPostScriptName(want[i]).length > 0; } catch (e) { fonts[want[i]] = null; } }
+for (i = 1; i <= app.project.numItems; i++) { it = app.project.item(i); if (it instanceof CompItem) { comps++; if (names.length < 12) { names.push(it.name); } } }
+var active = app.project.activeItem;
+PLAYRIG.ret({ ae: String(app.version), project: { path: app.project.file ? app.project.file.fsName : null, dirty: app.project.dirty, items: app.project.numItems }, comps: comps, compNames: names, active: active instanceof CompItem ? active.name : null, fonts: fonts });
+`);
+const run = runCli(['run', jobFile, '--id', id, '--json', '--no-undo', '--timeout', '30', '--root', root], { encoding: 'utf8', timeout: waitSec * 1000 });
+let ae = null;
+if (run.status === 0 || (run.stdout && run.stdout.trim().startsWith('{'))) {
+  try { ae = JSON.parse(run.stdout); } catch (e) { /* fall through */ }
+}
+if (!ae || ae.status !== 'ok') {
+  // Never leave a stale job behind: it would run later when the panel starts.
+  for (const f of [`${id}.jsx`, `${id}.json`, `${id}.jsx.tmp`, `${id}.json.tmp`]) fs.rmSync(path.join(root, 'inbox', f), { force: true });
+  const why = ae ? `job ${ae.status}: ${ae.error && ae.error.message}` : `no answer within ${waitSec}s`;
+  add('fail', 'After Effects + Playrig for After Effects panel', why, 'Open After Effects, then Window > Playrig and press Start (status "Idle"). First time? Install the panel: playrig install ae, and enable Settings > Scripting & Expressions > "Allow Scripts to Write Files and Access Network"');
+} else {
+  const v = ae.returnValue;
+  add('ok', 'After Effects + Playrig for After Effects panel', `AE ${v.ae}, panel answering`);
+  add('ok', 'Open project', `${v.project.path || '(unsaved project)'}${v.project.dirty ? ', unsaved changes' : ''}; ${v.project.items} items, ${v.comps} comps${v.active ? `; active comp: ${v.active}` : ''}`);
+  const missing = Object.entries(v.fonts).filter(([, ok]) => ok === false).map(([n]) => n);
+  const unknown = Object.entries(v.fonts).filter(([, ok]) => ok === null).map(([n]) => n);
+  add(missing.length ? 'warn' : unknown.length ? 'warn' : 'ok', 'Fonts (Inter, the library default)',
+    missing.length ? `not installed: ${missing.join(', ')}` : unknown.length ? 'could not check this AE version' : 'Regular, Medium, Bold, ExtraBold installed',
+    'Install Inter (https://rsms.me/inter/) or choose another font per recipe with --param font=<PostScript name>');
+  rows.ae = v;
+}
+fs.rmSync(jobFile, { force: true });
+
+// Report
+const icon = { ok: 'OK  ', warn: 'WARN', fail: 'FAIL' };
+console.log('Create AE Video: preflight\n');
+for (const r of rows) {
+  console.log(`${icon[r.status]}  ${r.name}: ${r.detail}`);
+  if (r.status !== 'ok' && r.fix) console.log(`      fix: ${r.fix}`);
+}
+const fails = rows.filter((r) => r.status === 'fail').length;
+const warns = rows.filter((r) => r.status === 'warn').length;
+console.log(`\n${fails ? 'NOT READY' : warns ? 'READY WITH NOTES' : 'READY'}: ${fails} blocking, ${warns} notes`);
+if (rows.ae && rows.ae.compNames.length) console.log(`Comps already in the project: ${rows.ae.compNames.join(', ')}${rows.ae.comps > rows.ae.compNames.length ? ', ...' : ''}`);
+process.exit(fails ? 1 : 0);

package/editions/ae/skills/use-ae-recipes/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: use-ae-recipes
+description: Build After Effects scenes and videos from the user's motion library (<library>/). Picks recipes from the index, chains them with parameters, previews and tunes them with the user, and assembles scenes into a master comp. Use when the user wants to make, animate, mock up or recreate a video, scene, title, intro, transition or effect in After Effects, says "use the recipes", or asks for a look the library may already cover (kinetic typography, chips, push-in, tilt, grade, fade...).
+---
+
+# use-ae-recipes
+
+You turn a brief into finished comps inside the user's **open** After Effects project by running tested recipes from `<library>/` through the Playrig for After Effects: pick, chain, tune, assemble, show.
+
+Missing or unsuitable recipe? Switch to the **`create-ae-recipe`** skill rather than improvising a one-off. Don't render final output: that stays with the user (render queue / Media Encoder).
+
+## 0. Preflight
+
+- After Effects open, Playrig for After Effects panel started (`Idle`). If a job times out, ask the user to start it.
+- You are working in their real project. **Create new comps only**; don't touch existing comps/layers unless asked. Never save the project. Every run is one Undo step.
+- Commands are `playrig ae ...`. Helper-script paths below (`.claude/skills/...`) are relative to the project folder where the skills were installed (`playrig install skills`). `<library>` is the folder printed by `playrig where library`.
+- For frame review you'll use `.claude/skills/create-ae-recipe/scripts/media` (run its `setup.sh` once if `media check` fails).
+
+## 1. Understand the brief (≤ 3 questions)
+
+Need: **goal**, **length/format** (default 1920×1080, 24 fps), **content** (headline text, labels, brand colours, font), **tone** (light/clean vs dark/technical). Ask only what changes the build; assume the rest and say what you assumed. If the user gave a reference video, match what they show against the recipe index.
+
+## 2. Route: find recipes (progressive disclosure)
+
+1. Read **only** `<library>/INDEX.md`. Match by summary and *aliases* (users say "typewriter", "RGB split", "dolly in", "fade from black").
+2. Open the **one** recipe file you will use next (parameters, "Tweaks that matter", "Gotchas", "Combine with"). Don't read scripts. Don't open recipes you won't use.
+3. `planned` recipes can't run: tell the user it exists as an idea; offer to build it via `create-ae-recipe`, or skip/substitute.
+4. Nothing fits → say so, propose the nearest recipe + a tweak, or hand off to `create-ae-recipe`.
+
+## 3. Plan the scenes (show a short table, then go)
+
+| Scene | Time | Background | Content | Recipe chain (in order) | Out |
+|---|---|---|---|---|---|
+
+Keep it small: **one idea per scene, 1.5-4 s each**. For a single effect request, skip the table and just run the recipe.
+
+## 4. Build each scene
+
+One comp per scene, named for the user (`S1 Hook`, `S2 Proof`). The first recipe creates it (pass `width`, `height`, `duration`, `fps` there); later recipes reuse it via the same `comp` value.
+
+```bash
+playrig ae lib show <id>                                   # parameters at a glance (optional)
+playrig ae lib run <id> --param comp="S1 Hook" --param text="Ship faster" ...   # prints preview frame paths
+```
+
+- **Order inside a scene:** background → content (type, chips, elements) → camera/rigs → grade → exits/overlays. Rigs and exits act on layers that must already exist; each recipe's Gotchas say so.
+- **Look at every preview** before the next step (read the PNGs). Fix with parameters, not scripts: use the recipe's "Tweaks that matter" table to translate feedback ("snappier" → fewer `moveFrames`, "calmer" → lower `rotY`).
+- Check fonts: if a headline looks like a different typeface, the font isn't installed: ask for another or pass `--param font=<PostScript name>`.
+- Record every command you run (you'll hand them back as the scene's recipe chain). If a recipe runs more than once in a scene (two headlines), give each run its own `--instance` name.
+
+## 5. Assemble
+
+Join scenes into a master comp with a structure recipe of your own (hard cuts, or an overlap with a crossfade), or a job script. Example, if your library has one called `comp-sequence-scenes`:
+
+```bash
+playrig ae lib run comp-sequence-scenes --param comp="MAIN" --param scenes="S1 Hook|S2 Proof|S3 CTA" --param overlap=0.4 --no-snap
+```
+
+Then review the whole timeline:
+
+```bash
+playrig ae run .claude/skills/use-ae-recipes/scripts/contact-sheet.jsx --param comp=MAIN --param step=0.25 --no-undo
+.claude/skills/create-ae-recipe/scripts/media sheet "<out folder printed above>" --cols 3 --out /tmp/main.png
+```
+Read the sheet(s): check pacing, transitions, text legibility, anything cut off.
+
+## 6. Iterate with the user (edit in place: don't rebuild scenes)
+
+Show the sheet (path + what to look at), ask for concrete changes, then change **only what was asked**, from lightest to heaviest:
+
+1. **Tiny edit, no rebuild.** New words: `playrig ae run .claude/skills/use-ae-recipes/scripts/edit-text.jsx --param comp="S1 Hook" --param layer=Headline --param text="…" --no-undo` (keeps animators and position). Other small changes (a colour, a position, a timing): a short bridge job on the existing layer. Use `PLAYRIG.inspect` first to see what's there.
+2. **Change a recipe's settings: replace just its layers, in place.**
+   ```bash
+   playrig ae lib run <id> --param comp="S1 Hook" --param <changed params…> --replace              # --instance <name> if you ran it more than once
+   ```
+   Every recipe tags the layers it creates (`aeb:<recipe>:<instance>` in the layer comment). `--replace` removes only that recipe's layers and puts the new ones in the **same stacking position**; the rest of the scene is untouched. Pass **all** the params you want (it rebuilds from the defaults plus what you give).
+   - Replaced **content** (type, chips, background)? Anything that was parented to a rig recipe won't follow it until you re-run that rig with `--replace` too.
+   - Running a recipe a second time **without** `--replace` adds a separate numbered instance on purpose (two headlines, two chip groups). Name them with `--instance`.
+   - Recipes marked not replaceable (`playrig ae lib show <id>` says "edit in place: NO", e.g. a rig or an exit effect) change existing layers: follow the note it prints (usually re-run the upstream recipe with `--replace`, then this one; or Edit > Undo).
+3. **Last resort only:** rebuild a whole scene (`scripts/remove-comp.jsx`, then re-run its chain), e.g. the structure changed so much that patching makes no sense. Say so before doing it; it discards manual changes the user made in that comp.
+
+Never rebuild a scene to change a parameter. After an in-place change, re-render only the affected times to check it.
+
+## 7. Hand over
+
+Report: comps created (names, lengths), the final command chain per scene (so it can be re-run or tweaked later), the parameters most worth tweaking, assumptions made, fonts used, recipes that were missing, and that the project is **unsaved** and **not rendered**. Offer next steps (tune, add a scene, build a missing recipe with `create-ae-recipe`).
+
+## Rules of thumb
+
+- Don't invent parameters: use the names in the recipe's frontmatter (`playrig ae lib show` lists them; unknown ones are rejected).
+- Respect each recipe's notes: a recipe written for light backgrounds must not be used on dark scenes.
+- Don't claim a scene works from "status ok": look at frames at start, mid and end of each move.
+- Keep it incremental: build and show one scene, get a reaction, then continue.
+- If something fails, read the printed error (line + source), fix the parameters or the order; don't retry blindly.
+
+## References
+
+- `scripts/contact-sheet.jsx` (review), `scripts/edit-text.jsx` (change words in place), `scripts/remove-comp.jsx` (last-resort rebuild).
+- `<library>/INDEX.md`, `<library>/README.md`: the library and its conventions.

package/editions/ae/skills/use-ae-recipes/scripts/contact-sheet.jsx

@@ -0,0 +1,10 @@
+// Renders frames of a comp at regular steps (use with: playrig ae run contact-sheet.jsx --param comp=NAME --param start=0 --param end=3 --param step=0.25)
+// Then tile them: .claude/skills/create-ae-recipe/scripts/media sheet <out folder printed by aeb>
+if (typeof P === "undefined" || !P.comp) { throw new Error("Pass --param comp=<comp name> (optional: start, end, step in seconds)"); }
+var c = PLAYRIG.comp(P.comp);
+var s = P.start === undefined ? 0 : Number(P.start);
+var e = P.end === undefined ? c.duration - 1 / c.frameRate : Number(P.end);
+var st = P.step === undefined ? 0.25 : Number(P.step);
+if (!(st > 0)) { throw new Error("step must be > 0"); }
+PLAYRIG.contactSheet(P.comp, s, e, st);
+PLAYRIG.log("queued frames of " + P.comp + " from " + s + "s to " + e + "s every " + st + "s");

package/editions/ae/skills/use-ae-recipes/scripts/edit-text.jsx

@@ -0,0 +1,12 @@
+// Changes the words of an existing text layer IN PLACE (keeps its animators, keys, position, stacking):
+//   playrig ae run edit-text.jsx --param comp="S1 Hook" --param layer="Headline" --param text="New words" --no-undo
+// Per-word styling (e.g. a bold keyword) may need re-applying; for that, re-run the recipe with --replace instead.
+if (typeof P === "undefined" || !P.comp || !P.layer || P.text === undefined) { throw new Error("Pass --param comp=… --param layer=… --param text=…"); }
+var c = PLAYRIG.comp(P.comp), i, l = null;
+for (i = 1; i <= c.numLayers; i++) { if (c.layer(i).name === P.layer) { l = c.layer(i); break; } }
+if (!l) { throw new Error("No layer \"" + P.layer + "\" in " + P.comp); }
+if (!(l instanceof TextLayer)) { throw new Error("\"" + P.layer + "\" is not a text layer"); }
+var prop = l.property("ADBE Text Properties").property("ADBE Text Document"), doc = prop.value, old = doc.text;
+doc.text = P.text;
+prop.setValue(doc);
+PLAYRIG.log("\"" + old + "\" -> \"" + P.text + "\" on " + P.layer + " (animators kept: " + l.property("ADBE Text Properties").property("ADBE Text Animators").numProperties + ")");

package/editions/ae/skills/use-ae-recipes/scripts/remove-comp.jsx

@@ -0,0 +1,18 @@
+// Removes a comp and the solids it used if nothing else uses them (use with: playrig ae run remove-comp.jsx --param name=NAME).
+// For rebuilding a scene with different settings. Refuses if the comp is used inside another comp.
+if (typeof P === "undefined" || !P.name) { throw new Error("Pass --param name=<comp name>"); }
+var c = PLAYRIG.comp(P.name), i, l, solids = [], n = 0, it;
+if (c.usedIn.length > 0) { throw new Error("\"" + P.name + "\" is used in " + c.usedIn.length + " other comp(s); remove those layers first"); }
+for (i = 1; i <= c.numLayers; i++) {
+    l = c.layer(i);
+    if (l.source && l.source instanceof FootageItem && l.source.mainSource instanceof SolidSource) { solids.push(l.source); }
+}
+c.remove();
+var folders = [];
+for (i = 0; i < solids.length; i++) {
+    try { var pf = solids[i].parentFolder; if (solids[i].usedIn.length === 0) { solids[i].remove(); n++; folders.push(pf); } } catch (e) { }
+}
+for (i = 0; i < folders.length; i++) { // drop folders this left empty (never the project root)
+    try { if (folders[i] !== app.project.rootFolder && folders[i].numItems === 0) { folders[i].remove(); } } catch (e2) { }
+}
+PLAYRIG.log("removed comp \"" + P.name + "\" and " + n + " unused solid(s)");

package/editions/pr/README.md

@@ -0,0 +1,60 @@
+# Playrig for Premiere Pro (UXP) — v0.1 spike
+
+Same folder protocol as the After Effects edition (`inbox/ running/ done/ out/<id>/result.json`), driven by a UXP panel in Premiere Pro 25.6+.
+Jobs are **modern JavaScript** (async function bodies; `await` works) receiving `PLAYRIG` (`BRIDGE` is an alias), `ppro` (the `premierepro` module), `alert`, `confirm`.
+
+## Install
+`playrig install pr` builds `Playrig (PR).ccx` (a zip of `plugin/` without the dev-only `dev.js`) and opens it with the Creative Cloud installer. For development: Adobe UXP Developer Tool > Add Plugin > select `plugin/manifest.json` > Load.
+Then in Premiere: Window > Extensions > Playrig. Pick a folder (default `~/Documents/Playrig/pr`; an existing `~/Documents/Premiere Bridge` is used until the new one exists), press Start, and run `playrig pr run examples/hello.js`.
+
+## Panel
+Main screen: project name under the title; status dot, a **power icon** (grey = stopped, green = running; click to start/stop) and a **settings gear** at the top right; an **Organize Project** button; and the **Recent jobs** table.
+
+**Recent jobs** is per project: it lists the jobs of the project that is open, read from `<project>/EDIT_LOGS/results/`, and reloads when you switch projects (so another project's history never shows up, and a project's history travels with it). Columns: status (icon + word: ok, error, rejected, timeout), **action** (a human-readable label from the defined list in `plugin/actions.js`, e.g. "Duplicate sequence", "Adjust audio levels", "Organize project"), time (DD-MM-YY HH:MM). A job declares its action with a `// @action <id>` header or `aeb --action`; otherwise it is inferred from the script (shown as "inferred"). Hover a row for a tooltip of what the job did (its description line, or the action's summary, plus result, duration, error, frames filed); click it for the full detail window: description, id, start/duration, project, Premiere version, error with line and source, log, exported frames, filed items, return value, the script itself and the file paths. Up to the latest 50 are shown, newest first. Jobs run in an unsaved project appear for this session only.
+
+Browse closes the Settings window while the native folder picker is open (a picker cannot be used on top of a modal window) and reopens it afterwards. The Settings window has three sections: **General** (bridge folder as an editable field: type or paste a full path and press Enter, or Browse; Start automatically; Back up), **Organization** (Keep organized, Edit structure) and **About** (version, developer, copyright, Twitter/Instagram links, icon credit). Version comes from `manifest.json` (`0.1.0`, shown as "preview").
+
+Edit structure uses `uxp.shell.openPath`, which needs the `launchProcess` permission in `manifest.json` (`schemes: ["https"]` for the About links, `extensions: [".json", ""]` for the structure file and folders). Premiere asks for consent the first time. If opening fails the panel shows the path.
+
+## Project-folder log
+Every job is mirrored into `<project folder>/EDIT_LOGS/` (`JOURNAL.md`, `jobs/`, `results/`, `assets.md/.json`), same idea as the AE bridge. `<project folder>` is the folder containing the open `.prproj` (e.g. `0_PROJECT`). Media paths are listed absolute and relative to that folder, flagged OFFLINE if missing.
+
+## Incremental editing (same idea as the AE bridge's `--replace`)
+Jobs should change what they own, not rebuild. The bridge tags clips it creates with a name suffix `[pb:<family>:<key>]` and `PLAYRIG.sync(seq, family, desired)` moves, swaps, adds or removes **only those clips** to match a desired list; re-running it is a no-op. `PLAYRIG.adopt` brings existing untagged clips under management once. Level helpers: `setLevelDb`, `levelKeys` (timeline seconds in, source time handled for you). `sync` computes the final layout first and refuses (changing nothing) if a clip would overwrite another. See `CLAUDE.md` for the full API and the Premiere rules.
+
+`playrig pr scratch start | status | clean --yes` records the project's sequences and items, and later deletes exactly what was added (clones, test imports). Files on disk are never touched.
+
+Code: `plugin/incremental.js` (loaded before `index.js`); client commands in `client/aeb.js`.
+
+## Project organization
+Keeps the project panel in a fixed bin scheme (1_MASTER, 2_FOOTAGE/{IMAGES,RAW,RENDERS,GRADED}, 3_SELECTS, 5_SOUND, 6_MUSIC, 7_LAYERS, 99_ARCHIVE). The scheme is **data**: `organize.default.json` is the template; a copy in `<project>/EDIT_LOGS/organize.json` (per project) or `<bridge folder>/organize.json` (personal default) overrides it. Edit bin names, what they mean, and the ordered rules (by item kind, name, file path, extension). The panel has:
+- **Keep the project organized** (checkbox): after every job, files new loose items. Never moves items already in a bin.
+- **Organize Project** (button): the full pass for a project that has drifted. Creates missing bins, files loose items, corrects items in the wrong scheme bin; one undo step; leaves your own bins and the archive alone.
+- **Edit structure** (button): writes the effective structure to the project's `EDIT_LOGS/organize.json` if there is none, and opens it.
+
+Code: `plugin/organize.js`.
+
+## Dev-only parts
+`plugin/dev.js` holds developer-only panel features (currently the job script in the job details window). Packaged builds leave that file out; see `DEV_ONLY.md`.
+
+## Updates
+Settings > About > **Check for Updates** reads the public feed (`updates/versions.json` on GitHub; the manifest declares the `network` permission for `raw.githubusercontent.com`), compares versions and links to the release. It also checks once a day (switch off with "Check for updates automatically") and shows a banner when a newer version exists. A UXP panel can't replace its own files: if you installed it from Adobe's marketplace, Creative Cloud updates it; otherwise download the new `.ccx` (or run `playrig update pr`, which verifies and opens it).
+
+## Security
+Anything that can write to `<root>/inbox` can run code in Premiere with full file access (`localFileSystem: fullAccess`). Use a private folder. Off until you press Start.
+
+## Verified on Premiere Pro 26.5.2 (macOS, 2026-10-02)
+Plugin loads via UDT; jobs run (`new AsyncFunction` works); `alert`/log capture; error path reports message, line and source line; `getSequences()`, `sequence.name`, `project.path/name`, `getVideoTrackCount()`, `getEndTime().seconds`, `getVideoTrack(i).getTrackItems(1,false)`, `clip.getName()/getStartTime()`; `Exporter.exportSequenceFrame` writes correct, time-dependent PNGs at the sequence's own frame size; `EDIT_LOGS/` (journal, jobs, results incl. PNGs) is written next to the `.prproj`.
+Note: an empty sequence exports black frames; that is correct, not a failure.
+
+## Still UNVERIFIED
+`PLAYRIG.transact` (one undo step per job), the unsaved-project backfill, rejection of badly named files, timeout behaviour. `PLAYRIG.inspect` is minimal (sequence names only). No asset manifest yet.
+
+## Differences from the AE bridge
+Timeouts are real (Promise.race) but the job is not cancelled. Undo grouping is explicit via `PLAYRIG.transact`, not automatic. Snapshots/inspect use `--snap "<sequence>@t"` / sequence names.
+
+## Skills (ship with the bridge)
+`skills/` holds the Claude Code skills that drive this bridge. Install into a project with `playrig install skills`.
+- **create-video**: end-to-end video workflow across After Effects, Premiere and sound, with the user's project layout, naming, interaction rules and gotchas (`SKILL.md`, `references/project-conventions.md`, `references/lessons.md`, job templates in `scripts/`).
+- **score-video**: music bed + SFX from Epidemic Sound, ducked and placed in Premiere (`scripts/mix.py`, `scripts/place.js`).
+The canonical copies are in `skills/`; edit there and re-run the installer.

package/editions/pr/SCORE_PROCESS.md

@@ -0,0 +1,41 @@
+# Adding a music score to Premiere sequences (draft process, for a future skill)
+
+Worked once on "Quadrant Chips Wide/Portrait" (7 s motion pieces). Epidemic Sound MCP + Playrig for Premiere Pro.
+
+## Steps
+1. **Read the timeline, not just the brief.** Get each sequence's length, frame size and the moments that carry rhythm (here: chip pops every 0.6 s starting 2.6 s). Derive a music brief from them:
+   - mood from the visual style (dark, technical, minimal) -> mood/genre tags
+   - **BPM from the motion cadence**: beat = 60/BPM, so 0.6 s between events = 100 BPM. Search a +-2 BPM window so hits can land on beats.
+   - instrumental only (`vocals: false`) for motion/explainer pieces.
+2. **Search** `SearchRecordings` (term + `bpm`, `vocals:false`, `first` ~8). Results skew pop; judge by tags (mood, genre) and pick one. Say why in one line. Playing the `lqmp3Url` preview is the only way to judge by ear; ask the user if the taste call is risky.
+3. **Fit the length with `EditRecording`**: `targetDurationMs` = sequence length, `forceDuration: true`, `downloadAudioFormat: WAV`, `maxResults: 1`, `skipStems: true`. It returns a version with a real ending (no hard cut). Poll `PollEditRecordingJob` until COMPLETED (was instant for 7 s), then `DownloadRecordingEdit` (needs `jobId` + `editId`).
+   - Tracks longer than ~5 min can't be edited; use a fade out instead.
+4. **Download into the project's music folder** (`3_MUSIC` here) with `curl -L`. The signed URL expires, so download immediately. Verify with `ffprobe` (duration) and `ffmpeg -af ebur128` (loudness ~ -14 to -16 LUFS is fine for music-only).
+5. **Place in Premiere** (job, modern JS):
+   - `p.importFiles([path], true, rootItem, false)`, then find the item by name in `root.getItems()`.
+   - `ppro.SequenceEditor.getEditor(seq).createOverwriteItemAction(item, TickTime.createWithSeconds(0), 0, 0)` (video track 0, audio track 0 = A1), added inside `p.lockedAccess(() => p.executeTransaction(ca => ca.addAction(...), "label"))` so it is one undo step.
+   - Verify: `seq.getAudioTrack(0).getTrackItems(1,false)` -> name, start, end.
+6. **Report**: track, artist, BPM, why chosen, file path, and that the project is unsaved.
+
+## Gotchas
+- Never save the Premiere project for the user. The bridge backs up the saved `.prproj` before each job.
+- Sequences made from an AE render already have 3 audio tracks; A1 was empty (the mp4 has no audio).
+- Premiere imports go to the project root unless a target bin is passed.
+
+## Open questions for the skill
+- How to audition tracks (we only have preview URLs).
+- Ducking/levels once SFX or voiceover exist.
+- Whether to put the music in a bin and label the track.
+
+## Sound effects + making the music work with them (done on the same piece)
+7. **Map events to sounds** from the motion plan: grid/axes growing -> one tech whoosh at 0 s; typewriter labels -> a tick bed; each chip pop -> a UI pop at its pop time (2.6, 3.2, 3.8, 4.4, 5.0 s). Skip sounds for minor moves; restraint beats wall-to-wall SFX.
+8. **Search** `SearchSoundEffects` (`duration` filter keeps results short). Download WAV into the project's sound folder (`2_SOUND/SFX`). Signed URLs expire; copy them exactly, a mistyped signature gives 401.
+9. **Inspect each SFX before using it.** The "typewriter letter button" file had its loud strike at 0.40 s, not at the start; trimming 0..0.11 s gave an almost silent tick. Look at a 20 ms RMS profile and cut around the real transient.
+10. **Build the typing bed in ffmpeg** (one tick per 2 characters at the label start times, alternating -8/-10 dB, 2.2 s long) instead of dozens of clips.
+11. **Level the SFX**: pops about -7 dBFS peak, whoosh about -11, ticks about -22. Bake the gain into `_lv` copies.
+12. **Music works with SFX = lower and duck, not beat-match.** The edit's beat phase came out different per frequency band (0.26 s vs 0.42 s), so a syncopated groove cannot be reliably locked to the pops. Instead: music -3 dB, then `sidechaincompress` keyed by a mix of all SFX at their timeline times (`threshold=0.02 ratio=3 attack=8 release=300 level_sc=0.25`) -> about -6.5 dB under pops, -1.5 dB under the whoosh/ticks, 0 dB between. Measure the dip (100 ms RMS, ducked vs original) and iterate; first settings dipped -17 dB.
+13. `sidechaincompress` drops the tail (7.0 -> 6.91 s): add `apad=whole_dur=N,atrim=0:N`.
+14. **Place in Premiere**: music A1, whoosh A2 @0, typing bed A3 @0, pops alternate A2/A3 (they are 0.66 s long on a 0.6 s cadence, so same-track overwrite would clip the previous tail). Premiere snaps to the frame (2.6 s -> 2.58 s at 24 fps), about 17 ms early, inaudible.
+15. Overwriting a longer clip with a shorter one leaves a remnant of the old clip; always check `getTrackItems` afterwards. Remove unused intermediates with `root.createRemoveItemAction(item)` inside `executeTransaction`.
+
+Still unverified: how it sounds (no audition path), clip-level gain/ducking via the Premiere API (we baked it into the files instead, so levels are not adjustable per clip in Premiere).

package/editions/pr/client/aeb.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+'use strict';
+// Deprecated: `aeb` is now `playrig pr <command>`. Kept so old commands and scripts keep working; it prints a notice and forwards.
+const fs = require('fs');
+const path = require('path');
+const candidates = [path.join(__dirname, '..', '..', 'cli', 'lib', 'main.js'), path.join(__dirname, '..', '..', '..', 'lib', 'main.js')];
+const main = candidates.find((f) => fs.existsSync(f));
+if (!main) { console.error('aeb is deprecated and could not find the playrig CLI. Install it: npm install -g playrig'); process.exit(2); }
+require(main).legacy('pr', process.argv.slice(2));

package/editions/pr/examples/frame.js

@@ -0,0 +1,6 @@
+// @action project.inspect
+// Lists the sequences; frames requested with --snap are exported after the job.
+// Usage: playrig pr run examples/frame.js --snap "My Sequence@0,1"
+// Frames requested with --snap are exported after the job ends.
+const seqs = await PLAYRIG.project.getSequences();
+PLAYRIG.log("sequences: " + seqs.map((s) => s.name).join(", "));

package/editions/pr/examples/hello.js

@@ -0,0 +1,4 @@
+// @action bridge.test
+// Checks that Playrig can run a job and lists the project's sequences.
+PLAYRIG.log("hi from Premiere");
+PLAYRIG.log(await PLAYRIG.inspect());