@mevdragon/vidfarm-devcli 0.2.0 → 0.2.1

package/SKILL.developer.md

@@ -1,150 +1,102 @@
 ---
 name: vidfarm-developer
-description: Build and extend Vidfarm video-production templates and platform features in this repository. Use this whenever the user wants to create a new Vidfarm template, add a pipeline stage or operation, wire billing or provider calls, integrate Remotion, extend the developer console, or modify the async jobs/auth/storage/webhook flow for Vidfarm.
+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 Developer
+# Vidfarm Third-Party Developer
 
-This skill is for working inside the Vidfarm platform in this repository.
+This skill is for third-party template developers authoring Vidfarm templates locally.
 
-## Distribution Notes
+Scope this skill to:
 
-Current published/distribution targets:
+- creating a new template
+- extending an existing template under `templates/*`
+- adding or refining template operations and jobs
+- improving local template authoring workflow
+- wiring template behavior to the developer's own AI provider keys
+- validating template behavior through the local CLI and API
 
-- npm package: `@mevdragon/vidfarm-devcli` as a private package
-- GitHub repo: `OfficeXApp/vidfarm-devcli` as a private repo
+Do not use this skill for:
 
-Keep that split in mind when changing package metadata or release instructions. The npm package is intentionally user-scoped right now because private publish succeeded there, while the GitHub repo lives under the OfficeX org.
+- platform auth, billing, storage, webhook, or database internals
+- developer console work under `/dev`
+- production Docker or deployment changes
+- shared AWS or release-admin workflows
+- cloud Remotion publishing or cloud render setup
 
-Use it when the task is any of:
+For third-party developers, Remotion is local. Do not require cloud Remotion credentials or shared AWS details in this skill.
 
-- add a new internal video template
-- extend an existing template with new operations or workflows
-- wire AI generation through customer-owned provider keys
-- add billing, artifacts, workspace, or webhook behavior
-- integrate Remotion render steps
-- modify the developer console at `/dev`
-- change the Docker/AWS-hosted platform runtime
+## Required Developer Env
 
-The current runtime is a single Node.js service with:
+Third-party developers should only need their own API credentials and Vidfarm API auth.
 
-- Hono API
-- SQLite job and lease state
-- in-process worker loop
-- local or S3-backed artifact storage
-- async-first job model
+Typical `.env`:
 
-The current release model also supports:
-
-- GitHub-backed template source records
-- admin-only import from the `production` branch
-- admin-only Remotion site publish to shared AWS
-- admin-only production Docker promotion
-- pinned commit-SHA releases
-- mandatory certification before activation
-
-Start from the current implementation, not just the original spec.
-
-## First Read
+```env
+GEMINI_API_KEY=""
+OPENAI_API_KEY=""
+OPENROUTER_API_KEY=""
+PERPLEXITY_API_KEY=""
 
-Read these files first before changing behavior:
+VIDFARM_USER_ID=""
+VIDFARM_API_KEY=""
+```
 
-1. [PLATFORM_SPEC.md](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/PLATFORM_SPEC.md)
-2. [video-pipeline-architecture-draft.md](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/video-pipeline-architecture-draft.md)
-3. [AWS_REMOTION_HANDOFF.md](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/AWS_REMOTION_HANDOFF.md) if the task touches Remotion or cloud render setup
-4. [src/app.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/app.ts)
-5. [src/db.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/db.ts)
-6. [src/worker.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/worker.ts)
-7. [src/template-sdk.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/template-sdk.ts)
-8. [templates/template_0000/src/template.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/templates/template_0000/src/template.ts)
-9. [src/dev-app.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/dev-app.ts)
-10. [src/cli.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/cli.ts) if the task touches local template developer workflow
+Notes:
 
-If the task is narrow, only read the relevant slice after this initial pass.
+- at least one AI provider key is usually enough
+- `VIDFARM_USER_ID` and `VIDFARM_API_KEY` are needed when calling the Vidfarm API directly
+- do not ask third-party developers for platform secrets like `ENCRYPTION_SECRET`, `API_KEY_SALT`, `WEBHOOK_SECRET`, admin emails, S3 config, or generic AWS credentials
+- do not ask third-party developers for `REMOTION_AWS_ACCESS_KEY_ID` or `REMOTION_AWS_SECRET_ACCESS_KEY`
 
