@mevdragon/vidfarm-devcli 0.2.8 → 0.2.9

package/.env.example

@@ -6,10 +6,19 @@ OPENROUTER_API_KEY=""
 GEMINI_API_KEY=""
 PERPLEXITY_API_KEY=""
 
+# Optional. Production CDK wires these automatically for the EC2 app and ZIP Lambda.
+VIDFARM_ZIP_LAMBDA_URL=""
+VIDFARM_ZIP_LAMBDA_SECRET=""
+VIDFARM_BILLING_URL=""
+VIDFARM_BILLING_SECRET=""
+VIDFARM_RATE_LIMITS_TABLE_NAME=""
+
 # Optional when calling a hosted Vidfarm API directly.
 VIDFARM_USER_ID=""
 VIDFARM_API_KEY=""
 
 # Optional local overrides. The CLI will choose sensible local defaults.
 PUBLIC_BASE_URL="http://localhost:3310"
+# Optional public browser-facing chat endpoint. Leave empty locally unless you want the UI to hit a separate chat host directly.
+PUBLIC_EDITOR_CHAT_URL=""
 REMOTION_MODE="local"

package/GETTING_STARTED.developers.md

@@ -46,7 +46,7 @@ https://calendly.com/zoom-gtm/creative-director-interviews
 
 0. Tell your manager your email so he can whitelist you access to Vidfarm. After he confirms you have access, login at https://vidfarm.cloud.zoomgtm.com
 
-1. Open VSCode in a new project called "Vidfarm-Developer"
+1. Open VSCode in a new project and create a new project folder "Vidfarm-Developer"
 
 2. Open terminal and login to github cli and npm cli (ask ai/codex if you need help). ask your manager if they gave you npm access to "vidfarm-devcli" yet.
 
@@ -85,28 +85,3 @@ That will populate with a reference folder of what a template code looks like. W
 8. Create a new folder beside src called `drafts/` which is where we will put messy files when needed.
 
 9. Now find an easy winning format from https://winning-formats-gallery-tiktok.cloud.zoomgtm.com/ and save the image to your drafts/ folder. then tell Codex to look at that image (right click, copy relative path, paste to codex), then tell codex please make a new template based on the image.
-
-## Shipping Updates
-
-For a brand-new template, register the source once.
-
-For an update to an already-registered template:
-
-1. Push the exact commit to GitHub.
-2. Submit that exact commit SHA to Vidfarm for review.
-3. Wait for platform admin approval and activation.
-
-Developer CLI example:
-
-```bash
-node dist/src/cli.js publish-update-hosted \
-  --env-file .env \
-  --template-id YOUR_TEMPLATE_ID \
-  --slug-id vidfarm_template_your_slug \
-  --repo-url https://github.com/your-org/your-repo.git \
-  --branch main \
-  --template-module-path src/vidfarm_template_your_slug/src/template.ts \
-  --commit-sha YOUR_GITHUB_COMMIT_SHA
-```
-
-This does not make the template live. The CLI packages that exact commit locally, uploads the artifact to Vidfarm-managed S3, and creates or refreshes the reviewable release so a platform admin can approve and activate it.

package/README.md

@@ -30,6 +30,7 @@ npx @mevdragon/vidfarm-devcli dev --port 3310 --reset
 npx @mevdragon/vidfarm-devcli session
 npx @mevdragon/vidfarm-devcli validate-template --template-id template_0000
 npx @mevdragon/vidfarm-devcli copy-reference-template --template-dir ./src/vidfarm_template_0000
+npx @mevdragon/vidfarm-devcli autocreate-template ./drafts/my_format ./templates/vidfarm_template_my_format
 npx @mevdragon/vidfarm-devcli generate-template --slug-id template_0001 --template-dir ./templates/vidfarm_template_0001
 npx @mevdragon/vidfarm-devcli analyze-viral-dna --template-dir ./templates/vidfarm_template_0001
 npx @mevdragon/vidfarm-devcli analyze-visual-dna --template-dir ./templates/vidfarm_template_0001
@@ -38,6 +39,8 @@ npx @mevdragon/vidfarm-devcli presign-preview-media --file ./drafts/preview/exam
 
 After install, the package exposes both `vidfarm` and `vidfarm-devcli` as local binaries.
 
