@mevdragon/vidfarm-devcli 0.2.12 → 0.2.13

package/SKILL.developer.md

@@ -1,1186 +0,0 @@
----
-name: vidfarm-developer
-description: Build and extend Vidfarm templates as a third-party developer. Use this when the task is to create or modify a template, add or adjust template operations, improve local template testing, wire AI generation through the developer's own provider keys, or document the external developer workflow. Do not use this skill for platform internals, shared AWS infrastructure, admin release flow, or production runtime changes.
----
-
-# Vidfarm Third-Party Developer
-
-This skill is for AI agents and developers authoring Vidfarm templates locally.
-
-Primary goal:
-
-- make "here is a media file, turn this into a reusable template" a complete, executable workflow
-
-Use this skill for:
-
-- creating a new template under `templates/*`
-- extending an existing template under `templates/*`
-- revising a template from natural-language feedback
-- analyzing source media into `viral_dna` and `visual_dna`
-- wiring prompts, operations, jobs, and local Remotion output
-- validating the template through the local CLI and REST API
-
-Do not use this skill for:
-
-- platform auth, billing, database, or webhook internals
-- 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
-- do not make GitHub setup or GitHub debugging a blocker for local template creation, testing, iteration, or validation
-- if the user is only building or revising a template locally, they should not need to worry about GitHub at all
-
-The third-party developer responsibility is:
-
-- build and validate the template locally
-- commit and push the template folder to GitHub
-- register or update the hosted template source metadata with `register-source-hosted` so Vidfarm knows which repo, branch, and template folder to import from
-- 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`
-- use AWS CloudFormation, SSM, EC2, or shared prod credentials
-- treat platform import/activation as part of template authoring
-- assume "make this template public/live" is their duty
-
-`import-source-prod` and `deploy-template-cycle` are platform-operator commands. They are for internal admin flow, not for external template authors.
-
-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:
-
-1. inspect the source media and extract the repeatable format
-2. start the native harness workflow with `vidfarm-devcli autocreate-template <input_path> <output_path>`
-3. review the generated run folder, manifest, and `agent_prompt.md`
-4. generate the preservation decision, production graph, and template plan
-5. run or consume `analyze-viral-dna` and `analyze-visual-dna`
-6. implement the template operations and jobs
-7. wire prompt logic, provider usage, storage writes, and local Remotion output
-8. expose the template through the standard REST routes
-9. validate the template locally with `validate-template` plus at least one real job run
-10. update the template-local `SKILL.md` so future agents can operate it
-
-Use `generate-template` directly only when the developer already knows the template architecture and wants a plain starter scaffold. Use `autocreate-template` when source media needs to be analyzed into a reusable format.
-
-Do not stop after scaffolding. The expected outcome is a runnable template, not just a folder.
-
-If the user gives revision feedback in natural language, treat that as a normal template-authoring input, not as a vague suggestion. Example revision prompts:
-
-- "make the hook feel more curiosity-driven"
-- "the captions are too low and get covered by TikTok UI"
-- "preserve the exact composition from frame 3"
-- "the pacing is too slow"
-- "make this work for product screenshots instead of faces"
-
-Your job is to translate that feedback into concrete template changes, rerun validation, and keep iterating until the template is reliable enough to reuse.
-
-## Minimum Inputs
-
-You can start from any of these:
-
-- one image file
-- one video file
-- multiple screenshots or clips in a folder
-- a URL to the original post
-- a short written explanation of the format
-- a natural-language revision request against an existing template
-
-When creating a brand-new template, prefer staging raw inspiration material in a repo-local `drafts/` folder first. This gives the developer one obvious place to drag in source media and rough notes before asking an agent to build the template.
-
-Recommended intake layout:
-
-- `drafts/source_notes.md` for rough notes, links, and adaptation goals
-- `drafts/preview/` for raw screenshots, clips, frames, or other inspiration media
-
-If the developer already has files elsewhere in the repo, relative paths are still fine. But when the user says some variant of "use the files in `drafts/` to make a template", treat that as the default starting point.
-
-If the source is weak, still scaffold the template and create `research/source_notes.md` with the missing questions called out. Do not block template creation on perfect research.
-
-## Required Developer Env
-
-Typical `.env`:
-
-```env
-GEMINI_API_KEY=""
-OPENAI_API_KEY=""
-OPENROUTER_API_KEY=""
-PERPLEXITY_API_KEY=""
-
-VIDFARM_API_KEY=""
-```
-
-Notes:
-
-- at least one runtime AI provider key is usually enough
-- `GEMINI_API_KEY` is the key used by the built-in DNA analysis commands
-- `VIDFARM_API_KEY` is needed when calling a hosted Vidfarm API directly, including when minting presigned preview-media uploads through `vidfarm-devcli presign-preview-media`
-- `VIDFARM_API_KEY` is also what `vidfarm-devcli register-source-hosted` and `vidfarm-devcli publish-update-hosted` use for hosted handoff
-- local `vidfarm-devcli session` already gives you a seeded local API key for the local runtime
-- when calling the hosted API directly, include both `vidfarm-user-id` and `vidfarm-api-key` headers
-- for local `vidfarm-devcli` sessions, you usually do not need to supply `VIDFARM_USER_ID` manually
-- template authoring is TypeScript-first; create and edit template source as `src/template.ts`, not `src/template.js`
-- keep exploratory scripts, one-off test runners, scratch validation files, and temporary job-driving code out of `src/`; place them in a repo-local tmp folder that is a sibling to `src` instead, for example `templates/vidfarm_template_0007/tmp/`
-- when registering a hosted template source, set `template_module_path` to the repo-relative TypeScript entrypoint inside the template folder, for example `templates/vidfarm_template_example/src/template.ts`; the platform build/import flow resolves the compiled `src/template.js` sibling after `npm run build`
-- hosted template registration is git metadata only: repo URL, branch, and template entrypoint path
-- if a template moves folders or switches branches, update the registration metadata; if the template code changed but the location stayed the same, just push a new Git commit
-- for an already-registered template, submit the exact commit you want reviewed with `publish-update-hosted --commit-sha <sha>`; that command packages the commit locally and uploads a review artifact to platform-controlled S3
-- a local shell GitHub auth failure does not prove the hosted Vidfarm platform lacks repo access
-- if `git ls-remote` fails locally, interpret that as local credential state unless the hosted import flow itself reports a GitHub access error
-- do not ask for platform secrets like `ENCRYPTION_SECRET`, `API_KEY_SALT`, `WEBHOOK_SECRET`, admin emails, S3 config, or generic AWS credentials
-- do not ask for `REMOTION_AWS_ACCESS_KEY_ID` or `REMOTION_AWS_SECRET_ACCESS_KEY`
-
-Current first-class speech model allowlists in the platform runtime:
-
-- text-to-speech
-- `openrouter`: `google/gemini-3.1-flash-tts-preview`
-- `gemini`: `gemini-3.1-flash-tts-preview`
-- `openai`: `gpt-4o-mini-tts-2025-12-15`
-
-- speech-to-text
-- `openrouter`: `openai/gpt-4o-mini-transcribe`
-- `gemini`: `gemini-3.1-flash-lite-preview`, `gemini-2.5-flash-lite`
-- `openai`: `gpt-4o-mini-transcribe-2025-12-15`
-
-## Hosted Registration Flow
-
-For a third-party developer, the hosted publish handoff is:
-
-1. push the repo changes that contain the target template folder
-2. register the source location if it is new, or update the existing registration if the repo, branch, or template path changed
-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
-- `branch`: the branch Vidfarm should watch for the latest version, usually `main`
-- `template_module_path`: the repo-relative path to the template TypeScript entrypoint, for example `src/vidfarm_template_funnychat/src/template.ts`
-- `install_command`: the exact command that installs dependencies for the registered template source
-- `build_command`: the exact command that leaves the compiled JavaScript entrypoint beside the declared TypeScript entrypoint, or `:` when the compiled `.js` files are already committed and no build step is needed
-- `commit_sha`: for developer publish flow, the exact GitHub commit to package locally and submit for review on an already-registered source
-
-Registration command rule:
-
-- do not guess `install_command` and `build_command`
-- for a standalone template repo rooted at the template itself, root-level commands like `npm install` and `npm run build` are usually correct
-- for a multi-template repo, the commands must match the registered template folder, usually with `--prefix <template-folder>`
-- if the declared `template_module_path` is `src/vidfarm_template_chadvirgin/src/template.ts`, then a typical install command is `npm install --prefix src/vidfarm_template_chadvirgin`
-- if that template folder already commits `src/template.js`, a typical build command is `:`
-- if that template folder requires compilation, a typical build command is `npm run build --prefix src/vidfarm_template_chadvirgin`
-- a broken `build_command` will block hosted import even if the source registration itself succeeded
-- before telling a user to register or update hosted source metadata, inspect the repo's actual `package.json` files and choose commands that match the template's real location
-
-Do not tell third-party developers to run AWS-backed operator commands just to publish template code. If the task is only "make my updated template available to Vidfarm", the correct answer is GitHub push plus source registration metadata for new sources, or GitHub push plus `publish-update-hosted --commit-sha ...` for existing sources.
-
-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.
-
-Hosted registration should use `register-source-hosted`, not a local DB-backed command. That command calls the Vidfarm REST API so the source appears in the production review queue with `pending_review` status.
-
-For updates to an already-registered template, use `publish-update-hosted` so the exact GitHub commit is packaged locally, uploaded as a signed artifact, and enters review as a pending release without granting approval or activation rights.
-
-## Template Deploy Cycle
-
-If the user explicitly says "template deploy cycle", interpret that as the internal platform-operator sequence:
-
-1. import that template commit into the hosted platform as a template source release
-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
-scripts/deploy-prod-inplace.sh --image-uri <current-prod-image> --skip-check --skip-build
-```
-
-## First Read
-
-Read these files first when doing template work:
-
-1. [GETTING_STARTED.developers.md](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/GETTING_STARTED.developers.md)
-2. [README.md](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/README.md)
-3. [templates/vidfarm_template_0000/SKILL.md](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/templates/vidfarm_template_0000/SKILL.md)
-4. [templates/vidfarm_template_0000/src/template.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/templates/vidfarm_template_0000/src/template.ts)
-5. [src/template-sdk.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/template-sdk.ts)
-6. [src/cli.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/cli.ts)
-
-If the task is narrow, read only the template files and CLI slice relevant to that task.
-
-## Mental Model
-
-A Vidfarm template is a local module loaded by the platform. Work at the template layer, not the platform layer.
-
-The contract is:
-
-- `defineTemplate({...})` declares the public template
-- `operations` define the public async API surface
-- `jobs` implement the actual work
-- `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`
-
-The platform-owned helper surface on `ctx.providers` currently includes:
-
-- `generateText(...)`
-- `generateImage(...)`
-- `analyzeImageLayout(...)`
-- `generateSpeech(...)`
-- `transcribeSpeech(...)`
-
-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
-- gather feedback in plain English
-- modify the template
-- re-run the job
-- repeat until output is dependable
-
-## Provider And Model Dependency Rule
-
-The current template standard does not have a first-class `dependencies`, `requirements`, or `supportedModels` field in `defineTemplate({...})`.
-
-Until the standard grows one, agents should document AI dependencies in two places for every template that uses external models:
-
-1. in the template-local `SKILL.md`
-2. near the top of `src/template.ts` as a checked-in constant or clearly named comment block
-
-That documentation should describe:
-
-- supported provider names
-- allowed model IDs per provider
-- which capability each model is intended for, such as `text`, `image`, `layout_analysis`, `tts`, `stt`, or `video`
-- whether the list is strict, preferred, or just known-good defaults
-- any runtime caveats, especially when a provider is only partially supported by the current platform adapter
-
-Use this shape as the current documentation convention:
-
-```ts
-const TEMPLATE_PROVIDER_REQUIREMENTS = {
-  text: [
-    { provider: "openai", models: ["gpt-5.4"], strict: false },
-    { provider: "gemini", models: ["gemini-3.1-flash-lite", "gemini-2.5-flash-lite"], strict: false },
-    { provider: "openrouter", models: ["qwen/qwen3.6-flash"], strict: false }
-  ],
-  image: [
-    { provider: "openai", models: ["gpt-image-1", "gpt-image-2"], strict: false },
-    { provider: "gemini", models: ["gemini-3.1-flash-image-preview", "gemini-2.5-flash-image"], strict: false },
-    { provider: "openrouter", models: ["bytedance/seedance-2.0", "bytedance-seed/seedream-4.5"], strict: false }
-  ],
-  video: [
-    { provider: "openai", models: ["sora-2"], strict: false },
-    { provider: "gemini", models: ["veo-3.0-generate-001"], strict: false }
-  ]
-} 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
-- do not pretend a provider/model pair is supported if the runtime adapter does not actually implement that path yet
-- if the runtime only supports a subset, mark the rest as planned or aspirational in `SKILL.md`
-- when a template depends on reference-image attachments, call out whether that currently works for all providers or only some of them
-
-## Golden Path: Media To Template
-
-Use this flow whenever the task is "make a new template from this source".
-
-### 1. Stage raw inspiration in `drafts/`
-
-Before scaffolding, encourage the developer to place source material in a repo-local `drafts/` folder.
-
-Suggested layout:
-
-```txt
-drafts/
-  source_notes.md
-  preview/
-    screenshot-01.png
-    clip-01.mp4
-```
-
-This is the preferred handoff shape for agent-driven template creation. A Vidfarm developer should be able to drag media into `drafts/preview/`, add rough notes to `drafts/source_notes.md`, then tell the agent to create a template from those relative paths.
-
-If the source media is not already present in the repo, upload it into the authenticated developer storage namespace first instead of inventing ad hoc external hosting. An agent can take a developer-provided local file path and run this directly:
-
-```bash
-npx @mevdragon/vidfarm-devcli presign-preview-media \
-  --file ./local/path/to/screenshot-01.png \
-  --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, 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
-
-```bash
-npx @mevdragon/vidfarm-devcli dev --port 3310 --reset
-npx @mevdragon/vidfarm-devcli session
-```
-
-This boots the local API, worker, SQLite state, provider-key seeding, and local Remotion rendering.
-
-### 3. Choose a new template slug and folder
-
-Use a folder name that starts with `vidfarm_template_`, such as `templates/vidfarm_template_<nnnn>/`.
-
-Keep the identifiers separate:
-
-- the folder / package name should keep the `vidfarm_template_` prefix
-- the `slugId` should stay clean and human-meaningful, for example `ugc_hooks_v1`
-- `about.title` is the user-facing display title and should not be prefixed with `Vidfarm Template` unless that phrase is genuinely part of the brand or concept
-- avoid redundant titles like `Vidfarm Template UGC Hooks V1` when `UGC Hooks V1` is the actual display name
-
-### 3a. Use the native auto-create harness for media-to-template work
-
-When the developer says "autocreate a template based on media in `<input_path>` and output template to `<output_path>`", use:
-
-```bash
-npx @mevdragon/vidfarm-devcli autocreate-template <input_path> <output_path>
-```
-
-Alias:
-
-```bash
-npx @mevdragon/vidfarm-devcli autocreate <input_path> <output_path>
-```
-
-The command accepts either positional paths or explicit flags:
-
-```bash
-npx @mevdragon/vidfarm-devcli autocreate-template \
-  --input-path ./drafts/my_format \
-  --output-path ./templates/vidfarm_template_my_format \
-  --link-to-original "https://www.tiktok.com/@example/video/1234567890"
-```
-
-What this does:
-
-- creates `auto-create-templates/runs/<run_id>/`
-- stages source notes and preview media under `source/`
-- creates the standard analyzer artifact folders: `frames`, `audio`, `transcripts`, `ocr`, `motion`, `dna`, `extraction`, and `plan`
-- snapshots the current reusable harness files into `runs/<run_id>/harness/` for traceability
-- runs basic `ffprobe`/`ffmpeg` extraction when source video and local tools are available
-- scaffolds the output template with the same starter logic as `generate-template`
-- writes `manifest.json` and `agent_prompt.md` as the agent handoff
-
-Useful options:
-
-- `--run-id <id>`: choose the run folder name
-- `--slug-id <slug>`: override the slug derived from the output folder
-- `--template-id <uuid>`: pin the template UUID
-- `--skip-dna-analysis`: scaffold without calling Gemini DNA analysis
-- `--skip-media-probes`: skip local `ffprobe`/`ffmpeg` artifact generation
-- `--skip-scaffold`: create only the run artifacts and handoff prompt
-- `--harness-dir <path>`: use a local harness checkout other than `auto-create-templates/`
-- `--force`: replace an existing output template folder
-
-After running `autocreate-template`, continue the harness workflow instead of stopping at scaffold:
-
-1. inspect `auto-create-templates/runs/<run_id>/agent_prompt.md`
-2. create `dna/preservation_decision.json`
-3. create `extraction/production_graph.json` matching `production-graph.schema.json`
-4. create `plan/template_plan.json` matching `template-plan.schema.json`
-5. implement `src/template.ts`, metadata, prompts, operations, jobs, and template-local `SKILL.md`
-6. run `validate-template` and at least one real local job
-
-The reusable harness lives in `auto-create-templates/AUTO_CREATE_TEMPLATES.md`. It is intentionally included in the devcli package as editable source material. Future improvements to the harness should be made there; each auto-create run stores a snapshot of the harness files used for that run so older runs remain explainable.
-
-### 3b. Generate a plain starter template
-
-Example:
-
-```bash
-npx @mevdragon/vidfarm-devcli generate-template \
-  --slug-id template_0007 \
-  --template-dir ./templates/vidfarm_template_0007 \
-  --link-to-original "https://www.tiktok.com/@example/video/1234567890" \
-  --source-notes-path ./drafts/source_notes.md \
-  --source-preview-dir ./drafts/preview
-```
-
-What this does:
-
-- copies the starter template into the new folder
-- rewrites IDs, names, and repo metadata
-- stages `research/source_notes.md`
-- stages `research/preview/*`
-- creates the generated template DNA module
-- automatically runs viral and visual DNA analysis when preview media exists and `GEMINI_API_KEY` is available
-
-If you only have one local media file, put it in a temporary preview folder first and point `--source-preview-dir` at that folder.
-
-If you need to scaffold before DNA analysis is ready:
-
-```bash
-npx @mevdragon/vidfarm-devcli generate-template \
-  --slug-id template_0007 \
-  --template-dir ./templates/vidfarm_template_0007 \
-  --skip-dna-analysis
-```
-
-### 4. Stage research cleanly
-
-Every new template should have:
-
-- `research/source_notes.md`
-- `research/preview/`
-
-`source_notes.md` should answer:
-
-- original format URL
-- creator/account
-- why it wins
-- what must survive adaptation
-- what can change for new brands
-
-`research/preview/` should contain screenshots, frames, or short source clips that capture the format clearly.
-
-### 5. Run DNA analysis explicitly when needed
-
-If the scaffold skipped analysis, or if the source research changed, rerun:
-
-```bash
-npx @mevdragon/vidfarm-devcli analyze-viral-dna --template-dir ./templates/vidfarm_template_0007
-npx @mevdragon/vidfarm-devcli analyze-visual-dna --template-dir ./templates/vidfarm_template_0007
-```
-
-These commands:
-
-- upload the preview media for analysis
-- generate structured viral and visual DNA JSON
-- 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`, `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:
-
-- treat missing required fields as a blocking bug, not as follow-up polish
-- before calling a template "ready", verify every required field in `defineTemplate(...)` is present and populated with real values
-- if a scaffold or older repo shape omits any current required field, update the template to the current contract in the same pass
-
-Do not hand-write these summaries if the CLI can generate them from the source media.
-
-### 6. Implement the actual repeatable workflow
-
-Use [templates/vidfarm_template_0000/src/template.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/templates/vidfarm_template_0000/src/template.ts) as the baseline pattern.
-
-For a new template, make sure it has:
-
-- `id`
-- `slugId`
-- `version`
-- `about`
-- `about.title`
-- `about.description`
-- `about.viral_dna`
-- `about.visual_dna`
-- `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`
-- `jobs`
-- template-local `SKILL.md`
-- `smokeTestPayload` for every operation
-
-Expected implementation work usually includes:
-
-- input schema design
-- prompt design
-- image generation and attachment usage
-- text generation where needed
-- slide, frame, manifest, or script output shaping
-- local Remotion render wiring where the template outputs video
-- artifact persistence through `ctx.storage`
-- revision-friendly config and prompt controls where repeated tuning is likely
-
-### 7. Expose standard REST routes only
-
-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`
-- `GET /api/v1/templates/:templateId/jobs/:jobId/logs`
-- `POST /api/v1/templates/:templateId/jobs/:jobId/cancel`
-
-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:
-
-```bash
-npx @mevdragon/vidfarm-devcli validate-template --template-id template_0007
-```
-
-Then call the real operation through the local API using the local session headers from:
-
-```bash
-npx @mevdragon/vidfarm-devcli session
-```
-
-Minimum bar:
-
-- save config if the template exposes config
-- launch at least one real job
-- poll job status
-- inspect logs
-- 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
-
-Use this flow whenever the task is "change this template so it behaves differently" and the input is ordinary feedback rather than code-level instructions.
-
-### 1. Interpret the feedback as implementation work
-
-Map the revision request onto one or more of these layers:
-
-- source research or DNA misunderstanding
-- prompt wording
-- operation schema
-- workflow logic
-- image attachment handling
-- layout or caption placement
-- storage artifacts or output manifest shape
-- Remotion composition, timing, or pacing
-- template config defaults
-- template-local `SKILL.md` examples and instructions
-
-Do not just restate the feedback. Convert it into code changes.
-
-### 2. Change the template, not just the prompt
-
-If the problem is structural, fix the template implementation. Examples:
-
-- if outputs drift from the source format, tighten prompt construction or reference attachments
-- if pacing is wrong, change duration logic or Remotion timing
-- if captions clip or overlap UI, change safe areas and layout logic
-- if the template needs more user control, extend `configSchema` or operation input schema
-- if DNA summaries are now wrong, update source notes and rerun DNA analysis
-
-Prefer durable fixes over fragile one-off prompt tweaks.
-
-### 3. Revalidate after each revision
-
-After every meaningful revision:
-
-- run `npx @mevdragon/vidfarm-devcli validate-template --template-id <templateIdOrSlug>`
-- run a real local job
-- inspect artifacts and logs
-- confirm the requested behavior actually changed
-
-If the revision changed the expected usage pattern, update the template-local `SKILL.md` in the same pass.
-
-### 4. Keep iterating until the template is reusable
-
-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`, `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
-
-Use this shape:
-
-```ts
-export const myTemplate = defineTemplate({
-  id: "123e4567-e89b-42d3-a456-426614174000",
-  slugId: "ugc_hooks_v1",
-  version: "1.0.0",
-  about: {
-    title: "UGC Hooks V1",
-    description: "Generate hooks, previews, and final render inputs.",
-    viral_dna: "Fast creator-style hooks with simple repeatable structure.",
-    visual_dna: "Presentation-led mobile layouts with recognizable creator-native framing.",
-    preview_media: ["templates/ugc_hooks_v1/about/preview-01.jpg"],
-    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.",
-      "Generate a short product explainer slideshow for a budgeting app aimed at freelancers."
-    ]
-  },
-  configSchema: z.object({
-    defaultProvider: z.enum(["openai", "openrouter", "gemini", "perplexity"]).default("openai")
-  }),
-  operations: {
-    scaffold: {
-      description: "Generate a script scaffold.",
-      inputSchema: z.object({
-        topic: z.string()
-      }),
-      workflow: "scaffoldWorkflow",
-      providerHint: "openai",
-      webhookSupport: true,
-      smokeTestPayload: {
-        topic: "creator hooks"
-      }
-    }
-  },
-  jobs: {
-    async scaffoldWorkflow(ctx, input) {
-      return {
-        progress: 1,
-        output: {}
-      };
-    }
-  }
-});
-```
-
-Keep these roles clear:
-
-- `id` is the UUID-style template identifier
-- `slugId` is the stable human-readable identifier
-- `version` is required and should be an explicit template version string such as `1.0.0`
-- `about.title` is the customer-facing display name; it does not need the folder prefix and should usually read like a normal product/template title
-- `about.description` is required and should explain the reusable output format, not just restate the folder name
-- `about.viral_dna` is required and should describe the repeatable distribution mechanics that make the format work
-- `about.visual_dna` is required and should describe the repeatable visual system, framing, pacing, and composition cues
-- `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
-- `smokeTestPayload` is required for each operation
-
-Required fields checklist:
-
-- `id`
-- `slugId`
-- `version`
-- `about.title`
-- `about.description`
-- `about.viral_dna`
-- `about.visual_dna`
-- `about.preview_media`
-- `about.link_to_original`
-- `about.proposal_generator`
-- `about.skeleton_prompt`
-- `about.sample_prompts`
-- `configSchema`
-- at least one operation
-- a valid workflow function for every operation
-- `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`.
-
-Check the currently installed CLI values with:
-
-```bash
-npx @mevdragon/vidfarm-devcli session
-```
-
-The current standard version is `2026-05-30`. The CLI response includes `caption_standard_version`, `fonts`, `text_background_colors`, `presets`, `package_dependencies`, the source standard file, and the starter template style file.
-
-Text background rendering rule:
-
-- any selected text background color must render as an inline highlight chip that hugs the text only
-- apply visible per-line padding around the glyph bounds; the background should feel intentional, not cramped
-- use slightly curved corners like TikTok's native text highlight shape
-- do not render full-width bars, paragraph washes, large caption panels, or loose boxes behind text
-- for multi-line captions, each line should get its own tight chip or a chip shape that follows the actual text block closely
-- support chip strength levels where practical: `subtle` for light editor-style chips, `standard` for normal TikTok color chips, and `strong` for high-contrast emphatic captions
-
-Multiline caption rendering rule:
-
-- wrap the caption once, choose one font size and line height for the whole caption, and render it as one multiline text block
-- do not render each wrapped line as a separate trimmed text image; per-line trim bounds change apparent glyph scale, weight, line height, and shadow placement
-- apply shadow or outline to the whole multiline text block, then composite the block into the frame
-- optional background chips may still be per-line, but their geometry should be derived from measured line bounds after the shared multiline layout is decided
-- tune TikTok Sans wrapping, size, and line spacing independently from Montserrat or generic sans assumptions
-- validate with a caption that wraps into one long line and one short line; both lines must look like the same font size and weight with consistent shadow strength
-
-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`
-
-Font package dependencies exposed by the CLI:
-
-- `@fontsource/tiktok-sans`
-- `@fontsource/montserrat`
-- `@fontsource/source-code-pro`
-- `@fontsource/libre-baskerville`
-
-Bundled starter assets may also be available for template-local rendering:
-
-- `TikTokSans-SemiBold.ttf`
-- `Montserrat[wght].ttf`
-- `SourceCodePro[wght].ttf`
-- `Yesteryear-Regular.ttf`
-- `Abel-Regular.ttf`
-
-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`
-
-Canonical style presets:
-
-- `tiktok_native_white`: TikTok Sans SemiBold, white fill, no color chip, native black shadow
-- `tiktok_native_chip`: TikTok Sans SemiBold, white fill, red default inline highlight chip, `standard` chip strength, native black shadow
-- `tiktok_editor_gray`: TikTok Sans SemiBold, dark fill, light gray default inline highlight chip, `subtle` chip strength, no shadow
-
-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 `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
-
-Templates should use the provider abstractions already available on `ctx.providers`.
-
-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
-- first-class speech helpers use a strict runtime allowlist per provider/model pair; if a template needs other speech models, document that it is using a custom provider path instead of the built-in helper
-- built-in DNA analysis commands currently depend on `GEMINI_API_KEY`
-
-## Storage And Upload Rules
-
-Do not hand-write direct S3 upload logic in template code. Use `ctx.storage`.
-
-Use the built-in namespace conventions:
-
-- `user/:user_id/*` for user-owned uploaded assets
-- `developer/:user_id/*` for developer-scoped authoring assets or scratch files
-- `templates/:template_id/users/:user_id/jobs/:job_id/*` for template job artifacts
-- `templates/:template_id/about/*` for template about-page media
-
-Rules:
-
-- keep user uploads under `user/`
-- keep developer-only working files under `developer/`
-- keep generated outputs under the template job namespace
-- keep about-page preview media under `templates/:template_id/about/`
-- 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
-
-When calling a hosted Vidfarm API directly, use:
-
-- `vidfarm-api-key`
-
-If you need the authenticated customer identity for display or debugging, call:
-
-- `GET /api/v1/user/me`
-
-The template-local `SKILL.md` should show concrete request examples for that template's operations and payloads.
-
-## Validation Checklist
-
-After changes, validate with as many of these as apply:
-
-1. `npm run check`
-2. `npm run build`
-3. `npx @mevdragon/vidfarm-devcli validate-template --template-id <templateIdOrSlug>`
-4. `npx @mevdragon/vidfarm-devcli session`
-5. save config if the template exposes config
-6. launch a real operation through the local REST API
-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
-2. captions remain readable and do not clip
-3. important subjects stay inside safe framing
-4. final local video output matches expected pacing and composition
-
-If the task was a revision request, also validate:
-
-1. the specific natural-language feedback is reflected in the output
-2. the revision did not break the original core format
-3. the template-local `SKILL.md` still matches the current behavior
-
-## What To Avoid
-
-- asking third-party developers for platform secrets
-- mixing admin release instructions into template authoring guidance
-- requiring cloud Remotion setup for normal template work
-- adding one-off custom endpoints when an operation already fits the job model
-- hardcoding a developer's personal provider choice into template logic
-- skipping DNA analysis when source media is available
-- omitting `SKILL.md`, `research/source_notes.md`, or `smokeTestPayload`
-- stopping after scaffold generation without making the template runnable
-- treating revision feedback as "prompt advice" without changing the template when the fix belongs in code
-- assuming the first pass is final
-
-## Output Style For Vidfarm Work
-
-When reporting back after Vidfarm template changes:
-
-- name the template changed
-- mention the operation or workflow affected
-- state whether you used scaffold plus DNA analysis or a manual extension path
-- summarize the natural-language revision request when the task was a revision
-- state how you verified it locally
-- call out any remaining gap such as mocked provider responses, missing preview media, or unexercised optional paths