-## Platform Shape
+## First Read
 
-Treat Vidfarm as one shared control-plane service.
+Read these files first when working on a template:
 
-- API routes live in `src/app.ts`
-- database schema and persistence helpers live in `src/db.ts`
-- background execution lives in `src/worker.ts`
-- template execution context is built in `src/context.ts`
-- provider leasing and outbound AI routing live in `src/services/providers.ts`
-- storage lives in `src/services/storage.ts`
-- jobs live in `src/services/jobs.ts`
-- webhooks live in `src/services/webhooks.ts`
-- Remotion integration seam lives in `src/services/remotion.ts`
-- templates are registered in `src/registry.ts`
-- template implementation code lives in `templates/*`, not `src/*`
+1. [GETTING_STARTED.developers.md](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/GETTING_STARTED.developers.md)
+2. [templates/template_0000/SKILL.md](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/templates/template_0000/SKILL.md)
+3. [templates/template_0000/src/template.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/templates/template_0000/src/template.ts)
+4. [src/template-sdk.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/template-sdk.ts)
+5. [src/cli.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/cli.ts)
 
-Do not split a new template into its own HTTP service unless the user explicitly wants that. The default Vidfarm pattern is internal code modules loaded by the shared platform.
+If the task is narrow, read only the template files and CLI slice relevant to that task.
 
-## Core Mental Model
+## Mental Model
 
-Every public template action is async and returns a `job_id`.
+A template is an internal module loaded by Vidfarm, but third-party developers should work at the template layer, not the platform layer.
 
-The normal request flow is:
+The normal workflow is:
 
-1. client calls `POST /templates/:templateId/operations/:operationName`
-2. platform authenticates with `vidfarm-user-id` and `vidfarm-api-key`
-3. platform validates payload against the template operation schema
-4. platform creates a queued job in SQLite
-5. worker picks up the job
-6. workflow emits logs, artifacts, billing events, and optional webhook deliveries
-7. client polls `GET /templates/:templateId/jobs/:jobId`
+1. define template metadata and schemas
+2. expose one or more operations
+3. implement the job workflows behind those operations
+4. test locally through the Vidfarm CLI and REST API
+5. iterate until the template can be rerun reliably
 
-Do not implement new synchronous flows unless the user explicitly asks for it. Prefer consistency with the async job model.
+Every public template action should remain async and job-based. Prefer fitting new behavior into the existing operation and job pattern instead of inventing one-off synchronous endpoints.
 
 ## When Adding A New Template
 
-Follow this checklist.
+Follow this checklist:
 
-1. Create a new folder under `templates/template_<nnnn>/`
-2. Put the template definition in that folder, not under `src/*`
-3. Export `defineTemplate({...})`
-4. Define:
+1. create a new folder under `templates/template_<nnnn>/`
+2. put template code in that folder, not under `src/*`
+3. export `defineTemplate({...})`
+4. define:
    - `id`
+   - `slugId`
    - `version`
-   - `about.description`
-   - `about.viral_dna`
-   - `about.visual_dna`
-   - `about.preview_media`
-   - `about.link_to_original`
-   - `skillPath`
+   - `about`
    - `configSchema`
    - `operations`
    - `jobs`
-5. Add a template-local `SKILL.md`
-6. Put original-format notes in `research/source_notes.md` and source screenshots/video in `research/preview/`
-7. Run `vidfarm analyze-viral-dna --template-dir <template-dir>` and `vidfarm analyze-visual-dna --template-dir <template-dir>`
-8. Add `smokeTestPayload` for every operation
-9. Register the template in `src/registry.ts`
-10. If useful, add default payload/config examples to `src/dev-app.ts`
-11. Verify end to end with the local developer console and/or curl
-
-Use the existing `template_0000` starter template as the baseline example.
-
-The starter scaffold now standardizes template DNA authoring:
+5. add a template-local `SKILL.md`
+6. put source research in `research/source_notes.md`
+7. put source screenshots or videos in `research/preview/`
+8. add `smokeTestPayload` for every operation
+9. verify the template locally end to end
 