+`autocreate-template` prepares the auto-create harness run folder, stages media from the input path, snapshots the current harness files, scaffolds the output template, and writes an agent handoff prompt at `auto-create-templates/runs/<run_id>/agent_prompt.md`. Keep improving `auto-create-templates/AUTO_CREATE_TEMPLATES.md`; each new run uses the current harness and stores a per-run snapshot for traceability.
+
 ## What The Local CLI Does
 
 The local CLI runs the same template contract used by the hosted platform, but with local-first defaults:

package/SKILL.developer.md

@@ -26,10 +26,51 @@ Do not use this skill for:
 - production deploys, release admin, or shared cloud infrastructure
 - asking for AWS, S3, Remotion cloud, or other platform secrets
 
+## Hosted Remotion Cost Reporting
+
+When a template runs a hosted Remotion Lambda render, template code should report the base render cost back to platform billing.
+
+Use the template job context billing helper:
+
+```ts
+await ctx.billing.record({
+  type: "render",
+  costUsd: 0.35,
+  costCenterSlug: "remotion_lambda",
+  idempotencyKey: `remotion_lambda:${render.renderId}`,
+  occurredAtMs: Date.now(),
+  metadata: {
+    render_id: render.renderId,
+    ...render.metadata
+  }
+});
+```
+
+Rules:
+
+- only report the raw base Remotion cost in `costUsd`
+- always use `costCenterSlug: "remotion_lambda"` for hosted Remotion Lambda usage
+- always provide a stable `idempotencyKey`, typically derived from `render.renderId`
+- include useful diagnostics in `metadata`, such as `render_id`, composition ID, mode, and output details
+- do not compute customer wallet debits in template code
+- do not set platform pricing policy in template code
+
+The platform billing service applies wallet mutations and pricing centrally. The default customer charge currently uses an approximately `20%` safety-buffer markup over reported base cost.
+
+Job-status billing response fields are also platform-managed. Template developers do not need to shape the API response; they only need to keep reporting real usage through existing helpers where applicable. The customer-facing job response exposes `billing.consumed_usd` and does not expose internal `base_cost_usd`.
+
 ## Third-Party Publish Rule
 
 Third-party template developers publish template code by pushing git commits to GitHub. That is the only code-distribution step they own.
 
+Default hosted update rule:
+
+- for an already-registered template, the default hosted handoff is `publish-update-hosted --commit-sha <sha>`
+- do not default to prod-side branch-head import for normal template updates
+- if the source repo is private, treat artifact publish as the normal path, not as a fallback
+- if `gh` is available, prefer an authenticated local clone such as `gh repo clone <owner>/<repo>` before publishing a hosted update
+- checked-in `about/preview-*` files only become live hosted preview media after platform import and activation sync them into `templates/:template_id/about/*`
+
 Important nuance:
 
 - GitHub is relevant for the hosted handoff, not for normal local template authoring
@@ -44,6 +85,25 @@ The third-party developer responsibility is:
 - for an already-registered template update, publish the exact GitHub commit SHA with `publish-update-hosted`
 - stop there and hand off to the platform team
 
+Preferred private-repo publish pattern:
+
+```bash
+gh repo clone mevdragon/vidfarm_templates ./vidfarm_templates
+git -C ./vidfarm_templates rev-parse HEAD
+node dist/src/cli.js publish-update-hosted \
+  --env-file .env \
+  --repo-dir ./vidfarm_templates \
+  --template-id <template-id> \
+  --slug-id <template-slug> \
+  --repo-url https://github.com/mevdragon/vidfarm_templates.git \
+  --branch main \
+  --template-module-path src/<template-folder>/src/template.ts \
+  --skill-path src/<template-folder>/SKILL.md \
+  --install-command "npm install --prefix src/<template-folder>" \
+  --build-command "npm run build --prefix src/<template-folder>" \
+  --commit-sha <exact-github-commit>
+```
+
 The third-party developer should not:
 
 - run `import-source-prod`
@@ -55,12 +115,30 @@ The third-party developer should not:
 
 Private repo rule:
 
