@mevdragon/vidfarm-devcli 0.2.0 → 0.2.1

package/SKILL.director.md

@@ -0,0 +1,599 @@
+---
+name: vidfarm-director
+description: Use Vidfarm as a director-facing agent-first video production platform. Use this whenever the user wants to log in with OTP, store their own AI provider keys, discover templates, read a template's published skill, submit template jobs, poll job status, inspect logs, or operate a multi-stage media production workflow through the Vidfarm REST API.
+---
+
+# Vidfarm Director
+
+Vidfarm is an agent-first media production platform.
+
+Use this skill when the user wants to operate Vidfarm as a director, not when they want to build templates or modify the platform.
+
+The user of this skill is a director or template operator:
+
+- they sign in to Vidfarm
+- they bring their own AI API keys
+- they discover available templates
+- they read each template's published skill and metadata
+- they submit async jobs to template operations
+- they poll jobs, read logs, and chain stages together
+
+Do not explain template developer internals unless the user explicitly asks for them.
+
+## Core Mental Model
+
+Treat Vidfarm as a shared control plane for many production templates.
+
+Each template is a production format with a common platform wrapper:
+
+- auth
+- API keys
+- async jobs
+- logs
+- webhooks
+- artifacts
+
+Each template then adds its own production logic through its operations.
+
+The platform is intentionally async-first:
+
+- every meaningful production action becomes a job
+- jobs immediately return `job_id`
+- the caller polls for status or receives a webhook
+
+This is important because video production is inherently multi-stage and often slow:
+
+- concept generation
+- research
+- script or storyboard scaffolding
+- image or scene generation
+- human review or revision
+- final render
+
+You should frame Vidfarm as a production pipeline system, not as a single prompt-response tool.
+
+## Agent-First Operating Style
+
+Vidfarm is designed for users who work through AI agents.
+
+Your role is usually to operate the API on the user's behalf:
+
+1. log the user in
+2. store their provider keys
+3. list templates
+4. inspect the selected template
+5. read the template's published skill
+6. choose the right operation
+7. submit the job
+8. monitor progress
+9. use outputs from one stage as inputs to the next stage
+
+Prefer doing this operational work for the user instead of only describing the docs.
+
+When helping a user choose what to do next, think in terms of pipeline stages. Ask what stage they are in:
+
+- idea
+- storyboard
+- asset generation
+- refinement
+- rendering
+- delivery
+
+## Bring Your Own AI Keys
+
+Vidfarm expects customers to bring their own AI provider credentials.
+
+Today the user-facing provider key API supports:
+
+- `openai`
+- `gemini`
+- `openrouter`
+- `perplexity`
+
+Before running most AI-backed template operations, the user should save at least one provider key that matches the template's expected provider flow.
+
+Do not imply that Vidfarm supplies the AI credits itself. The customer is expected to supply their own upstream AI access.
+
+## Base URL And Auth
+
+Production is intended to run under:
+
+```txt
+https://vidfarm.cloud.zoomgtm.com
+```
+
+The REST API base path is:
+
+```txt
+/api/v1
+```
+
+Authenticated API calls use these headers:
+
+```txt
+vidfarm-user-id: <customer id>
+vidfarm-api-key: <api key>
+```
+
+The API key is issued after OTP verification.
+
+## Login Flow
+
+Use this sequence for API login:
+
+1. `POST /api/v1/user/request-otp`
+2. `POST /api/v1/user/verify-otp`
+
+Request OTP:
+
+```bash
+curl -X POST "https://vidfarm.cloud.zoomgtm.com/api/v1/user/request-otp" \
+  -H "content-type: application/json" \
+  -d '{
+    "email": "user@example.com"
+  }'
+```
+
+Verify OTP:
+
+```bash
+curl -X POST "https://vidfarm.cloud.zoomgtm.com/api/v1/user/verify-otp" \
+  -H "content-type: application/json" \
+  -d '{
+    "email": "user@example.com",
+    "code": "123456",
+    "name": "Example User"
+  }'
+```
+
+Expected response shape:
+
+```json
+{
+  "customer": {
+    "id": "cus_...",
+    "email": "user@example.com",
+    "name": "Example User",
+    "defaultWebhookUrl": null,
+    "isDeveloper": false,
+    "isPaidPlan": true
+  },
+  "apiKey": "vf_key_..."
+}
+```
+
+Persist these values for later API calls:
+
+- `customer.id`
+- `apiKey`
+
+Useful shell variables:
+
+```bash
+BASE_URL="https://vidfarm.cloud.zoomgtm.com/api/v1"
+VIDFARM_USER_ID="cus_replace_me"
+VIDFARM_API_KEY="vf_replace_me"
+AUTH_HEADERS=(
+  -H "vidfarm-user-id: ${VIDFARM_USER_ID}"
+  -H "vidfarm-api-key: ${VIDFARM_API_KEY}"
+)
+JSON_HEADERS=(
+  "${AUTH_HEADERS[@]}"
+  -H "content-type: application/json"
+)
+```
+
+## Save Provider Keys
+
+Store the user's own AI key before starting template work:
+
+```bash
+curl -X POST "${BASE_URL}/user/me/provider-keys" \
+  "${JSON_HEADERS[@]}" \
+  -d '{
+    "provider": "openrouter",
+    "label": "primary",
+    "secret": "sk-or-v1-...",
+    "weight": 1
+  }'
+```
+
+List saved provider keys:
+
+```bash
+curl "${BASE_URL}/user/me/provider-keys" \
+  "${AUTH_HEADERS[@]}"
+```
+
+Use `GET /api/v1/user/me` to inspect the current authenticated customer profile:
+
+```bash
+curl "${BASE_URL}/user/me" \
+  "${AUTH_HEADERS[@]}"
+```
+
+## Template Standard
+
+Every customer-usable template follows the same platform shape:
+
+- `GET /api/v1/templates`
+- `GET /api/v1/templates/:templateId`
+- `GET /api/v1/templates/:templateId/skill`
+- `GET /api/v1/templates/:templateId/about/*`
+- `POST /api/v1/templates/:templateId/config`
+- `POST /api/v1/templates/:templateId/operations/:operationName`
+- `GET /api/v1/templates/:templateId/jobs`
+- `GET /api/v1/templates/:templateId/jobs/:jobId`
+- `GET /api/v1/templates/:templateId/jobs/:jobId/logs`
+- `POST /api/v1/templates/:templateId/jobs/:jobId/cancel`
+
+This common wrapper is the most important concept for users.
+
+No matter which template is chosen, the operating pattern stays the same:
+
+1. discover
+2. inspect
+3. configure
+4. submit operation
+5. monitor job
+6. feed outputs into the next stage
+
+## Discover Templates
+
+List all templates:
+
+```bash
+curl "${BASE_URL}/templates" \
+  "${AUTH_HEADERS[@]}"
+```
+
+The response includes each template's:
+
+- `id`
+- `slug_id`
+- `version`
+- `title`
+- `description`
+- `skill_url`
+- `operations`
+
+Read one template's about metadata:
+
+```bash
+curl "${BASE_URL}/templates/template_0000" \
+  "${AUTH_HEADERS[@]}"
+```
+
+Expected about fields include:
+
+- `id`
+- `slug_id`
+- `version`
+- `title`
+- `description`
+- `viral_dna`
+- `preview_media`
+- `link_to_original`
+- `skill_url`
+- `operations`
+
+Important detail:
+
+- `templateId` may be either the UUID-like template id or the human-readable `slug_id`
+- in practice, users will usually prefer the `slug_id`
+
+## Read The Template's Own Skill
+
+After identifying a template, read its published skill:
+
+```bash
+curl "${BASE_URL}/templates/template_0000/skill" \
+  "${AUTH_HEADERS[@]}"
+```
+
+This is how you discover the template's unique operating details.
+
+The template skill is the customer-facing contract for things like:
+
+- which operations exist
+- what each operation does
+- the expected payload shape
+- which output artifacts come back
+- any template-specific stage sequence
+- any style or formatting constraints
+
+When a user asks how to use a specific template, always inspect both:
+
+1. `GET /templates/:templateId`
+2. `GET /templates/:templateId/skill`
+
+Use the metadata endpoint for the standard wrapper and the skill endpoint for the template-specific behavior.
+
+## Template Configuration
+
+Some templates support saved per-user configuration.
+
+Write config with:
+
+```bash
+curl -X POST "${BASE_URL}/templates/template_0000/config" \
+  "${JSON_HEADERS[@]}" \
+  -d '{
+    "config": {
+      "defaultProvider": "gemini"
+    }
+  }'
+```
+
+Treat config as stable preferences for that template, such as:
+
+- default provider
+- default models
+- style settings
+- rendering defaults
+
+Always check the template skill for the config fields that the specific template expects.
+
+## Submit Template Operations
+
+Template work is submitted through operation routes:
+
+```txt
+POST /api/v1/templates/:templateId/operations/:operationName
+```
+
+Request shape:
+
+```json
+{
+  "tracer": "client-generated-reference",
+  "payload": {},
+  "webhook_url": "https://example.com/webhooks/vidfarm"
+}
+```
+
+`webhook_url` is optional.
+
+The standard response shape is:
+
+```json
+{
+  "job_id": "job_...",
+  "tracer": "client-generated-reference",
+  "status": "queued"
+}
+```
+
+Example, using the sample template's first stage:
+
+```bash
+curl -X POST "${BASE_URL}/templates/template_0000/operations/create_slideshow" \
+  "${JSON_HEADERS[@]}" \
+  -d '{
+    "tracer": "launch-story-001",
+    "payload": {
+      "slides": [
+        ["late night founder at laptop", "launching after hours", 2200],
+        {
+          "image_prompt": "skincare serum bottle on a clean bathroom counter near a window",
+          "caption": "the routine was simpler than i thought",
+          "duration_ms": 2800
+        }
+      ],
+      "meta_details_prompt": "Write native TikTok metadata for a US audience. Keep it curiosity-driven and casual."
+    }
+  }'
+```
+
+## Monitor Jobs
+
+List jobs for one template:
+
+```bash
+curl "${BASE_URL}/templates/template_0000/jobs" \
+  "${AUTH_HEADERS[@]}"
+```
+
+Filter by tracer or time window:
+
+```bash
+curl "${BASE_URL}/templates/template_0000/jobs?tracer=launch-story-001&start_time=2026-05-17T00:00:00.000Z&end_time=2026-05-18T00:00:00.000Z&limit=20" \
+  "${AUTH_HEADERS[@]}"
+```
+
+Get one job:
+
+```bash
+JOB_ID="job_replace_me"
+
+curl "${BASE_URL}/templates/template_0000/jobs/${JOB_ID}" \
+  "${AUTH_HEADERS[@]}"
+```
+
+Job responses commonly include:
+
+- `job_id`
+- `template_id`
+- `operation_name`
+- `workflow_name`
+- `tracer`
+- `status`
+- `progress`
+- `result`
+- `error`
+- `created_at`
+- `updated_at`
+- `started_at`
+- `completed_at`
+
+Current job statuses are:
+
+- `queued`
+- `running`
+- `waiting_for_child`
+- `waiting_for_human`
+- `succeeded`
+- `failed`
+- `cancelled`
+
+## Read Structured Logs
+
+Every job can expose a structured timeline:
+
+```bash
+curl "${BASE_URL}/templates/template_0000/jobs/${JOB_ID}/logs?start_time=2026-05-17T00:00:00.000Z&end_time=2026-05-18T00:00:00.000Z&limit=200" \
+  "${AUTH_HEADERS[@]}"
+```
+
+Treat logs as the best source for:
+
+- progress checkpoints
+- stage-level diagnostics
+- artifact references
+- machine-readable metadata emitted during production
+
+When a job fails or stalls, inspect logs before retrying blindly.
+
+## Cancel Jobs
+
+Cancel a job with:
+
+```bash
+curl -X POST "${BASE_URL}/templates/template_0000/jobs/${JOB_ID}/cancel" \
+  "${AUTH_HEADERS[@]}"
+```
+
+## Cross-Template Job Listing
+
+To see the current user's jobs across templates:
+
+```bash
+curl "${BASE_URL}/user/me/jobs" \
+  "${AUTH_HEADERS[@]}"
+```
+
+This endpoint also supports filters such as:
+
+- `template_id`
+- `tracer`
+- `start_time`
+- `end_time`
+- `limit`
+
+## Webhooks
+
+Vidfarm supports optional job webhooks on operation submission.
+
+Use them when the user wants asynchronous completion handling instead of polling.
+
+Webhook events can include:
+
+- `job.queued`
+- `job.running`
+- `job.succeeded`
+- `job.failed`
+- `job.cancelled`
+
+Webhook requests include:
+
+- `x-vidfarm-event`
+- `x-vidfarm-signature`
+
+The JSON body shape is:
+
+```json
+{
+  "type": "job.succeeded",
+  "emitted_at": "2026-05-17T12:00:00.000Z",
+  "job": {
+    "job_id": "job_...",
+    "tracer": "launch-story-001",
+    "status": "succeeded",
+    "template_id": "template_0000",
+    "operation_name": "create_slideshow",
+    "progress": 1,
+    "result": {},
+    "error": null
+  }
+}
+```
+
+## Multi-Stage Production Guidance
+
+The right way to think about Vidfarm is as a chain of production states.
+
+One operation often prepares the next one.
+
+Typical pattern:
+
+1. generate or scaffold assets
+2. inspect the result payload and artifacts
+3. optionally revise inputs
+4. submit the next operation
+5. repeat until final render or export
+
+For example, the current sample template behaves like this:
+
+1. `create_slideshow` generates finished slide frames plus manifest data
+2. the returned `renderVideoInput` becomes the clean handoff into `render_video`
+3. `render_video` turns those frames into a final vertical video
+
+When helping users, always look for explicit handoff fields in the previous stage's `result`.
+
+## How To Understand A Template's Unique API
+
+Vidfarm templates share the same outer API, but each template has unique operations and payloads.
+
+Use this exact sequence:
+
+1. call `GET /api/v1/templates`
+2. pick a template id or `slug_id`
+3. call `GET /api/v1/templates/:templateId`
+4. inspect `operations`
+5. call `GET /api/v1/templates/:templateId/skill`
+6. extract operation names, payload examples, and stage order from the skill
+7. submit the chosen operation under `/operations/:operationName`
+
+Do not invent undocumented subroutes.
+
+For customers, the unique template surface is primarily:
+
+- the operation names
+- the config schema
+- the payload contract
+- the returned artifacts and result structure
+
+The template skill is the authoritative human-readable guide for those differences.
+
+## Alpha Posture
+
+Vidfarm is in alpha.
+
+Prefer teaching users the flows that exist now and avoid dwelling on features that may arrive later.
+
+Focus on what lets a user become operational immediately:
+
+- OTP login
+- API key issuance
+- provider key upload
+- template discovery
+- template skill inspection
+- async job submission
+- job polling
+- logs
+- webhooks
+
+## Default Assistance Pattern
+
+When a user asks for help using Vidfarm, default to this style:
+
+1. get or confirm their auth state
+2. confirm they have brought their own AI key
+3. list templates
+4. inspect the chosen template
+5. read the template skill
+6. identify the current production stage
+7. submit the smallest sensible next operation
+8. monitor the job and interpret the outputs
+
+This keeps the interaction agentic, operational, and immediately useful.