-- `research/source_notes.md` is the source-format note file
-- `research/preview/` holds the screenshots or video the analyzers inspect
-- `src/template-dna.ts` is the checked-in generated module that feeds `about.viral_dna`, `about.visual_dna`, and `about.link_to_original`
-- `vidfarm generate-template` stages those files automatically, and if preview media is already present it will run both DNA analyzers during scaffold creation
-
-`template_0000` is intentionally opinionated and should be treated as the default starter pattern:
-
-- operation 1: `create_slideshow`
-- operation 2: `render_video`
-- stage 1 outputs finished 9:16 slide images with the text already composited
-- stage 2 only sequences those finished slide images into video
-- reserve TikTok UI safe zones at the top, right edge, and bottom
-- avoid subject cut-off during portrait normalization
-- use checked-in TikTok Sans for starter caption typography
-- prefer readable text with shadow/fade over caption boxes
-- if a new template does not need video, it can stop after stage 1
-
-Not every template uses Remotion. That is fine. Certification only expects Remotion behavior if the template actually calls `ctx.remotion`.
+Use [templates/template_0000/src/template.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/templates/template_0000/src/template.ts) as the baseline pattern.
 
 ## Template Contract
 
@@ -193,245 +145,16 @@ export const myTemplate = defineTemplate({
 });
 ```
 
-Keep the separation clear:
-
-- `id` is the self-issued UUIDv4 `template_id`
-- `slugId` is the human-readable stable `slug_id`
-- `operations` define the public API surface
-- `jobs` define internal execution workflows
-- `smokeTestPayload` defines the minimum certification input
-
-## GitHub Source Flow
-
-For GitHub-backed template distribution, treat the platform as importing approved source code, not live-tracking a repo.
-
-Rules:
+Keep these roles clear:
 
-- default source branch is `production`
-- admin manually reviews the repo and decides when to import
-- template authors do not publish directly to shared Remotion AWS
-- template authors do not directly promote templates into production Docker
-- import resolves to a pinned commit SHA
-- certification runs before activation
-- activation flips one certified release live
-- Remotion site publish is part of admin release promotion, not template authoring
-- production Docker rebuild/redeploy happens only after admin approval
-
-Do not implement floating branch-head production state. Live template state must always be tied to a specific commit.
-
-For the current demo standalone template repo, use:
-
-- project/package name: `vidfarm_template_0000`
-- GitHub repo target: `mevdragon/vidfarm_template_0000`
-- checked-in production config file: `template.config.json`
-- `slug_id`: `template_0000`
-- sample `template_id`: `4c7a7e1a-7f35-4f30-9f86-9c8a63c7f2db`
-
-When registering a template source with the platform:
-
-- `template_id` must be a self-issued UUIDv4
-- `slug_id` must be the human-readable stable identifier
-- registration must fail if another source already uses the same `template_id`
-- the conflict error should tell the developer to generate a different UUIDv4
-
-Template repos should prefer checked-in config for production topology over scattered env vars. In particular:
-
-- Remotion region/function/bucket/site/composition settings should live in `template.config.json`
-- release control metadata should also live in `template.config.json`
-- AI agents should read `template.config.json` as the source of truth
-- only secrets and credentials should come from the execution environment
-
-## Workflow Rules
-
-Inside a template workflow:
-
-- log meaningful progress
-- store large outputs as artifacts
-- record billing when you consume external or compute-heavy resources
-- route provider calls through `ctx.providers`
-- use `ctx.remotion` for render submission
-- use `ctx.jobs.enqueueChild(...)` only when a child-job boundary is truly useful
-
-Do not bypass framework-owned services with raw provider calls unless the user explicitly wants to break out of the shared routing and billing model.
-
-## Provider Usage
-
-For customer-billed AI calls, always go through:
-
-```ts
-await ctx.providers.generateText({
-  provider: "openai",
-  model: "gpt-4.1-mini",
-  prompt: "...",
-  temperature: 0.7
-});
-```
-
-Why:
-
-- it leases a compatible customer key
-- it respects cooldown and invalidation behavior
-- it records usage events
-- it fits the retry model in the worker
-
-Relevant files:
-
-- [src/services/providers.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/services/providers.ts)
-- [src/db.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/db.ts)
-
-## Billing Rules
-
-Templates should emit billable events through the framework context, not invent a separate ledger.
-
-Use:
-
-```ts
-await ctx.billing.record({
-  type: "ai_generation",
-  costUsd: 0.02,
-  metadata: { provider: "openai" }
-});
-```
-
-Current default behavior charges roughly `costUsd * 2` if `chargeUsd` is omitted.
-
-If you add a new billable resource type, update both:
-
-1. the domain types in `src/domain.ts`
-2. any services or reporting code that assumes the existing event kinds
-
-## Storage And Artifacts
-
-Use `ctx.storage.putJson(...)` for structured intermediate outputs.
-
-The current storage adapter supports:
-
-- local disk for development
-- S3-compatible object storage for hosted environments
-
-Store large stage outputs as artifacts rather than only embedding them inside `job.result`.
-Template-generated artifacts should be written under the logical prefix:
-
-```txt
-templates/:templateId/users/:userId/jobs/:jobId/...
-```
-
-Relevant files:
-
-- [src/services/storage.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/services/storage.ts)
-- [src/context.ts](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/src/context.ts)
-
-## Remotion Pattern
-
-Remotion is treated as a downstream adapter, not the platform center.
-
-Use:
-
-```ts
-const render = await ctx.remotion.render({
-  compositionId: "storyboard-main",
-  inputProps: {...}
-});
-```
+- `id` is the UUID-style template identifier
+- `slugId` is the human-readable stable identifier
+- `operations` define the public API
+- `jobs` implement the actual work
 
-If the user asks for real Lambda wiring, keep the template contract stable and upgrade `src/services/remotion.ts` rather than hardcoding provider-specific render logic directly into template files.
+## Local Workflow
 
-For real AWS-backed Remotion work in this repo:
-
-- use [AWS_REMOTION_HANDOFF.md](/Users/localghost/Projects/OfficeX/OfficeX/ZoomGTM/vidfarm/AWS_REMOTION_HANDOFF.md) as source of truth
-- target the shared `us-east-1` Remotion infra described there
-- pin Remotion packages to `4.0.355` unless the task is explicitly shared-infra upgrade work
-- publish a repo-specific site bundle instead of deploying a new render Lambda by default
-- treat shared AWS site publish and cloud render validation as release-admin work, not normal developer authoring work
-
-Important credential note:
-
-- this repo has separate Remotion AWS credentials available in local production env config as `REMOTION_AWS_ACCESS_KEY_ID` and `REMOTION_AWS_SECRET_ACCESS_KEY`
-- use those for Remotion site publish/render operations
-- do not assume generic `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are the correct identity for Remotion work
-
-Preferred env/config values for real Remotion integration:
-
-```env
-REMOTION_REGION=us-east-1
-REMOTION_FUNCTION_NAME=remotion-render-4-0-355-mem2048mb-disk2048mb-180sec
-REMOTION_BUCKET_NAME=remotionlambda-useast1-ujg7c0h43q
-REMOTION_SITE_NAME=your-site-name
-REMOTION_SERVE_URL=https://remotionlambda-useast1-ujg7c0h43q.s3.us-east-1.amazonaws.com/sites/your-site-name/index.html
-REMOTION_COMPOSITION_ID=YourComposition
-```
-
-If implementing real rendering, prefer one of these patterns:
-
-1. publish a site bundle with the shared bucket and site-name pattern from the handoff
-2. render against the shared function name and the repo-specific `REMOTION_SERVE_URL`
-
-Do not deploy a new Lambda function for every template unless the task explicitly requires shared infra changes.
-
-Release sequence for Remotion-backed templates:
-
-1. developer merges approved code into the template repo `production` branch
-2. release admin reviews and pins a commit SHA
-3. release admin publishes the site bundle to shared AWS
-4. release admin verifies a cloud render against that site
-5. release admin activates the pinned template release in the platform
-6. release admin rebuilds and redeploys the production Docker image
-
-## API Rules
-
-If you need new API surface area, prefer these patterns:
-
-- customer-facing template actions under `/templates/:templateId/*`
-- developer or customer profile actions under `/me/*`
-- auth under `/auth/*`
-- documentation or debug surfaces only when justified
-
-Do not create a separate route per stage if an operation-based route can cover it cleanly. The platform already normalizes work through:
-
-`POST /templates/:templateId/operations/:operationName`
-
-## Database Rules
-
-When changing persistence:
-
-- update schema in `src/db.ts`
-- add mapping helpers there too
-- keep writes idempotent where possible
-- preserve the worker’s retry safety
-- avoid introducing a second state store unless the user explicitly wants it
-
-For provider-key coordination, preserve the SQLite lease model unless the task is explicitly about moving to Postgres, Redis, or SQS.
-
-## Developer Console
-
-The browser console lives at `/dev`.
-
-If you add a new template or operation, consider whether `src/dev-app.ts` should also gain:
-
-- default config JSON
-- default payload JSON
-- extra developer affordances for that workflow
-
-Keep the console practical. It is for internal developers to test the platform quickly, not for polished end-user UX.
-
-## Local Runbook
-
-Typical local run:
-
-```bash
-npm install
-PORT=3100 ENCRYPTION_SECRET=test-secret API_KEY_SALT=test-salt MOCK_PROVIDER_RESPONSES=true npm run dev
-```
-
-Open:
-
-```txt
-http://127.0.0.1:3100/dev
-```
-
-Use mocked provider responses by default during local development unless the task specifically requires real provider traffic.
-
-Preferred local template developer workflow:
+Preferred local third-party developer workflow:
 
 ```bash
 npx @mevdragon/vidfarm-devcli dev --port 3310 --reset
@@ -439,139 +162,97 @@ npx @mevdragon/vidfarm-devcli session
 npx @mevdragon/vidfarm-devcli validate-template --template-id template_0000
 ```
 
