@vfrey/vfrey 0.0.1 → 1.0.0-beta.1

package/integration-tools/video/remotion.md

@@ -0,0 +1,50 @@
+# Remotion
+
+React components become frames. The frame number is the clock. A coding agent writes the component, then renders an MP4 or a PNG on this machine.
+
+License: source is public. Free for an individual and for a for-profit organization of up to 3 employees. A larger company needs a company license. See `LICENSE.md` in `remotion-dev/remotion`.
+
+This repo already depends on Remotion 4. The project entry is `src/remotion/index.ts`. The render port in `remotion.config.ts` is 4123. Do not render on 3000, 3001, or 3012. Those are other local apps.
+
+## Use it when
+
+The picture is a designed composition: type, SVG, captions, a product shot built in code. This is the default for a short in this repo.
+
+## Do not use it when
+
+You only need to join two files, or you only need to draw one PNG with no timeline. Use FFmpeg or an image tool.
+
+## Example
+
+```tsx
+import { AbsoluteFill, useCurrentFrame } from "remotion";
+
+export const Hello = () => {
+  const frame = useCurrentFrame();
+  const shown = Math.min(1, frame / 20);
+  return (
+    <AbsoluteFill style={{ background: "#0f1115", color: "#f6f3ec", opacity: shown }}>
+      <h1 style={{ fontSize: 120, margin: 80 }}>Hello</h1>
+    </AbsoluteFill>
+  );
+};
+```
+
+Register it in `src/remotion/Root.tsx` as a `Composition` at 1080x1920 and 30fps, then render from the pipeline directory:
+
+```bash
+npx remotion render src/remotion/index.ts Hello out/hello.mp4 --port=4123
+```
+
+A still, one frame:
+
+```bash
+npx remotion still src/remotion/index.ts Hello out/hello.png --frame=30 --port=4123
+```
+
+## Agent notes
+
+- Drive motion from `useCurrentFrame`. Do not use CSS transitions. They do not seek.
+- Do not set `durationInFrames` on `<Audio>`. That trims the file.
+- Do not import `@vfrey/contracts` from a composition. The barrel pulls in `node:crypto`, and the bundle cannot resolve it. `src/render/webpack.ts` stubs that scheme for the worker render.
+- `out/` is gitignored. The MP4 stays on the machine that rendered it.

package/integration-tools/video/revideo.md

@@ -0,0 +1,32 @@
+# Revideo
+
+TypeScript scenes, rendered by a Node process you run. The authoring style is the generator style: a scene adds nodes, then yields animations. There is no hosted render in the path this file describes.
+
+License: check `redotvideo/revideo` before you ship. Treat the local CLI as the renderer.
+
+## Use it when
+
+You want a TypeScript video that renders inside a server or a script you control, and you are not already inside this repo's Remotion project.
+
+## Do not use it when
+
+The job is a composition in `src/remotion/`. Do not start a second video stack for that.
+
+## Example
+
+```tsx
+import {makeScene2D, Txt} from "@revideo/2d";
+
+export default makeScene2D(function* (view) {
+  const title = new Txt({text: "Hello", fill: "#f6f3ec", fontSize: 120});
+  view.add(title);
+  yield* title.scale(1.2, 0.6);
+});
+```
+
+Render with the CLI the Revideo project documents after you install it. Read that project's `package.json` scripts. Do not guess a cloud URL.
+
+## Agent notes
+
+- Keep the scene file, the project file, and the output path in the repo you are editing.
+- If the CLI name differs from the docs you remember, the installed package wins. Read it.

package/package.json

