@mevdragon/vidfarm-devcli 0.2.7 → 0.2.8

package/GETTING_STARTED.developers.md

@@ -86,31 +86,27 @@ That will populate with a reference folder of what a template code looks like. W
 
 9. Now find an easy winning format from https://winning-formats-gallery-tiktok.cloud.zoomgtm.com/ and save the image to your drafts/ folder. then tell Codex to look at that image (right click, copy relative path, paste to codex), then tell codex please make a new template based on the image.
 
-## Publish Responsibility
+## Shipping Updates
 
-When your template is ready for hosted Vidfarm, your responsibility is only:
+For a brand-new template, register the source once.
 
-1. push your template code to GitHub
-2. register or update the template source metadata so Vidfarm knows the repo URL, branch, and template folder path
+For an update to an already-registered template:
 
-Your responsibility does not include:
+1. Push the exact commit to GitHub.
+2. Submit that exact commit SHA to Vidfarm for review.
+3. Wait for platform admin approval and activation.
 
-1. importing the source into the live platform
-2. activating the release
-3. making the template public/live
-
-Those are platform-admin steps. If an API route says `403 Admin access required` for import or activate, that means you reached the correct handoff boundary.
-
-When you need to register your template with hosted Vidfarm, use the dev CLI command below from your repo root:
+Developer CLI example:
 
 ```bash
-npx @mevdragon/vidfarm-devcli register-source-hosted \
+node dist/src/cli.js publish-update-hosted \
   --env-file .env \
-  --template-id <uuid-v4> \
-  --slug-id <template_slug> \
-  --repo-url https://github.com/<you>/<repo> \
+  --template-id YOUR_TEMPLATE_ID \
+  --slug-id vidfarm_template_your_slug \
+  --repo-url https://github.com/your-org/your-repo.git \
   --branch main \
-  --template-module-path templates/vidfarm_template_<slug>/src/template.ts
+  --template-module-path src/vidfarm_template_your_slug/src/template.ts \
+  --commit-sha YOUR_GITHUB_COMMIT_SHA
 ```
 
-That command uses your `VIDFARM_API_KEY` and sends the registration to the hosted REST API, so the template appears in Vidfarm's review queue with `pending_review` status.
+This does not make the template live. The CLI packages that exact commit locally, uploads the artifact to Vidfarm-managed S3, and creates or refreshes the reviewable release so a platform admin can approve and activate it.

package/README.md

@@ -88,6 +88,7 @@ The developer handoff ends at:
 
 - `git push` of the template code
 - template source registration or registration update
+- for an already-registered template, publishing the exact GitHub commit SHA that should enter review
 
 The developer handoff does not include:
 
@@ -95,7 +96,7 @@ The developer handoff does not include:
 - activating a release
 - making the template public/live
 
-If a developer receives `403 Admin access required` while trying to import or activate a registered source, that is expected. Those routes are for platform admins.
+If a developer receives `403 Admin access required` while trying to import or activate a registered source, that is expected. Those routes are for platform admins. Developers should use the publish-update flow to submit an exact commit SHA for review instead.
 
 ## Template Deploy Cycle
 
@@ -132,10 +133,10 @@ node dist/src/cli.js deploy-template-cycle \
 
 The important distinction is:
 
-- third-party developers only ship template repo changes plus registration metadata
+- third-party developers ship template repo changes plus registration metadata, and can publish an exact commit SHA for an existing registered template
 - platform admins import and activate those template repo changes
 - new source registrations land in the hosted review queue before approval
-- newly imported releases can be approved while an older active release stays live
+- developer-published commit SHAs become reviewable releases while an older active release stays live
 - platform code changes ship through the root prod deploy script
 - multiple templates can live in one git repo as long as each template has its own folder and its `template_module_path` points at that folder's `src/template.ts`
 
@@ -153,7 +154,20 @@ For hosted template source registration, treat `template_module_path` as repo-re
 
 For hosted registration, use `register-source-hosted`. It talks to the Vidfarm REST API directly, so the source record lands in the production database that backs the hosted review queue. `register-source-prod` remains as a compatibility alias for internal/operator workflows.
 
