@mevdragon/vidfarm-devcli 0.2.7 → 0.2.9

package/SKILL.developer.md

@@ -26,17 +26,84 @@ 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
+- 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`
@@ -46,8 +113,32 @@ The third-party developer should not:
 
 `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:
@@ -115,40 +206,79 @@ 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` uses for hosted source registration
+- `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, template entrypoint path, and optionally an explicit commit SHA for a specific import
+- 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
-- the platform determines whether an update exists by comparing the registered branch head against the latest imported release 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. stop there, then tell the platform operator which branch head or commit SHA should be imported if they ask
+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`
-- `commit_sha`: optional and only needed when you want to import a specific commit instead of the current branch head
+- `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 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.
+- 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:
@@ -157,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
@@ -169,8 +305,8 @@ 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/template_0000/SKILL.md](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/templates/template_0000/SKILL.md)
-4. [templates/template_0000/src/template.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/templates/template_0000/src/template.ts)
+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)
 
@@ -187,11 +323,33 @@ The contract is:
 - `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
@@ -213,7 +371,7 @@ 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`, or `video`
+- 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
 
@@ -238,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
@@ -273,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
 
@@ -288,6 +484,13 @@ This boots the local API, worker, SQLite state, provider-key seeding, and local
 
 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
+
 Example:
 
 ```bash
@@ -352,11 +555,19 @@ 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`, `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/template_0000/src/template.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/templates/template_0000/src/template.ts) as the baseline pattern.
+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:
 
@@ -364,6 +575,15 @@ For a new template, make sure it has:
 - `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`
@@ -387,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`
@@ -395,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:
@@ -418,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
@@ -471,6 +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`, `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
@@ -488,7 +771,16 @@ export const myTemplate = defineTemplate({
     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"
+    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")
@@ -522,25 +814,177 @@ 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`.
+
+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 `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
@@ -563,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
@@ -590,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