veed-engine-cli

.wv

<style>

@keyframes

animation-delay

pipeline/director-brief.md

• One video — recommended, and the best-travelled path. The transcript, the canvas (dims + fps) and the base frames are all derived from the file, which is what lets a compiled recipe run at zero tokens.
• Several videos — ONE batch, not one run each.

  prep/transcribe.ts

  ,

  veed/go.ts

  and

  prep/prep.ts

  all take

  <video.mp4> [...]

  and write one

  runs/<key>

  per video, so the provider question, the sign-in and any install happen once; STYLE, DESIGN + RENDER and MUX then run per

  runs/<key>

  .
• No video — FULLY SUPPORTED, not a degraded mode. Motion graphics, stills, slides, generated imagery, audio-only sources. Author the

  .wv

  INLINE per

  pipeline/director-brief.md

  and run the SAME gates as every other run:

  lint-template.ts

  →

  veed-engine-cli <dir> --verify

  →

  --record

  (the DESIGN + RENDER step's RENDER + VERIFY block — none of it reads

  meta.json

  ). Choose

  <key>

  from the ask, take the canvas and duration from the ask rather than from ffprobe, and drop only the steps that have no subject: the recipe draw (no footage to derive facets from),

  probe-qa

  (it diffs frames against source footage) and mux-audio (no audio track).

  generate-recipe.ts

  is the scripted convenience for 1+ videos, NOT the definition of a supported run — its absence costs you the shortcut, nothing else.

refs/html/<id>/recipe.ts

docs/FLOW.md

word-timings.json

pipeline/scripts/generate-recipe.ts

analysis.json

hook-…

--verify

simple

glass

• Never name the style — and never expose the mechanics of choosing it. The ref id, its metadata, and the sampling machinery ("the sampled pick", "the draw", seeds, alternates) are all internal. Talk about "the style" as an abstract thing that exists for this video: "the style centres text mid-frame, so I'm switching to one that anchors low" — not "the sampled pick is…". Describe a delivered look only in plain visual terms (colour, size, placement).
• No step-by-step progress. Don't announce transcript/prep/sampling/verify/probe/mux as they happen. One line when starting, then the deliverable with the preview URL. Silence in between is fine.
• "Render complete" = audio muxed. Muxing is not a separate user-visible step; say the render is done only once

  final/out.mp4

  exists.
• No recap. The delivery message is the

  out.mp4

  path plus at most a sentence or two about the result (on creative runs, the look you committed). Never a "What happened" list of stages, gates, counts, or QA results.
• Failures are the exception. When a gate fails and you must stop, explain in plain terms what is wrong on screen and the options; quote raw FAIL lines only if the user asks.
• Questions you must ask (renderer update consent, coverage gaps, probe failures) also stay in plain language: what it means for their video, not exit codes.

scripts/preflight.sh

SKILL.md

1. If SKILL_ROOT sits inside an Open Edit checkout, WORKSPACE is that checkout — preflight reuses it, and the run exercises that code.
2. Otherwise WORKSPACE is the user's current project root, or the current directory outside a project — preflight creates its own runtime at

   <WORKSPACE>/.open-edit/runtime

   and every step below runs there.

reusing the local checkout at …

will use a managed clone at …

bash "$SKILL_ROOT/scripts/preflight.sh" --dry --workspace "$WORKSPACE"

bash "$SKILL_ROOT/scripts/preflight.sh" --workspace "$WORKSPACE"

--dry

APPROVAL REQUIRED

bash "$SKILL_ROOT/scripts/preflight.sh" --auto-approve --workspace "$WORKSPACE"

--auto-approve

--dry

--dry

WOULD APPLY LOCALLY

not ready yet — run bare preflight …

preflight:

ready — OPEN_EDIT_ROOT=…

APPROVAL REQUIRED

--repository <URL-or-local-path> --ref <branch>

$OPEN_EDIT_ROOT/AGENTS.md

• They have a clip, or will record one → take the path, waiting for the filename if it is still coming, then continue to the PREP step unchanged.
• VEED Fabric (recommend this when they want a talking head) → a talking-head clip from a script, billed to one of their VEED workspaces. Fabric REUSES VEED transcription's authentication — the same veed.io account, the same OAuth login, the same stored token. There is no Fabric connector and no second sign-in: if they are already signed in for VEED transcription, they are signed in for this. Continue below.
• Another model (Veo, Kling, Luma, anything on fal) → their auth and their bill, not ours; take the finished file into the PREP step. Say this in the SAME BREATH as that option, every time: captions come from TRANSCRIBING the clip's audio, so the clip must contain SPEECH. Veo 3 does. Veo 2, Kling, Luma and most of fal's catalogue are SILENT, and a silent clip yields an empty transcript and no captions. This is a warning, not a decision — say it, then let them proceed.
• No video — work with other sources → raster graphics (stills, screenshots, photos), vector graphics (logos, shapes, SVG), motion graphics (titles, kinetic type, animation), or generated imagery, in any combination. Build the piece from those: go straight to the DESIGN + RENDER step, which reads no footage. If they have AUDIO it can still be transcribed for captions; PREP, the style draw and MUX are skipped for want of a video subject.

node --import tsx veed/generate.ts --script "<the script>" --key <key>

veed/.veed-workspace.json

--workspace <id>

veed/fabric-one-lipsync

• Fabric One Lipsync — ~4 credits per SECOND of finished video, measured.
• Speech synthesis — 2 credits per minute of generated audio, rounded up to the whole minute, so any read up to a minute costs 2.

--image <url|path>

--voice

--image

[{ id, script, image | character, voice }, …]

node --import tsx veed/generate-set.ts --shots shots.json --key <key> --workspace <id>

--yes

--resume

node --import tsx pipeline/scripts/concat-videos.ts <out.mp4> <clip1.mp4> <clip2.mp4> [...]

pipeline/scripts/concat-chapters.ts

node --import tsx veed/sample-presenter.ts --key <key> [--gender male|female] [--locale <locale>] [--portrait|--landscape]

