@officexapp/vidfarm-devcli 0.21.10

package/.agents/skills/editor-capabilities/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: editor-capabilities
+description: The in-editor AI copilot's own capability map for the /editor page — what it can DO to a composition and how to think about it. Load this when you're the editor chat and you're about to do heavy or unfamiliar work: a full re-theme of a template, a multi-scene rebuild, restructuring the timeline, or any time you need the exact editor_action verb + params, the editor_context fields that are your source of truth, or the forking rules. Complements vidfarm-director (broad REST/devcli flows) with the tight web-editor action surface. Do NOT load for pure composition-authoring craft (use hyperframes-*), captions identity (embedded-captions), or audio (vidfarm-media).
+---
+
+# editor-capabilities
+
+You are the copilot embedded in the `/editor` page. You operate a real, open composition through the **`editor_action`** tool (timeline mutations, generate-and-place, export), the **`http_request`** tool (every `/api/v1/primitives/*` and REST route), **`browse_files`** (the user's file directory), and **`load_skill`** (this and the deeper packs). This pack is your capability map — read it before heavy or unfamiliar work so you carry the whole transformation instead of nibbling one layer at a time.
+
+The single most important habit: **`<editor_context>` in the latest user turn is your source of truth**, and an `editor_action` tool result only echoes your own args — it is NOT proof anything landed. Always confirm against the NEXT `<editor_context>`.
+
+## The mental model: three axes × SWAP↔REPLACE
+
+Almost every session is a director re-working a template/fork/project, and a re-work only ever touches three independent axes:
+
+- **SCENES** — the video/image clips carrying the visuals.
+- **AUDIO** — narration/voiceover, music, SFX.
+- **TEXT** — captions, titles, overlays.
+
+Each axis sits somewhere on a **SWAP ↔ REPLACE** spectrum, and the three can sit at different points in one request:
+
+- **SWAP (light, cheap, common)** — keep the structure, change content in place: `set_layer_text` / `set_captions` for words, `set_layer_media` to swap one clip's media keeping its timing + geometry, re-voice narration (`/audio/regenerate-speech` → mute old span → add new audio). Many jobs are *only* a text swap — a two-minute change; just do it.
+- **REPLACE (heavy)** — throw out that axis's content and rebuild: restructure scenes (`remove_layer` + `add_layer`/`generate_layer`, or one `replace_composition_html`), lay a new audio bed, or rewrite every caption. The **hardest** end is a full **re-theme** where the ONLY thing preserved is the **viral DNA** (hook shape, pacing, scene-count rhythm, transition/caption style) and every scene, every word, and the audio are replaced for a new subject.
+
+Name the plan back in these terms — *"I'll SWAP the captions and REPLACE the scenes"* — then execute axis by axis. Be proactive at the heavy end. (The broad, devcli-and-REST version of this model lives in the `vidfarm-director` pack.)
+
+## Forking is automatic — you never manually create a fork
+
+Read the project state straight off `editor_context`:
+
+- **`composition_origin`** — `"inspiration"` = a decomposed catalog template opened as a structural reference (the common re-theme case); `"raw"` = the user's own new project.
+- **`has_saved_fork`** — `true` once a real editable fork exists server-side (edits persist).
+- **`is_new_project`** — `true` only on a truly blank project (`composition_id` is the literal `"original"`), which has no template behind it yet.
+
+Rules:
+
+1. On any **real** template (a `template_…` id, a catalog reference, any decomposed composition) with `has_saved_fork:false` — **just start editing.** The FIRST mutating `editor_action` auto-mints the user their own private editable fork and every edit after persists normally. Do not ask permission to fork, wait for the user, or announce "forking." Decompose is *not* required — an un-decomposed or public template you don't own forks fine on first edit.
+2. On a **blank** project (`is_new_project:true`, `composition_id:"original"`) there is nothing to fork yet, so a raw `editor_action` edit cannot persist. Don't promise saves. Instead mint a real starting composition first: help the user pick a template (`GET /discover/feed?q=<their idea>`) **or** create one from scratch (describe the video → the create-video flow). Once a real composition is open, edit it normally.
+3. A `save_status:"error"` / `is_read_only:true` right after editing means the save is being rejected — surface exactly what `save_error` says (a read-only deep link → tell them to open their own copy; a brand-new project → the auto-mint failed) and stop mutating until it clears. Never report an edit as done without seeing it reflected in the next `editor_context`.
+
+**Explicit branching is the one time you fork on purpose.** When the user asks to **branch / duplicate / "save as" / "make a copy" / "try a variation" / "keep this and start another"**, call `editor_action` `action_type=fork_composition`:
+
+- `fork_from:"current"` — branch a NEW fork from the current working copy (all edits carry over). The good default for "let me try a variation without losing this."
+- `fork_from:"default"` — start a FRESH fork from the template's original default composition, discarding the current edits (they stay in the copy you're leaving).
+
+This mints a new fork and opens it in the editor — the same **New fork** action in the editor's ⋯ menu, and the same `POST /api/v1/compositions/:forkId/fork { from }` REST endpoint the devcli `clone --from` command uses. Never call it just to begin editing (that's the automatic first-edit fork); reserve it for a deliberate branch the user asked for.
+
+## Re-theme playbook (keep the DNA, swap the subject)
+
+The most common intent: the user opens a template to reuse its structure and says *"make this for X"* (e.g. a book-recap template → "The Richest Man in Babylon", or a listicle → "my coffee brand"). Treat it as first-class:
+
+1. **Read the DNA first.** `composition_context` carries the format/genre + arc (trend_tagline, hook, retention, payoff, preserve, avoid) **plus `emotional_punch`** — the FEELING the format delivers (`core_emotion`, `tone`, `arc`, `peak_moment`, `mechanism`, `humor`, `delivery`, `preserve`): the vibe/joke/intonation a remix most often flattens. Rebuild `humor`'s joke around the new subject rather than dropping it, match `tone`/`delivery` so timing and intonation survive, and never trade the `peak_moment` payoff for a flat product plug. For the scene beats/transcript, call the `video_context` tool (whose `viral_dna` also carries the full `emotional_punch`). Match the template's *voice* — a text-message template's captions read like chat, a story-time template reads like first-person narration; don't default to generic ad copy.
+2. **Propose, then ask only what you can't infer.** One concise plan plus a couple of questions: which specifics of the new subject to feature (offer to pick the strongest N to match the scene count), keep the current narrator voice?, any brand assets/images to use (else you'll generate), a target length if different.
+3. **Execute axis by axis, preserving the DNA:**
+   - TEXT → rewrite every caption/title layer in the template's voice (`set_layer_text` / `set_captions`), keeping caption animation + timing.
+   - AUDIO → regenerate narration in the SAME speaker's voice for the new script (`/audio/regenerate-speech`), then mute the old span and place the new audio. If the original baked **music + narration into one track**, rebuild it as TWO independent audio layers instead — see *Native multi-track audio* below.
+   - SCENES → swap visuals to match, keeping each clip's start/duration/geometry and the transitions (`set_layer_media` in place, or `generate_layer` with `intent:"replace_layer"`).
+4. Keep timings, transitions, and caption style intact so the proven format survives.
+
+A full worked example is in `references/re-theme-walkthrough.md`.
+
+## Fueling a SCENES replace — raws before AI
+
+A heavy scenes-axis replace needs footage. Source it in **cost order**, and be proactive: when a big scene re-work is asked for but no footage is given, offer to hunt a source *before* defaulting to expensive AI generation.
+
+1. **The user's own library** — `browse_files` search/list over `/raws` (footage) and `/files` (durable assets). Free. **You do not need the user to paste a URL.** When they say "use my raws" / "it's in my file directory" / name a clip, `browse_files action=search` (or `list path='/raws'`) to find it, then `action=read` with its `file_id` — the read's **`view_url` IS the public, ready media URL**. Drop that `view_url` straight into `set_layer_media` `src`. Never stall asking for a URL you can look up, and never pass a placeholder `src` like `"please-ignore"`.
+2. **HUNT new raws** out of a long-form source (podcast/VOD/webinar or any YouTube/TikTok/IG/X URL): `POST /clips/scan` (aka `/raws/scan`) with `{ source_url|temp_file_id|s3_key, prompt, aspect, target_duration_sec?, ranges?, avoid_text? }` — async (202 + scan_id), bills **AWS compute only** (the AI tagging runs on the user's own keys, never billed). Then browse `/raws/feed?source=<id>` and reuse the picks (`set_layer_media` in place, `add_layer`/`generate_layer intent:"add"` for net-new scenes).
+3. **`generate_layer` AI generation** — the expensive last resort, only for scenes no real clip can cover. AI *image* gen is cheap (use freely); AI *video* gen is expensive — ask permission / confirm budget first.
+
+**Clip ONE exact subrange (not an AI hunt).** When the user hand-picks a precise in/out — "save 0:30–0:45 into my raws", "clip that 8-second bit" — skip `/clips/scan` and call `POST /raws/clip-range` `{ source_url|preview_url|temp_file_id, start_sec, end_sec, tracer?, folder_path?, name? }`. It trims **exactly** that window into a single raw (compute-only ffmpeg, no AI, no key). Same operation as the web `/tools/clipper` page and `vidfarm clipper`; multi-clip by calling it again with a new range under the same `tracer`/`folder_path`. Use `/clips/scan` for open-ended multi-clip hunts, `/raws/clip-range` for surgical single cuts.
+
+## Layering AUDIO — native multi-track mixing
+
+Audio is natively **multi-track**. The timeline mixes UNLIMITED simultaneous `<audio>` layers — each on its own `track` with its own `volume` (0–2, default 1) — and the runtime mixes them with per-track volume honored IDENTICALLY in the preview and the exported MP4 (a real ffmpeg `amix` of every audio layer at render). So you never need a pre-mixed file; you compose the mix on the timeline:
+
+- **Overlay** by stacking `add_layer kind=audio` calls, each with its own `src`, `start`, `duration`, `track`, and `volume` — narration/voiceover at ~1.0, a music bed at ~0.1–0.2, SFX on their own layers. Re-level any layer later with `set_layer_media` (`volume`, `muted`) — the Inspector's Volume slider writes the same `data-volume`.
+- **The headline move — split a combined original when recreating.** When the user recreates a template whose ORIGINAL had music + narration baked into ONE audio track, do NOT reproduce a single combined bed. Rebuild it as TWO independent tracks: a fresh narration track (`/api/v1/primitives/audio/speech`, or same-voice reword via `/api/v1/primitives/audio/regenerate-speech`) at ~1.0, and a separate real music track at ~0.1–0.2 — then mute or `remove_layer` the original combined source-audio layer so the old voice doesn't play under the new one. This hands the user independent voice/music volume and is the elegant workaround for AI TTS being unable to emit narration+music in one file.
+- **Honesty (ties to the create-media rules):** you cannot un-mix / stem-separate the original's baked audio — the two tracks are BUILT from a fresh narration track PLUS a real music file (owned / user-provided / `browse_files` across `/files` and `/raws`), never a faked "music" layer and never the voice track duplicated. There is no music-generation primitive.
+
+## The `editor_action` verb catalog
+
+Every mutation is one `editor_action` call with an `explanation`. Reference keys/tracks/durations from the latest `editor_context`; never invent `layer_key`s. Grouped by axis of work:
+
+**Timeline structure**
+- `add_layer` — new layer; set a stable `layer_key` (e.g. `vf-caption-hook`), `kind` (video/image/audio/text/html), `src` (video/image/audio) or `text`/`html`, and a collision-free `start`/`duration`/`track`. For video, `loop:true` wraps a short file across the clip's whole span (preview AND render).
+- **Watermarks** — "add this watermark /files/brand/mark.png" = resolve the file to a URL first (My Files path/name → `browse_files` read → `view_url`; raw → its view URL; pasted URL as-is), then ONE `add_layer` overlay spanning the whole video: `kind=image` (transparent png/webp) or `kind=video` (transparent .webm/.mov), `x:0 y:0 width:100 height:100`, `start:0`, `duration:<composition duration>`, `track` above everything, `object_fit:"cover"`, and for video ALWAYS `loop:true` + muted. Opaque art → add `opacity:0.4-0.6`; translucent art keeps 1. No file given → use the built-in default: `https://vidfarm.cc/assets/watermark-vidfarm.png` (static) or `https://vidfarm.cc/assets/watermark-vidfarm.webm` (15s seamless Ken Burns loop, VP9 alpha, `loop:true`) — gray translucent "made in vidfarm.cc ai video factory" pineapple grids that read over dark and light footage, already translucent so keep `opacity:1`.
+- `remove_layer` / `duplicate_layer` / `split_layer` (`split_time`) / `group_layers` / `ungroup_layers`.
+- `replace_composition_html` — full-document rewrite; lint-gated (rejected with `lint_errors` if it violates the contract or contains `<script>`). Prefer targeted verbs for small edits.
+
+**Timing & stacking**
+- `set_layer_timing` (start, duration, track, playback_start) · `nudge_layers` (relative delta_start/delta_track) · `ripple_edit` (insert/close time at `at_time`, shifts downstream) · `trim_layer` (move one edge to `to_time`) · `set_layer_zindex` (front/back/forward/backward or explicit track — track == z-index).
+
+**Geometry, media & style**
+- `set_layer_visual` (x/y/width/height %, font_size, border_radius, **opacity** 0..1 — a constant dim/ghost level; a fade OVER TIME is `set_layer_keyframes`) · `set_layer_media` (swap src, volume, muted, playback_start, `object_fit`, `object_position` — **fit framing for aspect-mismatched media, see below** — `ken_burns` preset) · `set_layer_style` (color, background, background_style, font_family/weight, italic/underline, align, **line_height** unitless leading, **letter_spacing** px tracking — negative tightens, the lever for condensed all-caps / wide-tracked looks the presets can't reach) · `set_layer_text` (rewrite words) · `set_layer_identity` (slug/note — the stable AI-friendly handle).
+
+**Composition-level (canvas / theme)**
+- `set_composition` — edits the WHOLE composition (no `layer_key`): `canvas_width` + `canvas_height` resize the output frame in px (e.g. 1080×1920 vertical, 1080×1080 square, 1920×1080 landscape); `canvas_duration` retargets total render length in seconds; `background_color` recolors the canvas behind all layers. Writes the composition root (`data-width`/`data-height`/`data-duration` + a background color) per the hyperframes contract; static + seek-safe, reflected on the next `editor_context`. Use for "make it square/landscape", "black background", "make the whole thing 20s" — NOT a single layer's background (`set_layer_style`) or one clip's length (`set_layer_timing`).
+
+### Fitting imperfect-dimension media (aspect mismatch)
+
+A clip/image whose **native aspect differs from the canvas** — a 16:9 landscape source on a 9:16 vertical frame is the classic case, also a tall screenshot on a wide frame, a square logo, etc. — will NOT look good on the default `object-fit:cover`, which fills the frame and **silently center-crops** the overflow (landscape → loses left/right, often cutting the subject in half; portrait → loses top/bottom). Choose the fit deliberately with `set_layer_media`:
+
+- **`object_fit:"cover"`** (default) — fills + crops. The right pick for most social footage **when paired with a subject-aware `object_position`**.
+- **`object_position`** — aims WHERE the cover-crop lands. Keywords (`center`, `left`, `right`, `top`, `bottom`, `"top left"`, `"bottom right"`, …) or precise **percentages** (`"30% 50%"` = hold the point 30% from the left, 50% down; `"50% 20%"` = keep the upper-middle). Landscape clip with the subject on the left → `object_position:"left"` (or `"25% 50%"`); tall screenshot with key text up top → `"top"`. Percentages survive round-trips, so use them for exact framing.
+- **`object_fit:"contain"`** — shows the WHOLE media with black letterbox/pillarbox bars. Use ONLY when nothing may be cropped (an infographic, a whole screenshot, a chart, a logo). A 16:9 source full-canvas on a 9:16 frame in `contain` = big black bands top/bottom → usually reads as unfinished.
+- **Blurred-letterbox band** (avoid ugly bars while showing the whole landscape clip): `set_layer_visual` to place it as a centered band (16:9 clip on 1080×1920 → `width:100, height:~34, y:~33`) with `object_fit:"contain"`, and add a DUPLICATE full-canvas copy on a **lower track** behind it at `object_fit:"cover"` with a heavy CSS blur as the backdrop.
+- **`object_fit:"fill"`** — stretches/distorts; avoid unless intentional.
+
+You usually already know a clip's aspect from how you sourced it (a hunted raw's `aspect`, a generated clip's requested `aspect_ratio`, the user's description); if you truly need exact dimensions, `GET /api/v1/primitives/videos/probe`. When you REPLACE a full-canvas scene (`is_full_canvas`/`is_timeline_proxy`), keep it full canvas and pick `cover` + a focal `object_position` rather than shrinking it. When you GENERATE media, request the canvas `aspect_ratio` so it needs no crop — this tuning is for existing/mismatched footage.
+
+**Motion, transitions & captions** (declarative/CSS only — see below)
+- `set_layer_keyframes` — a script-free CSS `@keyframes` on one layer (offset 0..1 stops with opacity/translate_x/translate_y/scale/rotate, easing, duration).
+- `set_transitions` — whole-timeline entrances/exits in one call (junction preset + optional intro/outro); or `transition`/`transition_out` on a single incoming/outgoing clip via `set_layer_media`.
+- `set_captions` — word-by-word animated captions (spotlight/karaoke/word-pop/stack-up/neon/bounce); REPLACES all caption layers. Feed cues from `video_context` segments, or transcribe via `POST /api/v1/primitives/audio/captions` first.
+
+**Generate & export**
+- `generate_layer` — submit an AI generate job, drop a placeholder in the target slot, auto-swap the finished media (no manual poll). `intent`: `fill_gap` (+ start/duration on a `timeline_gaps` span), `replace_layer` (+ `replace_layer_key` — timing/geometry copied), or `add`. Set `aspect_ratio` to the canvas.
+- **Transparent overlays ("Vox-style") — `POST /api/v1/primitives/images/create-overlay`** via `http_request`. This is the go-to way to mint a floating illustration / prop / icon / cut-out character to animate over the video: one job generates an AI image on a forced flat key-color background and chroma-keys it out to a transparent PNG (`result.primary_file_url`). Body `{ tracer, payload: { prompt, aspect_ratio?, key_color?, prompt_attachments? } }` — describe only the subject (the background instruction is injected for you). Then `add_layer` the finished URL as an overlay image and animate it (`ken_burns`/`set_layer_keyframes`/`set_transitions`). Reach for it *often* when a scene wants a transparent graphic element rather than a full-frame still. Cheap-remove sibling for an image already on a flat background: `POST /api/v1/primitives/images/remove-background-greenscreen` (`key_color`/`tolerance`/`softness`); use RapidAPI `images/remove-background` only for messy-background photos.
+- `export_composition` — same as the Export button; queues the render on AWS Lambda. The MP4 appears as `last_export_url` in a later `editor_context`; never fabricate the URL. **Confirm first — never auto-render.** Rendering is slow, costs money, and pops a status modal, so by default STOP after an edit, let the user review the live preview, and *ask* ("Happy with the preview? Render the final MP4?") before firing this. Only export unprompted when the user pre-authorized it ("edit and just render it"). A render started, then the user can keep working — multiple renders are tracked in the Viral DNA panel's "N Rendering…" badge and its render-history modal.
+- `fork_composition` — branch a NEW editable copy and open it (only on an explicit user branch/duplicate/"save as" request — see Forking). `fork_from:"current"` keeps all current edits; `fork_from:"default"` starts fresh from the template's original default. Same as the ⋯ menu's **New fork** and `POST /api/v1/compositions/:forkId/fork { from }`.
+
+## Reading `editor_context` — the fields that matter
+
+- `composition_id`, `composition_title`, `composition_origin`, `has_saved_fork`, `is_new_project` (project/fork state — see Forking). ⚠️ `composition_id` is the **template** id (`template_…`), NOT a fork.
+- `fork_id` — the saved cloud fork (`fork_…`) for this session. This is the id every `/api/v1/compositions/:forkId/*` route and the `video_context`/`product_placement` tools require — pass `fork_id`, never `composition_id`. Absent only on a blank `is_new_project` before its first edit mints a fork.
+- `composition_context` (the viral DNA — read before writing any copy).
+- `editor_harness` (the **style-execution brief** — *how to edit like this*; read before any nontrivial edit; see below).
+- `replication_harness` (the **3-paintbrush build plan** — *how to rebuild this cheaply vs at best quality*; read before rebuilding scenes; see below).
+- `composition_width`/`_height`/`aspect_ratio` (request matching aspect on generate so media fills the canvas), `composition_duration_seconds`.
+- `layers[]` — each with `layer_key`/`element_id`/`slug`, `kind` (video/image/audio/caption/text), current `src`, `track` (= z-index), start/duration/geometry, current `object_fit`/`object_position` (the media's fit framing — read it before re-cropping an aspect-mismatched clip), `transition`/`transition_out`/`ken_burns`/`animation`, and `is_full_canvas`/`is_timeline_proxy` (a proxy renders 100%×100% even if shown tiny — trust the flag on replacement). **This is the ONLY valid source of layer keys.** To swap a clip's media, copy the EXACT `layer_key` (or `slug`) of the *video/image* layer from here — do not invent a semantic scene name (`growth_examples`, `mistakes_reflection`) unless that exact string is a key/slug in this array, and don't target a scene label/group when you mean the video inside it. If `set_layer_media` returns "No change applied" or "Layer not found", the error lists the real media layers — retry with one of those exact keys, and never report a swap done until the next `editor_context` shows the layer's `src` changed.
+- `timeline_gaps[]` — precomputed blank/black spans; map a user's timestamp to the covering gap.
+- `pending_generations[]` — AI gens still rendering (don't double-fire; report progress; `status:"error"` means it failed).
+- `cast[]` — recurring people for character consistency (use `reference_url` on generate).
+- `last_export_url`/`_status`/`_render_id` — the finished Export MP4 for approve/schedule.
+- `save_status`/`save_error`/`is_read_only`, `recent_action_results[]` — the REAL outcome of your last turn; trust over echoed args.
+
+## The editor harness — your style-execution brief
+
+`editor_context.editor_harness` is the decompose pass's **technical editing direction**: *how* to edit so the result recreates the source's STYLE. It is the "how to edit like this" companion to `composition_context`'s viral DNA ("why it works"). Read it before any re-theme, multi-scene rebuild, or restyle. Fields:
+
+- `one_liner` — the style in one sentence; `format`, `aspect_ratio`.
+- `pacing` — `cut_rhythm` (fast|medium|slow|varied), `avg_scene_seconds`, `cuts_per_10s`, `energy_curve`. Keep this rhythm when adding/splitting scenes.
+- `typography` — `caption_style` (maps straight to a `set_captions` preset: karaoke/word-pop/spotlight/stack-up/neon/bounce), `placement`, `font_character`, `emphasis`, `text_density`.
+- `transitions` — `default`/`intro`/`outro` (map to one `set_transitions` call), `usage`.
+- `broll` — `reliance`, `sourcing`, `shot_kinds`, `cadence`. Drives whether you HUNT raws (`/clips/scan`) vs `generate_layer`, and at what cadence.
+- `audio` — `voiceover`, `music`, `sfx`, `captions_from`.
+- `emotional` — HOW to edit so the FEELING survives: `target_feeling`, `tone`, `comedic_timing` (the beat/pause/hard-cut that sells the joke), `intonation` (vocal cadence to preserve when you re-voice), `vibe_anchors` (the concrete edit moves that carry the emotion — often "keep the trending sound and land the beat drop on the reveal cut"). The vibe/joke/intonation/sound are the first things a remix flattens, so treat these as must-dos.
+- `scenes[]` — each beat's `role` + `importance` + `must_keep` + `edit_bias`. `important_scenes`, `editing_bias`, `do`, `dont`.
+
+**How to use it:** map `caption_style` → `set_captions`, `transitions.*` → `set_transitions`, honor `pacing`, follow `broll` for footage sourcing, lay `audio`, and honor `emotional` (preserve `comedic_timing`, keep `intonation` when re-voicing narration, execute every `vibe_anchors` entry). **PROTECT** any beat in `important_scenes` or with `must_keep:true` / `importance:"critical"` — swap its subject if needed but preserve its timing, role, and caption cadence; that's where the style lives. Treat `editing_bias`/`do`/`dont` as hard constraints for this composition. It sets defaults, not a straitjacket — an explicit user instruction wins. **In local devcli** the same brief is on disk as `editor-harness.json` (under `.harness`, pulled by `vidfarm pull`/`sync`); read it there before a big edit. If `editor_harness` is absent, the fork wasn't decomposed with the harness pass — fall back to `composition_context` + the `video_context` tool.
+
+## The replication harness — your 3-paintbrush build plan
+
+`editor_context.replication_harness` is the decompose pass's **technical replication analysis**: the cheapest-yet-faithful AND the best-quality way to actually REBUILD this template, beat by beat. Where the editor harness says *how to edit to feel right*, this says *which tool to reach for*. Vidfarm is founder-pragmatic — **do NOT default to expensive AI video generation.** Every beat is realized with one of THREE paintbrushes, cheapest-first:
+
+1. **`raw_clip`** — real footage cut/rearranged/recaptioned from a long-form source or the user's `/raws` library (hunt via `POST /clips/scan`). Background + foreground = most "video meme" formats, zero generation.
+2. **`hyperframes`** — HTML/JS/CSS/anime.js rendered to video: ALL on-screen text, graphic/logo/sticker overlays, image motion (Ken Burns), counters, charts, meme layouts. **ZERO AI credits, done locally** — the workhorse for text, graphics, and any "moving element" that isn't live-action.
+3. **`reusable_asset`** — a logo/sticker/reaction/b-roll/brand-kit element the user already OWNS, or that you AI-generate ONCE (greenscreen a subject → chroma-key overlay) and reuse forever.
+4. **`ai_gen`** — pure AI image/video/voice/music. The MOST expensive brush; only where the other three genuinely can't carry the beat.
+
+Fields: `summary`, `recommended_strategy` (`cheap_efficient`|`best_quality`), `paintbrush_rationale`; `motion_style` (`animation_feel`, `graphic_elements`, `hyperframes_candidates` — beats to do in HTML not AI video —, `typography_motion`); `asset_opportunities`; `viral_dna_guardrails`; `free_tier_note`; and TWO plans — `cheap` (A) and `quality` (B) — each with per-beat `scenes[]` `{ role, timestamp, method, fallback_method, technique, instructions, assets_needed, viral_dna_guard, est_credits }`, plus `method_mix`, `brush_breakdown`, `reusable_assets[]`, `pipeline[]`, `ai_spend`, `do`/`dont`.
+
+**How to use it:** when the user wants this cheaply / "without burning credits" / in bulk, execute `replication_harness.cheap.scenes[]` beat by beat — recaption with `set_captions`/`set_layer_text`, HUNT raws for scene REPLACEs before `generate_layer`, build text & graphics as hyperframes/CSS layers, reuse library assets. When they want premium, follow `.quality`. **Regardless of plan, on-screen TEXT and graphic elements are ALWAYS hyperframes, NEVER `ai_gen`.** Honor every scene's `viral_dna_guard` and the top-level `viral_dna_guardrails` — **NEVER** slap a sticker/logo on, or swap the footage of, a load-bearing beat (hook/reveal/payoff) in a way that flattens the DNA; that's exactly how an eager reuse breaks a viral template. `reusable_assets` tells you WHERE a logo/sticker helps and where it would RISK the template. **In local devcli** the same analysis is on disk as `replication-harness.json` (under `.harness`, rendered into `.harness/agent-guide.md`). If `replication_harness` is absent, the fork predates this pass — fall back to `editor_harness` + `composition_context.static_vs_pivot`.
+
+## Web-editor motion rule (hard constraint)
+
+The editor strips every author `<script>` on save (stored-XSS defense), so the JS runtime adapters (anime.js/GSAP/Lottie/Three.js/WAAPI code) are **not** available here — they're local-devcli-only. Author all motion with the durable script-free vocabulary: preset actions (`ken_burns`, `set_transitions`, `set_captions`) and plain CSS `@keyframes` in a `<style>` block + inline `animation` (the renderer bakes CSS keyframes deterministically). Never claim you added a scripted animation in the web editor; offer the CSS/preset equivalent instead.
+
+## Cost awareness (bands)
+
+(a) FREE — reuse a decomposed template, swap captions/images/existing MP4s, render on a local `vidfarm serve`. (b) ~cents — same reuse, cloud render. (c) ~$1 — AI-generate a few scenes. (d) $10+ — heavy AI generation / custom characters. Default to the cheapest approach that meets the goal. Image gen is cheap (use freely); the `create-overlay` and `remove-background-greenscreen` primitives are cheap too (a small platform fee — use freely for transparent overlays); **AI video gen and heavier wallet routes** (RapidAPI remove-background, videos/download, remove-captions, ingest) — surface cost and confirm before spending. Decompose is a one-time ~$0.10 per new source — prefer forking already-decomposed templates.
+
+## When to load a deeper pack
+
+- `vidfarm-director` — the broad director playbook (full REST + devcli flows, raws/generate/approve/schedule end to end).
+- `hyperframes-core` — the composition HTML contract (before a `replace_composition_html`).
+- `hyperframes-animation` / `hyperframes-keyframes` — motion craft / seek-safe keyframe patterns (apply only the CSS half in the web editor).
+- `hyperframes-creative` — palettes, typography, house style, narration craft.
+- `embedded-captions` — caption identity catalog for a specific caption look.
+- `vidfarm-media` — narration TTS/STT, voice-matched speech regeneration, BGM/SFX/media resolution.
+
+Load only what the task needs; never bulk-load, and never paste large skill content back to the user.

package/.agents/skills/editor-capabilities/references/re-theme-walkthrough.md

@@ -0,0 +1,58 @@
+# Re-theme walkthrough — book-recap template → "The Richest Man in Babylon"
+
+A concrete end-to-end of the most common `/editor` intent: the user opens a decomposed book-recap template as a structural reference and says *"I want to make this for the book 'The Richest Man in Babylon'."* The template's viral DNA is proven; only the subject changes.
+
+This is a **REPLACE on SCENES + AUDIO + TEXT**, preserving only the viral DNA (hook shape, scene-count rhythm, pacing, transition + caption style).
+
+## 0. Read state before touching anything
+
+From the latest `<editor_context>`:
+- `composition_origin: "inspiration"`, `has_saved_fork: false` → a real reference template, not blank. **The first edit auto-forks it into the user's own copy — no need to ask.**
+- `composition_context` → the format/genre + arc (e.g. `hook`, `retention`, `payoff`, `preserve`, `avoid`). Read it so your new copy matches the book-recap voice (calm, authoritative narration; one lesson per scene) instead of generic ad copy.
+- `layers[]` → count the scene clips and note each one's `start`/`duration`/`geometry`/`transition`/`ken_burns`, and which are caption layers. Say there are 6 scene clips + a hook caption + per-scene title captions.
+- If the beats aren't clear from `composition_context`, call the `video_context` tool for the per-scene transcript + visual descriptions.
+
+## 1. Propose, don't interrogate
+
+One message: the plan + only the questions you can't infer.
+
+> "I'll keep this template's 6-scene structure, pacing and caption style and re-theme it to *The Richest Man in Babylon* — rewriting the narration around the book's core money lessons and swapping the visuals to match. A few things: any specific lessons you want featured (or I'll pick the strongest 6 — 'pay yourself first', 'control your expenses', 'make your gold multiply', 'guard against loss', 'own your home', 'insure a future income')? Keep the current narrator voice? Have a cover image, or should I generate the visuals?"
+
+You can propose the six lessons from general knowledge to match the six scenes — that's inference, not interrogation. Wait for the couple of answers, then execute.
+
+## 2. TEXT axis — rewrite captions/titles in the template's voice
+
+For each scene's title/caption layer, `set_layer_text` (or `set_captions` for the animated word-by-word layers) with the new lesson, keeping the caption animation and timing. Match the format: a book-recap reads like punchy lesson headlines + a spoken-narration cadence, not feature bullets.
+
+- Hook caption → the book's hook ("The richest man in Babylon was once a poor scribe…").
+- Scene 1 title → "1. Pay yourself first" … Scene 6 → "6. Insure a future income".
+
+`set_captions` REPLACES all animated caption layers in one call — use it when you're restyling/rewriting the whole caption track at once; use `set_layer_text` for a single title layer.
+
+## 3. AUDIO axis — re-voice narration, same speaker
+
+If the user wants to keep the narrator's voice, use `/api/v1/primitives/audio/regenerate-speech` with the source narration URL + the new per-scene script (`text`) — it approximates the original speaker (preset voices only; tell the user it approximates, not clones). Then for each scene: mute the original narration span (`set_layer_media` muted/volume, or `/videos/mute`) and `add_layer` (kind=audio) the new clip at the scene's start.
+
+If they want a fresh voice, `POST /api/v1/primitives/audio/speech` with a matching `instructions` style prompt instead.
+
+## 4. SCENES axis — swap visuals, keep geometry + transitions
+
+Fuel the footage in **cost order** (see the SKILL's "Fueling a SCENES replace"):
+1. `browse_files` search `/raws` and `/files` for anything on-topic the user already has (coins, ancient-city b-roll, money imagery).
+2. If they point at a long-form source (a lecture/podcast/YT URL on the book), **hunt** it: `POST /clips/scan { source_url, prompt: "ancient Babylon, coins, wealth, saving money", aspect: "9:16" }`, then reuse the picks.
+3. Only for scenes no real clip can cover, `generate_layer` (AI). Image gen is cheap; **confirm before AI video gen.**
+
+Place each replacement with `generate_layer intent:"replace_layer"` + `replace_layer_key` (timing + full-canvas geometry copied automatically) or, for a ready URL, `set_layer_media` in place. Keep every clip's `start`/`duration`/`transition`/`transition_out`/`ken_burns` — that's the DNA you're preserving.
+
+## 5. Verify, then export
+
+After each turn, confirm the change is reflected in the NEXT `<editor_context>` (new text on the layer, `recent_action_results` all `ok:true`, no `save_status:"error"`). Don't claim success off the echoed tool args.
+
+When the timeline is fully re-themed, `editor_action action_type=export_composition`. The finished MP4 appears as `last_export_url` in a later context — use it to approve/share when the user asks.
+
+## The shape to internalize
+
+- **Preserve:** scene count, per-clip timing, transitions, caption animation, aspect ratio, narration cadence — the viral DNA.
+- **Replace:** every word (TEXT), the narration script (AUDIO), every visual (SCENES).
+- **Forking:** automatic on the first edit; you never create a fork by hand.
+- **Blank exception:** if `is_new_project:true` (`composition_id:"original"`) there's no template to re-theme — use the `create_video` tool to mint one first, then re-theme the result.

package/.agents/skills/embedded-captions/CATALOG.md

@@ -0,0 +1,93 @@
+# THE CATALOG — one front-end, three engines behind
+
+This is the skill's single selection surface. **The user picks an IDENTITY from
+this table; everything else (engine, compiler, authoring file) is derived by
+lookup — never ask the user (or yourself) "Standard or Cinematic or Theme?"**
+Those are backend names; a product has one UX even when it has several engines.
+
+Routing procedure (replaces any mode decision):
+
+1. Probe the clip (decision gate + pre-flight probes as in SKILL.md).
+2. Shortlist 2–3 identities from this table by **content register + the user's
+   own words + scene constraints**.
+3. Recommend ONE with a one-line why; the user picks.
+4. Author the identity's file (last column), then render with its engine's
+   pipeline. Done — no category question ever surfaced.
+
+## Identities
+
+| Identity      | Reading surface                                          | Voice (one line)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Recommend for                                                                                                                                                                                                  | Scene needs                                                                                                            | Author → engine                 |
+| ------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| `cream`       | scene-embedded column flow                               | warm poetic light, emergence + glow                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | introspective, narrative, emotional monologues                                                                                                                                                                 | dark/mid-tone warm scenes (luma < 150)                                                                                 | cinematic.json → make-cinematic |
+| `ink`         | scene-embedded column flow                               | letterpress pressed into bright surfaces                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | the bright scenes everything else washes out on                                                                                                                                                                | BRIGHT scenes (luma > 150)                                                                                             | cinematic.json → make-cinematic |
+| `editorial`   | scene-embedded column flow                               | lowercase italic serif, pen-stroke glides                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | fashion / beauty / lyrical / premium brand films                                                                                                                                                               | mid/dark scenes                                                                                                        | cinematic.json → make-cinematic |
+| `keynote`     | scene-embedded column flow                               | confident centered slides-in-the-scene                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | launches, founder updates, tech explainers (mood over verbatim reading)                                                                                                                                        | any mid/dark                                                                                                           | cinematic.json → make-cinematic |
+| `documentary` | scene-embedded column flow                               | burn-in stillness, bone on charcoal                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | interviews, journalism, testimony — gravitas IS the style                                                                                                                                                      | any                                                                                                                    | cinematic.json → make-cinematic |
+| `loud`        | scene-embedded, body in front                            | percussion type that competes with the face                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | hype, social reels, sport, music, motivational                                                                                                                                                                 | any (counter-accent handles warm)                                                                                      | cinematic.json → make-cinematic |
+| `neon`        | scene-embedded column flow                               | captions as neon signage in the dark                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | cyberpunk / nightlife / tech-noir / music                                                                                                                                                                      | dark scenes                                                                                                            | cinematic.json → make-cinematic |
+| `glitch`      | scene-embedded column flow                               | corrupted-feed RGB-split type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | hacker / AI / dystopia content                                                                                                                                                                                 | mid/dark                                                                                                               | cinematic.json → make-cinematic |
+| `chrome`      | scene-embedded column flow                               | liquid-metal hero with sheen sweeps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | fashion-tech, Y2K, product-flex                                                                                                                                                                                | mid/dark                                                                                                               | cinematic.json → make-cinematic |
+| `velocity`    | scene-embedded column flow                               | every word arrives along its motion vector                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | sport, automotive, fitness, kinetic content                                                                                                                                                                    | any mid/dark                                                                                                           | cinematic.json → make-cinematic |
+| `anchor`      | verbatim lower-third rail + 1 settled climax             | the quiet professional — fade-up rail that simply reads; the apex settles behind the subject with a drawn accent underline. Discipline IS the style.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | explainers, tutorials, corporate, news-adjacent — **where every word must be read**; the conservative default                                                                                                  | any (opaque rail; settle carries a soft veil)                                                                          | theme.json → make-theme         |
+| `ordnance`    | stamped verbatim rail + detonation apex                  | military marking system; everything has mass; the room reacts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | punchy announcements, drops, "炸一点 / 像 AE 做的" asks                                                                                                                                                        | any (charge-dim makes its own contrast)                                                                                | theme.json → make-theme         |
+| `terminal`    | typed console panel + glyph-decode apex                  | the transcript is a signal log; apex decodes from noise                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | tech / data / AI / investigative, "终端/控制台/解码" asks                                                                                                                                                      | cool/dusk preferred                                                                                                    | theme.json → make-theme         |
+| `neonsign`    | warm tube rail + hand-written neon apex                  | a sign district at dusk; the apex is WRITTEN stroke by stroke                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | lifestyle / music / mood, "霓虹/手写" asks                                                                                                                                                                     | dusk/dark backdrop; needs `python3` (stroke-path gen)                                                                  | theme.json → make-theme         |
+| `stardust`    | accumulating poem, condensing letters                    | words condense from dust and return to it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | poetic / memory / science-wonder monologues                                                                                                                                                                    | one clear column side (probe fails → fall back to `cream`)                                                             | theme.json → make-theme         |
+| `stomp`       | full-frame takeover cards                                | hard-cut typographic takeover with a void before the drop                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | hooks, manifestos, ad openers — the words ARE the show                                                                                                                                                         | any (plate runs dimmed)                                                                                                | theme.json → make-theme         |
+| `lastpage`    | manuscript rail + a blurred future-field                 | the future hangs unreadable in the room; one rack-focus reveals every faint line was the apex word                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | visionary thesis, prophecy-toned talks, trailers, literary content                                                                                                                                             | mid/dark (the field needs air)                                                                                         | theme.json → make-theme         |
+| `nightcity`   | corrupted-UI rail + cover-letterform apex                | body words boot through a corrupted-cyan frame into acid-yellow UI; the apex slams in BEHIND the subject set in the CP2077 cover replica typeface (cyan offset, baseline streak, circuit trace), tears in as displaced slices, lives as a glitching print                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | gaming / tech-edge / glitch culture / hype drops, "赛博朋克/游戏封面" asks                                                                                                                                     | any (the lockup carries its own contrast); CP2077-adjacent content only (fan-kit terms)                                | theme.json → make-theme         |
+| `scoreboard`  | split-flap chyron rail + departures-board apex           | stadium split-flap mechanics — body words flip-cycle wrong words on tiles before clacking onto the real one; ROW counter + odometer chip furniture; the apex is a giant departures board behind the subject that locks the word letter-by-letter under floodlights and a crowd-flash, status ticker types on                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | sports, transit/travel, scores, countdowns, reveals, "翻牌/记分牌/机场大屏" asks                                                                                                                               | any (board + chyron bring their own dark metal contrast)                                                               | theme.json → make-theme         |
+| `transit`     | LED departure-strip rail + illumination-wipe apex        | amber dot-matrix station PA — body words light column-by-column (L→R LED wipe + arrival flicker) on a docked departure strip whose lines page by scroll-snap; platform tag, ticking clock, ⚠ DELAYED → ● ON TIME gag; the apex panel expands behind the subject inside a chasing LED-marquee border, the word illuminates column-by-column under a PA flash + ding pulses, then pages up and collapses                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | travel/transit, announcements, schedules, countdowns, retro-terminal, "LED屏/车站到站/点阵屏" asks                                                                                                             | any (LED strip + panel bring their own dark contrast)                                                                  | theme.json → make-theme         |
+| `vhs`         | camcorder OSD rail + REC-FREEZE tracking-slam apex       | tape playback — permanent lens vignette + OSD furniture (▶ PLAY, ● REC, blinking green timestamp); body words carry a permanent red/cyan misregistration fringe, arrive by tracking glitch and REWIND off with flat-white echoes + scrub lines (the deck flips PLAY→REW in dead air); the apex is REC FREEZE: 1-frame white tear + head-switching noise bar, the word slams in behind the subject as three sheared tracking bands that SNAP into register, misregistration breathes through the hold under tape weave + auto-iris, then rewinds off                                                                                                                                                                                                                                                                                                                                                                                                                   | retro / nostalgia / found-footage / home-video, '90s tech, music & lifestyle edits, "录像带/VHS/复古/DV" asks                                                                                                  | any (backlight-comp scrim makes its own contrast on bright skies)                                                      | theme.json → make-theme         |
+| `arcade`      | arcade HUD rail + pixel-block boss-intro apex            | 8-bit cabinet attract mode — the frame plays through CRT scanlines + a corner vignette; body words coin-pop onto a bordered HUD bar (blinking 1UP, CREDIT 01) with a 1-frame white blip each, emphasis words run a cyan→magenta palette swap, lines dissolve checkerboard; the apex is a BOSS INTRO behind the subject: the room dims, WARNING blinks twice, ~64 seeded pixel blocks fall quantized into a matrix grid over the word rect, the word flashes ON in Press Start 2P with chromatic ghost layers + a 3-frame palette strobe while letterbox bars slam in and a HI-SCORE odometer rolls top-right; everything dissolves checkerboard and the blocks drop away                                                                                                                                                                                                                                                                                              | gaming, retro-tech, playful hype, launches, achievement/level-up beats, "像素/街机/8-bit/打游戏" asks                                                                                                          | any (boss dim + dark HUD bar bring their own contrast)                                                                 | theme.json → make-theme         |
+| `dossier`     | manila case-file strip + rubber-stamp apex               | cold-war case file — carbon Special Elite HAMMERS onto a manila transcript strip char by char (seeded baselines + ribbon ink, every strike kicks the paper; typed case header, CONFIDENTIAL watermark, red ink circles around the evidence; pages are X-row over-struck and carriage-fed away); the apex is a RUBBER STAMP behind the subject: the footage goes sepia-archival, the stamp crushes in at −8° with a double-strike ghost + thin-ink patches, then holds DEAD STILL — sold only by a breathing paper indent — until the page is filed away with a mechanical yank                                                                                                                                                                                                                                                                                                                                                                                        | investigations, exposés, true-crime, document-driven storytelling, declassified/archival framing, "档案/卷宗/解密/盖章" asks                                                                                   | any (the manila strip is self-lit; the stamp brings its own sepia charge)                                              | theme.json → make-theme         |
+| `laser`       | beam-ignited rail + 6-beam laser-cage apex               | concert laser rig in a blackout — every body word is IGNITED where a green and a magenta beam converge on it two frames early (flare pop, snap-on, single strobe on emphasis; a sweeper beam carries each line away); the apex is the drop: a 6-beam array sweeps to one hot point, the word ignites behind the subject in an additive glow stack with two controlled strobe pops, a criss-cross beam cage draws around it, the array fans out wide through the hold, then the beams sweep everything off L→R                                                                                                                                                                                                                                                                                                                                                                                                                                                         | music, nightlife, festivals, drops, hype reveals, keynote 'one more thing' beats, "激光/灯光秀/蹦迪字幕" asks                                                                                                  | any (the concert blackout makes its own contrast, bright skies included)                                               | theme.json → make-theme         |
+| `thunder`     | rain-washed rail + branched-bolt strike apex             | the storm is the editor — slate storm mood on the room, ambient slanted rain falling in front of the subject, and the sky "kisses" (1-frame brighten) on every body word; rail words arrive with a lit-bright lightning pop (emphasis = sheet-lightning double flash mirrored by a double sky-kiss); the apex is THE STRIKE: a hand-authored branched bolt flashes two frames before the word, the word slams in lit HARD with its shadow flipped toward the bolt, ozone under-glow breathes through the hold while the rain doubles, then everything washes downward with the rain                                                                                                                                                                                                                                                                                                                                                                                   | dramatic reveals, storm/weather content, epic hype beats, trailer-toned monologues, "雷电/闪电/暴风雨字幕" asks                                                                                                | any (charge-dim + radial word scrim make their own contrast, bright skies included)                                    | theme.json → make-theme         |
+| `hologram`    | volumetric projection plate + hologram-boot apex         | every caption is LIGHT cast from an emitter — body words boot onto a scanlined projection plate with a rising sweep, a 1-frame interference glitch and a permanent cyan/magenta fringe (emphasis words drop out for 2 frames and restore brighter; lines drift in rotationY and exit by projector cut); the apex is the full volumetric boot: a desk emitter dot pops, the cone snaps wide, a seed beam fires, and the word materializes behind the subject as a 7-layer hologram with climbing interference bands — a hand passes through it before the projector cuts it back to the dot                                                                                                                                                                                                                                                                                                                                                                            | tech / sci-fi / AI / space / imaging explainers, futuristic product reveals, "全息/投影/科幻字幕" asks                                                                                                         | any (the apex scrim + dim make their own contrast; wants a lower frame edge for the emitter dots)                      | theme.json → make-theme         |
+| `biolume`     | jellyfish glow-on rail + bioluminescent-bloom apex       | deep-sea bioluminescence — the clip sinks into an abyss grade with a breathing vignette and every caption is a living light: body words GLOW ON like jellyfish (radial bloom from center while a cyan glow breathes in; emphasis words pulse a slow propulsion double-beat) across two coexisting floating rows and SINK away dimming; seeded plankton motes drift the open water and the ones ringing the apex are pulled into the bloom; the apex is the BLOOM behind the subject: a creature pre-glow double-beats and crushes to a point, the word condenses in, six luminous tendrils draw outward like filaments while caustics shimmer, cyan light spills onto the scene and spores burst past — then all the light sinks back into the deep                                                                                                                                                                                                                   | ocean / nature / science-wonder docs, dreamy or meditative monologues, slow night-time reveals, "深海/发光水母/水下字幕" asks                                                                                  | any (the abyss grade + pocket scrim make their own contrast on bright scenes)                                          | theme.json → make-theme         |
+| `aurora`      | iridescent sheen rail + silk-ribbon draw-on apex         | polar-night elegance — two huge aurora blobs drift the sky all clip; body words are silk serif ink whose rose→teal→violet sheen drifts continuously through the letters (entrance = 2-frame flow-on + y8 settle; emphasis = one bright highlight sweep marching through the word), lines share two coexisting rows like a woven couplet and dissolve UPWARD into drifting light streaks; the apex is a SILK RIBBON: the hero word is hand-WRITTEN into the sky behind the subject stroke by stroke (script single-line font, blurred halo + bright core, a light mote riding the pen) and the aurora gradient keeps FLOWING through the drawn ribbon during the hold while a soft spill tints the sky and light motes rise past the subject — gentle, no shake                                                                                                                                                                                                        | dreamy / romantic / wonder content, night-sky and travel pieces, poetry, weddings, elegant brand films, "极光/丝带/优雅手写字幕" asks                                                                          | any (apex scrim + dark understroke carry contrast on bright skies; loves dusk/night)                                   | theme.json → make-theme         |
+| `spectrum`    | oscilloscope scope-band rail + phosphor trace-write apex | an oscilloscope is listening — a dark scope band hosts an ALWAYS-ALIVE waveform (seeded pseudo-RMS envelope: speech grows it, silence flattens it, every word arrival kicks a local burst) under VT323 phosphor lines that wipe in L→R over reserved slots with a 2-frame just-traced flash (emphasis words get a ticking frequency-readout chip, the trig LED blinks on every word); the apex is the trace itself LEAPING off the scope (surge column) to hand-WRITE the hero word in a thin phosphor script stroke, fill flicker-on, hum + breathe, then COLLAPSE to a flatline before the next spoken word — and on the FINAL word the trace explodes to max-amp chaos, flatlines to a single dot and stamps SIGNAL LOST                                                                                                                                                                                                                                           | science / signal / audio / measurement / astronomy explainers, data-nerd content, retro-lab or synth aesthetics, "示波器/波形/信号字幕" asks                                                                   | any (the scope band brings its own dark glass; the apex scrim handles bright skies); needs `python3` (stroke-path gen) | theme.json → make-theme         |
+| `papercut`    | paper-chip craft rail + stop-motion papermat apex        | stop-motion paper craft — the frame becomes an animator's table: body words are cream paper chips PLACED one by one (steps(2) drop, seeded crooked, ~5fps wobble) on a kraft strip with torn top edge, washi-taped corners and a handwritten cut&paste tag; emphasis words get a washi-tape slap, the final word is an accent-red sign-off chip, and a red paper star stands in for the hero word; the apex is a torn kraft mat slapped down behind the subject where torn-edge letter chips DROP with stepped gravity + anticipation shadows, land crooked, settle in 12fps poses, wobble at 8fps while a warm vignette charges — then the FINAL word bumps the table and everything scatters off down-right                                                                                                                                                                                                                                                         | craft/DIY, kids & family, indie product demos, behind-the-scenes, maker channels, "手工/剪纸/定格动画字幕" asks                                                                                                | any (kraft strip + cream chips bring their own warm contrast)                                                          | theme.json → make-theme         |
+| `popup`       | pop-up book page rail + centerfold starburst apex        | a pop-up book opens inside the frame — body words POP UP on a baseline hinge (rotationX back.out, paper overshoot, a growing back-shadow) along a cream page strip that unfolds from the bottom edge (center foldline, two alternating reading rows); emphasis words land bigger with a contact squash the page FEELS (1px strip dip), then flick-wobble with a blue paper strut leaning in behind; line exits fold flat in an L→R wave (the page closing), the whole page TILTS on the final word and the strip folds shut on the last frame; the apex is THE CENTERFOLD: blue + cream 12-point paper starbursts unfold behind the subject, the hero word pops up in three hinged clip-path segments, kraft struts lean in, backdrop + word wobble-settle TOGETHER and breathe through the hold — then the whole spread folds flat before the next sentence; a blue paper star holds the hero slot on the rail and paper confetti flicks past the subject at the pop | kids and family content, storytelling, education, greeting-card / wholesome brand spots, picture-book and craft channels, "立体书/弹出书/纸艺字幕" asks                                                        | any (the cream page strip is self-lit; the apex dusk scrim guards bright skies)                                        | theme.json → make-theme         |
+| `chalkboard`  | chalk-band rail + hand-written chalkwrite apex           | night lecture — a worn deep-green chalk band where every word is SCRIBBLED in fast chalk (2-frame pop + steps(4) scribble reveal + dust puff at the base, seeded crooked); emphasis gets double underline dashes, the final word lands in yellow chalk, and between sentences an ERASER SWIPE smears the old words off (blurred light band, ghost smudges stay — chalk never fully erases); the apex: the band GROWS into a full blackboard behind the subject and the hero word is HAND-WRITTEN 130px tall stroke by stroke (jittered chalk nib, dust falling from the pen, blurred halo under a tight core), finished with a hand-slap dust CLAP in front of the subject + a 1-frame board shake and two violent accelerating underlines, then the halo breathes through the hold                                                                                                                                                                                   | education / explainers, science and lecture content, teacher channels, documentary asides, "黑板/粉笔/板书/老师讲课字幕" asks                                                                                  | any (the deep-green board brings its own contrast); needs `python3` (stroke-path gen)                                  | theme.json → make-theme         |
+| `graffiti`    | marker rail + spray-tagged handstyle apex                | street bombing run — marker words FLICK onto the rail crooked (1-frame squeak skew, seeded rotation, back.out settle); emphasis takes alternating yellow/magenta paint + a spray-underline swoosh with overspray dots; spent lines are ROLLER-BUFFED away (gray roller sweep, wet smear lingers) and the final word lands BIG in yellow with the punch; the apex: the dusk wall dims, the can RATTLES, and the hero word is spray-TAGGED stroke by stroke behind the subject in fat yellow paint (dark under-stroke armor + blurred overspray halo + glowing nib + seeded overspray dots), paint DRIPS grow from the low points through the hold, a magenta paint splat pops at the pen-finish and the plate punches on it                                                                                                                                                                                                                                            | street culture, hip-hop / rap, sneaker & fashion drops, urban sports, skate/BMX, rebellious brand spots, "涂鸦/喷漆/街头字幕" asks                                                                             | any (the dark under-stroke armors the tag against bright skies); needs `python3` (stroke-path gen)                     | theme.json → make-theme         |
+| `brush`       | washi paper-band rail + sumi-e brush-gesture apex        | sumi-e study — a deckle-edged washi paper band swipes in behind a traveling brush-head shadow; body words are brush-WIPED on in a Mincho serif (clip reveal behind a per-word brush head, seeded ±1° tilt), emphasis gets a double curved ink underline, and spent lines are wiped OFF right-to-left like a wet cloth (erase brush head riding the wipe); the apex: a warm paper wash charges behind the subject and the hero word is written in ONE violent calligraphic gesture — pressure-tapered wet brush (four stacked stroke widths, blurred bleed underneath), start-SPLAT at the first pen contact with ink flecks kicking past the subject, spatter droplets ejected at the sharpest curves — then the ink BLEEDS into the paper through the hold (the work breathes) and a vermilion SEAL chop (観) stamps beside the ink with the plate punch                                                                                                             | calm-authority explainers, craft / design / philosophy / Japan-adjacent content, tea / meditation / writing channels, elegant brand films, "水墨/毛笔/书法字幕" asks                                           | mid/bright scene band (dark ink + its paper wash carry the contrast); needs `python3` (stroke-path gen)                | theme.json → make-theme         |
+| `inkwater`    | three-row ink rail + ink-drop bloom apex                 | sumi ink dropped in still water — paper-white radial washes back the text zones, Mincho-serif ink words BLEED into three fixed reading rows (blur+scale bleed over a paper-glow halo, dark blurred halo overshoots then tightens, an ink-settling hairline under each line, emphasis sheds a curling ink wisp) and spent lines re-dissolve upward like dispersing ink; the apex: a dark drop falls behind the subject, hits an invisible water surface at the word point and BLOOMS (three stacked blurred ink ellipses at counter-rotating rates + two thin ripple rings) while the world stills under a gentle vignette — the hero words resolve out of the blob on their own spoken times, breathe at the glyph edges through the hold, then re-dissolve before the next thought needs the reader                                                                                                                                                                  | contemplative / literary / scientific-wonder narration, astronomy / nature / memory / essay films, poetry and slow-craft channels — one liquid meditative event instead of an impact, "水墨滴落/墨水字幕" asks | mid/bright scene band (dark ink + its paper washes carry the contrast)                                                 | theme.json → make-theme         |
+| `ransom`      | cutout-chip collage rail + ransom-note slam apex         | kidnapper's collage — every word is a chip clipped from a different page (cream Anton / black Inter / newsprint typewriter / accent-yellow marker, torn edges, hard offset shadows) PASTED crooked on the rail with misaligned baselines (the apex slam at low amplitude); emphasis words get a 1-frame RE-PASTE lift (shadow grows, rotation flips sign for good) and spent chips are RIPPED off one by one under 1-frame paper-tear flashes; the apex: a collage scrim darkens the sky and the hero word slams in letter by letter as a ransom note BEHIND the subject — each letter a different cutout chip, flight shadow popping tight on contact — the whole word JOLTS as the last letter lands (the plate punches with it), looms crooked through the hold, then is torn off chip by chip while the closing line speaks                                                                                                                                       | true crime, mystery / thriller, heist energy, punk / DIY zine aesthetics, edgy drops, unhinged-comedy hooks, "勒索信/剪贴/拼贴字幕" asks                                                                       | any (solid chip backgrounds carry their own contrast; the apex scrim guards bright skies)                              | theme.json → make-theme         |
+
+## Shortlisting heuristics (identity-level, not category-level)
+
+- **"每个词都要被读到 / accessibility / 教程·新闻"** → rail or panel surfaces:
+  `anchor`, `ordnance`, `terminal` (all verbatim by construction).
+- **"嵌进场景 / 电影感 / 高级"** → the column-flow ten; pick by register + scene luma
+  (bright → `ink`; warm dark → `cream`; fashion → `editorial`; …). Bright + must-read → `anchor`.
+- **"炸 / 特效 / 酷炫 / 像 AE"** → `ordnance`, `stomp`, `terminal`, `loud` — pick by
+  what should explode: a word (`ordnance`), the frame (`stomp`), a decode (`terminal`),
+  every beat (`loud`).
+- **Named worlds** → direct hits: 控制台/终端 → `terminal`; 霓虹/招牌 → `neonsign`;
+  诗/星尘/记忆 → `stardust`; 军事/重击 → `ordnance`; 预言/未来/悬念揭示 → `lastpage`;
+  赛博朋克/游戏封面/夜之城 → `nightcity`.
+- **Scene constraints veto last**: luma > 180 kills cream/screen column looks
+  (→ `ink` or a rail/panel surface); dusk/dark unlocks `neon`/`neonsign`.
+- **Unsure** → `anchor` (the conservative default: words read, scene safe, zero spectacle).
+  EXCEPTION: if the ask literally says "嵌进场景 / embed into the scene / 电影感", that signal
+  OUTRANKS the conservative default — go column-flow (pick by register + luma), not a rail.
+
+Adjacencies worth knowing (these pairs are why the old mode question was hard —
+recommend by the difference, don't agonize over category): `loud` vs `ordnance`
+(percussive type vs a themed world with plate reaction) · `neon` vs `neonsign`
+(neon-styled captions vs a sign being written) · `cream` vs `stardust` (warm
+embedded flow vs an accumulating poem with semantic dispersal) · `terminal` vs
+`glitch` (a console WORLD with typed log + decode vs corrupted-feed styling on
+normal captions) · `stomp` vs `loud` (every beat takes over the dead-center
+frame vs energetic type that still shares the frame with the subject).
+
+## Rules
+
+- Identities are **engine-locked** — no cross combos. Opening a new combo (e.g.
+  another DNA under rail) is a validation event: render → user review → flip the
+  DNA's `deliveries.rail` flag (see dna/README.md).
+- New identities join via their family's registry rules (dna/README.md for
+  classic, themes/README.md for themed — "any input, zero hand-fixing" bar).
+- The engines' internals (Standard/Cinematic/Theme compilers, gates, layers)
+  are documented in their own files; this catalog is the only routing surface.