-That CLI should be the default path for local template testing because it:
+That CLI should be the default path because it:
 
-- boots the real REST API and worker
-- provisions local SQLite automatically
-- seeds a dev auth session
+- boots the local API and worker
+- provisions local state automatically
+- creates a local developer session
 - seeds provider keys from local env vars when present
-- falls back to mock provider keys plus mocked AI responses when needed
-- renders Remotion locally
+- uses local Remotion rendering
 
-Reset local state when you need a clean test pass:
+For third-party developers, local rendering is the default and expected path. Do not document or require cloud Remotion setup here.
+
+Reset local state when needed:
 
 ```bash
 rm -rf .vidfarm/local
 npx @mevdragon/vidfarm-devcli dev --port 3310 --reset
 ```
 
-For slideshow-style templates, remember the artifact distinction:
-
-- `slides/*.png` are background images only
-- text overlay appears in `renders/final.mp4`
-- if text seems missing, inspect the final MP4 before assuming generation failed
-
-If the task requires real Remotion cloud rendering, confirm these before coding:
-
-1. the repo is using the shared function and bucket from `AWS_REMOTION_HANDOFF.md`
-2. the Remotion package version matches `4.0.355`
-3. the runner is using `REMOTION_AWS_ACCESS_KEY_ID` and `REMOTION_AWS_SECRET_ACCESS_KEY`
-4. the site name is repo-specific and not reusing another repo’s published bundle unintentionally
-
-## 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. hit `/health`
-5. use `/dev`
-6. request OTP and verify login
-7. add a provider key
-8. save template config
-9. launch a job
-10. poll job status and logs
-11. inspect produced artifacts
-
-If the task touches GitHub-backed template releases, also validate:
-
-1. source branch is `production`
-2. module path points to the built template export
-3. `SKILL.md` path is correct
-4. import creates a release pinned to a commit SHA
-5. only certified releases are activatable
-
-For new template scaffolds, use the CLI instead of copy-pasting the starter repo by hand:
+## Provider Usage
 