+- if the registered source repo is private, do not treat prod-side `git ls-remote` or raw GitHub import as the primary publish mechanism
+- for private repos, the reliable default is: authenticated local clone -> `publish-update-hosted --commit-sha ...` -> platform review -> admin approve/activate
 - if the registered source repo is private, assume the intended hosted setup is that Vidfarm has already been granted access to it
 - when repo sharing is needed, the repo should be shared with GitHub username `mevdragon`
 - do not treat a private repo itself as a problem if that access assumption is already stated
 
 For third-party developers, Remotion is local and storage should be accessed through Vidfarm helpers. Do not require cloud Remotion setup or hand-written S3 integration for normal template work.
 
+## Media Storage Boundary
+
+Template job results must keep binary media out of JSON. If a workflow produces, fetches, or accepts image/audio/video bytes, write those bytes through `ctx.storage.putBuffer(...)` and put the returned URL in the job output, manifest, and render inputs.
+
+Rules:
+
+- use `ctx.storage.putBuffer(...)`, `ctx.storage.putJson(...)`, and `ctx.storage.putText(...)` for artifacts
+- return artifact URLs in fields like `imageUrl`, `thumbnailUrl`, `audioUrl`, `videoUrl`, `files`, `manifest`, and render input objects
+- do not persist `data:image/...;base64,...`, raw base64 strings, Buffers, or large inline SVG/image strings in `result.output`
+- accepting a `data:image/*` input is allowed, but decode it and store it as an artifact before including it in any durable output
+- generated provider media should be stored immediately; never use `Buffer.from(bytes).toString("base64")` as a durable result value
+- Remotion render props may reference artifact URLs; use short-lived inline data only inside a private render helper if it is not returned, logged, or written to a manifest
+- keep manifests lightweight enough to inspect in job history and webhooks; they should describe artifacts by URL, not embed artifact bytes
+
+This boundary matters because job results are saved in SQLite, returned by REST APIs, included in webhooks, and surfaced in editor history. Embedding base64 media can turn one small job result into multi-megabyte JSON and break UI history views.
+
 ## Agent Operating Rule
 
 If the user gives you a media file, a screenshot, a folder of source assets, or a link to an original viral post and says some variant of "turn this into a template", you should default to this workflow:
@@ -164,6 +242,8 @@ For a third-party developer, the hosted publish handoff is:
 3. if the template is already registered and the location did not change, publish the exact GitHub commit SHA with `publish-update-hosted`; that command uploads a signed artifact for that commit
 4. stop there, then tell the platform operator which commit was submitted if they ask
 
+If the repo is private or prod-side GitHub access is uncertain, use the exact same `publish-update-hosted` flow anyway. It packages the commit locally and avoids relying on hosted `git ls-remote` or hosted branch-head import as the update path.
+
 Registration data should be treated like this:
 
 - `repo_url`: the GitHub repo that contains the template code
@@ -191,6 +271,7 @@ When reasoning about hosted visibility:
 - the required developer-side outcome is that the intended commit is pushed to the registered branch
 - do not infer hosted GitHub access failure from a local CLI auth error
 - for hosted template updates, the review artifact is uploaded from the developer machine and prod later imports it from S3, so server-side GitHub access is not part of the normal publish path
+- if prod-side import fails on `git ls-remote`, GitHub username/password prompts, or private-repo access, the correct fix is usually to publish the exact commit as an artifact from a locally authenticated checkout, not to keep retrying branch-head import
 
 If a developer can register a source but receives `403 Admin access required` when trying to import or activate it, that is the expected boundary, not a blocker they are supposed to solve. It means the handoff point was reached correctly.
 
@@ -206,6 +287,12 @@ If the user explicitly says "template deploy cycle", interpret that as the inter
 2. approve and activate the new release
 3. run the prod deploy script if platform code changed, or reuse the current prod image for a formal restart if the change was template-only
 