@@ -1,10 +1,78 @@
 {
   "name": "@vfrey/vfrey",
-  "version": "0.0.1",
-  "description": "vfrey: make short vertical videos by asking your own coding agent. Not released on npm yet; see https://vfrey.vercel.app",
-  "homepage": "https://vfrey.vercel.app",
+  "version": "1.0.0-beta.1",
+  "type": "module",
+  "description": "vfrey worker. Generate, render, publish, engage, and collect metrics.",
   "license": "SEE LICENSE IN LICENSE",
-  "bin": { "vfrey": "bin/index.js" },
-  "files": ["bin", "README.md", "LICENSE"],
-  "engines": { "node": ">=22.13" }
+  "bin": {
+    "vfrey": "./bin/vfrey.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "vendor",
+    "integration-tools",
+    "accounts.example.json",
+    "accounts.first-run.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "scripts": {
+    "vfrey": "node bin/vfrey.mjs"
+  },
+  "dependencies": {
+    "@vfrey/contracts": "file:vendor/@vfrey/contracts",
+    "@vfrey/ingest": "file:vendor/@vfrey/ingest",
+    "@hono/node-server": "2.1.5",
+    "@puppeteer/browsers": "3.2.6",
+    "@remotion/bundler": "4.0.537",
+    "@remotion/renderer": "4.0.537",
+    "acorn": "8.19.0",
+    "adm-zip": "0.6.1",
+    "citty": "0.2.2",
+    "compare-versions": "6.1.1",
+    "css-tree": "3.2.1",
+    "debug": "4.4.3",
+    "esbuild": "0.28.2",
+    "fontkit": "2.0.4",
+    "giget": "3.3.1",
+    "hono": "4.13.14",
+    "ignore": "5.3.2",
+    "open": "10.2.0",
+    "postcss": "8.5.31",
+    "puppeteer-core": "25.16.0",
+    "react": "19.0.0",
+    "react-dom": "19.0.0",
+    "remotion": "4.0.537",
+    "tsx": "4.19.3",
+    "yauzl": "3.4.0"
+  },
+  "optionalDependencies": {
+    "@esbuild/linux-x64": "0.28.2",
+    "@remotion/compositor-linux-x64-gnu": "4.0.537",
+    "@rollup/rollup-linux-x64-gnu": "4.64.12",
+    "@rspack/binding-linux-x64-gnu": "1.7.11"
+  },
+  "overrides": {
+    "zod": "4.6.6"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "homepage": "https://vfrey.vercel.app",
+  "keywords": [
+    "vfrey",
+    "video",
+    "shorts",
+    "youtube",
+    "remotion",
+    "ai-agent",
+    "claude-code",
+    "automation"
+  ]
 }

package/skills/vfrey-orchestrator/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: vfrey-orchestrator
+description: Operate this repo from a coding-agent session. Read the desk, run ticks, and report what the pipeline did.
+---
+
+The pipeline writes the video package itself, through the configured model. Your job is to run it, read what happened, and report it.
+
+1. Read `docs/ARCHITECTURE.md`. It describes what runs today.
+2. Read the desk with `npx vfrey desk snapshot --json`. Each series carries its `cadence` and `paused` fields. `mode` is the stored orchestrator setting (`vfrey desk mode set` writes it). The pipeline does not wait on it today.
+3. Run `npx vfrey tick` to make a video for every due series. A series is due only when it is not paused and the cadence allows it. Add `--series <id>` for one series. Add `--now` when the person asked for a video now. A paused series is never run.
+4. Quality and compliance checks run inside the pipeline. A `rejected` job failed a quality gate. A `blocked` job failed a compliance rule. Neither retries. Report the job's timeline from the snapshot and say which check stopped it.
+5. Disclosure is always on. A package that is not marked synthetic is `blocked`.
+6. Publish happens inside `tick`, and only with the operator's own platform keys. With no key, publish skips with `missing_key`.
+7. Do not call platform APIs yourself. Do not print secrets.
+8. Channel video design lives in `channel-style/<seriesId>/STYLE.md`. Read it when a person asks about a channel's look. See `skills/vfrey-orchestrator/channel-video/SKILL.md`.

package/skills/vfrey-orchestrator/channel-video/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: channel-video
+description: Produce one JSON content package for a single channel from its STYLE.md. Do not publish or review.
+---
+
+The subagent reads this before producing a package. Return one JSON object and no other files. Do not claim the review passed. The orchestrator reviews.
+
+1. Read only the one `STYLE.md` path in the prompt. Do not read other `channel-style/` folders.
+2. The engine is Remotion. HyperFrames is unavailable here. If the `remotion-best-practices` skill is installed, read it before you change a template.
+3. The pipeline picks the template, pacing, caption style, palette, hook pattern, and voice in code, and rotates them between videos. `STYLE.md` describes the channel's voice and limits. It does not pin a template.
+4. Return one JSON object and no other files. This is the shape the pipeline writes:
+
+```json
+{
+  "synthetic": true,
+  "candidate": {},
+  "plan": {},
+  "title": "",
+  "hook": "",
+  "beats": [],
+  "caption": "",
+  "description": "",
+  "hashtags": [],
+  "thumbnailPrompt": "",
+  "imagePrompts": [],
+  "voiceoverScript": "",
+  "durationSec": 0,
+  "assets": [],
+  "svg": []
+}
+```
+
+`candidate` matches `Candidate` in `@vfrey/contracts` (`types`): `fingerprint`, `provider`, `title`, `url`, `excerpt`, `publishedAt`. Use the source candidate from the prompt.
+
+`plan` fields match `VariationPlan`: `templateId`, `pacing`, `captionStyle`, `paletteId`, `hookPattern`, `structure`, `hashtagStrategy`, `durationTargetSec`, `durationBucket`, `voiceId`, `coverTimestampMs`, `layoutSeed`. Take `templateId`, `pacing`, `captionStyle`, and `paletteId` from `STYLE.md`. `hookPattern` is `question`, `contrarian`, `story`, `statistic`, or `cold-open`. `structure` is `list`, `narrative`, `debate`, or `breakdown`. `hashtagStrategy` is `niche-first`, `question-led`, or `plain-language`. `durationBucket` for a 16 to 24 second video is `short`.
+
+`beats` match `Beat`: `{ "role", "text", "caption", "seconds" }`. `role` is `hook`, `setup`, `turn`, `evidence`, `payoff`, or `cta`.
+
+`svg` is a list of SVG document strings, one per beat, or an empty list when the template is pure Remotion props. `assets` is `{ "name", "url" }[]`. `assets[].url` is `https` or the list is empty. `synthetic` is `true`.
+
+5. Do not publish, do not read other `channel-style/` folders, and do not claim the review passed.

package/skills/vfrey-product/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: vfrey-product
+description: Help the person make videos with vfrey. Use when they ask for a video, a short, an edit, a render, to see their videos or the dashboard, or a push to YouTube or another platform. The person does not need to know the commands.
+---
+
+# vfrey
+
+The person asks in plain language; you run `npx vfrey`. Everything lives in a project folder (it has a `vfrey.json`).
+
+## Find the project
+
+1. Look for `vfrey.json` in this folder or any folder above. Found: work there (`cd` to it). Read its `AGENTS.md` if you have not.
+2. Not in a project and they want a video: ask where it should live (suggest `./vfrey`, or a name for their channel). Then `npm create vfrey@latest <dir>` (beta: `@beta`; `npx create-vfrey <dir>` is the same) and `cd <dir>`. If they want the current folder: `npx @vfrey/vfrey init`. Never run `npx vfrey` or `npm i vfrey` outside a project. Both are safe to repeat.
+3. They have old videos in `~/.vfrey`: `npx vfrey init --from ~/.vfrey` imports them (the source is not changed).
+4. `npx vfrey doctor` checks the machine; it exits 1 with a `Fix:` line when something is wrong. Relay the fix.
+5. Skill not loaded in this agent: `npx vfrey skill install --agent <claude|codex|grok|cursor|gemini|all>` (restart Claude Code and Cursor; Gemini: `/skills reload`).
+
+## Plain words to commands
+
+- "show me", "open the dashboard", "where is my video": `npx vfrey open [run id | video title or path]` (reuses the project's dashboard or starts it, prints the URL; `--no-browser` only prints). Never start the dashboard any other way.
+- "my videos": `npx vfrey videos` (newest first, with paths); "my other projects": `npx vfrey projects`.
+- "what should I make", "trending in X": `npx vfrey topics --niche X` (ids: `topics niches`, free); cite the evidence, then `tick --now --about "<title>"`. Topics need an account and credits (`login`, `whoami`); a `✗`/`Fix:` says which is missing. "find creators / KOLs in X": `creators search --niche X` (Research plan). Outreach: draft with `npx vfrey mail draft`; NEVER approve or send unless the person says so for that specific draft; mail needs the Mail add-on.
+- "sign in", "my plan": `npx vfrey login` (prints a link and a code to relay) or `npx vfrey whoami`. Free features never need an account. Team sync: `npx vfrey cloud link|push [--videos]|pull|status` (newest wins; the other copy is kept as `<file>.conflict-<time>`).
+- Old machine data, update, engines: `npx vfrey desk snapshot --json`, `npx vfrey update`, `npx vfrey engine list`. A run with `status: awaiting_review` waits for the person (series review on): tell them, then `npx vfrey desk job approve|reject --id <id> [--reason T]`. `npx vfrey --help` and `npx vfrey <command> --help` list the rest.
+
+## Make a video
+
+You are the writer and the designer. vfrey has no model of its own; without your script the words are template filler, and without your scene the picture is a plain fallback.
+
+1. **Script.** Write `scripts/<idea>.json`: `{ "title", "hook", "lines": [...], "hashtags": [...] }` (`npx vfrey tick --script-template` prints one). 6 to 10 short spoken lines (4 to 12 allowed, at most 220 characters each), hook first, title at most 100 characters, 1 to 8 hashtags starting with `#`. Be accurate and plain: no invented statistics, numbers, quotes or sources; leave out what you are not sure of. Use the topic's key words (the quality check rejects a script that never mentions its subject). A bad file gets a `✗` line and a `Fix:` line; a rejected script prints its reason. Fix and rerun.
+2. **Scene.** Always design a scene for the idea (scene init, design, `--frame` preview, then tick with `--scene` and `--engine`). Use the default template only if the person explicitly asks for a quick text-only video, and say so. Every idea gets its own picture ("what's the difference?", "3 facts", "how a mutex works" look different). There are no fixed templates: never reuse one scene for a new idea.
+   - `npx vfrey scene init scenes/<idea>` writes a commented starter (`index.html`; `--engine remotion` writes `index.tsx`). Replace it. Draw SVGs yourself and `<img>` them from the folder.
+   - `index.html` renders with `vfrey-framey` (or `hyperframes`), `index.tsx` with `remotion`; a mismatch stops with a `Fix:` line. Always pass `--engine` with a scene.
+   - vfrey supplies in `DIR/vfrey/` (rewritten at render, do not edit): `timing.json`, `voice.wav`, `vfrey.js`, local `gsap.min.js`, `fonts/fonts.css` (Titan One, JetBrains Mono, Google Sans Flex), `assets/` (stick figures `stick-*.svg`, glyphs `glyph-*.svg`).
+   - Timing: `vfrey.timing` (HTML) or `useTiming()` (Remotion): `durationSec`, `words[{i,text,start,end,line}]`, `lines[...]`, `beats[...]`, in seconds. The film is voice length plus 0.3 s, 1080x1920, 30 fps.
+   - HTML: `<link rel="stylesheet" href="vfrey/fonts/fonts.css">`, `<script src="vfrey/gsap.min.js">`, `<script src="vfrey/vfrey.js">`; `const tl = vfrey.timeline()` (the one paused GSAP timeline); `vfrey.captions("#el", {style})` (`box`, `color`, `underline`, `pop`, `plain`; also `size`, `color`, `highlight`, `font`, `maxWords`, `align`); `vfrey.at(t, fn)`, `vfrey.onWord(i, fn)`, `vfrey.onLine(i, fn)`, `vfrey.line(i)`. Everything visible must be a function of timeline time (no `Date.now`, no unseeded random).
+   - Remotion: `import { useTiming, useTime, Captions, AtLine } from "@vfrey/scene"`; `export default function Scene()`.
+   - vfrey burns the `AI-GENERATED` label on top after render; nothing can hide it. The network is blocked while rendering (no CDNs). A scene folder is at most 50 MB.
+   - Before designing, read `scenes/craft.md` next to this file (layout, type, safe areas, motion, pacing); `scenes/motion.md` has GSAP recipes.
+   - Two worked examples are in `examples/` next to this file (`concurrency-vs-parallelism/`, `octopus-facts/`). Read one, then design for the idea in front of you; do not copy.
+   - Preview: `npx vfrey render --scene scenes/<idea> --engine vfrey-framey --script scripts/<idea>.json --frame 2.5 out.png` (silent, label on). Open it, fix the layout, check a second moment (`--frame 9`).
+3. **Quality checks.** vfrey reviews every video before and after the render. Read the Checks list on the run page or `checks` in `npx vfrey tick --json`; each check has an id and a Fix line. Do the Fix; never work around a check. Limits: spoken length 6-75 s at about 2.6 words per second; rendered file 1080x1920, not black, not frozen. A dry run skips the after-render checks.
+   - Quality failures (copy, pace, scene, frames) reject the job; vfrey re-renders once when a render can change the result. Otherwise fix the named problem and rerun.
+   - Compliance failures (banned claims, missing disclosure, missing AI label) block the job and are never retried. Fix the content.
+4. **Scene blocks.** Ready-made pieces (lower thirds, charts, code, chat cards, overlays, backgrounds, transitions) to restyle, not templates; one or two per short at most.
+   - `npx vfrey scene blocks [--category X]` lists them; `npx vfrey scene add BLOCK scenes/<idea>` copies one into the scene and prints the snippet to paste into `#root`.
+   - Time it with `vfrey.block("#block-<name>", t)` inside `vfrey.onLine` or `vfrey.at`; mount each block once per scene; HTML scenes only. Placement, fit modes and restyling are in `scenes/blocks.md`.
+5. **Make it.** `npx vfrey tick --now --about "<subject>" --script scripts/<idea>.json --scene scenes/<idea> --engine vfrey-framey`. Subject goes in `--about` (no feed is read; it runs as its own job). Without `--about` the default series reads the Federal Reserve feed: say so and ask once for a topic. Leave `--script` out only if they say to let vfrey write it, and then say the words are generic. Never set `--dry-run` for a real video (it skips the file). `render --subject` is only a silent, untracked preview.
+6. **Tell them.** The summary has `✓ Video ready: <path>` (length and size from ffprobe: quote them), the transcript, the upload outcome, and `See it: http://127.0.0.1:<port>/runs/<id>`. That link is live because the tick starts the dashboard: relay it and the readable video path in `videos/` as they are, without hedging. Only if `curl` to it fails, run `npx vfrey open`. Say `Scene: agent-written`; with the default template say so. `--json` has `{processed, jobs:[{id, series, status, mp4, transcript, durationSec, publish, engage, runUrl, scene, engine}]}`. Nothing made: the summary says why (`not due`, `paused`, `job <id> in progress` with its `npx vfrey desk job cancel --id <id>` fix). Never move or rename videos by hand; vfrey tracks the paths.
+
+Voice is on (macOS `say`; `TTS_PROVIDER=openai` is the paid voice, `none` is silent). A machine without it stops with a `Fix:` line. No model key is needed. To check a dashboard link is live: `curl -s -o /dev/null -w "%{http_code}" <url>` expects `200`.
+
+## Engines
+
+The person chooses. `npx vfrey engine list` shows ready or unavailable with reasons; `npx vfrey engine use <id>` sets the machine default (Remotion until then). When they name one, pass `--engine remotion|vfrey-framey|hyperframes`; order: `--engine`, the series engine, the project's `engine` in `vfrey.json`, then the machine default. The `Engine:` line says when it came from `vfrey.json`. Otherwise pass none and say which engine rendered (`Engine:` line). Framey's first render downloads Chrome Headless Shell (about 170 MB). HyperFrames needs the upstream CLI; ComfyUI is not wired. There is no fallback: an unavailable or failed engine ends the run with a `Fix:` line naming another one. Relay it; never quietly switch.
+
+## Rules
+
+- Do not post, scrape, or open the old console. Ingest is built into the source stage. A fresh install has no platform key: publish skips with `missing_key` and the video stays on this machine; do not promise a push (`npx vfrey push` refuses for now). Only if they say push, read `push/SKILL.md` next to this file. Keys are the person's own.
+- Every video carries the `AI-GENERATED` disclosure. Never hide it or claim a real person made it.
+- Updating: `npx vfrey update` prints the commands; run them only when asked (`--apply`).
+
+There is no MCP server; this file is how you find the commands.

package/skills/vfrey-product/examples/concurrency-vs-parallelism/framey/cook-one.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 420 500" fill="none" stroke="#000" stroke-width="9" stroke-linecap="round" stroke-linejoin="round">
+  <!-- one cook, two dishes: the cook turns between them -->
+  <path d="M170 120c-30-10-34-52 0-60 6-30 52-34 66-8 28-8 52 22 30 48-8 8-20 12-30 10v22H170z" fill="#fff"/>
+  <circle cx="210" cy="190" r="52" fill="#fff"/>
+  <circle cx="192" cy="184" r="5" fill="#000"/><circle cx="228" cy="184" r="5" fill="#000"/>
+  <path d="M196 208q14 12 28 0"/>
+  <path d="M150 360q0-110 60-120t60 120z" fill="#E3F2FD"/>
+  <path d="M168 270L96 330M252 270l72 60"/>
+  <rect x="30" y="330" width="110" height="64" rx="10" fill="#90CAF9"/><path d="M24 346h-14M140 346h12"/>
+  <rect x="280" y="330" width="110" height="64" rx="10" fill="#2196F3"/><path d="M276 346h-12M390 346h14"/>
+  <path d="M60 310c-8-18 8-26 0-44M100 306c-8-18 8-26 0-44" stroke="#0D47A1" stroke-width="6"/>
+  <path d="M170 440h80m-24-20 24 20-24 20M250 470h-80m24-20-24 20 24 20" stroke="#0D47A1" stroke-width="7"/>
+  <path d="M210 360v80"/>
+</svg>

package/skills/vfrey-product/examples/concurrency-vs-parallelism/framey/cook-two.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 420 500" fill="none" stroke="#000" stroke-width="9" stroke-linecap="round" stroke-linejoin="round">
+  <!-- two cooks, one dish each, working together in time -->
+  <g>
+    <path d="M40 150c-22-8-24-38 0-44 4-22 38-24 48-6 20-6 36 16 22 34-6 6-14 8-22 6v16H40z" fill="#fff"/>
+    <circle cx="74" cy="196" r="38" fill="#fff"/>
+    <circle cx="62" cy="192" r="4" fill="#000"/><circle cx="88" cy="192" r="4" fill="#000"/><path d="M64 210q10 9 20 0"/>
+    <path d="M30 370q0-90 44-98t44 98z" fill="#E3F2FD"/>
+    <path d="M48 292L20 340M100 292l30 48"/>
+    <rect x="10" y="352" width="190" height="60" rx="10" fill="#90CAF9"/>
+    <path d="M40 336c-8-16 8-24 0-40M84 332c-8-16 8-24 0-40" stroke="#0D47A1" stroke-width="6"/>
+  </g>
+  <g>
+    <path d="M250 150c-22-8-24-38 0-44 4-22 38-24 48-6 20-6 36 16 22 34-6 6-14 8-22 6v16h-48z" fill="#fff"/>
+    <circle cx="284" cy="196" r="38" fill="#fff"/>
+    <circle cx="272" cy="192" r="4" fill="#000"/><circle cx="298" cy="192" r="4" fill="#000"/><path d="M274 210q10 9 20 0"/>
+    <path d="M240 370q0-90 44-98t44 98z" fill="#E3F2FD"/>
+    <path d="M258 292l-28 48M310 292l30 48"/>
+    <rect x="220" y="352" width="190" height="60" rx="10" fill="#2196F3"/>
+    <path d="M250 336c-8-16 8-24 0-40M294 332c-8-16 8-24 0-40" stroke="#0D47A1" stroke-width="6"/>
+  </g>
+  <path d="M190 450h40" stroke="#0D47A1" stroke-width="7"/><path d="M120 462h180" stroke-dasharray="2 16" stroke="#0D47A1" stroke-width="7"/>
+</svg>

package/skills/vfrey-product/examples/concurrency-vs-parallelism/framey/index.html

@@ -0,0 +1,70 @@
+<!doctype html>
+<!-- "What's the difference?" as a scene: a light page, two labelled pictures, one big question, a stick figure that
+     reacts to what is being said, and word-highlighted captions. The idea is the picture; vfrey only supplies the
+     voice timing (vfrey.timing), the captions helper, GSAP, fonts and the stick figure art. -->
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1080, height=1920" />
+    <link rel="stylesheet" href="vfrey/fonts/fonts.css" />
+    <script src="vfrey/gsap.min.js"></script>
+    <script src="vfrey/vfrey.js"></script>
+    <style>
+      html, body { margin: 0; width: 1080px; height: 1920px; overflow: hidden; }
+      /* --mix is 0 for the opening layout and 1 for the explaining layout; everything below is a function of it. */
+      #root { --mix: 0; position: relative; width: 1080px; height: 1920px; overflow: hidden; background: #fff; color: #000; font-family: "Titan One", sans-serif; }
+      #root * { box-sizing: border-box; }
+      .wash { position: absolute; left: 0; top: 0; width: 100%; height: 700px; background: linear-gradient(180deg, rgba(0,0,0,.22), rgba(0,0,0,.1) 20%, rgba(0,0,0,.03) 48%, rgba(0,0,0,0)); }
+      .lab { position: absolute; width: 540px; text-align: center; white-space: nowrap; line-height: 1; top: calc(118px + (70 - 118) * var(--mix) * 1px); font-size: calc(60px - 8px * var(--mix)); }
+      .lab.b { left: 540px; }
+      .pic { position: absolute; top: calc(268px + (172 - 268) * var(--mix) * 1px); width: calc(420px - 100px * var(--mix)); height: calc(500px - 200px * var(--mix)); }
+      .pic img { width: 100%; height: 100%; object-fit: contain; }
+      .pic.a { left: calc(60px + 50px * var(--mix)); }
+      .pic.b { right: calc(60px + 50px * var(--mix)); }
+      .divider { position: absolute; left: 537px; top: 70px; width: 7px; height: 400px; border-radius: 4px; background: #000; opacity: var(--mix); }
+      .question { position: absolute; left: 0; width: 100%; top: 760px; text-align: center; line-height: 1.05; font-size: 104px; opacity: calc(1 - var(--mix) * 1.6); }
+      .fig { position: absolute; left: 50%; width: calc(360px + 140px * var(--mix)); height: calc((360px + 140px * var(--mix)) * 1.3); top: calc(1010px + (640 - 1010) * var(--mix) * 1px); transform: translateX(-50%); }
+      .fig img { position: absolute; inset: 0; width: 100%; height: 100%; opacity: 0; }
+      .fig img.on { opacity: 1; }
+      #captions { position: absolute; left: 50px; right: 50px; bottom: 196px; height: 250px; }
+    </style>
+  </head>
+  <body>
+    <div id="root" data-composition-id="main" data-start="0" data-width="1080" data-height="1920">
+      <div class="wash"></div>
+      <div class="divider"></div>
+      <div class="lab a">CONCURRENCY</div>
+      <div class="lab b">PARALLELISM</div>
+      <div class="pic a"><img src="cook-one.svg" alt="" /></div>
+      <div class="pic b"><img src="cook-two.svg" alt="" /></div>
+      <div class="question">What's the<br />difference?</div>
+      <div class="fig">
+        <img id="p-shrug" src="vfrey/assets/stick-shrug.svg" alt="" class="on" />
+        <img id="p-left" src="vfrey/assets/stick-point-left.svg" alt="" />
+        <img id="p-right" src="vfrey/assets/stick-point-right.svg" alt="" />
+        <img id="p-idea" src="vfrey/assets/stick-idea.svg" alt="" />
+      </div>
+      <div id="captions"></div>
+    </div>
+    <script>
+      const tl = vfrey.timeline();
+      const lines = vfrey.timing.lines;
+      // The opening (big question, shrug) lasts while the first line is spoken, then the layout settles.
+      const openingEnd = Math.min(3, Math.max(2.2, vfrey.line(0).end + 0.25));
+      tl.fromTo("#root", { "--mix": 0 }, { "--mix": 1, duration: 0.35, ease: "power2.inOut" }, openingEnd);
+      // One pose per spoken line: the hook shrugs, concurrency lines point left, parallelism lines point right, the last has the idea.
+      const POSE = ["shrug", "left", "left", "right", "left", "right", "idea"];
+      let shown = "shrug";
+      lines.forEach((line, i) => {
+        const pose = i === lines.length - 1 ? "idea" : POSE[i] || "shrug";
+        if (pose === shown) return;
+        vfrey.at(Math.max(line.start, i === 0 ? 0 : openingEnd), (tl, t) => {
+          tl.set("#p-" + shown, { className: "" }, t);
+          tl.set("#p-" + pose, { className: "on" }, t);
+        });
+        shown = pose;
+      });
+      vfrey.captions("#captions", { style: "box" });
+    </script>
+  </body>
+</html>

package/skills/vfrey-product/examples/concurrency-vs-parallelism/remotion/cook-one.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 420 500" fill="none" stroke="#000" stroke-width="9" stroke-linecap="round" stroke-linejoin="round">
+  <!-- one cook, two dishes: the cook turns between them -->
+  <path d="M170 120c-30-10-34-52 0-60 6-30 52-34 66-8 28-8 52 22 30 48-8 8-20 12-30 10v22H170z" fill="#fff"/>
+  <circle cx="210" cy="190" r="52" fill="#fff"/>
+  <circle cx="192" cy="184" r="5" fill="#000"/><circle cx="228" cy="184" r="5" fill="#000"/>
+  <path d="M196 208q14 12 28 0"/>
+  <path d="M150 360q0-110 60-120t60 120z" fill="#E3F2FD"/>
+  <path d="M168 270L96 330M252 270l72 60"/>
+  <rect x="30" y="330" width="110" height="64" rx="10" fill="#90CAF9"/><path d="M24 346h-14M140 346h12"/>
+  <rect x="280" y="330" width="110" height="64" rx="10" fill="#2196F3"/><path d="M276 346h-12M390 346h14"/>
+  <path d="M60 310c-8-18 8-26 0-44M100 306c-8-18 8-26 0-44" stroke="#0D47A1" stroke-width="6"/>
+  <path d="M170 440h80m-24-20 24 20-24 20M250 470h-80m24-20-24 20 24 20" stroke="#0D47A1" stroke-width="7"/>
+  <path d="M210 360v80"/>
+</svg>

package/skills/vfrey-product/examples/concurrency-vs-parallelism/remotion/cook-two.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 420 500" fill="none" stroke="#000" stroke-width="9" stroke-linecap="round" stroke-linejoin="round">
+  <!-- two cooks, one dish each, working together in time -->
+  <g>
+    <path d="M40 150c-22-8-24-38 0-44 4-22 38-24 48-6 20-6 36 16 22 34-6 6-14 8-22 6v16H40z" fill="#fff"/>
+    <circle cx="74" cy="196" r="38" fill="#fff"/>
+    <circle cx="62" cy="192" r="4" fill="#000"/><circle cx="88" cy="192" r="4" fill="#000"/><path d="M64 210q10 9 20 0"/>
+    <path d="M30 370q0-90 44-98t44 98z" fill="#E3F2FD"/>
+    <path d="M48 292L20 340M100 292l30 48"/>
+    <rect x="10" y="352" width="190" height="60" rx="10" fill="#90CAF9"/>
+    <path d="M40 336c-8-16 8-24 0-40M84 332c-8-16 8-24 0-40" stroke="#0D47A1" stroke-width="6"/>
+  </g>
+  <g>
+    <path d="M250 150c-22-8-24-38 0-44 4-22 38-24 48-6 20-6 36 16 22 34-6 6-14 8-22 6v16h-48z" fill="#fff"/>
+    <circle cx="284" cy="196" r="38" fill="#fff"/>
+    <circle cx="272" cy="192" r="4" fill="#000"/><circle cx="298" cy="192" r="4" fill="#000"/><path d="M274 210q10 9 20 0"/>
+    <path d="M240 370q0-90 44-98t44 98z" fill="#E3F2FD"/>
+    <path d="M258 292l-28 48M310 292l30 48"/>
+    <rect x="220" y="352" width="190" height="60" rx="10" fill="#2196F3"/>
+    <path d="M250 336c-8-16 8-24 0-40M294 332c-8-16 8-24 0-40" stroke="#0D47A1" stroke-width="6"/>
+  </g>
+  <path d="M190 450h40" stroke="#0D47A1" stroke-width="7"/><path d="M120 462h180" stroke-dasharray="2 16" stroke="#0D47A1" stroke-width="7"/>
+</svg>

package/skills/vfrey-product/examples/concurrency-vs-parallelism/remotion/index.tsx

@@ -0,0 +1,49 @@
+// "What's the difference?" for Remotion: the same scene as framey/index.html, written as a React component.
+// vfrey provides the voice (it plays it for you), the timing (useTiming) and the captions (<Captions/>).
+import { AbsoluteFill, Img, interpolate, staticFile } from "remotion";
+import { Captions, useTime, useTiming } from "@vfrey/scene";
+
+const lerp = (a: number, b: number, mix: number) => a + (b - a) * mix;
+const POSE = ["shrug", "point-left", "point-left", "point-right", "point-left", "point-right", "idea"];
+
+export default function Scene() {
+  const timing = useTiming();
+  const t = useTime();
+  // The opening (big question, shrug) lasts while the first line is spoken, then the layout settles.
+  const first = timing.lines[0]!;
+  const openingEnd = Math.min(3, Math.max(2.2, first.end + 0.25));
+  const mix = interpolate(t, [openingEnd, openingEnd + 0.35], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
+  // One pose per spoken line; the last line has the idea.
+  let pose = "shrug";
+  if (t >= openingEnd) {
+    timing.lines.forEach((line, i) => {
+      if (line.start <= t) pose = i === timing.lines.length - 1 ? "idea" : POSE[i] ?? "shrug";
+    });
+  }
+  const label = (text: string, left: number) => (
+    <div style={{ position: "absolute", left, top: lerp(118, 70, mix), width: 540, textAlign: "center", whiteSpace: "nowrap", lineHeight: 1, fontSize: lerp(60, 52, mix) }}>{text}</div>
+  );
+  const pic = (src: string, side: "left" | "right") => (
+    <div style={{ position: "absolute", top: lerp(268, 172, mix), [side]: lerp(60, 110, mix), width: lerp(420, 320, mix), height: lerp(500, 300, mix) }}>
+      <Img src={staticFile(src)} style={{ width: "100%", height: "100%", objectFit: "contain" }} />
+    </div>
+  );
+  const figWidth = lerp(360, 500, mix);
+  return (
+    <AbsoluteFill style={{ background: "#fff", color: "#000", fontFamily: '"Titan One", sans-serif' }}>
+      <div style={{ position: "absolute", left: 0, top: 0, width: "100%", height: 700, background: "linear-gradient(180deg, rgba(0,0,0,.22), rgba(0,0,0,.1) 20%, rgba(0,0,0,.03) 48%, rgba(0,0,0,0))" }} />
+      <div style={{ position: "absolute", left: 537, top: 70, width: 7, height: 400, borderRadius: 4, background: "#000", opacity: mix }} />
+      {label("CONCURRENCY", 0)}
+      {label("PARALLELISM", 540)}
+      {pic("cook-one.svg", "left")}
+      {pic("cook-two.svg", "right")}
+      <div style={{ position: "absolute", left: 0, width: "100%", top: 760, textAlign: "center", lineHeight: 1.05, fontSize: 104, opacity: 1 - mix * 1.6 }}>
+        What's the<br />difference?
+      </div>
+      <div style={{ position: "absolute", left: 540 - figWidth / 2, top: lerp(1010, 640, mix), width: figWidth, height: figWidth * 1.3 }}>
+        <Img src={staticFile(`vfrey/assets/stick-${pose}.svg`)} style={{ width: "100%", height: "100%" }} />
+      </div>
+      <Captions captionStyle="box" style={{ position: "absolute", left: 50, right: 50, bottom: 196, height: 250 }} />
+    </AbsoluteFill>
+  );
+}

package/skills/vfrey-product/examples/concurrency-vs-parallelism/script.json

@@ -0,0 +1,15 @@
+{
+  "title": "Concurrency vs parallelism: what's the difference?",
+  "hook": "What is the difference between concurrency and parallelism?",
+  "lines": [
+    "What is the difference between concurrency and parallelism?",
+    "Concurrency is one cook switching between two dishes: stir one, then chop for the other.",
+    "Only one thing happens at any instant, but both dishes make progress.",
+    "Parallelism is two cooks, each working on their own dish at the very same time.",
+    "Concurrency is about dealing with many things at once.",
+    "Parallelism is about doing many things at once.",
+    "So concurrency is how you structure the work, and parallelism is how it runs."
+  ],
+  "hashtags": ["#programming", "#concurrency", "#parallelism"],
+  "subject": "concurrency vs parallelism"
+}

package/skills/vfrey-product/examples/octopus-facts/index.html

@@ -0,0 +1,60 @@
+<!doctype html>
+<!-- "3 facts about octopuses": a different idea, so a different picture. Each fact gets a full-screen colour and a huge
+     numeral; the octopus watches from the corner. Same helpers: vfrey.line() for when a fact is spoken, vfrey.captions
+     for the words. Nothing here came from a template. -->
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1080, height=1920" />
+    <link rel="stylesheet" href="vfrey/fonts/fonts.css" />
+    <script src="vfrey/gsap.min.js"></script>
+    <script src="vfrey/vfrey.js"></script>
+    <style>
+      html, body { margin: 0; width: 1080px; height: 1920px; overflow: hidden; }
+      #root { position: relative; width: 1080px; height: 1920px; overflow: hidden; background: #0d47a1; color: #fff; font-family: "Titan One", sans-serif; }
+      .panel { position: absolute; inset: 0; opacity: 0; }
+      .panel .big { position: absolute; left: 0; right: 0; top: 250px; text-align: center; font-size: 560px; line-height: 1; }
+      .panel .word { position: absolute; left: 60px; right: 60px; top: 860px; text-align: center; font-size: 110px; line-height: 1.05; }
+      #intro { opacity: 1; }
+      #intro .head { position: absolute; left: 60px; right: 60px; top: 300px; text-align: center; font-size: 150px; line-height: 1.02; }
+      #octo { position: absolute; width: 440px; height: 440px; left: 320px; top: 1010px; }
+      #captions { position: absolute; left: 50px; right: 50px; bottom: 196px; height: 260px; }
+    </style>
+  </head>
+  <body>
+    <div id="root" data-composition-id="main" data-start="0" data-width="1080" data-height="1920">
+      <div class="panel" id="intro"><div class="head">3 facts about octopuses</div></div>
+      <div class="panel" id="f1" data-bg="#d84315"><div class="big">1</div><div class="word">three hearts</div></div>
+      <div class="panel" id="f2" data-bg="#00838f"><div class="big">2</div><div class="word">blue blood</div></div>
+      <div class="panel" id="f3" data-bg="#6a1b9a"><div class="big">3</div><div class="word">nine brains</div></div>
+      <img id="octo" src="octopus.svg" alt="" />
+      <div id="captions"></div>
+    </div>
+    <script>
+      const tl = vfrey.timeline();
+      const T = vfrey.timing;
+      // Which spoken line opens each fact: the lines that start with "One.", "Two." and "Three.".
+      const opens = ["One", "Two", "Three"].map((w) => T.lines.findIndex((l) => l.text.startsWith(w + ".")));
+      const end = T.durationSec;
+      const starts = opens.map((i) => (i >= 0 ? vfrey.line(i).start : end));
+      // Intro until the first fact; then each fact owns the screen until the next begins; the outro keeps the last colour.
+      tl.set("#root", { backgroundColor: "#0d47a1" }, 0);
+      ["f1", "f2", "f3"].forEach((id, k) => {
+        const at = Math.max(0, starts[k] - 0.05);
+        const bg = document.getElementById(id).dataset.bg;
+        vfrey.at(at, (tl, t) => {
+          tl.set("#root", { backgroundColor: bg }, t);
+          tl.set("#intro", { opacity: 0 }, t);
+          if (k > 0) tl.set("#f" + k, { opacity: 0 }, t);
+          tl.set("#" + id, { opacity: 1 }, t);
+          tl.fromTo("#" + id + " .big", { scale: 0.4 }, { scale: 1, duration: 0.45, ease: "back.out(2.2)" }, t);
+          tl.fromTo("#" + id + " .word", { y: 40, opacity: 0 }, { y: 0, opacity: 1, duration: 0.35, ease: "power3.out" }, t + 0.15);
+        });
+      });
+      tl.fromTo("#intro .head", { y: 60, opacity: 0 }, { y: 0, opacity: 1, duration: 0.5, ease: "power3.out" }, 0.1);
+      // The octopus sways all the way through (a finite loop: the video is a known length).
+      tl.to("#octo", { rotation: 6, y: -18, duration: 1.2, ease: "sine.inOut", yoyo: true, repeat: Math.max(0, Math.floor(end / 1.2) - 1) }, 0);
+      vfrey.captions("#captions", { style: "pop", highlight: "#ffd54f", color: "#ffffff", stroke: "#000000" });
+    </script>
+  </body>
+</html>

package/skills/vfrey-product/examples/octopus-facts/octopus.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 400" fill="none" stroke="#fff" stroke-width="10" stroke-linecap="round" stroke-linejoin="round">
+  <!-- an octopus: dome head, two eyes, eight wavy arms -->
+  <path d="M90 190c0-90 50-140 110-140s110 50 110 140c0 20-6 36-14 46H104c-8-10-14-26-14-46z" fill="#FF8A65"/>
+  <circle cx="160" cy="170" r="16" fill="#fff"/><circle cx="240" cy="170" r="16" fill="#fff"/>
+  <circle cx="164" cy="174" r="7" fill="#0D47A1" stroke="none"/><circle cx="244" cy="174" r="7" fill="#0D47A1" stroke="none"/>
+  <path d="M176 210q24 18 48 0"/>
+  <path d="M108 236c-30 30-10 60-44 80M138 240c-14 36 8 64-12 92M170 242c-4 40 14 60 4 98M200 244v100M230 242c4 40-14 60-4 98M262 240c14 36-8 64 12 92M292 236c30 30 10 60 44 80" stroke="#FF8A65" stroke-width="16"/>
+</svg>

package/skills/vfrey-product/examples/octopus-facts/script.json

@@ -0,0 +1,14 @@
+{
+  "title": "3 facts about octopuses",
+  "hook": "Here are three facts about octopuses that sound made up, but are true.",
+  "lines": [
+    "Here are three facts about octopuses that sound made up, but are true.",
+    "One. An octopus has three hearts.",
+    "Two of them pump blood through the gills, and the third pumps it to the rest of the body.",
+    "Two. An octopus has blue blood, because it carries oxygen with copper instead of iron.",
+    "Three. An octopus has nine brains: one central brain, and a small one in each of its eight arms.",
+    "Octopuses really are strange and clever animals."
+  ],
+  "hashtags": ["#octopus", "#animalfacts", "#ocean"],
+  "subject": "3 facts about octopuses"
+}

package/skills/vfrey-product/push/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: vfrey-push
+description: Answer a request to push a finished vfrey video to a platform. Use when the person says push, publish, or upload a video to YouTube or another platform.
+---
+
+# Push
+
+`npx vfrey push` is not built yet. It prints `✗ push is not built yet.` and `Fix: publishing runs inside \`vfrey tick\` once the platform keys are set.` and exits 1. Do not promise a push and do not call a platform API.
+
+1. Say plainly that the video stays on this machine under `~/.vfrey/renders/` (or `$VFREY_HOME/renders/`).
+2. Publishing runs inside `npx vfrey tick`, through the official platform APIs, and only with the operator's own platform keys. With no key, publish skips with `missing_key`. `npx vfrey desk snapshot --json` or `npx vfrey dashboard` shows the skipped publish.
+3. Do not run `npx vfrey push` to look for a hidden upload. It has none.
+4. Disclosure stays fail-closed: any upload is labeled synthetic. A missing label is `blocked`, not a retry without the label.
+
+Nothing in this skill sends mail or collects topics.