package/dist/src/account-pages.js

@@ -220,6 +220,40 @@ function shell(input) {
         color: var(--muted);
         background: rgba(255,255,255,0.7);
       }
+      .status-row {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 10px;
+        align-items: center;
+      }
+      .status-pill {
+        display: inline-flex;
+        align-items: center;
+        gap: 8px;
+        padding: 8px 12px;
+        border: 1px solid var(--line);
+        background: rgba(255,255,255,0.78);
+        color: var(--ink);
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+        font-size: 12px;
+      }
+      .status-pill::before {
+        content: "";
+        width: 9px;
+        height: 9px;
+        border-radius: 999px;
+        background: #7a6d61;
+      }
+      .status-pill.is-active::before {
+        background: var(--accent);
+        box-shadow: 0 0 0 4px rgba(159, 61, 36, 0.12);
+      }
+      .developer-panel {
+        background:
+          linear-gradient(135deg, rgba(159, 61, 36, 0.11), rgba(255,255,255,0.68)),
+          rgba(255,255,255,0.62);
+      }
       .key-list, .attachment-list {
         display: grid;
         gap: 12px;
@@ -402,6 +436,21 @@ export function renderSettingsPage(input) {
                   data-copy-content='${escapeAttribute(input.developerSkill)}'
                   data-copy-label="Developer SKILL.md"
                 >Developer SKILL.md</button>
+  ` : "";
+    const developerPanel = input.isDeveloper ? `
+          <section class="settings-panel developer-panel">
+            <div class="card-head">
+              <div>
+                <div class="pill">Developer Access</div>
+                <h2>Template developer tools are enabled</h2>
+              </div>
+              <div class="status-pill is-active">Developer</div>
+            </div>
+            <p class="helper">This account can submit template sources and use the developer workflow. The <code>Developer SKILL.md</code> prompt is available here for fast copy into your agent tooling.</p>
+            <div class="toolbar">
+              ${developerSkillButton}
+            </div>
+          </section>
   ` : "";
     return shell({
         title: "Settings",
@@ -423,7 +472,10 @@ export function renderSettingsPage(input) {
                 <div class="pill">Profile</div>
                 <h2>Workspace identity</h2>
               </div>
-              <div class="tiny">${input.isPaidPlan ? "Paid plan" : "Inactive plan"}</div>
+              <div class="status-row">
+                <div class="status-pill ${input.isPaidPlan ? "is-active" : ""}">${input.isPaidPlan ? "Paid plan" : "Inactive plan"}</div>
+                <div class="status-pill ${input.isDeveloper ? "is-active" : ""}">${input.isDeveloper ? "Developer" : "Standard"}</div>
+              </div>
             </div>
             <form method="post" action="/settings/profile">
               <label for="settings-email">Email</label>
@@ -440,10 +492,11 @@ export function renderSettingsPage(input) {
               </div>
             </form>
           </section>
+          ${developerPanel}
           <section class="settings-panel">
             <div class="pill">Vidfarm API</div>
-            <h2>Your control-plane key</h2>
-            <p class="helper">Use this key with the <code>vidfarm-user-id</code> header pair when calling the API directly.</p>
+            <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>
             <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 />
@@ -457,7 +510,6 @@ export function renderSettingsPage(input) {
                 data-copy-content='${escapeAttribute(input.directorSkill)}'
                 data-copy-label="Director SKILL.md"
               >Director SKILL.md</button>
-              ${developerSkillButton}
             </div>
           </section>
           <section class="settings-panel">
@@ -506,7 +558,7 @@ export function renderSettingsPage(input) {
           <section class="settings-panel">
             <div class="pill">Attachments</div>
             <h2>Shared files</h2>
-            <p class="helper">Uploads are stored under your <code>user/*</code> storage path and can be opened via public read URLs.</p>
+            <p class="helper">Uploads are stored under your <code>user/&lt;user_id&gt;/*</code> namespace and can be opened via public read URLs.</p>
             <form method="post" action="/settings/attachments" enctype="multipart/form-data">
               <label for="settings-files">Images, video, audio, PDF, Markdown, or text</label>
               <input id="settings-files" type="file" name="files" multiple accept="image/*,video/*,audio/*,.pdf,.md,.txt,text/markdown,text/plain,application/pdf" />