+Operator preference rule:
+
+- if a pending artifact-backed release already exists for the intended commit, prefer approving and activating that release instead of asking prod to resolve branch head from GitHub
+- activation is the step that syncs checked-in template `about/` preview assets into hosted storage under `templates/:template_id/about/*`
+- if a hosted template exists in the catalog but its preview media redirects to missing S3 keys, re-activating the intended release on a platform build that contains the sync logic is the correct fix
+
 Do not assume "template deploy cycle" means "deploy the entire dirty root repo". If the root worktree has unrelated changes and the release is template-only, prefer reusing the current prod image with:
 
 ```bash
@@ -237,6 +324,7 @@ The contract is:
 - `configSchema` defines editable per-user template config
 - `about.viral_dna` and `about.visual_dna` explain why the format wins
 - `about.proposal_generator` tells directors and agents how to turn product/about context into template-native post ideas
+- `about.skeleton_prompt` gives directors and agents a fill-in-the-blanks prompt scaffold for the template
 - `about.sample_prompts` shows future users and agents how to prompt the template well
 - `SKILL.md` teaches humans and agents how to call the template correctly
 - the canonical template entrypoint is `src/template.ts`
@@ -251,6 +339,17 @@ The platform-owned helper surface on `ctx.providers` currently includes:
 
 Every public template action should remain async and job-based. Prefer one or more named operations behind `POST /api/v1/templates/:templateId/operations/:operationName` instead of inventing custom synchronous endpoints.
 
+Keep operation design reasonably coarse-grained. These routes are customer-facing, usage-limited API calls, so avoid exploding one user action into a large number of tiny operations unless the workflow genuinely needs that split.
+
+Vidfarm already has native queueing for template jobs. When a task needs multiple runs, do not invent a custom batch manager, worker pool, queue coordinator, or other fancy orchestration layer in the template or in temporary validation code. The default pattern is:
+
+- submit jobs in a reasonable loop
+- record the returned job IDs
+- poll those jobs through the standard job endpoints
+- if completion will take a while, tell the user to check back later instead of overengineering lifecycle control
+
+Use extra job-management code only when the user explicitly asks for it and there is a concrete platform requirement that the built-in queue cannot satisfy.
+
 Templates are expected to evolve through multiple revisions. One-shot generation is not the standard. The standard is:
 
 - create a working first pass
@@ -297,6 +396,42 @@ const TEMPLATE_PROVIDER_REQUIREMENTS = {
 } as const;
 ```
 
+Recommended baseline model set, matching the current repo examples unless a template has a specific 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-1",
+    gemini: "gemini-3.1-flash-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;
+```
+
 Important:
 
 - this is documentation for humans and agents, not a framework-consumed schema field
@@ -332,7 +467,9 @@ npx @mevdragon/vidfarm-devcli presign-preview-media \
   --directory drafts/preview
 ```
 
-That command calls the hosted Vidfarm API with the user's `VIDFARM_API_KEY`, mints a presigned PUT URL scoped under `developer/<user_id>/*`, stores each uploaded file under a UUID path segment while preserving the original filename, uploads the file automatically when `--file` is provided, and returns both the `storage_key` and a public-read `preview_media_url`. Public readability for `developer/<user_id>/*` comes from Vidfarm bucket policy, not from public write access, so objects may be read directly by URL but should not be treated as listable or writable without authenticated API access. Agents should prefer that path for hosted preview uploads whenever the input is a local media file path.
+That command calls the hosted Vidfarm API with the user's `VIDFARM_API_KEY`, mints a presigned PUT URL scoped under `developer/<user_id>/*`, stores each uploaded file under a UUID path segment while preserving the original filename, uploads the file automatically when `--file` is provided, and returns both the `storage_key` and a public-read `preview_media_url`. Public readability for `developer/<user_id>/*` comes from Vidfarm bucket policy, not from public write access, so objects may be read directly by URL but should not be treated as listable or writable without authenticated API access. Agents should prefer that path for hosted preview uploads whenever the input is a local media file path, and should paste the returned absolute `preview_media_url` directly into `about.preview_media` when the template needs to work immediately in the hosted catalog.
+
+Do not assume a checked-in repo asset like `about/preview-01.png` already exists at `templates/:template_id/about/*` in hosted S3. That stable template namespace is populated by the platform import and activation flow, not by the developer presign command. Before admin import/activation, the immediately valid hosted preview URL is the returned `developer/<user_id>/*` public URL.
 
 ### 2. Start local runtime
 
@@ -418,7 +555,7 @@ These commands:
 - sync the generated DNA module back into the template
 - populate the strings consumed by `about.viral_dna`, `about.visual_dna`, and `about.link_to_original`
 
