@mevdragon/vidfarm-devcli 0.2.1 → 0.2.3

package/SKILL.developer.md

@@ -5,30 +5,79 @@ description: Build and extend Vidfarm templates as a third-party developer. Use
 
 # Vidfarm Third-Party Developer
 
-This skill is for third-party template developers authoring Vidfarm templates locally.
+This skill is for AI agents and developers authoring Vidfarm templates locally.
 
-Scope this skill to:
+Primary goal:
 
-- creating a new template
+- 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/*`
-- 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
+- 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, 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
+- 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
 
-For third-party developers, Remotion is local. Do not require cloud Remotion credentials or shared AWS details in this skill.
+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.
 
-## Required Developer Env
+## 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. scaffold a new template with `vidfarm-devcli generate-template`
+3. stage the source notes and preview media inside the template
+4. run `analyze-viral-dna`
+5. run `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
+
+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
 
-Third-party developers should only need their own API credentials and Vidfarm API auth.
+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`:
 
@@ -38,69 +87,349 @@ OPENAI_API_KEY=""
 OPENROUTER_API_KEY=""
 PERPLEXITY_API_KEY=""
 
-VIDFARM_USER_ID=""
 VIDFARM_API_KEY=""
 ```
 
 Notes:
 
-- 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`
+- 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`
+- 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`
+- 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`
+
+## Template Deploy Cycle
+
+If the user says "do a template deploy cycle", interpret that as:
+
+1. push the repo changes that contain the target template folder
+2. import that template commit into the hosted platform as a template source release
+3. approve and activate the new release
+4. 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
+
+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 working on a template:
+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. [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)
+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)
+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 template is an internal module loaded by Vidfarm, but third-party developers should work at the template layer, not the platform layer.
+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
+- `SKILL.md` teaches humans and agents how to call the template correctly
+- the canonical template entrypoint is `src/template.ts`
+
+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.
+
+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({...})`.
 
-The normal workflow is:
+Until the standard grows one, agents should document AI dependencies in two places for every template that uses external models:
 
-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
+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
 
-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.
+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`
+- 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;
+```
+
+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 preview-media namespace first instead of inventing ad hoc external hosting. Use:
+
+```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>/preview_media/*`, and returns both the `storage_key` and a Vidfarm `preview_media_url`. Agents should prefer that path for hosted preview uploads.
+
+### 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>/`.
+
+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
+```
 
-## When Adding A New Template
+### 4. Stage research cleanly
 
-Follow this checklist:
+Every new template should have:
 
-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`
-   - `configSchema`
-   - `operations`
-   - `jobs`
-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`
+- `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`
+
+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.
 
-## Template Contract
+For a new template, make sure it has:
+
+- `id`
+- `slugId`
+- `version`
+- `about`
+- `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`
+- `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.
+
+### 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/`
+
+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
 
-Each template should expose operations, not ad hoc endpoints.
+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
+- the usage instructions still match the implementation
+
+## Template Contract
 
 Use this shape:
 
@@ -114,7 +443,7 @@ export const myTemplate = defineTemplate({
     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: ["https://cdn.example.com/templates/ugc_hooks_v1/about/preview-01.jpg"],
+    preview_media: ["templates/ugc_hooks_v1/about/preview-01.jpg"],
     link_to_original: "https://www.tiktok.com/@example/video/1234567890"
   },
   configSchema: z.object({
@@ -148,55 +477,33 @@ export const myTemplate = defineTemplate({
 Keep these roles clear:
 
 - `id` is the UUID-style template identifier
-- `slugId` is the human-readable stable identifier
+- `slugId` is the stable human-readable identifier
 - `operations` define the public API
 - `jobs` implement the actual work
+- `smokeTestPayload` is required for each operation
 
-## Local Workflow
-
-Preferred local third-party developer workflow:
-
-```bash
-npx @mevdragon/vidfarm-devcli dev --port 3310 --reset
-npx @mevdragon/vidfarm-devcli session
-npx @mevdragon/vidfarm-devcli validate-template --template-id template_0000
-```
-
-That CLI should be the default path because it:
-
-- boots the local API and worker
-- provisions local state automatically
-- creates a local developer session
-- seeds provider keys from local env vars when present
-- uses local Remotion rendering
-
-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
-```
-
-## Provider Usage
+## Provider Rules
 
-Templates should prefer the Vidfarm provider abstractions already available in context.
+Templates should use the provider abstractions already available on `ctx.providers`.
 
 Rules:
 
 - 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
 
-If a task only needs image generation, do not force extra model providers for text or research.
+Important distinction:
 
-## Storage Namespaces
+- runtime template generation can use OpenAI, OpenRouter, Gemini, or Perplexity according to template logic
+- built-in DNA analysis commands currently depend on `GEMINI_API_KEY`
 
-Use the built-in storage namespace conventions instead of inventing one-off key layouts.
+## Storage And Upload Rules
 
-Current namespaces:
+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
@@ -205,20 +512,26 @@ Current namespaces:
 
 Rules:
 
-- 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
+- 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
-- prefer the shared storage helpers over handwritten string concatenation for new paths
+
+The runtime may back these writes with local filesystem storage or S3 depending on environment. The template should not care.
 
 ## API Usage
 
-When testing through the API, use:
+When calling a hosted Vidfarm API directly, use:
 
-- `vidfarm-user-id`
 - `vidfarm-api-key`
 
-The template-local `SKILL.md` should show the concrete routes and example payloads for that template.
+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
 
@@ -227,26 +540,37 @@ 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. 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
+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 changed slideshow or text-overlay behavior, also validate:
+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. final local video output matches expected pacing and framing
+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
+- adding one-off custom endpoints when an operation already fits the job model
 - hardcoding a developer's personal provider choice into template logic
-- omitting `SKILL.md` or `smokeTestPayload`
+- 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
 
@@ -254,5 +578,7 @@ 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 or unexercised optional paths
+- call out any remaining gap such as mocked provider responses, missing preview media, or unexercised optional paths

package/dist/src/account-pages.js

@@ -496,7 +496,7 @@ export function renderSettingsPage(input) {
           <section class="settings-panel">
             <div class="pill">Vidfarm API</div>
             <h2>Your Vidfarm API key</h2>
-            <p class="helper">Use this key with the <code>vidfarm-user-id</code> header pair when calling the Vidfarm API directly.</p>
+            <p class="helper">Use this key as the auth header when calling the Vidfarm API directly. If you need your customer ID, fetch it from <code>/api/v1/user/me</code>.</p>
             <label for="vidfarm-api-key">Current API key</label>
             <div class="secret-wrap">
               <input id="vidfarm-api-key" type="password" value="${escapeHtml(input.vidfarmApiKey)}" readonly />