-For private GitHub repos, set `VIDFARM_GITHUB_TOKEN` or `GITHUB_TOKEN` in the hosted runtime environment before using the REST import and approval flow. The production API now performs the clone/import itself, so the token must be available to the server process rather than injected from the operator shell.
+For updates to an already-registered template, use `publish-update-hosted` with the exact reviewed commit SHA. The CLI packages that commit locally into a signed artifact, uploads it to platform-controlled S3 through the Vidfarm API, and then creates or refreshes the pending release for admin review without granting developers approval or activation rights.
+
+```bash
+node dist/src/cli.js publish-update-hosted \
+  --env-file .env \
+  --template-id c7af2cd8-f032-45fa-9d4d-7af0e85cf4ef \
+  --slug-id vidfarm_template_reddit_brainrot \
+  --repo-url https://github.com/mevdragon/vidfarm_templates.git \
+  --branch main \
+  --template-module-path src/vidfarm_template_reddit_brainrot/src/template.ts \
+  --commit-sha 5e05a90a05a40105cc6e3b6a06774fdfb60c1893
+```
+
+The hosted publish path no longer depends on server-side GitHub access for template updates. Prod imports the uploaded artifact from S3 during review/import.
 
 For local CLI usage, the `session` command gives you a local seeded session so you can test without manually wiring auth state.
 
@@ -180,4 +194,4 @@ If your template uses `ctx.remotion`, develop and validate it locally through th
 
 ## Next Read
 
-For the external template-author workflow, continue with [GETTING_STARTED.developers.md](./GETTING_STARTED.developers.md) and the example template in [`templates/template_0000`](./templates/template_0000).
+For the external template-author workflow, continue with [GETTING_STARTED.developers.md](./GETTING_STARTED.developers.md) and the example template in [`templates/vidfarm_template_0000`](./templates/vidfarm_template_0000).

package/SKILL.developer.md

@@ -30,11 +30,18 @@ Do not use this skill for:
 
 Third-party template developers publish template code by pushing git commits to GitHub. That is the only code-distribution step they own.
 
+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
 
 The third-party developer should not:
@@ -46,6 +53,12 @@ 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, 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.
 
 ## Agent Operating Rule
@@ -115,40 +128,76 @@ 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
 
 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 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:
@@ -169,8 +218,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,9 +236,19 @@ 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.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.
 
 Templates are expected to evolve through multiple revisions. One-shot generation is not the standard. The standard is:
@@ -213,7 +272,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
 
@@ -288,6 +347,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 +418,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` and `about.sample_prompts` manually. The standard now requires both. `proposal_generator` should help a director combine product/about information with the template's format to invent many post proposals, and `sample_prompts` should show what strong final prompts look like. Do not leave either as optional polish.
+
+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 +438,14 @@ 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.sample_prompts` with multiple concrete examples
 - `configSchema`
 - `operations`
 - `jobs`
@@ -471,6 +553,7 @@ A revision is not complete just because the code compiles. It is complete when:
 - the requested change is visible in the output
 - the change does not obviously regress the core format
 - the template can still be rerun by another user or agent
+- `about.proposal_generator` and `about.sample_prompts` still reflect the best current way to ideate and prompt the template
 - the usage instructions still match the implementation
 
 ## Template Contract
@@ -488,7 +571,14 @@ 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.",
+    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,10 +612,48 @@ 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.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.sample_prompts`
+- `configSchema`
+- at least one operation
+- a valid workflow function for every operation
+- `smokeTestPayload` for every operation
+- template-local `SKILL.md`
+
+Best-practice rule:
+
+- every template should ship with sample prompts
+- every template should ship with a proposal generator prompt
+- proposal generation should support a workflow of proposal -> prompts -> posts
+- proposal outputs should be useful either as direct one-off prompts or as seeds for a whole series
+- include more than one example so users can see the range of valid requests
+- prefer prompts that are specific enough to be reusable exemplars, not vague one-liners
+- refresh both `about.proposal_generator` and `about.sample_prompts` when the template's prompting strategy or supported use cases change
+
 ## Provider Rules
 
 Templates should use the provider abstractions already available on `ctx.providers`.
@@ -541,6 +669,7 @@ Rules:
 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

package/dist/src/account-pages.js

@@ -516,7 +516,7 @@ export function renderSettingsPage(input) {
             <div class="card-head">
               <div>
                 <div class="pill">AI Providers</div>
-                <h2>Attached inference keys</h2>
+                <h2>Attached AI API keys</h2>
               </div>
             </div>
             <p class="helper">These are stored in plain text in SQLite for now, per your current platform requirement.</p>