-After DNA analysis, add `about.proposal_generator` and `about.sample_prompts` manually. The standard now requires both. `proposal_generator` should help a director combine product/about information with the template's format to invent many post proposals, and `sample_prompts` should show what strong final prompts look like. Do not leave either as optional polish.
+After DNA analysis, add `about.proposal_generator`, `about.skeleton_prompt`, and `about.sample_prompts` manually. The standard now requires all three. `proposal_generator` should help a director combine product/about information with the template's format to invent many post proposals. `skeleton_prompt` should provide the default fill-in-the-blanks structure a director can instantiate quickly. `sample_prompts` should show what strong final prompts look like. Do not leave any of them as optional polish.
 
 Required-field rule:
 
@@ -445,6 +582,7 @@ For a new template, make sure it has:
 - `about.preview_media`
 - `about.link_to_original`
 - `about.proposal_generator` with a reusable instruction for proposal generation
+- `about.skeleton_prompt` with a reusable fill-in-the-blanks prompt scaffold
 - `about.sample_prompts` with multiple concrete examples
 - `configSchema`
 - `operations`
@@ -469,6 +607,7 @@ The platform route shape is fixed. A template should work behind:
 
 - `GET /api/v1/templates/:templateId`
 - `GET /api/v1/templates/:templateId/skill`
+- `GET /api/v1/rate-limit-status`
 - `POST /api/v1/templates/:templateId/config`
 - `POST /api/v1/templates/:templateId/operations/:operationName`
 - `GET /api/v1/templates/:templateId/jobs/:jobId`
@@ -477,6 +616,65 @@ The platform route shape is fixed. A template should work behind:
 
 Do not invent one-off REST endpoints for template behavior that already fits an operation workflow.
 
+Template-local docs do not need to restate platform plan names or operation quota numbers unless a template adds stricter limits of its own.
+
+Every template-local `SKILL.md` must also include TypeScript route templates for those routes. Treat this as part of the template standard, not optional documentation. The type block must name the concrete template slug, list every operation as a string-literal union, define each operation payload, and show the standard wrapper bodies.
+
+Minimum block to adapt per template:
+
+```ts
+type TemplateSlug = "vidfarm_template_example";
+type TemplateOperation = "create_asset" | "render_video";
+
+type TemplateConfigRequest = {
+  config: {
+    defaultProvider?: "openai" | "gemini" | "openrouter" | "perplexity";
+    [key: string]: unknown;
+  };
+};
+
+type SubmitTemplateOperation<TPayload> = {
+  tracer?: string;
+  payload: TPayload;
+  webhook_url?: string;
+};
+
+type QueuedJobResponse = {
+  job_id: string;
+  tracer?: string;
+  status: "queued";
+};
+
+type JobStatusResponse<TOutput = unknown> = {
+  job_id: string;
+  template_id: TemplateSlug;
+  operation_name: TemplateOperation;
+  tracer?: string;
+  status: "queued" | "running" | "succeeded" | "failed" | "cancelled";
+  progress?: number;
+  output?: TOutput;
+  error?: string;
+};
+
+type TemplateRoute =
+  | `GET /api/v1/templates/${TemplateSlug}`
+  | `GET /api/v1/templates/${TemplateSlug}/skill`
+  | `POST /api/v1/templates/${TemplateSlug}/config`
+  | `POST /api/v1/templates/${TemplateSlug}/operations/${TemplateOperation}`
+  | `GET /api/v1/templates/${TemplateSlug}/jobs`
+  | `GET /api/v1/templates/${TemplateSlug}/jobs/${string}`
+  | `GET /api/v1/templates/${TemplateSlug}/jobs/${string}/logs`
+  | `POST /api/v1/templates/${TemplateSlug}/jobs/${string}/cancel`;
+```
+
+For collection-style REST reads, use cursor pagination instead of assuming a single unbounded response:
+
+- send `limit`
+- if the response returns `next_cursor`, request the next page with `cursor=<that value>`
+- this applies to template job lists, structured logs, artifacts, and the admin source/release queues
+
+If the template accepts custom HTML, attachment URLs, generated image prompts, render-slide manifests, provider/model choices, or template-specific output artifacts, include those fields in the route types instead of leaving them as `Record<string, unknown>`.
+
 ### 8. Validate end to end
 
 Run:
