@mevdragon/vidfarm-devcli 0.2.12 → 0.2.14

package/auto-create-hyperframe-templates/template-plan.schema.json

@@ -0,0 +1,311 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "HyperFrame Template Plan",
+  "type": "object",
+  "required": [
+    "template",
+    "composition",
+    "source_assets",
+    "layers",
+    "caption_layout",
+    "editor_behavior",
+    "lambda",
+    "deployment",
+    "artifacts",
+    "validation",
+    "implementation_files"
+  ],
+  "properties": {
+    "template": {
+      "type": "object",
+      "required": ["slug_id", "title", "description", "source_folder", "source_type"],
+      "properties": {
+        "slug_id": { "type": "string" },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "source_folder": { "type": "string" },
+        "source_type": { "enum": ["single_video", "scene_split_video", "slideshow", "mixed_media"] },
+        "viral_dna": { "type": "object" },
+        "visual_dna": { "type": "object" }
+      },
+      "additionalProperties": false
+    },
+    "composition": {
+      "type": "object",
+      "required": ["composition_id", "width", "height", "fps", "duration_seconds", "background_color", "root_attributes"],
+      "properties": {
+        "composition_id": { "type": "string" },
+        "width": { "type": "integer", "minimum": 1 },
+        "height": { "type": "integer", "minimum": 1 },
+        "fps": { "type": "number", "minimum": 1 },
+        "duration_seconds": { "type": "number", "minimum": 0 },
+        "background_color": { "type": "string" },
+        "root_attributes": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "source_assets": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/sourceAsset" }
+    },
+    "layers": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/layer" }
+    },
+    "caption_layout": {
+      "type": "object",
+      "required": ["safe_areas", "default_style", "surfaces", "rules"],
+      "properties": {
+        "safe_areas": { "$ref": "#/$defs/safeAreas" },
+        "default_style": { "$ref": "#/$defs/textStyle" },
+        "surfaces": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "layer_ids", "geometry", "rules"],
+            "properties": {
+              "id": { "type": "string" },
+              "layer_ids": { "type": "array", "items": { "type": "string" } },
+              "geometry": { "$ref": "#/$defs/geometry" },
+              "rules": { "type": "array", "items": { "type": "string" } }
+            },
+            "additionalProperties": false
+          }
+        },
+        "rules": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "editor_behavior": {
+      "type": "object",
+      "required": ["publish_source_of_truth", "track_collision_policy", "delete_scene_test"],
+      "properties": {
+        "publish_source_of_truth": { "type": "string" },
+        "preview_playback_source_allowed": { "type": "boolean" },
+        "track_collision_policy": { "type": "string" },
+        "delete_scene_test": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "lambda": {
+      "type": "object",
+      "required": ["memory_estimate", "render_defaults"],
+      "properties": {
+        "memory_estimate": { "$ref": "#/$defs/lambdaMemoryEstimate" },
+        "render_defaults": {
+          "type": "object",
+          "required": ["width", "height", "fps"],
+          "properties": {
+            "width": { "type": "integer", "minimum": 1 },
+            "height": { "type": "integer", "minimum": 1 },
+            "fps": { "type": "number", "minimum": 1 }
+          },
+          "additionalProperties": false
+        },
+        "estimated_lambda_gb_seconds": { "type": "number", "minimum": 0 },
+        "estimated_cost_usd": { "type": "number", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "deployment": {
+      "type": "object",
+      "required": ["prod_lambda_site", "output_url_policy"],
+      "properties": {
+        "prod_lambda_site": {
+          "type": "object",
+          "required": ["schema", "stack_name", "region", "site_id", "project_dir", "composition_file", "memory_mb"],
+          "properties": {
+            "schema": { "const": "vidfarm.hyperframe.lambda-site.v1" },
+            "stack_name": { "type": "string" },
+            "region": { "type": "string" },
+            "site_id": { "type": ["string", "null"] },
+            "project_dir": { "type": "string" },
+            "composition_file": { "type": "string" },
+            "memory_mb": { "enum": [2048, 3072, 4096, 6144, 8192, 10240] },
+            "render_defaults": {
+              "type": "object",
+              "properties": {
+                "width": { "type": "integer", "minimum": 1 },
+                "height": { "type": "integer", "minimum": 1 },
+                "fps": { "type": "number", "minimum": 1 }
+              },
+              "additionalProperties": false
+            },
+            "output_url_policy": { "enum": ["signed_https_final_output_only"] },
+            "prestage_site_requested": { "type": "boolean" },
+            "site_upload_command": { "type": "string" },
+            "site_upload_api": { "type": "string" },
+            "site_upload_stdout": { "type": "string" },
+            "site_upload_error": { "type": "string" },
+            "estimated_lambda_gb_seconds": { "type": "number", "minimum": 0 },
+            "estimated_cost_usd": { "type": "number", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "output_url_policy": { "enum": ["signed_https_final_output_only"] }
+      },
+      "additionalProperties": false
+    },
+    "artifacts": {
+      "type": "object",
+      "required": ["files", "decomposition_shape", "lambda_site_shape"],
+      "properties": {
+        "files": { "type": "array", "items": { "type": "string" } },
+        "decomposition_shape": { "type": "object" },
+        "lambda_site_shape": { "type": "object" }
+      },
+      "additionalProperties": false
+    },
+    "validation": {
+      "type": "object",
+      "required": ["artifact_checks", "timeline_checks", "publish_checks", "caption_checks", "lambda_checks", "final_output_checks"],
+      "properties": {
+        "artifact_checks": { "type": "array", "items": { "type": "string" } },
+        "timeline_checks": { "type": "array", "items": { "type": "string" } },
+        "publish_checks": { "type": "array", "items": { "type": "string" } },
+        "caption_checks": { "type": "array", "items": { "type": "string" } },
+        "lambda_checks": { "type": "array", "items": { "type": "string" } },
+        "final_output_checks": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "implementation_files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "purpose"],
+        "properties": {
+          "path": { "type": "string" },
+          "purpose": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "sourceAsset": {
+      "type": "object",
+      "required": ["id", "type", "path"],
+      "properties": {
+        "id": { "type": "string" },
+        "type": { "enum": ["video", "image", "audio", "font", "json", "html"] },
+        "path": { "type": "string" },
+        "width": { "type": "integer", "minimum": 0 },
+        "height": { "type": "integer", "minimum": 0 },
+        "duration_seconds": { "type": "number", "minimum": 0 },
+        "role": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "geometry": {
+      "type": "object",
+      "required": ["x", "y", "width", "height"],
+      "properties": {
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "width": { "type": "number", "exclusiveMinimum": 0 },
+        "height": { "type": "number", "exclusiveMinimum": 0 },
+        "unit": { "const": "percent" }
+      },
+      "additionalProperties": false
+    },
+    "safeAreas": {
+      "type": "object",
+      "properties": {
+        "top_percent": { "type": "number", "minimum": 0 },
+        "right_percent": { "type": "number", "minimum": 0 },
+        "bottom_percent": { "type": "number", "minimum": 0 },
+        "left_percent": { "type": "number", "minimum": 0 },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "textStyle": {
+      "type": "object",
+      "properties": {
+        "font_family": { "type": "string" },
+        "font_weight": { "type": "integer" },
+        "font_size_px": { "type": "number" },
+        "line_height": { "type": "number" },
+        "color": { "type": "string" },
+        "background": { "type": "string" },
+        "background_style": { "enum": ["plain", "outline", "radial_halo", "highlight_solid", "highlight_translucent", "panel"] },
+        "text_align": { "enum": ["left", "center", "right"] },
+        "max_lines": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": false
+    },
+    "layer": {
+      "type": "object",
+      "required": ["id", "kind", "start", "duration", "track", "z", "mode", "source_of_truth", "geometry", "viral_alignment"],
+      "properties": {
+        "id": { "type": "string" },
+        "kind": { "enum": ["video", "image", "audio", "caption", "html", "shape", "effect"] },
+        "start": { "type": "number", "minimum": 0 },
+        "duration": { "type": "number", "exclusiveMinimum": 0 },
+        "track": { "type": "integer", "minimum": 0 },
+        "z": { "type": "integer" },
+        "mode": { "enum": ["both", "editor", "publish"] },
+        "source_of_truth": { "enum": ["source_media", "deterministic_html", "generated_asset", "user_asset", "computed_effect"] },
+        "geometry": { "$ref": "#/$defs/geometry" },
+        "media": {
+          "type": "object",
+          "properties": {
+            "src": { "type": "string" },
+            "asset_id": { "type": "string" },
+            "media_start": { "type": "number", "minimum": 0 },
+            "media_end": { "type": "number", "minimum": 0 },
+            "fit": { "enum": ["cover", "contain", "fill", "none"] },
+            "muted": { "type": "boolean" },
+            "volume": { "type": "number", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "text": {
+          "type": "object",
+          "properties": {
+            "content": { "type": "string" },
+            "style": { "$ref": "#/$defs/textStyle" }
+          },
+          "additionalProperties": false
+        },
+        "html_contract": {
+          "type": "object",
+          "properties": {
+            "description": { "type": "string" },
+            "required_classes": { "type": "array", "items": { "type": "string" } },
+            "editable_fields": { "type": "array", "items": { "type": "string" } }
+          },
+          "additionalProperties": false
+        },
+        "viral_alignment": { "type": "string" },
+        "publish_notes": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "lambdaMemoryEstimate": {
+      "type": "object",
+      "required": ["recommended_memory_mb", "confidence", "complexity_scores", "rationale", "risk_flags"],
+      "properties": {
+        "recommended_memory_mb": { "enum": [2048, 3072, 4096, 6144, 8192, 10240] },
+        "confidence": { "enum": ["low", "medium", "high"] },
+        "complexity_scores": { "type": "object", "additionalProperties": { "type": ["number", "integer", "string", "boolean"] } },
+        "rationale": { "type": "string" },
+        "risk_flags": { "type": "array", "items": { "type": "string" } },
+        "benchmark_override": {
+          "type": ["object", "null"],
+          "properties": {
+            "memory_mb": { "enum": [2048, 3072, 4096, 6144, 8192, 10240] },
+            "reason": { "type": "string" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/auto-create-hyperframe-templates/template-planner-prompt.md

@@ -0,0 +1,144 @@
+# HyperFrame Template Planner Prompt
+
+You are a senior HyperFrames composition engineer.
+
+Given a HyperFrames production graph, produce a concrete implementation plan for `composition.html`, `composition.json`, and `lambda-site.json`. Return only JSON matching `template-plan.schema.json`.
+
+## Planning Rules
+
+- The output is an editable HyperFrames project, not a Vidfarm operation package.
+- Persist the source format's viral and visual rules inside `composition.json`.
+- Use deterministic HTML/CSS for captions, text, app UI, comments, notifications, overlays, shapes, and simple graphics.
+- Use timed media layers for MP4 scenes and image slides.
+- Separate source audio from source video when audio should continue across cuts.
+- Do not use a permanent background video as the publish source of truth.
+- If an editor-only playback source is included, mark it `mode: "editor"` or `preview_only: true`.
+- Publish-visible media must be represented by timed layers with explicit start/duration.
+- Empty timeline ranges are valid and should render background only.
+- Use percent geometry for layout and seconds for timing.
+- Use approved font families where possible: `TikTok Sans`, `Montserrat`, `Source Code Pro`, `Georgia`, `Abel`, or a documented custom font.
+- Important readable text must be deterministic unless the source format explicitly depends on poster/artifact-native generated text.
+- Include safe-area rules for TikTok/Reels vertical output.
+- Include Lambda memory estimate and production site metadata.
+- The frontend publish UX should expose the final signed output URL only, not S3 Console or Step Functions Console links.
+
+## Required Output Content
+
+The plan must include:
+
+- template metadata
+- source asset inventory
+- HyperFrames composition root settings
+- layer list
+- caption layout rules
+- safe-area rules
+- editor behavior rules
+- Lambda memory estimate
+- production Lambda site metadata
+- artifact manifest shape
+- validation checklist
+- implementation files to create
+
+## Composition HTML Requirements
+
+The root element should include:
+
+- `data-composition-id`
+- `data-source-folder`
+- `data-width`
+- `data-height`
+- `data-duration`
+
+Layer elements should include:
+
+- `data-hf-id`
+- `data-layer-kind`
+- `data-layer-mode`
+- `data-start`
+- `data-duration`
+- `data-track-index`
+- `data-label`
+
+Media slices should include:
+
+- `data-media-start`
+- `data-playback-start`
+- `src` or `data-src`
+
+For timeline proxies, include:
+
+- `data-vf-timeline-proxy="video"`
+- `data-src`
+
+The publish path must normalize proxies into real timed `<video>` elements.
+
+## Decomposition JSON Requirements
+
+The manifest should include:
+
+- `schema: "vidfarm.hyperframe-decomposition.v1"`
+- `source_folder`
+- `source_type`
+- `created_at`
+- `source_assets`
+- `summary`
+- `viral_dna`
+- `visual_dna`
+- `editor_layers`
+- `caption_layout`
+- `lambda_memory_estimate`
+- `lambda_site`
+- `validation`
+
+Use the same layer IDs in `composition.json` and `composition.html`.
+
+## Lambda Site Requirements
+
+Create `lambda-site.json` with:
+
+- `schema: "vidfarm.hyperframe.lambda-site.v1"`
+- `stack_name`
+- `region`
+- `site_id`
+- `project_dir`
+- `composition_file`
+- `memory_mb`
+- `render_defaults`
+- `output_url_policy`
+- `site_upload_command` or SDK equivalent when `site_id` is null
+
+Default stack settings:
+
+- stack: `hyperframes-vidfarm-prod`
+- region: `us-east-1`
+- memory: `3072`
+
+The plan may recommend `2048`, `4096`, or higher when justified by the memory estimator.
+
+## Lambda Memory Planning
+
+Use `lambda-memory-estimator.md` and return:
+
+- `recommended_memory_mb`
+- `estimated_lambda_gb_seconds`
+- `estimated_cost_usd`
+- `confidence`
+- `rationale`
+- `risk_flags`
+- `benchmark_override`
+
+Use `3072` MB as the ordinary social-video baseline. Prefer lowering to `2048` only for simple static/slideshow cases or measured lightweight video. Prefer raising to `4096` when active video decode, resolution, or effects justify it.
+
+## Validation Gates
+
+The plan is not complete unless it defines:
+
+- artifact checks
+- timeline checks
+- layer publish checks
+- caption/safe-area checks
+- Lambda deployment checks
+- final output checks
+
+Include a specific test for deleting or disabling one video scene and confirming the final render shows background/overlay only during that time range.
+

package/auto-create-templates/AUTO_CREATE_TEMPLATES.md

@@ -37,6 +37,16 @@ The core idea is to avoid asking an agent to "clone this video" in one prompt. T
 
 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:
@@ -196,6 +206,8 @@ 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`
@@ -299,6 +311,8 @@ Run [template-planner-prompt.md](/Users/localghost/Projects/OfficeX/OfficeX/Zoom
 - slug and title
 - `about.viral_dna`
 - `about.visual_dna`
+- `about.links_to_inspiration`
+- `about.sound`
 - `about.proposal_generator`
 - `about.skeleton_prompt`
 - `about.sample_prompts`
@@ -339,12 +353,60 @@ Then implement from the plan:
 - 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
@@ -381,6 +443,18 @@ Every video-producing template should make timing explicit. The default input sh
 
 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
@@ -389,6 +463,35 @@ Multiline caption renderer requirement:
 - 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
@@ -399,6 +502,12 @@ 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
@@ -451,7 +560,14 @@ The graph should separate four layers:
 - 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.

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

@@ -34,6 +34,10 @@ Return only JSON matching `production-graph.schema.json`.
 - 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, line height, and fallback font stack.
+- Classify every important readable text surface as deterministic overlay text, source-media text, or AI-rendered poster/artifact text. Important captions, subtitles, UI labels, offers, prices, claims, and CTAs should default to deterministic overlay text unless the format is explicitly poster/artifact-native.
+- Treat fonts as an allowlist decision. Prefer approved Vidfarm font IDs where possible: `tiktok_sans_semibold`, `montserrat_semibold`, `source_code_pro_bold`, `georgia_bold`, or `abel`. Mark custom or AI-rendered typography as source-critical only when the viral mechanism depends on it.
+- When a text background color appears, classify it as an inline highlight chip unless the source clearly uses a deliberate poster panel. Record that the chip must be measured per wrapped line and must not become a full-width caption box or paragraph wash.
+- When white creator-authored TikTok captions appear, distinguish native radial black halo/outline from web-style directional drop shadow. Record centered multi-layer shadow/blur requirements when the shadow radiates around the glyphs.
 - When captions wrap across lines, record block-level rendering requirements: one shared font size and line height for the full multiline caption, shadow/outline applied to the whole block, and any per-line chip geometry derived after the shared layout. Do not recommend independently trimmed per-line text images.
 - 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.
@@ -68,6 +72,7 @@ Extract:
 - safe areas and layout constraints
 - provider/tool dependencies
 - validation checklist
+- output quality harness gates: preflight, asset check, composition check, final-output check, and targeted retry rules
 
 ## Implementation Classification
 
@@ -107,7 +112,7 @@ 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. Tune TikTok Sans wrapping, size, and line spacing separately from Montserrat or generic sans defaults.
+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. Tune TikTok Sans wrapping, size, and line spacing separately from Montserrat or generic sans defaults. If a background color is present, describe inline line chips that hug the text. If a white caption needs contrast, describe a radial black halo/outline instead of a large one-direction web shadow.
 
 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.