@mevdragon/vidfarm-devcli 0.2.13 → 0.3.0

package/auto-create-templates/AUTO_CREATE_TEMPLATES.md

@@ -1,599 +0,0 @@
-# Auto-Create Templates Harness
-
-This is the harness for turning an arbitrary TikTok or short-form video into a reusable Vidfarm template that can generate the same format in bulk.
-
-## Start Here
-
-Give a Codex agent these two things:
-
-1. this entry file: `auto-create-templates/AUTO_CREATE_TEMPLATES.md`
-2. one media reference folder, preferably shaped like:
-
-```txt
-drafts/<format_slug>/
-  source.md
-  preview/
-    source.mp4
-    screenshot-01.png
-```
-
-Then ask:
-
-```txt
-Use auto-create-templates/AUTO_CREATE_TEMPLATES.md as the harness. Analyze drafts/<format_slug>/ as the source format, create the run artifacts, generate the production graph and template plan, then scaffold and implement a runnable Vidfarm template.
-```
-
-The media folder can contain a video, screenshots, reference images, or all of them. If `source.md` is missing, the agent should create one with the original URL, creator, adaptation goal, and any constraints it can infer.
-
-The core idea is to avoid asking an agent to "clone this video" in one prompt. The harness splits the job into staged extraction:
-
-1. inspect source media and source notes
-2. run Vidfarm viral and visual DNA analysis
-3. decide which visual traits must be preserved because they support the viral mechanism
-4. extract a production graph from the actual video
-5. classify which parts are fixed format rules vs replaceable inputs
-6. choose a generation strategy: pure prompt, Remotion assembly, AI image storyboard, AI video, source clip swapping, or a hybrid
-7. generate a Vidfarm template plan with schemas, operations, jobs, prompts, and validation cases
-
-Supporting harness files live beside this entry file in [auto-create-templates](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/auto-create-templates).
-
-## Cacheable Context
-
-When `vidfarm-devcli autocreate-template` creates a run, it snapshots this harness and the root `SKILL.developer.md` into the run folder. Treat both files as stable, cacheable prompt context:
-
-1. read `harness/SKILL.developer.md` first
-2. read `harness/AUTO_CREATE_TEMPLATES.md` and the supporting harness prompt/schema files next
-3. only then load run-specific source media notes, analyzer outputs, DNA JSON, OCR, transcripts, and production graph artifacts
-
-Keep that order in agent prompts and implementation passes. The developer skill and harness should form the stable prompt prefix so provider-side prompt caching can reuse them across repeated auto-create runs.
-
-## Sample Read
-
-I sampled the local drafts across the spectrum:
-
-- Easy:
-  - `cute_diagram_grid`: one static generated infographic with repeated layout slots, title, illustrations, and short explanatory labels.
-  - `history_swap_news`: one meme/news image where the reusable mechanic is text replacement inside a familiar historical/news surface.
-  - `before_after_slides` and `video_in_chat`: short screen-native videos where most of the format is slot timing, overlay text, and a small number of replaceable media regions.
-- Medium:
-  - `app_demo_captioned`: app interface recording with caption track and visible UI state changes across time.
-  - `face_upclose_yapper`: close-face UGC speech with top hook, word-level captions, and performance pacing driven by audio.
-  - `unique_sketch_character`: recurring illustrated character/vibe, scene beats, and animation continuity rather than simple text swaps.
-- Hard:
-  - `movie_montage`: external clip montage plus reaction/meter overlays and app interstitials.
-  - `claymation_ads`: full AI-video storyboard with character continuity, product/problem narrative, captions, and scene-to-scene action.
-  - `full_animated_science_explainer`: horizontal drawn explainer with abstract diagrams, narration, transitions, and educational sequencing.
-
-This implies three production tiers:
-
-- `easy`: one image or a few fixed visual slots. Usually pure image generation, reference image editing, HTML/CSS compositing, or Remotion slideshow.
-- `medium`: timed media replacement. Usually Remotion plus STT/TTS/captions, exact overlay timing, screen recordings, UI mocks, and optional AI image inserts.
-- `hard`: multi-stage production. Sometimes script -> storyboard -> assets -> AI image/video generation -> Remotion edit -> captions/audio/master. Other times the source is too visually fluid for reliable Remotion reconstruction and should be treated as an AI-native prompt/reference template.
-- `full_ai_character_video`: recurring AI-generated characters across scenes. Usually character sprite/reference cards -> image storyboard -> scene video generation -> Remotion stitch/caption/master.
-
-## What To Extract
-
-The obvious primitives are captions, TTS, STT, scene snipping/replacement, pointing/circling/magnifying. The harness should also extract these:
-
-- hook mechanic: first-frame promise, curiosity gap, shock, status signal, objection, or payoff setup
-- viral steering contract: the non-negotiable distribution psychology that every generated output must preserve
-- visual preservation decision: which visual traits are essential, supportive, optional, or irrelevant based on the viral DNA
-- format container: chat, app screen, map, notification, yearbook, bodycam, news, diagram, ranking, montage, list, interview, vlog, or cinematic scene
-- shot list: ordered scene beats with start/end times, source asset type, camera framing, and purpose
-- edit rhythm: cut frequency, beat drops, zooms, pauses, jump cuts, freeze frames, scroll speed, and loop point
-- audio plan: music bed, narrator, on-camera voice, dialogue, sound effects, silence, and sync points
-- caption style: font, case, color, outline, background chip, placement, max words per line, word-level highlighting, safe areas
-- timing controls: total duration, per-scene duration, per-slide duration, caption group duration, hold time, transition duration, zoom duration, loop point, and minimum/maximum slot length
-- typography controls: TikTok-native font choice, fallback font stack, font size, weight, line height, outline/shadow, background chip, word highlight style, and whether the caller can override them
-- overlay inventory: arrows, circles, magnifiers, stickers, screenshots, reaction meters, emoji, app chrome, progress bars, counters, comments, and lower thirds
-- layout anchors: bounding boxes for faces, products, captions, buttons, UI slots, and safe/unsafe zones
-- replaceable variables: product, person, pain point, website, app screen, object, character, text, location, statistic, clip, or CTA
-- invariant rules: what must stay consistent for the format to remain recognizable
-- adaptive rules: what can change per brand without breaking the format
-- asset requirements: exact user-uploaded references vs AI-generated assets vs external clips vs rendered UI
-- continuity requirements: character identity, wardrobe, room, lighting, prop placement, visual style, and voice
-- character bible: character names, roles, facial/body traits, wardrobe, sprite/reference cards, expression range, poses, props, negative prompts, and consistency constraints
-- storyboard requirements: start/end frame prompts, keyframe images, scene-to-scene continuity notes, camera/action notes, and which frames feed video generation
-- production dependencies: Remotion only, image model, video model, layout analysis, TTS, STT, OCR, background removal, object tracking, or media search
-- architecture fit: whether the format is better as deterministic Remotion assembly, AI-native prompt/reference generation, or a hybrid
-- compliance risks: copyrighted media dependency, celebrity likeness, medical/financial claims, unsafe camera/bodycam contexts, and platform UI imitation
-- validation signals: first-frame legibility, caption readability, subject safe framing, slot replacement correctness, timing fidelity, audio sync, and renderability
-
-## Pipeline
-
-### 1. Intake
-
-Put the source into a clean draft folder:
-
-```txt
-drafts/<format_slug>/
-  source.md
-  preview/
-    source.mp4
-    screenshot-01.png
-```
-
-`source.md` should include:
-
-- original URL
-- creator/account if known
-- product/category being adapted, if any
-- what the human believes is repeatable
-- any constraints such as "must use product photo" or "no AI video"
-
-### 2. Prepare Analyzer Artifacts
-
-For every video, create analyzer artifacts before asking AI for a template plan:
-
-```txt
-auto-create-templates/runs/<run_id>/
-  source/
-  frames/contact-sheet.jpg
-  frames/frame-0001.jpg
-  audio/source.wav
-  transcripts/stt.json
-  ocr/frame_text.json
-  motion/scene-cuts.json
-  dna/viral_dna.extraction.json
-  dna/visual_dna.extraction.json
-  extraction/production_graph.json
-  plan/template_plan.json
-```
-
-Minimum useful extraction:
-
-- `ffprobe` metadata: duration, resolution, fps, audio presence
-- contact sheet: 6-12 frames across the video
-- scene cuts: start/end/duration and representative frame
-- STT transcript with word timestamps when speech exists
-- OCR pass on representative frames
-- object/layout pass for faces, products, UI panes, captions, and overlay regions
-- audio summary: narrator/music/sfx and approximate sync events
-- timing table: every meaningful scene, caption, overlay, zoom, highlight, hold, and transition with exact or inferred start/end times
-- font inventory: visible creator-authored caption/overlay fonts, approximate TikTok font match, styling, and fallback stack
-
-### 3. Run Viral And Visual DNA
-
-Use the existing Vidfarm analyzer before the production graph step:
-
-```bash
-npx @mevdragon/vidfarm-devcli analyze-viral-dna --template-dir ./templates/<template_dir>
-npx @mevdragon/vidfarm-devcli analyze-visual-dna --template-dir ./templates/<template_dir>
-```
-
-The underlying pattern is based on:
-
-- [1-analyze-viral-dna.mjs](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/tiktok-winning-formats/src/scripts/1-analyze-viral-dna.mjs)
-- [1b-analyze-visual-dns.mjs](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/tiktok-winning-formats/src/scripts/1b-analyze-visual-dns.mjs)
-
-Those scripts upload preview media to Gemini, ask for strict JSON, and store extraction results. For auto-creation, treat viral DNA and visual DNA as upstream context, not the final template plan.
-
-Use viral DNA for why the format works. Use visual DNA for what the viewer recognizes. Use the production graph for how to recreate it.
-
-### 3b. Decide Viral Steering And Visual Preservation
-
-Before planning the template, create a short preservation decision:
-
-```json
-{
-  "viral_steering": {
-    "must_preserve": [
-      "specific hook psychology",
-      "curiosity or tension pattern",
-      "payoff structure",
-      "pacing behavior that creates retention"
-    ],
-    "must_not_dilute": [
-      "things that would make the output generic or less clickable"
-    ]
-  },
-  "visual_preservation": {
-    "importance": "critical | supportive | optional | low",
-    "preserve_because": "how the visual trait reinforces the viral mechanism",
-    "preserve": [
-      "only visual traits that materially support the viral DNA"
-    ],
-    "can_change": [
-      "visual traits that are not part of the viral engine"
-    ]
-  }
-}
-```
-
-This decision is viral-first. A visual trait is `critical` only when changing it would damage the hook, recognition, curiosity, credibility, emotional tension, or retention loop. Some formats are presentation-driven and must preserve visual layout tightly. Other formats win because of premise, pacing, or voice, and their visuals can vary more freely.
-
-The generated template must persist this decision in:
-
-- `about.viral_dna`
-- `about.visual_dna`
-- `about.links_to_inspiration`
-- `about.sound`
-- `about.proposal_generator`
-- `about.skeleton_prompt`
-- `sample_prompts`
-- template-local `SKILL.md`
-- prompt constants or comments near the top of `src/template.ts`
-- runtime plan/checklist output where the template has a `create_plan` operation
-
-### 4. Extract Production Graph
-
-Run the prompt in [extractor-system-prompt.md](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/auto-create-templates/extractor-system-prompt.md) against:
-
-- source notes
-- source media or contact sheet
-- frame OCR
-- transcript
-- scene cuts
-- viral DNA
-- visual DNA
-- viral steering and visual preservation decision
-
-The output should match [production-graph.schema.json](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/auto-create-templates/production-graph.schema.json).
-
-The graph is the critical artifact. It should answer:
-
-- what is the timeline?
-- which clips/images/text/audio are fixed?
-- which viral mechanics must be steered in every generated output?
-- which visual traits are actually preservation-worthy because of the viral mechanics?
-- which elements are replaceable?
-- which elements are generated?
-- which elements need exact timing?
-- which parts are best implemented in Remotion?
-- which parts would become brittle if implemented in Remotion?
-- whether the format should instead be generated as a prompt/reference with AI-native image or video generation
-- which parts require AI image/video generation?
-
-### 5. Choose Template Strategy
-
-Use this decision table, but make an explicit architecture-fit decision instead of defaulting to Remotion:
-
-| Source pattern | Recommended strategy |
-| --- | --- |
-| Single static infographic, meme, diagram, notification, poster, fake UI with simple geometry | AI image or HTML/CSS/Canvas composition, optional image reference attachment |
-| Dense illustrated poster, painterly infographic, organic collage, or high-detail aesthetic image | AI-native prompt/reference image generation; avoid rebuilding every region in Remotion |
-| Static multi-slide carousel | structured slide manifest -> image generation/compositing -> optional Remotion video |
-| Screenshot or app interface with simple motion | Remotion-rendered UI shell plus replaceable media/text slots |
-| App demo / screen recording | user-provided clip or generated UI recording -> Remotion captions/zooms/highlights |
-| Face talking-head with captions | STT/TTS or user audio -> caption renderer -> optional B-roll slots |
-| UGC reaction/demo | shot list with user-provided or generated clips, captions, overlays, jump cuts |
-| Character animation / clay / anime / Pixar-like with complex motion, acting, camera, or texture | character sprite cards -> image storyboard -> generated video scenes -> Remotion stitch/captions/audio |
-| Movie montage / celebrity montage | avoid copyrighted source dependency by making it a generic montage slot template with user-supplied clips or generated parody-safe scenes |
-| Explainer animation with simple diagrams | script -> visual metaphor list -> Remotion/Canvas diagrams -> narration -> edit |
-| Explainer animation with hand-drawn morphs, organic transitions, or cinematic continuity | script -> storyboard -> AI-native image/video generation -> Remotion only as final edit |
-
-#### Remotion Ceiling Heuristics
-
-Choose AI-native prompt/reference generation when the format has several of these traits:
-
-- organic or painterly visual details where every frame would require many hand-positioned layers
-- complex character acting, facial expression, body motion, or physics
-- camera moves that rely on generated perspective, parallax, handheld realism, or cinematic continuity
-- style consistency matters more than exact bounding boxes
-- the source wins because the whole generated image/video feels native, not because it uses a deterministic UI layout
-- recreating it in Remotion would require dozens of brittle scene-specific layers, masks, paths, or keyframes
-- small visual deviations are acceptable as long as the viral hook, premise, pacing, and style family survive
-
-Choose Remotion when the format has several of these traits:
-
-- UI containers, screenshots, chat bubbles, scorecards, diagrams, slides, labels, or other geometric layout
-- exact caption timing, word highlighting, arrows, circles, magnifiers, or overlays are the main reusable mechanic
-- source clips/images are user-supplied and only need deterministic trimming, cropping, zooming, or captioning
-- brand/product slots need reliable positioning across hundreds of outputs
-- validation depends on exact safe areas, text legibility, and repeatable timing
-
-Use hybrid when AI should generate complex source assets but Remotion should assemble, caption, crop, time, and package them.
-
-#### Full AI Character Video Detection
-
-Detect `full_ai_character_video` when the source has several of these traits:
-
-- recurring generated character or mascot across multiple scenes
-- consistent face, body, wardrobe, material style, or prop relationship
-- multiple story beats where the same character performs actions, reacts, or changes location
-- animation style is part of recognition, such as claymation, anime, Pixar-like, game cutscene, illustrated skit, or puppet/doll style
-- video cannot be reduced to one static image or deterministic UI shell
-- quality depends on maintaining identity through a sequence, not just generating one good shot
-
-For this case, the template should usually expose this operation family:
-
-- `create_character_cards`: generate or normalize character sprite/reference cards, including front/side/close-up/expression/pose references.
-- `create_storyboard`: generate a scene-by-scene image storyboard from the viral steering contract, character cards, and user brief.
-- `generate_scene_videos`: turn storyboard frames/keyframes into short AI video clips with scene-level action and camera prompts.
-- `stitch_video`: assemble clips, narration, captions, audio, transitions, CTA, and final safe-area formatting.
-
-Use Remotion for `stitch_video`, captions, audio, timing, crop/fit, and light overlays. Do not use Remotion to fake character acting frame by frame.
-
-### 6. Plan Vidfarm Template
-
-Run [template-planner-prompt.md](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/auto-create-templates/template-planner-prompt.md) with the production graph. It should output a template plan containing:
-
-- slug and title
-- `about.viral_dna`
-- `about.visual_dna`
-- `about.links_to_inspiration`
-- `about.sound`
-- `about.proposal_generator`
-- `about.skeleton_prompt`
-- `about.sample_prompts`
-- viral steering rules that every prompt/output must satisfy
-- visual preservation rules, with an explicit importance level
-- config schema
-- operation list
-- operation input schemas
-- workflow/job plan
-- Remotion composition plan if needed
-- architecture fit decision, including why Remotion is or is not appropriate
-- AI-native prompt/reference plan when deterministic assembly would be brittle
-- character-consistency workflow when the source is a full AI character video
-- provider requirements
-- validation checklist
-- risk notes
-
-The output should match [template-plan.schema.json](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/auto-create-templates/template-plan.schema.json).
-
-### 7. Generate And Validate
-
-Scaffold normally:
-
-```bash
-npx @mevdragon/vidfarm-devcli generate-template \
-  --slug-id <slug_id> \
-  --template-dir ./templates/vidfarm_template_<slug> \
-  --link-to-original "<source_url>" \
-  --source-notes-path ./drafts/<format_slug>/source.md \
-  --source-preview-dir ./drafts/<format_slug>/preview
-```
-
-Then implement from the plan:
-
-- public operations stay coarse-grained and async
-- viral DNA is persisted as a steering contract, not just descriptive metadata; generation prompts should actively enforce the hook, tension, payoff, pacing, and audience psychology that make the format work
-- visual DNA is persisted according to its preservation decision; preserve tightly only when visuals support the viral mechanism, otherwise allow controlled variation
-- timing parameters are exposed when useful instead of being buried as constants; at minimum support `duration_ms` per scene/slide/media slot and sensible min/max clamping
-- caption/font parameters prefer TikTok-native defaults and can be configured when the format's recognizability depends on typography
-- generated media goes through `ctx.storage`
-- `ctx.storage` keys are job-relative only, such as `backgrounds/slide-01.png`, `slides/slide-01.png`, `audio/narration.wav`, `renders/final.mp4`, or `manifests/run.json`
-- do not generate absolute platform storage keys like `templates/${templateId}/users/${ctx.customer.id}/...`; hosted Vidfarm prefixes template job artifacts automatically
-- do not import the AWS SDK, create S3 clients, mutate `process.env.AWS_*`, or read `REMOTION_AWS_*` in template code
-- video render props reference artifact URLs, not base64
-- Remotion is used only where it is the right tool: deterministic layout, captions, overlays, timing, simple motion, and final edit
-- if the format exceeds Remotion's practical complexity ceiling, preserve it as an AI-native prompt/reference template and use Remotion only for optional wrapping, captions, or stitching
-- image/video providers are used for assets that cannot be deterministically composed
-- provider/model recommendations from `SKILL.developer.md` are persisted in the template-local `SKILL.md` and near the top of `src/template.ts` as a checked-in constant or clearly named comment block
-- generated templates must not set a fixed `providerHint`, hidden provider fallback, or operation payload default that can strand jobs when the customer lacks that provider key. Operations should be provider-agnostic where possible and must call `ctx.providers.*` so platform provider resolution runs before AI generation.
-- provider preferences are saved template config, not operation payload defaults. Keep operation provider fields optional explicit overrides, and express provider preference as payload override -> saved config -> platform-compatible fallback from available customer keys -> documented failure.
-- do not generate schemas like `provider: z.enum(...).default("gemini")`, `tts_provider: z.enum(...).default("openai")`, or `transcription_provider: z.enum(...).default(...)` inside operation input schemas.
-- do not generate parser helpers that silently return `"gemini"`, `"openai"`, or `"openrouter"` when config is missing unless the downstream `ctx.providers.*` call can still fall back to another compatible saved customer key.
-- avoid generating `defaultProvider: z.enum(...).default("openai")` or similar fixed config defaults unless the job still falls back to another compatible saved provider key when that default is unavailable
-- OpenAI image calls must use only supported `size` values: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `2048x1152`, `3840x2160`, `2160x3840`, or `auto`
-- Gemini image calls must use `aspectRatio` from `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `21:9`, or `9:21`, plus `imageSize` from `1K`, `2K`, or `4K`; do not pass arbitrary pixel sizes to Gemini
-- translate requested framing into the selected provider's supported size fields at call time, especially when fallback can switch providers
-- template-local `SKILL.md` must describe operations, payloads, provider caveats, and examples
-
-Recommended baseline models, unless the template has an explicit reason to differ:
-
-```ts
-const TEMPLATE_PROVIDER_RECOMMENDATIONS = {
-  text: {
-    openai: "gpt-5.4",
-    gemini: "gemini-3.1-flash-lite",
-    openrouter: "qwen/qwen3.6-flash"
-  },
-  layout_analysis: {
-    openai: "gpt-5.4",
-    gemini: "gemini-3.1-flash-lite",
-    openrouter: "qwen/qwen3.6-flash"
-  },
-  image: {
-    openai: "gpt-image-2",
-    gemini: "gemini-3-pro-image-preview",
-    openrouter: "google/gemini-3.1-flash-image-preview"
-  },
-  video: {
-    openai: "sora-2",
-    gemini: "veo-3.0-generate-001"
-  },
-  tts: {
-    openai: "gpt-4o-mini-tts-2025-12-15",
-    gemini: "gemini-3.1-flash-tts-preview",
-    openrouter: "google/gemini-3.1-flash-tts-preview"
-  },
-  stt: {
-    openai: "gpt-4o-mini-transcribe-2025-12-15",
-    gemini: "gemini-3.1-flash-lite-preview",
-    openrouter: "openai/gpt-4o-mini-transcribe"
-  }
-} as const;
-```
-
-Validate:
-
-```bash
-npx @mevdragon/vidfarm-devcli validate-template --template-id <slug_id>
-npx @mevdragon/vidfarm-devcli session
-```
-
-Then run at least one real local operation and inspect artifacts.
-
-## Operation Patterns
-
-Most auto-created templates should expose two paths:
-
-- `create_plan`: turn a prompt/product brief into a concrete script, shot list, asset list, and render plan.
-- `render_video` or `create_video`: generate/assemble the final output from explicit assets or from the plan.
-
-`create_plan` must include a viral compliance section in its output:
-
-- which viral DNA rules the plan is using
-- how the first frame/hook preserves the source format's click driver
-- how the middle preserves tension, curiosity, status, proof, or emotional movement
-- how the ending preserves payoff, loop, share/save behavior, or CTA
-- whether visual DNA is critical, supportive, optional, or low-importance for this format
-- which visual rules are enforced vs allowed to vary
-
-Every video-producing template should make timing explicit. The default input shape should allow:
-
-- `duration_ms` for each scene, slide, or media slot
-- `caption_timing_mode`: transcript-derived, fixed beat groups, or manual timestamps
-- `transition_ms`
-- `hold_ms`
-- optional `total_duration_ms` target with proportional scaling
-- min/max duration clamps so batch generation cannot create broken pacing
-
-Every captioned template should strongly prefer TikTok-native typography. Use checked-in fonts when available, especially `TikTokSans-SemiBold.ttf` from the reference template assets, with practical fallbacks such as Montserrat or system sans. Expose caption styling in config only where it is useful; otherwise default to the closest source-matching TikTok style.
-
-Caption fonts are an allowlist, not a vibe. New templates should default to these IDs:
-
-- `tiktok_sans_semibold` for native TikTok captions, subtitles, and creator-authored overlays
-- `montserrat_semibold` for clean bold social cards and modern overlays
-- `source_code_pro_bold` for code, terminal, receipt, data, and intentionally monospaced formats
-- `georgia_bold` for serif editorial formats
-- `abel` for narrow/condensed UI-like captions
-
-Legacy IDs `montserrat` and `source_code_pro` may be accepted for compatibility, but new configs should use the explicit weighted IDs. A `custom` font is an exception, not an option to expose casually. If a custom font is needed, the template plan and `SKILL.md` must name the font, asset path, fallback, role, and why an approved font would damage the source format.
-
-Important readable text should normally be deterministic. Do not ask image or video models to render captions, subtitles, app UI labels, prices, claims, CTAs, or product offers when those can be composited after generation. Generate a clean background or scene first, then place text with Remotion, SVG/canvas, or Sharp. Allow AI-rendered text only when the whole format is poster/artifact-native and the validation harness includes OCR/readability checks.
-
-Multiline caption renderer requirement:
-
-- wrap each caption once, choose one font size and line height for the whole caption block, and render it as one multiline text block
-- do not render each wrapped line as an independently trimmed image; that makes shorter lines look larger or heavier because trim bounds, line height, and shadow placement vary per line
-- apply shadow/outline to the whole multiline block, then composite the block; line chips can be measured per line after the block layout is fixed
-- tune TikTok Sans wrapping, size, and line spacing separately from Montserrat or generic sans defaults
-- validate with mixed-length wrapped captions and confirm both lines retain the same apparent size, weight, baseline rhythm, and shadow strength
-
-## Output Quality Harness
-
-Every video-producing or image-producing template should include a quality harness in its plan, manifest, and template-local `SKILL.md`. The point is to reject predictable low-quality outputs before the director burns three full generations.
-
-Required report fields:
-
-- `viralCompliance`: whether the first-frame hook, retention driver, and payoff still match the source format
-- `visualPreservation`: which critical visual rules passed or failed
-- `fontPolicy`: selected font IDs, custom font exceptions, and generated-vs-deterministic text decisions
-- `captionReadability`: wrap, size, contrast, shadow/outline, and phone-size legibility
-- `safeArea`: TikTok top/right/bottom collision checks for captions and important UI
-- `assetIntegrity`: missing assets, malformed text in generated images, bad crops, or wrong aspect ratios
-- `finalOutput`: artifact URLs, manifest URLs, duration clamps, ending/payoff, and storage boundary checks
-- `retryPlan`: the smallest failed stage to rerun
-
-The harness should run in four gates:
-
-- Preflight: validate the structured plan before generating expensive assets. The plan must name exact hook text, media slots, caption surfaces, font IDs, timing clamps, and visual preservation rules.
-- Asset check: inspect generated images, clips, audio, and uploaded media before final assembly. Reject bad crops, wrong aspect ratios, AI text artifacts, or missing references here.
-- Composition check: validate deterministic layout. Caption safe area, font allowlist, multiline renderer, chip geometry, and shadow/outline failures are code/config failures, not creative prompt failures.
-- Final check: validate the rendered image or MP4 against the viral DNA, visual preservation contract, duration, storage artifacts, and retry plan.
-
-Retry rules:
-
-- If font, safe-area, caption wrapping, chip geometry, storage, or Remotion layout fails, fix code/config and rerender. Do not regenerate the whole creative.
-- If one generated asset fails, retry only that asset with stronger references or tighter prompt constraints.
-- If the first-frame hook, story logic, or payoff fails, regenerate the script/plan before spending more image/video generations.
-- If an AI-native style rule fails twice, switch to storyboard/keyframes, better references, or deterministic compositing for the failing surface.
-
-For simple image formats:
-
-- `create_image`: exact/director-controlled path
-- `create_image_auto`: AI-brief path that writes exact text and image prompts first
-
-For slideshow formats:
-
-- `create_slides`: returns frames, manifest, and render input
-- `render_video`: turns frames or mixed media slots into MP4
-
-For Remotion formats that include remote source footage:
-
-- preserve director-supplied media URLs as direct render inputs
-- prefer Remotion `Video` or `@remotion/media` `Video` for remote video playback
-- do not choose `OffthreadVideo` for remote source footage
-
-For complex video formats:
-
-- `create_script`: hook, narration/dialogue, beat list
-- `create_storyboard`: frame prompts and continuity notes
-- `generate_assets`: AI images/video clips/audio
-- `render_video`: deterministic edit and overlays
-
-For full AI character videos:
-
-- `create_character_cards`: produces character reference images and a character bible manifest
-- `create_storyboard`: produces ordered storyboard frames/keyframes with scene prompts, camera notes, action notes, and continuity notes
-- `generate_scene_videos`: produces one video clip per storyboard scene, using character cards and storyboard frames as references where the provider supports it
-- `stitch_video`: combines generated clips, voice/music/sfx, captions, transitions, and CTA into the final video
-
-The output manifest should keep character cards, storyboard frames, scene clips, audio, and final render as separate artifacts so the workflow can be resumed or revised at any stage.
-
-For AI-native reference formats:
-
-- `create_prompt_plan`: convert a product/audience brief into a source-faithful prompt/reference contract
-- `generate_reference_asset`: produce the final image or video using source DNA, attachments, and style constraints
-- `wrap_video` or `render_video`: optional Remotion wrapper for platform-safe duration, captions, music, CTA, or end card
-
-## Production Graph Principles
-
-The graph should be precise enough that an agent can implement a template without rewatching the source.
-
-Every timeline item should include:
-
-- `start_ms` and `end_ms`
-- `duration_ms`
-- `role`: hook, setup, proof, gag, reveal, CTA, transition, b-roll, UI, caption, overlay, audio
-- `asset_kind`: source_video, generated_video, generated_image, uploaded_image, uploaded_video, rendered_ui, text, audio, shape, effect
-- `replaceability`: fixed, variable, optional, generated
-- `implementation`: remotion, ai_image, ai_video, tts, stt, user_upload, external_clip, html_canvas
-- `architecture_fit`: remotion, ai_native_reference, hybrid, or manual_review
-- `character_consistency`: none, light, strict, or identity_locked
-- `safe_area_notes`
-- `validation_notes`
-
-The graph should separate four layers:
-
-- viral layer: hook, audience psychology, tension, payoff, retention, share/save reason
-- narrative layer: what story or argument happens
-- visual layer: frames, shots, UI, layout, overlays
-- audio layer: speech, captions, music, sfx
-- interaction layer: pointing, circling, zooming, highlighting, magnifying, camera movement
-
-## Guardrails
-
-- Do not turn copyrighted movie/TV clips into a template dependency. Model those formats as user-supplied clip slots or generate parody-safe replacements.
-- Do not require AWS, S3, or cloud Remotion setup for local template creation.
-- Do not write binary media into JSON outputs. Store with `ctx.storage` and return URLs.
-- Do not include hosted platform prefixes in template storage keys. The platform owns `templates/:template_id/users/:user_id/jobs/:job_id/`; templates provide only the artifact path inside the job.
-- Do not use direct AWS/S3 or Remotion credential environment variables in template code. Use `ctx.storage` and `ctx.remotion`.
-- Do not reconstruct hosted storage URLs. Preserve URLs returned by `ctx.storage`, provider uploads, or prior job results, and pass canonical `result.renderVideoInput` objects through to downstream `render_video` operations.
-- Every `ctx.remotion.render(...)` call must include `preflightUrls` for remote media Remotion will load, with field labels such as `slides[2].imageUrl`, `scene_media_url`, or `demo_video_url`.
-- Do not invent REST endpoints. Use standard Vidfarm operations and jobs.
-- Do not put provider defaults in operation payload schemas. That bypasses saved customer template config and can make the editor agent wait for the wrong provider key.
-- Do not set fixed `providerHint` or hardcoded provider defaults that make an operation wait for OpenAI, Gemini, or another provider when the customer has a different compatible provider saved.
-- Do not send unsupported image dimensions to provider APIs: OpenAI accepts only `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `2048x1152`, `3840x2160`, `2160x3840`, or `auto`; Gemini uses supported `aspectRatio` plus `imageSize` `1K`/`2K`/`4K`, not raw pixel sizes.
-- Do not treat DNA analysis as sufficient. It explains why and what; the production graph explains how.
-- Do not bury viral DNA as static `about` text only. It must steer prompts, plans, operation outputs, validation checks, and template usage docs.
-- Do not preserve visual traits blindly. First decide whether each trait materially supports the viral DNA; then preserve only the traits that matter.
-- Do not overuse AI video when Remotion or HTML composition can reproduce the format deterministically.
-- Do not force Remotion onto formats whose value comes from organic generated style, character acting, cinematic movement, or dense visual texture. Use AI-native prompt/reference generation when it will be more robust.
-- Do not ignore audio. Many medium/hard formats are paced by voice, captions, and beat timing.
-
-## Suggested Automation Command
-
-A future CLI command could wrap the harness like this:
-
-```bash
-npx @mevdragon/vidfarm-devcli auto-create-template \
-  --source ./drafts/<format_slug>/preview/source.mp4 \
-  --source-notes ./drafts/<format_slug>/source.md \
-  --slug-id <slug_id> \
-  --template-dir ./templates/vidfarm_template_<slug> \
-  --run-dir ./auto-create-templates/runs/<run_id>
-```
-
-Internally it should:
-
-1. stage source media
-2. extract media artifacts
-3. scaffold template with DNA analysis
-4. generate production graph
-5. generate template plan
-6. optionally open a code-generation pass to implement the template
-7. validate template metadata and run smoke jobs