-```bash
-npx @mevdragon/vidfarm-devcli generate-template --slug-id hooks_v1 --template-dir templates/template_0007
-```
+Templates should prefer the Vidfarm provider abstractions already available in context.
 
-That command copies `templates/template_0000`, strips `.git` and `node_modules`, rewrites the starter placeholders for the new template, and generates a UUIDv4 `template_id` if you do not pass one explicitly.
+Rules:
 
-The generated template repo is still authoring-only. It can contain admin release scripts and config, but only the release admin should run those scripts against shared AWS or production infrastructure.
+- 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
+- avoid requiring multiple provider accounts unless the template genuinely needs them
 
-If you changed worker behavior, do not stop at compile success. Run a real job.
+If a task only needs image generation, do not force extra model providers for text or research.
 
-If you changed Remotion integration, also validate:
+## Storage Namespaces
 
-1. site publish config
-2. serve URL shape
-3. function name
-4. composition ID
-5. render submission path
+Use the built-in storage namespace conventions instead of inventing one-off key layouts.
 
-If you changed slideshow or text-overlay behavior, also validate:
+Current namespaces:
 
-1. the generated background slide images do not contain baked-in text unless explicitly intended
-2. the final MP4 shows the overlay text in the expected zone
-3. long captions wrap correctly and do not clip
-4. the stored slide assets are the expected aspect ratio, especially for strict 9:16 templates
+- `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
 
-## Common Tasks
+Rules:
 
-### Add a new operation to an existing template
+- keep user uploads under the `user/` namespace
+- keep developer-only working files under the `developer/` namespace
+- keep generated job outputs under the template job namespace
+- do not scatter files across arbitrary top-level prefixes
+- prefer the shared storage helpers over handwritten string concatenation for new paths
 
-1. update `operations` in the template file
-2. add the workflow implementation under `jobs`
-3. add sample payload defaults in `src/dev-app.ts` if useful
-4. verify through `/dev`
+## API Usage
 
-### Add a new template-wide config field
+When testing through the API, use:
 
-1. extend `configSchema`
-2. read it from `ctx.templateConfig`
-3. test save/load through `/templates/:templateId/config`
+- `vidfarm-user-id`
+- `vidfarm-api-key`
 
-### Add a new provider-aware generation step
+The template-local `SKILL.md` should show the concrete routes and example payloads for that template.
 
-1. call `ctx.providers.generateText(...)`
-2. record billing
-3. log progress and persist the artifact
+## Validation Checklist
 
-### Add webhook behavior
+After changes, validate with as many of these as apply:
 
-1. prefer queueing delivery through the existing webhook service
-2. do not send ad hoc `fetch()` calls directly from template code
+1. `npm run check`
+2. `npm run build`
+3. `npx @mevdragon/vidfarm-devcli validate-template --template-id <templateIdOrSlug>`
+4. run the template locally through the CLI session
+5. save template config if the template exposes config
+6. launch a real job
+7. poll job status and logs
+8. inspect produced artifacts
 
-### Register a GitHub-backed template source
+If you changed slideshow or text-overlay behavior, also validate:
 
-1. create or update the template source record
-2. use branch `production`
-3. point `template_module_path` at the built module the platform should import
-4. point `skill_path` at the template-local `SKILL.md`
-5. import the source to create a pinned release
-6. activate only after certification passes
+1. output images are the expected aspect ratio
+2. captions remain readable and do not clip
+3. final local video output matches expected pacing and framing
 
 ## What To Avoid
 
-- bypassing auth and job creation by adding custom one-off endpoints
-- storing plaintext customer provider secrets
-- making raw AI calls outside the provider lease system for customer workloads
-- writing template-specific persistence logic outside `src/db.ts` without reason
-- activating a template from a floating branch head instead of a pinned commit
+- 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
+- hardcoding a developer's personal provider choice into template logic
 - omitting `SKILL.md` or `smokeTestPayload`
-- coupling the platform too tightly to one render engine
-- returning giant generated outputs only inline when they should be artifacts
 
 ## Output Style For Vidfarm Work
 
-When reporting back after Vidfarm changes:
-
-- name the main platform area changed
-- mention the template or route affected
-- state how you verified it
-- call out any remaining gap such as `Remotion path still mocked` or `real provider calls not exercised`
+When reporting back after Vidfarm template changes:
 
-That keeps Vidfarm work easy to review and safe to iterate on.
+- name the template changed
+- mention the operation or workflow affected
+- state how you verified it locally
+- call out any remaining gap such as mocked provider responses or unexercised optional paths