--portrait

--landscape

--seed N

1. CONFIRM (spends NOTHING):

   node --import tsx veed/generate.ts --script "<the script>" --key <key> --workspace <id>

   It prints the script, the character, voice, framing ("portrait 9:16"), the workspace being billed with its balance, and the exact credit cost, records that approval at

   runs/<key>/.fabric-pending.json

   , and prints the exact next command. Show the user the cost in plain terms and get an explicit yes. NOT ENOUGH CREDITS is checked HERE too, before anything is written: if the workspace's balance is below the quote this step refuses, names both figures, and records no approval — so it never hands you a "run exactly" command for the ANALYSE step that is guaranteed to fail.
2. SPEND (only after that yes) — copy the command it printed, with no

   --script

   :

   node --import tsx veed/generate.ts --key <key> --yes

   It re-confirms against the server and REFUSES to spend if the fresh quote is above the cost that was approved, if the recorded script no longer matches its hash, if the approval is over an hour old, or if a

   --workspace

   here disagrees with the one that was approved. In any of those cases nothing is charged: re-run the PREP step and get a fresh yes for the new figure. That yes binds the SCRIPT, the FIGURE (character, voice, framing, quoted cost) and the WORKSPACE together for one hour; if any of the three drifts the run refuses rather than charging something the user never saw. A quote that came in LOWER proceeds — only a rise refuses. NOT ENOUGH CREDITS is checked again HERE, against the balance as it stands right now (it can have moved since the PREP step) — the balance is what actually guards the money, and it refuses, names both figures, and charges nothing. That goes back to the workspace question — top the workspace up, shorten the script, or re-confirm against a workspace the user explicitly names. NEVER move the run to a richer workspace on their behalf; a balance that simply cannot be read is not a refusal and proceeds, on either step.

--script

--yes

• The movement AGREES with the quote → give both, the quote as the figure and the movement as the check.
• The movement is BIGGER than the quote → say so, and say the observed number. A concurrent run billing that workspace is the likely cause; our estimate simply running low is the other, and neither can be ruled out. Tell the user to check that workspace — never quietly report the quote as if nothing had happened.
• The balance could not be read credibly → the run prints the ESTIMATE and labels it one; pass that on as an estimate, never as the charge. A

  --resume

  reports on the same terms, and never re-decides a figure the spend pass already measured — a balance read an hour later says nothing about a charge that landed then. Every attempt leaves its own audit trail at

  runs/<key>/.fabric-spend-<sessionId>.json

  , so re-running a key never erases the earlier run's. Never let a run that spent credits end silently about cost.

runs/<key>/<key>.mp4

<key>

runs/

.

-

_

.

..

-

assertSafeKey

veed/generate.ts

runs/<key>/.fabric-charge-<sessionId>.json

• Generation FAILED (VEED reports the job failed) — report plainly what VEED said. Do NOT re-run

  --yes

  to "retry": a retry is a SECOND charge for the same script. A fresh attempt needs a fresh confirm pass and a fresh explicit yes from the user; the dead job blocks nothing.
• The run was interrupted (transport blip, polling died, download stalled, closed laptop) — the video is already PAID FOR and nothing needs approving. Collect it with

  node --import tsx veed/generate.ts --key <key> --resume

  , which polls, downloads and spends NOTHING. Polling gives up after 15 minutes, or after a run of consecutive status-check failures — the job may still be finishing server-side, so always

  --resume

  before ever paying again.
• The attempt vanished mid-charge (

  --yes

  refuses saying a charge MAY have landed) — no job id was ever recorded, so nothing can collect it. Tell the user plainly that VEED may already have charged, and have them check that workspace's balance and videos around the time the refusal named. To free the key, run

  node --import tsx veed/generate.ts --key <key> --abandon <sessionId>

  with the id from the refusal; it clears that one record and nothing else, and any credits that attempt spent are gone.

  --yes

  REFUSES while another run of the same key is charging, while a paid job is uncollected (it points at

  --resume

  ), and while an abandoned attempt is unresolved. Runs of DIFFERENT keys never block each other, and running them at the same time is fine.

--character

--voice

--yes

FAL_MODELS

--model

ffprobe

prep/whisper.ts <json> <media>

for a living—

pipeline/providers/assets.ts

spendLine

runs/<key>/transcript.json

words: [{text, timestamp:[start,end]}]

<key>

_

runs/<key>

$OPEN_EDIT_ROOT/.open-edit-prefs.json

Before I can add captions I need a transcript. Four ways to get one:

1. VEED — best quality. One-time browser sign-in. A free account covers about 10 minutes of transcription a month; beyond that it needs a plan (https://www.veed.io/pricing).
2. WhisperX, better quality — free, runs locally, nothing leaves your machine. Slower, and the first run installs it plus a model — around 2 GB of disk.
3. WhisperX, fastest — same, but quicker; weaker on names and jargon, which captions show off.
4. Your own transcription service — point me at it and I'll wire that up instead.

I'll remember your pick.

node --import tsx prep/transcribe.ts --record veed

node --import tsx prep/transcribe.ts --record whisperx --model medium

node --import tsx prep/transcribe.ts --record whisperx --model small.en

node --import tsx prep/transcribe.ts --record custom

small.en

whisperx

• veed →

  node --import tsx veed/go.ts <video> [...]

  , login flow below. When the browser opens, say exactly: "I've opened a VEED login tab in your browser — click Allow if it asks. I'll wait here; there's nothing to paste."
• whisperx →

  node --import tsx prep/transcribe.ts <video> [...]

  — the recorded tier applies; pass

  --model medium|small.en

  only to override it. If the binary is missing, ASK before installing: "WhisperX isn't installed. It's a local Python tool — the install pulls in PyTorch and the first run downloads a model, so expect a slow first pass and around 2 GB of disk. It goes in its own isolated environment, not your system Python and not this project, and

  uv tool uninstall whisperx

  removes it again. Install it now?" On yes run

  bash pipeline/scripts/install-whisperx.sh

  and stream its output.
• custom → the user's service is yours to drive: get a Whisper-family JSON out of it (their MCP, their CLI, their API — their credentials, never handled here), then

  node --import tsx prep/whisper.ts <json> <video>

  — one json per video, repeated in pairs for a batch.

  prep/whisper.ts

  IS the shipped mapper; what we ship no helper for is DRIVING the user's service, which is yours to do with their tool.

• VEED sign-in declined → "No problem, I'll leave VEED alone. I can run WhisperX locally instead: free, offline, nothing leaves your machine. It needs a one-off install that pulls in PyTorch, so the first pass is slow. Want that?"
• WhisperX install declined → "Then I'll skip the local route. VEED transcription needs a one-time browser sign-in and runs on your VEED account's limits. Shall I open that instead?"
• Both hosted routes declined → "Then I won't transcribe — every caption is built from a transcript and I won't invent one. Two routes are still open: point me at your own transcription service and I'll wire it up, or give me the caption copy and I'll place it by hand rather than synced to speech. Otherwise, say the word if you change your mind about VEED or WhisperX." Stop only if they decline those two as well.
• No audio track → "That clip has no audio track, so there's no speech to caption. I can still put text on it — titles, lower thirds, motion graphics — from copy you give me. Want that?" Transcription is the step with no subject here, not the run: with no transcript there is no recipe to route to, so author DESIGN + RENDER INLINE per

  director-brief.md

  exactly as the NO VIDEO case does, with the footage as the base layer and timings chosen by you rather than synced to speech. Only an ask for speech captions specifically has nothing left to do.

• Out of credits (

  veed/go.ts

  says "out of transcription credits") → the account is the blocker, not the choice, so go back to the Q1 question with VEED still on the table: "VEED is out of transcription credits for this workspace — a free account covers about 10 minutes a month. You can add a plan at https://www.veed.io/pricing and I'll retry, or I can run WhisperX locally instead: free, offline, and it installs on first use. Which would you like?" Do not rewrite the recorded provider until something succeeds.
• Login failed or expired → run the login flow once more. If it fails again, treat it as declined and offer the alternative in the words above.
• Anything else (upload failure, poll timeout, network) → retry the command ONCE, then offer the alternative. A blip must not cost the user their provider choice.

go.ts

• Run

  node --import tsx veed/login.ts

  in the background — it starts a local catcher, prints an authorize URL, and OPENS THAT URL IN THE USER'S BROWSER ITSELF (

  execFile('open', …)

  ). You open nothing: watch its output for

  Logged in.

  and meanwhile tell the user a VEED login tab has opened and to click "Allow" if a consent screen appears (usually it auto-approves — they're likely already signed into veed.io). The browser redirects to

  http://127.0.0.1:8977/callback

  , the running login.ts catches it, and stores the token. No pasting needed. If this box has no browser

  open

  can reach (headless/SSH), use

  VEED_LOGIN_MANUAL=1 …

  instead and paste the redirected URL back to it.
• If the OAuth flow misbehaves, re-run it. NEVER read the user's browser cookies or local storage to obtain a token, and never ask them to paste one out of DevTools.

node --import tsx prep/prep.ts <video> [...]

runs/<key>/

• meta.json

  — the single source of truth downstream: canvas

  width/height/fps

  ,

  durationSec

  , and all paths (

  videoPath

  ,

  transcriptPath

  ,

  wordTimingsPath

  ,

  framesDir

  ). Canvas = the source's own dims (rotation-corrected) and fps, probed by prep;

  aspect

  = portrait (9:16) or landscape (16:9) label.

• word-timings.json

  — per beat:

  cueDelayMs

  /

  cueDurMs

  + every word's absolute-ms

  delayMs

  , synthesized from the VEED chunks' real per-word times (even split only if a transcript has none). The DESIGN + RENDER step pastes these VERBATIM — compiled recipes by construction, the inline creative passes per the director brief; timing is never re-derived.

• frames/beat-N.png

  — one clean still per beat at the chunk MID time, emitted at HALF canvas (×2 → canvas).

node --import tsx pipeline/scripts/sample-style.ts --run runs/<key>

refs/tags.json

fit

runs/<key>/style.json

{refId, refPath, facets, hasRecipe, seed, energy, coverage, alternates}

recipe=yes|no

style.json

recipe=yes

style.json

--seed N

--style <id>

--exclude <id>

--exclude

• THE INDEX IS THE RUNTIME UNIVERSE: every entry ships a validated sheet (

  refs/html/<id>/recipe.md

  )
  • its compiled module (

    recipe.ts

    ) — the script fail-louds on any entry missing either, or missing its prefab.
• COVERAGE MODE (

  coverage.filtered:false

  — possible only if curation ever shrinks an aspect below the threshold): STOP and tell the user honestly the aspect isn't covered by recipes; options are

  --style

  by their explicit pick, an authored-from-scratch run if they ask for one, or cancel. NEVER reach for the from-scratch pass SILENTLY — the ban is on substituting it without the user choosing it, not on the path existing.
• RECIPES ARE THE PRODUCT: the draw,

  --style

  , and

  alternates

  are all RECIPE-BACKED only — the runtime index contains nothing else.
• CLASSIC POOL — explicit-simplicity route (intent, not vibe):

  refs/html/classic/tags.json

  holds a small set of plain caption presets (single font, simple or no word animation; every preset is dual-aspect). Route here ONLY when the user's INITIAL prompt itself asks for a simplified/standard look — "simple", "clean", "minimal", "just subtitles", "black bars behind the text", "highlight the spoken word", or similar prose (each entry lists its

  cues

  ; match on meaning, not exact strings). On this route SKIP sample-style and pick in TWO stages: (1) the ask's cues NARROW the pool — often barely ("simple" alone eliminates nothing; a concrete ask like "black bars" narrows hard); (2) the CONTENT decides among what remains, the same signal the seeded draw scores from the transcript — word rate, caps, exclamations, overall tone: calm/measured speech → the soft picks (

  energy: calm|clean

  ), fast punchy delivery → the highlight picks (

  energy: punchy

  ); busy footage favors a

  bg

  (bars/plate) for legibility. DEFAULT TO MOTION: prefer a word-by-word preset (

  motion

  != none — float-in, colour flash, per-word fade) even for calm content; pick a static preset (

  motion: none

  ) only when the user says no animation ("static", "no motion", "nothing moving") or their concrete ask lands on one ("black bars" → the bars preset is static, and the concrete ask wins). Preset ids are ARBITRARY LABELS, never selectors — "give me a simple style" does NOT mean the preset named

  simple

  ; a hype-paced clip answering that ask is better served by

  rizz

  or

  mint

  than by a static preset. Then run DESIGN + RENDER variant A with

  --module refs/html/classic/<id>/recipe.ts

  appended (same command, same gates; no

  style.json

  exists and none is needed). The pick is INTERNAL like any other (User-facing output): never surface "classic", "preset", preset ids, or the pool's existence — the user hears at most "going with a clean look for this clip". No simplicity hint → never classic; the seeded draw stays the default. Classic presets are END styles on the bank side: never donors or craft substrate for any OTHER run's remix/face-1, and never in the seeded draw. Iteration on a delivered classic run routes three ways: PARAMETER AMENDS stay classic — "make the text blue", "add an outline", "bigger", "move it up", "highlight in green", "all caps": anything expressible as a field of the classic spec (color, outline, shadow, size/position fractions, casing, highlight colour, font weight). COPY the preset's

  recipe.ts

  to the scratchpad, fix its relative

  classic-lib.ts

  import to the absolute path, edit ONLY the spec fields in the copy, rerun with

  --module <copy>

  (same gates; the library recipe is never edited). "Another simple one / different simple style" re-picks a different classic preset through this same route. A new creative DIRECTION (a mood, a reference, new layout/motion language, "make it more interesting") GRADUATES to REMIX — but the user is iterating on THEIR current look, so the delivered classic design is the CONTINUITY SKELETON (donor A): translate its spec (font, casing, palette, placement, bars/plate, motion) into the skeleton role and keep whatever the ask doesn't touch; runtime-index donors supply only the divergence (B by

  type

  , optional C by

  device

  ) per REMIX MODE. The never-a-donor bar is about the BANK: classic refs never serve as donors or craft substrate for any OTHER run and never enter the seeded draw — a classic run's own iteration keeping its own skeleton is not a violation.
