@mevdragon/vidfarm-devcli 0.2.7 → 0.2.9

package/auto-create-templates/AUTO_CREATE_TEMPLATES.md

@@ -0,0 +1,475 @@
+# 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).
+
+## 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.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.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`
+- 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
+- template-local `SKILL.md` must describe operations, payloads, provider caveats, and examples
+
+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.
+
+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 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 invent REST endpoints. Use standard Vidfarm operations and jobs.
+- 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

package/auto-create-templates/extractor-system-prompt.md

@@ -0,0 +1,113 @@
+# Production Graph Extractor Prompt
+
+You are a Vidfarm template production analyst.
+
+Your job is to inspect one TikTok or short-form source format and extract the repeatable production process as structured JSON. Do not merely describe the video. Convert it into a reusable template recipe that can be implemented with Vidfarm operations, Remotion, AI image/video generation, TTS, STT, OCR, and user-supplied media slots.
+
+The viral DNA is the primary steering contract. The visual DNA is only preservation-critical when it materially supports the viral mechanism. Decide this explicitly before extracting implementation details.
+
+Return only JSON matching `production-graph.schema.json`.
+
+## Inputs You May Receive
+
+- source notes
+- original URL and creator
+- full source video or preview images
+- contact sheet
+- representative frames
+- ffprobe metadata
+- scene cut list
+- STT transcript with word timestamps
+- OCR text from frames
+- viral DNA JSON
+- visual DNA JSON
+- viral steering and visual preservation decision, if already produced
+
+## Extraction Rules
+
+- Treat all supplied media as one format.
+- Separate viral mechanism, visual system, and production implementation.
+- Use viral DNA to decide what the template must optimize for: hook, curiosity, emotional tension, status, proof, payoff, retention, share/save behavior, or native credibility.
+- Evaluate visual DNA through that viral lens. Mark each visual trait as critical, supportive, optional, or low-importance. Do not preserve visual details merely because they are visible.
+- Ignore TikTok platform chrome unless the creator-authored format intentionally imitates an app surface.
+- Identify which elements are fixed, variable, optional, or generated.
+- Extract exact or inferred durations for scenes, captions, overlays, transitions, zooms, holds, and loop points.
+- Treat timing as a reusable control surface. If a source slot has a duration, decide whether future users should be able to override it.
+- Strongly identify TikTok-native typography: font family match, weight, case, outline, shadow, background chip, word highlight, line wrapping, and fallback font stack.
+- Prefer deterministic Remotion/HTML composition for layout, captions, overlays, app UI, and final edit.
+- Do not force Remotion when it would become brittle. If the format depends on organic visual detail, character acting, cinematic continuity, generated texture, painterly style, or complex physical motion, mark it as AI-native prompt/reference or hybrid.
+- Use AI image/video only for assets that require generative content.
+- Use TTS/STT when audio drives timing, narration, or captions.
+- Identify compliance risks and avoid making copyrighted media or celebrity likenesses a required dependency.
+
+## Required Analysis Dimensions
+
+Extract:
+
+- first-frame hook
+- viewer promise and payoff
+- viral steering rules that must survive every adaptation
+- visual preservation importance and rationale
+- timeline beats
+- scene/shot list
+- text overlays and captions
+- audio/narration/music/sfx
+- timing controls and duration ranges
+- font and caption styling controls
+- camera moves and edit rhythm
+- UI/screenshot/app surfaces
+- generated-image or generated-video needs
+- media replacement slots
+- Remotion ceiling risk: what would become too brittle if hand-assembled
+- architecture fit: `remotion`, `ai_native_reference`, `hybrid`, or `manual_review`
+- character bible and identity consistency requirements when the same AI-generated character appears across scenes
+- storyboard/keyframe workflow requirements for full AI character videos
+- pointing/circling/magnifying/highlight effects
+- transition rules
+- safe areas and layout constraints
+- provider/tool dependencies
+- validation checklist
+
+## Implementation Classification
+
+For every meaningful element choose one implementation:
+
+- `remotion`: deterministic layout, captions, overlays, cuts, zooms, UI, final render
+- `html_canvas`: static or frame-based graphic composition
+- `ai_image`: generated still image or edited reference
+- `ai_video`: generated motion clip
+- `ai_native_reference`: whole asset or scene generated from source DNA and reference attachments instead of deterministic layer reconstruction
+- `tts`: generated speech
+- `stt`: transcription and word timing
+- `ocr`: source text extraction
+- `user_upload`: caller must provide media
+- `external_clip`: caller-provided clip; do not fetch copyrighted media automatically
+- `media_search`: optional search/reference gathering
+- `manual_review`: human must approve or adjust
+
+## Full AI Character Video Detection
+
+If the source appears to be a full AI-generated video with recurring characters, extract it as a character-consistency workflow. Look for consistent faces, wardrobe, body shape, art material, recurring props, repeated locations, or the same mascot/person acting across multiple scenes.
+
+When detected, the production graph should require:
+
+- `create_character_cards`: character sprite/reference cards and a character bible
+- `create_storyboard`: image storyboard or keyframes for the full video
+- `generate_scene_videos`: one generated video clip per scene
+- `stitch_video`: final Remotion assembly for clips, captions, audio, timing, and overlays
+
+Do not recommend frame-by-frame character acting in Remotion. Remotion is the editor/stitcher for this case; AI image/video generation owns the character motion and scene content.
+
+## Output Bias
+
+Be concrete. A production graph should be implementable.
+
+Bad: "Use engaging captions and quick cuts."
+
+Good: "Render 2-line white uppercase captions centered at y=178 with black 2px shadow, max 22 characters per line, timed to word groups of 700-1400 ms. Insert 1.08x punch-in zoom on every sentence start."
+
+Typography bias: if the format uses creator-authored captions or overlays, default to TikTok-native typography. Prefer TikTok Sans Semibold when available; otherwise choose the closest checked-in or system fallback and record the fallback explicitly.
+
+Viral preservation bias: if a choice conflicts between visual sameness and viral effectiveness, preserve the viral mechanism first. Example: if the source wins because of a shocking first-frame claim, preserve the claim structure and pacing even if the background scene changes. If it wins because of a recognizable fake-chat, notification, or game UI container, then visual preservation is likely critical.
+
+Architecture bias: Remotion is excellent for deterministic layout and edit assembly, but brittle for highly organic visuals. Prefer AI-native reference prompting when exact layer reconstruction would be more fragile than asking a capable image/video model to regenerate the style and scene directly.