@@ -500,6 +698,8 @@ Minimum bar:
 - inspect produced artifacts
 - if you need ad hoc scripts or test-run inputs to drive this validation, keep them under a sibling `tmp/` folder and not inside `src/`
 
+For multi-job validation, keep it simple: create the jobs in a loop, wait or poll, inspect the finished results, and move on. Do not turn local validation into a custom batch-processing subsystem.
+
 The expected result is that another agent can rerun the template without reverse-engineering the workflow.
 
 ## Golden Path: Natural-Language Revisions
@@ -553,7 +753,7 @@ A revision is not complete just because the code compiles. It is complete when:
 - the requested change is visible in the output
 - the change does not obviously regress the core format
 - the template can still be rerun by another user or agent
-- `about.proposal_generator` and `about.sample_prompts` still reflect the best current way to ideate and prompt the template
+- `about.proposal_generator`, `about.skeleton_prompt`, and `about.sample_prompts` still reflect the best current way to ideate and prompt the template
 - the usage instructions still match the implementation
 
 ## Template Contract
@@ -574,6 +774,8 @@ export const myTemplate = defineTemplate({
     link_to_original: "https://www.tiktok.com/@example/video/1234567890",
     proposal_generator:
       "Given the director's product, audience, and positioning, propose multiple UGC hook post ideas that fit this template. Return ideas that can either be used directly as prompts or expanded into a larger series of related prompts.",
+    skeleton_prompt:
+      "Create a [number]-slide UGC hook post for [audience] about [topic or product]. Hook: [opening]. Middle beats: [proof, story, objection, or comparison]. Ending: [CTA or payoff]. Tone: [voice].",
     sample_prompts: [
       "Create a 3-slide UGC hook sequence for a sleep supplement targeting new parents.",
       "Make a creator-style launch teaser for a skincare serum with one hook, one proof point, and one CTA.",
@@ -620,6 +822,7 @@ Keep these roles clear:
 - `about.preview_media` is required and should contain checked-in preview asset paths that represent the template well
 - `about.link_to_original` is required and should point to the original inspiration post or source reference when one exists
 - `about.proposal_generator` is required and should help directors turn product/about context into a list of strong post proposals for that template
+- `about.skeleton_prompt` is required and should give directors a template-native fill-in-the-blanks prompt scaffold they can instantiate quickly
 - `about.sample_prompts` is required and should contain realistic, high-signal examples that teach users how to get good results
 - `operations` define the public API
 - `jobs` implement the actual work
@@ -637,6 +840,7 @@ Required fields checklist:
 - `about.preview_media`
 - `about.link_to_original`
 - `about.proposal_generator`
+- `about.skeleton_prompt`
 - `about.sample_prompts`
 - `configSchema`
 - at least one operation
@@ -644,15 +848,119 @@ Required fields checklist:
 - `smokeTestPayload` for every operation
 - template-local `SKILL.md`
 
+## Caption Style Standard
+
+For TikTok-native captions, use the platform caption standard exposed by `vidfarm-devcli session` under `starter_style_options`.
+
+Canonical font IDs:
+
+- `tiktok_sans_semibold`: default native TikTok caption font, backed by `@fontsource/tiktok-sans` or the bundled `TikTokSans-SemiBold.ttf` starter asset
+- `montserrat_semibold`: rounded modern caption style
+- `source_code_pro_bold`: bold monospace caption style
+- `yesteryear`: script caption style
+- `georgia_bold`: bundled Georgia-style bold serif caption, backed by Libre Baskerville from Fontsource
+- `abel`: condensed caption style
+
+Legacy aliases remain accepted for older starters:
+
+- `montserrat` -> `montserrat_semibold`
+- `source_code_pro` -> `source_code_pro_bold`
+
+Canonical text background color IDs:
+
+- `black`: `#000000`
+- `red`: `#EA403F`
+- `orange`: `#FF933D`
+- `yellow`: `#F2CD46`
+- `lime_green`: `#78C25E`
+- `teal`: `#77C8A6`
+- `light_blue`: `#3496F0`
+- `dark_blue`: `#3496F0`
+- `violet`: `#5756D4`
+- `pink`: `#F7D7E9`
+- `brown`: `#A3895B`
+- `dark_green`: `#32523B`
+- `blue_gray`: `#2F688C`
+- `light_gray`: `#92979E`
+- `dark_gray`: `#333333`
+
+Templates that expose caption styling should use these IDs in `configSchema`, operation payloads, manifests, and docs instead of inventing local names or hardcoding unrelated font stacks. If a template intentionally uses a format-specific typography system, document the exception in the template-local `SKILL.md`.
+
+The caption standard is a default, not a hard lock. Templates may support `captionFont: "custom"` or template-specific text rendering when the user explicitly needs typography outside the standard. In that case, keep the standard options available, document the custom fields, and prefer bundled or template-local font assets over system fonts or remote Google Fonts URLs.
+
 Best-practice rule:
 
+- when creating a new template, the agent should author `about.proposal_generator`, `about.skeleton_prompt`, `about.sample_prompts`, and the template-local `SKILL.md` in the same pass without waiting for a separate follow-up request
 - every template should ship with sample prompts
 - every template should ship with a proposal generator prompt
+- every template should ship with a skeleton prompt that captures the default prompt structure
 - proposal generation should support a workflow of proposal -> prompts -> posts
+- proposal generation should use the skeleton prompt as a quality harness, so the ideas it emits can be instantiated cleanly without inventing a brand-new structure every time
 - proposal outputs should be useful either as direct one-off prompts or as seeds for a whole series
+- sample prompts should feel like strong filled-out versions of the skeleton prompt, not disconnected examples
 - include more than one example so users can see the range of valid requests
 - prefer prompts that are specific enough to be reusable exemplars, not vague one-liners
-- refresh both `about.proposal_generator` and `about.sample_prompts` when the template's prompting strategy or supported use cases change
+- refresh `about.proposal_generator`, `about.skeleton_prompt`, and `about.sample_prompts` when the template's prompting strategy or supported use cases change
+
+## Typical Template Patterns
+
+When a developer says "use typical template patterns", interpret that as the default template-authoring contract below unless the template has a strong reason to differ.
+
+Authoring defaults:
+
+- when creating a new template, automatically write `about.proposal_generator`, `about.skeleton_prompt`, `about.sample_prompts`, and the template-local `SKILL.md`
+- the template-local `SKILL.md` should explain the template's operations, expected payloads, sample requests, provider caveats, and any format-specific guidance future agents need
+- if the template intentionally does not follow one of these patterns, call that out explicitly in the template-local `SKILL.md`
+
+Asset-input defaults:
+
+- image-generating or slide-generating operations should usually accept either an AI image prompt or an exact image source supplied by the director
+- video-aware operations should usually accept either an AI video prompt or an exact video source supplied by the director when the format benefits from source footage
+- exact media sources should accept either direct URLs or raw prompt text in the same high-level input family when practical
+- URL detection should be robust enough to handle normal query strings and signed URLs; do not assume a media URL has a clean extension with no params
+- media-type detection should prefer explicit user fields first, then MIME type or fetch metadata when available, then conservative URL/path heuristics as a fallback
+- if a template supports file uploads or attachment arrays, document whether it expects a single asset, multiple assets, or either
+
+Operation-pattern defaults:
+
+- for most image-generation or slide-generation capabilities, provide two operations or two clearly documented modes of one operation
+- one mode should be an explicit director-controlled path where the caller can provide exact copy, exact media, or exact slide instructions
+- one mode should be a full-auto AI path where the caller provides a higher-level prompt or brief and the template decides the detailed text, imagery, and slide plan
+- name these modes clearly in the template-local `SKILL.md` so future agents and developers can tell which route is deterministic versus generative
+
+Slideshow-to-video defaults:
+
+- any operation that turns slideshow media into a video should, by default, accept `[{ media_url: string, duration_ms: number }]`
+- `media_url` may point to either an image or a video, and the slideshow renderer should handle both
+- when video clips are supplied in slideshow media, preserve the clip visually for the requested slot duration using a documented strategy such as trim, loop, freeze-last-frame, or fit-to-slot
+- when the template needs richer control than this default shape, extend it rather than replacing it with an unrelated format
+
+Remotion arbitrary-slide default:
+
+- include an arbitrary slide operation when it fits the template family, backed by Remotion rendering
+- that operation should accept either an AI image prompt or custom HTML as the slide source
+- the intended use is arbitrary inserts such as outro call-to-action slides, sponsor cards, transitions, or other one-off slides that do not need a dedicated template-specific generator
+- if custom HTML is accepted, document the styling, sanitization, and asset-loading constraints in the template-local `SKILL.md`
+
+Recommended input-shape convention:
+
+```ts
+const TYPICAL_MEDIA_SOURCE = z.object({
+  media_url: z.string().url().optional(),
+  image_url: z.string().url().optional(),
+  video_url: z.string().url().optional(),
+  image_prompt: z.string().optional(),
+  video_prompt: z.string().optional(),
+  html: z.string().optional(),
+  duration_ms: z.number().int().positive().optional()
+});
+```
+
+Notes:
+
+- templates may expose clearer, narrower schemas than this when that improves usability
+- prefer explicit fields like `image_prompt`, `image_url`, `video_prompt`, and `video_url` over guessing from one overloaded string when designing a new schema
+- if you still accept a single overloaded field for convenience, document the precedence rules clearly
 
 ## Provider Rules
 
@@ -660,12 +968,19 @@ Templates should use the provider abstractions already available on `ctx.provide
 
 Rules:
 
+- templates do not need to support all of `openai`, `gemini`, and `openrouter`; supporting at least one real provider path is usually enough unless the template explicitly promises broader portability
 - use the configured provider path instead of hardcoding one provider everywhere
 - let templates work with whichever supported provider key the developer actually has
 - keep prompts and model choices configurable when useful
 - use image attachments when the format depends on source references
 - avoid requiring multiple provider accounts unless the template genuinely needs them
 
+Recommended defaults when a template supports these providers:
+
+- `openai`: `gpt-5.4` for `text` and `layout_analysis`, `gpt-image-1` for `image`, `sora-2` for `video`, `gpt-4o-mini-tts-2025-12-15` for `tts`, `gpt-4o-mini-transcribe-2025-12-15` for `stt`
+- `gemini`: `gemini-3.1-flash-lite` for `text` and `layout_analysis`, `gemini-3.1-flash-image-preview` for `image`, `veo-3.0-generate-001` for `video`, `gemini-3.1-flash-tts-preview` for `tts`, `gemini-3.1-flash-lite-preview` for `stt`
+- `openrouter`: `qwen/qwen3.6-flash` for `text` and `layout_analysis`, `google/gemini-3.1-flash-image-preview` as the recommended paid `image` default where runtime support exists, `google/gemini-3.1-flash-tts-preview` with PCM for `tts`, `openai/gpt-4o-mini-transcribe` for `stt`
+
 Important distinction:
 
 - runtime template generation can use OpenAI, OpenRouter, Gemini, or Perplexity according to template logic
@@ -692,6 +1007,12 @@ Rules:
 - prefer `putJson`, `putText`, `putBuffer`, and `getPublicUrl`
 - do not scatter files across arbitrary top-level prefixes
 
+Hosted preview-media rule for developers:
+
+- if an agent uploads preview media with `presign-preview-media`, the resulting hosted `about.preview_media` entry should be the returned absolute `developer/<user_id>/*` URL
+- only use `templates/:template_id/about/*` in `about.preview_media` when that object already exists there, typically after platform import/activation sync or another platform-managed copy step
+- a repo-local file such as `about/preview-01.png` is fine for source control and for platform sync, but it is not by itself an immediately valid hosted catalog URL
+
 The runtime may back these writes with local filesystem storage or S3 depending on environment. The template should not care.
 
 ## API Usage
@@ -719,6 +1040,8 @@ After changes, validate with as many of these as apply:
 7. poll the job and fetch logs
 8. inspect produced artifacts
 
+If you need several runs, submit them in a reasonable loop and poll the returned job IDs. Rely on Vidfarm's native queueing instead of adding bespoke batch scheduling or coordination logic.
+
 If you changed slideshow, overlay, or video output behavior, also validate:
 
 1. output images are the expected aspect ratio