• CREATIVE PASS, two faces: the user does NOT know recipes exist and never needs to — route on the SHAPE of the ask, never on whether they said "mix". face-1 — the prompt ARRIVES WITH the user's OWN reference/brand/concept (an image, a brand kit, a described idea): skip the draw-and-ship — run the from-scratch INLINE pass (DESIGN + RENDER variant B). The USER'S materials are the design authority (their files/links must be OPENED and looked at); 1-2 nearest recipe SHEETS (picked from

  refs/tags.json

  by facets — closest type/energy;

  alternates

  in style.json is a ready shortlist) ride along as engine-proven craft substrate — mechanics only, never their look. Those sheets may come from EITHER aspect: a mechanic, an engine workaround or a calibration note is not aspect-bound, and the pool is small enough that locking to one

  fit

  throws away half the proven craft. Anything GEOMETRIC taken from an off-aspect sheet (bands, margins, ladder px, placement constants) is re-derived at this run's canvas — see the cross-aspect rule in

  director-brief.md

  . Set a DIRECTION — content angle, mood/energy, placement intent ONLY (never fonts/palette/device — those come from the user's materials; on any collision the user's materials win). face-2 — the user iterates on a DELIVERED result:
  • REMIX is the DEFAULT creative answer. ANY iteration carrying creative input — "make it more interesting", "surprise me", a mood/direction, a concrete aesthetic change — goes STRAIGHT to REMIX on the first ask. No re-roll step in between. (Inline, at session effort — you compose it yourself, no subagent): pick 2-3 INGREDIENT sheets from the runtime index — the current pick is the SKELETON donor (A); choose a TYPE+PALETTE donor (B) with a DIFFERENT

    type

    facet and (optionally) a DEVICE donor (C) with a DIFFERENT

    device

    facet (read

    refs/tags.json

    facets to pick contrast deliberately). A must match the run's aspect — its skeleton carries the canvas geometry. B and C may come from EITHER aspect: type, palette, device and motion ideas are aspect-free, so a landscape run draws on portrait recipes and vice versa; re-derive every geometric number from that donor at this canvas. Execute per

    director-brief.md

    REMIX MODE in a fresh run dir

    runs/<key>-remix

    — then the same gates: lint → verify → record → probe → mux (commands in DESIGN + RENDER). Never a raw prefab, never an id outside the index.
  • RE-ROLL only when the user asks for VARIANTS, not for creative input: "show me more options", "another style", "make 5 different versions" (that's N draws — run them as N

    --seed

    s through DESIGN + RENDER variant A, parallel when N>1). Re-roll serves the user who never had an idea in the first place; the moment the ask carries ANY creative direction it is a REMIX, never a re-roll.
  • Defect repairs (typo, overlap, out-of-sync word) are neither — fix at the source, then re-run the gates. Creative-run output (face-1/REMIX — agent-authored) → patch the run's template directly. Recipe-run output → NEVER hand-edit the generated .wv document (generate-recipe.ts owns it): a text/timing defect = fix transcript/word-timings and re-run the script; placement-vs-footage = the refine path (ANALYSE); a deliberate one-run tweak = the CUSTOMISING

    --module

    copy (DESIGN + RENDER variant A).
  • A BRAND OR A SET GETS A FILE, NOT A PARAGRAPH. When the user supplies a brand, or several pieces are being made together, write

    brand.json

    beside the run (palette BY ROLE, colour law, type pair, the mark's file path and placement, and for a set the bone every piece keeps). Validate it with

    node --import tsx pipeline/scripts/brand.ts --file <brand.json> --check

    — it fails when a named mark is not on disk, which is what makes a design pass draw its own — and paste

    --brief

    into the design pass. Retyping the law per piece is how four cards drifted apart.
  • RECORD WHAT WAS REJECTED, AND WHY. Before starting another round on the same footage:

    node --import tsx pipeline/scripts/creative-log.ts --for <video> --reject "<what it was>" --why "<their reason>"

    and when something lands,

    --accept "<the aesthetic>" --why "<why it landed>"

    . Then start the next round by reading it back with

    --brief

    and putting that text in the design pass. It is keyed by the FOOTAGE, so rounds two, three and four inherit it, and it survives a compaction — which the same list carried in your head does not. Parallel attempts that converge on one idea are the complaint this exists to prevent.
  • A SCOPED EDIT MUST PROVE ITS SCOPE. When the user asks for one thing and says to leave the rest alone, copy the accepted document first, then check the result against it:

    node --import tsx pipeline/scripts/scoped-edit.ts <accepted.wv> <new.wv> --allow <selector-or-id>…

    It names every difference outside what you were allowed to touch, with both values. Run it before you say the change is done — "you moved something I told you not to move" is the correction this pipeline earns most often, and neither

    --verify

    nor probe-qa can see it: both documents render perfectly, one of them is just not what was asked for.

• ENGAGEMENT mode — pass the seed copy VERBATIM to DESIGN + RENDER (see below; wording changes output).
• ANIMATION LEVEL —

  word

  (default; almost always) /

  cue

  line (titles, or plain/corporate) /

  none

  (minimal/corporate). Respect any stated user preference; ask if genuinely unsure. (Recipe runs need NONE of these — the compiled recipe fixes engagement, animation, and design. A REMIX needs neither: its look comes from the donor sheets per the brief's REMIX MODE.)

open-edit

• before writing

  design/system.json

  ;
• before authoring any

  .wv

  document, and before each chapter of a longer piece;
• before adding or RESTYLING any caption, graphic, plate, chart, mark, title, end card or motion — a touch on one of those is an authoring touch however small it looks.

runs/<key>

• variant A (

  recipe=yes

  — every default run): SCRIPT — no agent, no model, zero tokens. The recipe is compiled code. (Rerun the SAMPLE ONE STYLE script if you no longer have its output — same run key → same result.) The classic route (SAMPLE ONE STYLE's CLASSIC POOL) is this same variant with

  --module refs/html/classic/<id>/recipe.ts

  appended.
• variant B (creative face-1; also refine re-runs after ANALYSE): INLINE — you execute the from-scratch contract (B below) YOURSELF, no subagent. A default run can NEVER route here: the runtime index is recipes-only, so an implicit draw always has a recipe.
• REMIX (face-2 creative iteration): INLINE — you author the donor blend yourself per

  director-brief.md

  REMIX MODE (no subagent), then drive the same gates by hand (commands below).
• NO VIDEO (see INPUTS): INLINE — neither PREP nor SAMPLE ONE STYLE ran, so there is no recipe to route to and nothing to route on. Write

  runs/<key>/design/system.json

  first (this path authors from scratch, so it needs a system as much as face-1 —

  groundedIn

  names whatever the run's own facts are: the brief, a script, a shot list), author per

  director-brief.md

  with the canvas and duration from the ask, then run

  bash pipeline/scripts/gates.sh runs/<key> --no-probe --no-mux

  — no source footage to diff frames against, and no source track to restore. If the run HAS a built soundtrack, pass

  --audio runs/<key>/audio/mix.m4a

  instead of

  --no-mux

  . A footage-free run is as supported as any other; what it lacks is a source file to derive from, not a path through this step. Place pictures with

  <img src="asset.png">

  — a file BESIDE the document renders,

  object-fit

  included (probe: img-file-src). A

  data:

  URI does NOT (probe: img-data-uri-blank), so write the bytes to the run and reference them by name rather than inlining them.

hasRecipe:true

node --import tsx pipeline/scripts/generate-recipe.ts --run runs/<key> --record

refs/html/<id>/recipe.ts

runs/<key>/final/{template.wv, manifest.json}

meta.json

word-timings.json

--verify

FAIL[bounds]

final/out.silent.mp4

--progress-output

probe-qa

--verify

--seed

--style

style.json

refs/html/<id>/recipe.ts

{repo}/pipeline/recipes/lib.ts

--module <copy path>

pipeline/director-brief.md

.wv

veed-engine-cli --verify

pipeline/director-brief.md

Author ONE captioned composition over the
footage as a single-timeline .wv document, verify it with --verify, then render it.
CONTRACT (obey exactly): READ {repo}/pipeline/director-brief.md — it is the full engine contract (paint order,
the opacity/stacking trap, the one safe reveal recipe, engine limits, the single-timeline mechanic, render+verify).
INPUTS:
  - {repo}/runs/{key}/meta.json — canvas W/H/fps + durationSec + paths (authoritative for the manifest).
  - {repo}/runs/{key}/analysis.json — ONLY IF IT EXISTS (refine runs): per-beat composition facts in CANVAS px
    (shot, subjectBbox, faceBbox, negSpaceRect, brightness, caption text + start/end/mid/midFrame). If present,
    COMPOSE FROM THESE NUMBERS. If absent (the default), compose from the transcript + the brief's safe
    margins. EITHER WAY you never read the frames.
  - {repo}/runs/{key}/transcript.json — captions + windows; chunks carry REAL per-word timings in
    `words: [{text, timestamp:[start,end]}]` — animate each word on ITS OWN window (fake by even-split
    ONLY in the unlikely case a chunk has no `words` array).
  - video {videoPath} (in meta.json).
METHOD: the USER'S MATERIALS below ARE the design authority — OPEN them (images/files included) and study
their design DNA: positions, fonts, weights, sizes, colours, letter-spacing, shadows, mood. Translate it into
an engine-safe system; adopt and REMIX, never copy their content verbatim. The CRAFT SUBSTRATE sheets are
validated, engine-proven recipes from our bank — lift their MECHANICS (timing idioms, grounding, width
budgets, engine workarounds), NOT their look, unless the user's materials point the same way.
USER MATERIALS (design authority): {paths / links / the user's described concept — whatever they brought}.
CRAFT SUBSTRATE (recipe sheets, engine-proven; nearest by facets):
  1. {repo}/refs/html/{idA}/recipe.md   2. {repo}/refs/html/{idB}/recipe.md
DIRECTION = {the aesthetic lane: content angle + mood + placement intent; NO fonts/palette/device}.
ENGAGEMENT MODE = {seed copy — verbatim}.
ANIMATION LEVEL = {word | cue | none}.
TASK: WRITE THE SYSTEM DOWN FIRST, then author against it.
  node --import tsx {repo}/pipeline/scripts/design-gate.ts {repo}/runs/{key}
  fails until {repo}/runs/{key}/design/system.json exists and every document obeys it. Author that file
  before any .wv: 2-3 Google @import fonts, a type LADDER (each rung a role + size + its own optical
  tracking — `opticalTracking(px)` in {repo}/pipeline/recipes/type.ts gives the measured curve), a named
  palette, spacing, NAMED easings and durations, the reveal unit, the devices in play, and `donors` =
  the recipe ids you took mechanics from (they are checked against the runtime index). `groundedIn` must
  name the run's own content files, and the gate refuses a system whose files do not exist — a design
  authored before the content is a design authored from nothing, which is exactly how a delivered film
  ended up with 23 font sizes and one easing curve used 934 times.
LEARN THE REPERTOIRE BEFORE YOU DESIGN ANYTHING. Open two or three ref folders under {repo}/refs/html/
  — the sheet AND the document beside it — and read what the engine is SHOWN doing: how a word is set
  at a different size from the words around it (a beat is a column of separate text blocks, not one
  styled line), how an underline is drawn, what arrows, brackets, corner marks, rules and badges look
  like when they are made well, which faces are already proven to render. Write down what you found and
  what you intend to use. This is a bank of what is POSSIBLE, not a template: look at how something is
  done, then do it better for the piece in hand. An agent that skips this designs from its own defaults,
  and its own defaults are a centred line of one size — which is the single most common reason a
  delivered piece reads as machine-made.
COMPOSE, don't type: {repo}/pipeline/recipes/devices.ts (dividers, ground shadow and the rest of the
  delivered vocabulary — a rule is a hairline + shadow + stub that DRAWS, never a lone grey line),
  {repo}/pipeline/design/captions.ts (per-word reveal off the real timings, travelling cursor, lines as
  blocks), {repo}/pipeline/recipes/geometry.ts (arcs, lattices, springs, clip polygons),
  {repo}/pipeline/recipes/type.ts (the ladder and the tracking curve).
  Contrast over footage comes from the two-layer ground shadow, NOT a scrim box.
PLACEMENT IS A DECISION, MADE PER BEAT AND WRITTEN DOWN. For every beat say where the block sits, WHY
  there — what is behind it, which way the subject faces, where the frame is empty — and what changed
  since the last one. A block that holds one position for a whole piece is the defect, not the default:
  two delivered runs shipped it, one with 217 cues in one box and one with six of eight cues on the
  same left edge, and in both the author's own reference notes said the block moves every beat.
  Emphasis is carried by the WORD that takes the beat, not by a phrase set in bolder type.
  With footage, the system's `placement.measuredIn` must name a file holding one entry per cue,
  measured off this run's own picture — the gate refuses the system otherwise, because grounding in
  the transcript and the cue times is grounding in the WORDS, and a run that did exactly that put six
  of eight blocks on one edge while believing it had measured everything.
NOT ACROSS THE FACE. Type passing BEHIND a person is the technique; type across their eyes is a
  mistake no amount of measurement excuses. One run scored its own coverage at 0.65 and 0.71, reasoned
  that nothing fit behind the speaker, and put the block in front — over his face in the opening shot
  and over his eyes in the last. When the clean ground runs out the answer is a smaller rung, a
  re-broken line, a different anchor or a later window, never the face. Read the face box off the
  subject's own silhouette (the head is the top of its bounding box) and keep it clear.
GRAPHICS GO WHERE THE CONTENT ASKS FOR THEM — not everywhere, and never as decoration. A number
  spoken in the script is the clearest invitation there is: a figure that arrives as type alone spends
  a beat saying what a count, a bar, a scale or a comparison would land. So is anything the speech
  describes that a picture states faster than a sentence. Whether to reach for them at all is settled
  by the material: if the reference carries graphics between the talking, that is both the permission
  and the measure of how much; if the user's ask implies them, the same. Where neither does, don't.
A DEVICE THAT APPEARS TWICE NEEDS A LOGIC. One run put two chapter marks in a thirty-second piece,
  both in its second half and none in its first. Each was fine alone; together they read as an
  accident, because nothing said when the thing appears. Either it follows a rule the piece keeps —
  every subject turn, every figure, every change of speaker — or it does not appear at all. And a
  device that recurs varies: same logic, different corner, different scale, so the second one is a
  system rather than a repeat.
LINES ARE SEPARATE BLOCKS, SO GIVE THEM DIFFERENT EDGES. A three-line beat whose lines all start at
  the same x is a paragraph, not a composition — one run printed `safeX` as the left edge of eight
  blocks in a row. The lines are already separate elements, which is what makes an indent, a hang or a
  step free; use it, and let the size change inside the block so one word carries the beat.
Hold the system across all beats; vary scale/composition per beat; escalate hook → close. Author ONE
{repo}/runs/{key}/final/template.wv (z0 base video FIRST; EVERY text layer position:absolute + explicit
z-index>=1 + a UNIQUE `id` e.g. id="cap3" — see the opacity trap; the id makes --verify name the element in
its failure lines; each caption visible only in its cue window) +
{repo}/runs/{key}/final/manifest.json {"render":{"width":W,"height":H,"fps":FPS,"duration":durationSec}}.
RENDER + VERIFY (OUTSIDE any sandbox — needs the window-server; binary = {repo}/.veed-engine/veed-engine-cli, NOT on PATH):
  DESIGN GATE (mechanical, no engine): node --import tsx {repo}/pipeline/scripts/design-gate.ts {repo}/runs/{key}
     — reads every .wv in the run back against design/system.json: a font, size, tracking, colour or
     easing the system does not declare is an error, as is a donor id that is not a real ref. Exit 1 →
     fix the document, or amend the system deliberately. Run it FIRST: every finding is a string in a
     file, and learning it after a record costs minutes of encode to discover what a regex knew instantly.
  LINT (mechanical, no engine): node --import tsx {repo}/pipeline/scripts/lint-template.ts {repo}/runs/{key}/final/template.wv
     — engine-limit anti-patterns (animated blur, the stacking trap, missing cue ids, per-corner radius).
     Exit 1 → fix the flagged rule, re-lint before verifying.
  VERIFY (analytic, fast, no video, reads manifest render block):
       {repo}/.veed-engine/veed-engine-cli {repo}/runs/{key}/final --verify
     It replays the whole timeline offscreen and checks the REAL draw list. Exit 0 = clean. Exit 1 = it prints ONE
     stdout line per problem, naming the element id, e.g.:
       frame 3 t=0.400s FAIL[bounds] #cap3 glyph 14 right 3.1px outside (8.42% of glyph box) viewport 736x1312
       FAIL[never-visible] #cap5 glyph 2 ink in 300 frames, never fully visible (best 0.00% at frame 0 ...)
       frame 2 t=0.200s FAIL[occluded] #cap2 glyph 5 fully covered by later opaque rect
     Built-in rules = the exact defects this pipeline hits: bounds (type off the viewport), never-visible (type
     clipped away in EVERY frame — e.g. stuck behind a mask/box), occluded (type fully hidden under a later opaque
     layer — the z-order/opacity trap). Fix ONLY the flagged element (nudge inside the safe zone / fix z-order or the
     mask) and re-run --verify until exit 0. (exit 2 = engine render failure = a real authoring error, not a nit.)
  EXPECT WINDOWS (optional) — word-reveal TIMING: to assert a caption is shown/hidden in a time window, add a "verify" block to
     manifest.json alongside "render": {"verify":{"expect":[{"element":"cap3","visible":true,"from":2.1,"to":3.4}]}}.
     --verify then FAILs[expect-visible]/[expect-hidden] if a word isn't on-screen when it should be. Use when a
     beat's reveal timing is subtle; ids only (a word with no id can't be targeted).
  WCAG PASS (DEFAULT on creative runs; level AA) — after --verify is clean, before recording. It
     DETECTS and REPORTS; it NEVER silently changes colours — the human chooses.
       node --import tsx {repo}/pipeline/scripts/wcag-pass.ts --run {repo}/runs/{key}
     It samples the REAL rendered background behind every caption, checks WCAG AA contrast, writes
     final/contrast-statistics.json (the policy-free statistics the verdicts and the recommendation
     studio are computed from), and STOPS. It prints `status: pass|attention` plus EXHAUSTIVE `review:`
     disposition lines (will fix / no colour satisfies / halo recommended / indeterminate — report these
     honestly). Exit 1 = tooling missing or crashed (fix the environment; see config.ts WCAG_* vars) —
     not a design failure.
     - `status: pass` → all caption text clears AA. Note it and move on.
     - `status: attention` → some caption text has low contrast. Tell the user in PLAIN PRODUCT TERMS:
       how many of how many text elements fail, and the worst offenders (from the `review:` lines). Then
       ASK which of these to do — do NOT pick for them, do NOT silently apply:
         (a) OPEN THE RECOMMENDATION STUDIO — curated, clickable colour/design options to choose from. It
             is served by the preview server (the PREVIEW step) at the /wcag/ route — if that server is
             running, open `http://127.0.0.1:<port>/wcag/` for the user (the port from the `preview:`
             line); only if no preview server is up, generate the static page instead:
               node --import tsx {repo}/pipeline/scripts/wcag/recommend.ts --run {repo}/runs/{key}
             (writes runs/{key}/final/wcag-recommendations.html — open that file).
             When the user CLICKS a choice, the studio writes runs/{key}/final/wcag-choice.json
             ({"schema":1,"chosen":[{level,group,kind:"colour"|"shadow"|"outline"|"background",hex,backingHex?,selector?}]}).
             READ that file to tell the user what they picked, then run the apply step (b) — a clicked
             choice always takes effect (wcag-pass sees the file and drives the applier with it).
             CHAT IS AN EQUAL PATH: if the user says what they want in words ("apply the AA corpus colour",
             "add a shadow halo behind the caption" → kind:"shadow"), WRITE the same wcag-choice.json shape
             yourself, then apply.
         (b) APPLY — promoted only on MEASURED improvement:
               node --import tsx {repo}/pipeline/scripts/wcag-pass.ts --run {repo}/runs/{key} --apply
             With a runs/{key}/final/wcag-choice.json present, --apply drives the applier from that explicit
             choice (colour / shadow / outline / background backing) and ALWAYS runs it; with NO choice file it falls
             back to the automatic hue-preserving colour set (value/saturation shift only, design identity
             kept), applied only where a colours-only fix is applicable. FINAL IS FINAL — no sibling dirs,
             no video artifacts; on promotion the remediated template becomes runs/{key}/final/template.wv
             and the file artifacts land inside final/: template.draft.wv (pre-remediation original),
             template.draft.wcag-remediated.wv (the remediation output), template.final.wv (clone of
             the shipping template on promotion), wcag-remediation.css (per-rule evidence),
             wcag-remediation-plan.json, contrast-statistics{,.remediated}.json. After promoting it re-runs
             --verify on final/ itself, and prints `status: pass|remediated|not-improved|residual` + the
             same EXHAUSTIVE `review:` lines.
         (c) LEAVE AS-IS — record the original unchanged.
  RECORD the deliverable — ONLY after --verify is clean, always FROM runs/{key}/final (whatever the
     user chose in the WCAG PASS already lives in final/template.wv — the untouched original, or an
     --apply promotion). --verify and --record are mutually exclusive, so this is a
     SECOND invocation:
       {repo}/.veed-engine/veed-engine-cli {repo}/runs/{key}/final --progress-output --record {repo}/runs/{key}/final/out.silent.mp4
     --progress-output prints `progress: N/M frames (X%)` lines during the record; recording is long-running —
     watch these to confirm it's alive, but don't narrate them to the user.
  Change NOTHING else — no aesthetic/colour/font/device/animation/timing edits. Author correctly up front (recipe +
  limits in the brief) so --verify passes first try; it is a safety net, not a design loop. (probe-qa — the
  mechanical frame QA — comes right AFTER the record step; it is not part of the verify loop.)
OUTPUT: {repo}/runs/{key}/final/{template.wv, manifest.json, out.silent.mp4}.
THEN (same turn, no pause): note the locked system so you can describe the delivered look in plain
terms (aesthetic, fonts, palette, device — not gate status), note the wcag status (pass / attention with
what the user chose — recommendation studio, --apply's remediated palette shift, or leave-as-is), and
continue straight to probe-qa + mux.

node --import tsx pipeline/scripts/probe-qa.ts runs/<key>

runs/<key>-remix

meta.json

transcript.json

word-timings.json

runs/<key>

key

meta.json

<key>-remix

type

device

refs/html/<id>/recipe.md

runs/<key>-remix/design/system.json

donors

runs/<key>-remix/final/{template.wv, manifest.json}

director-brief.md

bash pipeline/scripts/gates.sh runs/<key>-remix

--verify

--record

--verify

status: attention

/wcag/

wcag/recommend.ts

final/wcag-choice.json

wcag-pass.ts --apply

• scroll-stopping (default, social): "the first frame must STOP the thumb — big numbers, oversized, chrome/neon, saturated; optimize for a feed."
• wow: "push the WOW ceiling — oversized, bleed past edges, heavy effects."
• design-grade: "gallery-quality AND maximally engaging — high-design, premium, crisp."
• variety / bold-broadcast (good for 16:9 landscape): "loud broadcast / sports-lower-third energy; big type in the landscape thirds; heavy effects."

• veed-engine-cli is checked by PREFLIGHT — keep it current via

  bash pipeline/scripts/install-veed-engine.sh

  ; macOS-arm64 binary. Older builds lose features (e.g. pre-0.3 = no shadows = major degrade).
• Sandbox: PREP (veed/go.ts) needs network egress to

  *.veed.io

  — a sandboxed

  fetch failed

  there means the sandbox blocked the call; re-run it outside the sandbox. The DESIGN + RENDER step's engine

  --verify

  /

  --record

  always runs OUTSIDE the sandbox (it needs the window-server).
• Recipes are COMPILED CODE (

  refs/html/<id>/recipe.ts

  over the shared

  pipeline/recipes/lib.ts

  ), authored + validated OFFLINE, one-time per ref (derived from the ref's prose sheet

  refs/html/<id>/recipe.md

  — which doubles as the creative pass's craft-substrate/donor material) — the fast path only ever RUNS them via

  generate-recipe.ts

  . The runtime index is recipes-only, so implicit runs are always scripted end to end; the from-scratch inline pass runs only for creative face-1 (and refine re-runs).
• USER MATERIALS GET OPENED (creative face-1): the design pass OPENS and studies the user's files/links (that's the point). The opt-in ANALYSE pass stays the only agent that reads the FOOTAGE frames.
• Word timing is NEVER invented — DESIGN + RENDER pastes

  word-timings.json

  delays verbatim (compiled recipes do this by construction).
• The preview server (PREVIEW) is loopback-only and additive — if its default port 8978 is busy (an orphan from a dead session), it self-selects an ephemeral port; trust the URL it prints.
• TRANSCRIPTION WARNINGS (local provider) — read them precisely, same discipline as the font rules below. A WhisperX run prints a wall of

  Could not load libtorchcodec

  ,

  dlopen

  failures and

  Library not loaded: @rpath/libavutil.<N>.dylib

  for several FFmpeg majors, plus a Lightning checkpoint-upgrade notice. Those are pyannote probing FFmpeg builds it cannot find and are HARMLESS — they look fatal and are not. The signal that transcription actually worked is the line

  [transcribe] whisperx: <N> words -> <path>

  : if it appears, the transcript is written and you continue. If it does NOT appear, the run failed for a real reason — read the last error, not the dlopen wall.
• Rendering fetches Google Fonts over the network (the .wv documents use a

  <link>

  to

  fonts.googleapis.com

  ); an offline box = font fallback. FONT WARNINGS — read them precisely, don't chase noise:

  no data/font-cache seed found

  , generic-keyword lines —

  'sans-serif'

  ,

  'serif'

  ,

  'cursive'

  ,

  'monospace'

  ,

  'system-ui'

  unresolved by Google

  — and

  has no italic face; substituting upright

  come from unsourceable fallback-chain members and are HARMLESS. A warning naming YOUR display family (

  '<Family>' unresolved by Google — rendering with embedded variable fallback

  ) is REAL — the type identity is gone; stop and fix the import/network before recording. (The engine's bundled

  .veed-engine/data/fonts/

  registry ships as dead Git-LFS pointers in current releases — upstream packaging bug; only live Google fetches resolve real families.)
• Ref pool =

  refs/tags.json

  (v3, the RUNTIME INDEX — recipes only; every entry ships

  template.wv

  +

  recipe.md

  +

  recipe.ts

  ).
• DIRECTION never names fonts/palette/device — on creative runs those come from the USER'S materials (the design authority); craft-substrate sheets contribute mechanics only.
• Don't scan the bulk asset dir —

  refs/html/

  is data, not code. Never

  ls -R

  /glob it broadly; pick via

  refs/tags.json

  .