@feastalytics/cli 0.1.18 → 0.1.19

package/README.md

@@ -10,7 +10,7 @@ Feastalytics ships as a plugin (the `feast` skill plus the hosted MCP server at
 
 - **Claude Code**: `/plugin marketplace add feastalytics/cli`, then `/plugin install feastalytics@feast`.
 - **claude.ai and Claude Desktop**: add a custom connector with the URL `https://mcp.feast-api.com/mcp`. A directory listing is to follow.
-- **ChatGPT**: `npm run build:chatgpt` writes `dist/feastalytics-chatgpt.zip` (the root `plugin.json`, `mcp.json` and `skills/`).
+- **ChatGPT**: `npm run build:chatgpt` writes `dist/feastalytics-chatgpt.zip` (`plugin/plugin.json`, `plugin/mcp.json`, the icon and `plugin/skills/`).
 - **Skill only** (Claude Code, Codex, Cursor and other agents): `npx skills add feastalytics/cli`.
 
 ### CLI
@@ -75,7 +75,7 @@ Mutations additionally require `--org` and print the server-resolved org before
 
 ## Agent skill
 
-The `skills/feast/` directory is an [agent skill](https://www.skills.sh) that teaches an agent to operate Feastalytics through its tools, either this CLI or the hosted MCP server at `https://mcp.feast-api.com/mcp` (same tools, same names). Install it into your agent(s):
+The `plugin/skills/feast/` directory is an [agent skill](https://www.skills.sh) that teaches an agent to operate Feastalytics through its tools, either this CLI or the hosted MCP server at `https://mcp.feast-api.com/mcp` (same tools, same names). Install it into your agent(s):
 
 ```bash
 npx skills add feastalytics/cli

package/dist/cli.js

@@ -9045,6 +9045,35 @@ var CLI_MANIFEST = {
         "$schema": "http://json-schema.org/draft-07/schema#"
       }
     },
+    {
+      "id": "approveVideo",
+      "domain": "ads",
+      "description": "Approve a video and save its MP4 to the campaign's creative library, returning the libraryKey. Pass the projectId; runId is optional and defaults to the latest run that has an export (the one getVideo's exportUrl plays), so pass it only to approve an earlier run from listCampaignVideos. Fails until that run's export is ready (getVideo pipeline.status ready). Only once the human has watched the video and approved it.",
+      "type": "mutation",
+      "path": [
+        "api",
+        "bevyl",
+        "approveProject"
+      ],
+      "inputJsonSchema": {
+        "type": "object",
+        "properties": {
+          "projectId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "runId": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "projectId"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
     {
       "id": "awardReward",
       "domain": "membersProgram",
@@ -13530,7 +13559,7 @@ var CLI_MANIFEST = {
     {
       "id": "createRecruitmentCreatives",
       "domain": "creators",
-      "description": "Generate the five AI recruitment ad creatives for a location. Pass campaignId (or offerId) so they attach to its recruitment offer. Only missing types are generated; force deletes and regenerates the whole set. foodCredit from getInfluencerBoardConfig.",
+      "description": "Render the five recruitment ad images for a location from fixed templates, using its own photo, logo and food credit (no AI image generation). Pass campaignId (or offerId) so they attach to its recruitment offer. Only missing types are generated; force deletes and regenerates the whole set. foodCredit from getInfluencerBoardConfig.",
       "type": "mutation",
       "path": [
         "api",
@@ -13843,6 +13872,90 @@ var CLI_MANIFEST = {
         "$schema": "http://json-schema.org/draft-07/schema#"
       }
     },
+    {
+      "id": "generateVideo",
+      "domain": "ads",
+      "description": "Start a Bevyl ad video for a campaign from its b-roll. Returns { projectId, pipelineStatus } at once; the server uploads the clips, waits for Bevyl to process them, creates the video and exports it. Poll getVideo with the projectId every 30 seconds or so until pipeline.status is ready (exportUrl is the MP4) or failed (message says why). Spends Bevyl generation credits, so only with the human's explicit approval. Build prompt from getVideoPromptOptions (its defaultPrompt, edited or not): Bevyl reads it verbatim, up to 5000 characters. Set format yourself (talking-head, voiceover, trending-sounds which needs trendId, or no-audio); the chosen direction's suggestedFormat is a good default. Optional: angleId from listCampaignVideos to add a version to an existing angle (otherwise angleTitle names a new one, defaulting to the concept's first line), voiceoverProfileId, backgroundMusicTrackId, durationSeconds 10 to 80 in steps of 5, and brollKeys (S3 keys from listMedia scope creativeLibraryBroll; omit to use every clip already synced to Bevyl).",
+      "type": "mutation",
+      "path": [
+        "api",
+        "bevyl",
+        "generate"
+      ],
+      "inputJsonSchema": {
+        "type": "object",
+        "properties": {
+          "campaignId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "angleId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100
+          },
+          "angleTitle": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 300
+          },
+          "prompt": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 5e3
+          },
+          "format": {
+            "type": "string",
+            "enum": [
+              "talking-head",
+              "voiceover",
+              "trending-sounds",
+              "no-audio"
+            ],
+            "default": "talking-head"
+          },
+          "voiceoverProfileId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "trendId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "backgroundMusicTrackId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "durationSeconds": {
+            "type": "integer",
+            "minimum": 10,
+            "maximum": 80,
+            "multipleOf": 5
+          },
+          "brollKeys": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "maxItems": 100
+          },
+          "bevylVideoIds": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "maxItems": 100
+          }
+        },
+        "required": [
+          "campaignId"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
     {
       "id": "getAutomationDraft",
       "domain": "automations",
@@ -14805,6 +14918,56 @@ var CLI_MANIFEST = {
         "$schema": "http://json-schema.org/draft-07/schema#"
       }
     },
+    {
+      "id": "getVideo",
+      "domain": "ads",
+      "description": "Read one Content Studio video by projectId. pipeline.status moves uploading, processing, creating, rendering, exporting, then ready (exportUrl is the MP4 to watch) or failed (message says why). pipeline is null for videos made before the server pipeline; use listCampaignVideos for those. Reads Feastalytics only, so it is cheap to poll.",
+      "type": "query",
+      "path": [
+        "api",
+        "bevyl",
+        "getProject"
+      ],
+      "inputJsonSchema": {
+        "type": "object",
+        "properties": {
+          "projectId": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "projectId"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
+    {
+      "id": "getVideoPromptOptions",
+      "domain": "ads",
+      "description": "The building blocks for a generateVideo prompt for one campaign. defaultPrompt is what Content Studio would send with its default picks: plain text in four sections (Campaign, Concept, Creative direction, CTA), each a heading line followed by its text. campaign, concept, direction and cta list the alternatives for each section ({ id, label, text }); concept options also carry the reference video they were distilled from, and direction options a suggestedFormat to pass as generateVideo's format. Send defaultPrompt as is, or swap a section's text for another option's, or rewrite it entirely: generateVideo sends the prompt to Bevyl verbatim. Reads Feastalytics only.",
+      "type": "query",
+      "path": [
+        "api",
+        "bevyl",
+        "getVideoPromptOptions"
+      ],
+      "inputJsonSchema": {
+        "type": "object",
+        "properties": {
+          "campaignId": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "campaignId"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
     {
       "id": "inviteUser",
       "domain": "core",
@@ -14965,6 +15128,31 @@ var CLI_MANIFEST = {
       ],
       "inputJsonSchema": null
     },
+    {
+      "id": "listCampaignVideos",
+      "domain": "ads",
+      "description": "Every Content Studio video for a campaign, newest first: projectId, angleId and angleTitle (videos are grouped into angles), the concept and direction they were made from, latestRun (the Bevyl run, whose runId approveVideo needs), approvedRunId, edits, and pipeline (status, message, exportUrl) for videos made through generateVideo. Calls Bevyl to read run status, so prefer getVideo to poll a single video.",
+      "type": "query",
+      "path": [
+        "api",
+        "bevyl",
+        "listCampaignProjects"
+      ],
+      "inputJsonSchema": {
+        "type": "object",
+        "properties": {
+          "campaignId": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "campaignId"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
     {
       "id": "listCreatives",
       "domain": "creators",
@@ -15710,6 +15898,41 @@ var CLI_MANIFEST = {
         "$schema": "http://json-schema.org/draft-07/schema#"
       }
     },
+    {
+      "id": "requestVideoEdit",
+      "domain": "ads",
+      "description": `Ask Bevyl to remake a video with one change, for example "make the hook punchier" or "use the patio shots first". Send only the change in note (600 characters at most); Bevyl builds from the video's current state. On-screen text cannot be moved or resized. Starts a new run: getVideo moves back to rendering, then ready with the new export. Spends Bevyl generation credits, so only with the human's explicit approval.`,
+      "type": "mutation",
+      "path": [
+        "api",
+        "bevyl",
+        "regenerateProject"
+      ],
+      "inputJsonSchema": {
+        "type": "object",
+        "properties": {
+          "projectId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "note": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 600
+          },
+          "requestId": {
+            "type": "string",
+            "format": "uuid"
+          }
+        },
+        "required": [
+          "projectId",
+          "note"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
     {
       "id": "saveAutomationEdits",
       "domain": "automations",
@@ -22321,23 +22544,6 @@ var CLI_MANIFEST = {
                 },
                 "additionalProperties": false
               },
-              "openTableConfig": {
-                "type": "object",
-                "properties": {
-                  "baseUrl": {
-                    "type": "string"
-                  },
-                  "numDaysCanReserveAhead": {
-                    "type": "number"
-                  }
-                },
-                "required": [
-                  "baseUrl",
-                  "numDaysCanReserveAhead"
-                ],
-                "additionalProperties": false,
-                "description": "Deprecated: Use openTableConfigs instead"
-              },
               "openTableConfigs": {
                 "type": "array",
                 "items": {
@@ -23603,13 +23809,6 @@ var CLI_MANIFEST = {
             "maxItems": 20,
             "description": "Additional email addresses for scheduled, rescheduled, confirmed and cancelled visit emails and Calendar invitations. No Feast account is required. Send an empty array to remove all email-only recipients; omit to preserve them. Requires the organization's booking notification feature to be enabled."
           },
-          "passConfigured": {
-            "type": "boolean"
-          },
-          "calendarConfigured": {
-            "type": "boolean",
-            "description": "Ignored. Kept while older clients still send it."
-          },
           "maxBookingDaysOut": {
             "anyOf": [
               {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feastalytics/cli",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Command-line client for the Feastalytics platform — list, create, and update campaigns, automations, offers, and members-program rewards from the terminal.",
   "type": "module",
   "bin": {
@@ -9,7 +9,7 @@
   "files": [
     "dist",
     "!dist/*.zip",
-    "skills"
+    "plugin/skills"
   ],
   "author": "Feastalytics",
   "license": "UNLICENSED",
@@ -30,7 +30,7 @@
     "feast": "tsx src/cli.ts",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build",
-    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json plugin.json",
+    "version": "node scripts/sync-plugin-version.mjs && git add plugin/.claude-plugin/plugin.json plugin/plugin.json",
     "build:chatgpt": "sh scripts/build-chatgpt-zip.sh"
   },
   "devDependencies": {

package/{skills → plugin/skills}/feast/SKILL.md

@@ -85,6 +85,7 @@ Many tasks are multi-step and have a required ordering the app normally enforces
 | Writing guest-facing Meta ad copy (`adCopy`) | `references/workflows/ad-copy-guest.md` |
 | Writing creator-recruitment ad copy (`recruitmentAdCopy`) | `references/workflows/ad-copy-creator.md` |
 | Publishing, pausing, budgeting or diagnosing Meta ads | `references/workflows/ads.md` |
+| Making a video ad with Bevyl: prompt, generate, edit, approve | `references/workflows/videos.md` |
 | Creator sourcing: approving applicants, reviewing content, creatives, payouts, reimbursements, texting a creator | `references/workflows/creators.md` |
 | Members-program rewards, granting a reward to one member; reading or saving the wallet pass configuration | `references/workflows/members-program.md` |
 | Working the onboarding taskboard; brand identity; phone, media, invites, billing | `references/workflows/onboarding.md` |

package/{skills → plugin/skills}/feast/references/domains.md

@@ -41,6 +41,10 @@ Restaurants recruit local content creators to visit and post. One config per loc
 
 A template-driven publish pipeline: `listAdTemplates` → `planAds` → `publishAds` → `getJob` → `setAdCampaignStatus`, plus `ads_*` tools for reading and steering what's already on the ad account. See `workflows/ads.md`.
 
+## Video ads (Content Studio)
+
+Bevyl edits a campaign's b-roll into ad videos, grouped into angles. One `projectId` per video: `getVideoPromptOptions` → `generateVideo` → poll `getVideo` → `requestVideoEdit` or `approveVideo`. See `workflows/videos.md`.
+
 ## The data catalog
 
 `describeData` / `queryData` expose a read-only, org-scoped query surface over the data model: guests, orders, menu items, texts, creator visits, payouts. When no purpose-built tool answers a read question, the catalog usually does; `describeData` with no arguments is the index.

package/{skills → plugin/skills}/feast/references/setup.md

@@ -30,7 +30,7 @@ If the global install fails on permissions, don't retry with `sudo`. Tell the us
 
 ### Authenticating
 
-Authenticate once. Tokens are cached in `~/.config/feast-cli/credentials.json` and refreshed automatically:
+Authenticate once. The CLI keeps you signed in and refreshes the session itself:
 
 ```bash
 feast login                        # opens a browser to authorize (default)
@@ -64,7 +64,7 @@ Feastalytics publishes further skills that build on this one (campaign diagnosis
 
 ```bash
 feast skill list                       # what is published for your organization
-feast skill install feast-playbooks    # install or refresh one into ~/.claude/skills/
+feast skill install feast-playbooks    # install or refresh one for your agent
 ```
 
 Install what `feast skill list` offers when the user asks for a playbook this skill does not cover, and re-run the install when the CLI prints an update notice.

package/{skills → plugin/skills}/feast/references/workflows/ads.md

@@ -55,8 +55,4 @@ An effect that reports `error` in the job is a case for the dashboard, not for p
 - `ads_activate_entity`: go-live for structures Feastalytics did *not* publish. No cascade: activate top-down and check `willDeliver`; a child under a paused parent is live in name only. For campaigns Feastalytics published, `setAdCampaignStatus` cascades and is the right tool: those are published paused at all three levels, so activating the campaign alone would spend nothing.
 - `ads_get_datasets` / `ads_create_dataset`: pixel checks and creation. The pixel a campaign should optimise against is the one its funnel actually fires (from the layout config), not whichever pixel looks plausible on the account. After creating one, write its id back with `updateBrandIdentity`; creation alone connects nothing. That layout config value is what makes the funnel fire the pixel and what the onboarding task reads.
 
-### Reference scripts for video ads
-
-`listReferenceScripts` returns the reference ad scripts Content Studio offers as Concept presets for Bevyl videos, each distilled from an ad that performed: `description` (what the video shows), `videoUrl` (a public MP4 preview), `structure` (the ordered beats), `keyPhrases` (lines to adapt, with `<placeholders>` filled from the campaign's facts) and `concept` (the exact text Content Studio sends to Bevyl). Copy the structure and pacing, not the words. The list is the same for every organization.
-
 > **Not exposed:** ad-copy generation (write it yourself: `ad-copy-guest.md` / `ad-copy-creator.md`), creative *content* editing on Meta (immutable there), and publishing creator content as partnership ads.

package/{skills → plugin/skills}/feast/references/workflows/automations.md

@@ -89,12 +89,14 @@ When an automation's trigger is `receiveAutomation`, ask the user whether it sho
 
 ### Text-content best practices (rules when creating, checklist when reviewing)
 
-1. **Descriptive names**: "Day 2: Visit Reminder with Pass Link", not "Reminder 1".
-2. **Lead with the pass link**: the first post-signup text MUST include it ("add your pass: {{pass link}}").
-3. **Always `https://`** on every link (carriers block bare/protocol-less links).
+1. **Descriptive names**: "Day 2: Visit Reminder with Wallet Link", not "Reminder 1".
+2. **Lead with the wallet link**: the first post-signup text MUST include the link that adds the guest's card to Apple or Google Wallet, written with the `passLink` text variable (see the variables below).
+3. **Every link starts with https**: carriers block links written without it.
 4. **Mobile Google Maps links only**: `https://maps.app.goo.gl/...`, never desktop `maps.google.com`.
 5. **Correct reservation links**: `https://{subdomain}.feastalytics.com/i/{shorthand}/reservation` using the *current* campaign's shorthand (from `listCampaigns`) and a valid subdomain. Never reuse another campaign's link.
-6. **Personalize** with `{{firstName}}`; **vary** tone/wording across automations; **re-share** useful info (pass link, hours, maps, reservation) in reminders; keep **empty lines** between blocks for readability.
+6. **Personalize** with the `firstName` variable; **vary** tone/wording across automations; **re-share** useful info (wallet link, hours, maps, reservation) in reminders; keep **empty lines** between blocks for readability.
 7. **Align offer expirations with open hours**: never expire an offer while the restaurant is closed.
 
+**Text variables.** A text action fills these in per guest when it sends. Write each one as its name wrapped in double curly braces (two opening braces, the name, two closing braces), exactly as spelled: `firstName`, `lastName`, `memberNumber`, `serialNumber`, `progress`, `passLink` (the guest's wallet link), `referralLink` (the campaign referral link), `googleMapsLink`, `membersProgramLink`, `visitCount`, `offer`. Any other name is sent to the guest as literal text.
+
 ---

package/{skills → plugin/skills}/feast/references/workflows/campaigns.md

@@ -52,7 +52,7 @@ Three tools, all keyed by the Feast campaign `id` from `listCampaigns` (a UUID),
 
 **Units.** `count`; `percent` as 0 to 100 (not 0 to 1); `usd` in dollars (not cents); `days`; `multiple` for ROAS (2 means 2x). In the breakdown: sessions, visitors, signups, impressions and reach are counts; every `*Rate`, `thumbStopRatio`, `holdRate` and `uniqueClickthrough` are percents; spend, cpm, revenue, costPerSignup and revenuePerSignup are USD; averageTimeToShow is days from signup to first scan.
 
-**Headline numbers: `getCampaignKpis`** with `{ "campaignId": "...", "start"?: ..., "end"?: ... }`. Pass both `start` and `end` for a date range; with either missing it covers all time. `"isPrimaryOnly": true` returns only the primary metrics. Returns one `{ id, type, value, unit }` row per metric, covering ad performance (spend, impressions, hook rate, hold rate, CTR, from synced Facebook data, so ROAS is revenue divided by spend), the funnel, automations and results. Rate metrics with a target band also carry `benchmark: { min, good, great }` in the same unit. A metric whose value would be zero is left out rather than returned as 0. So a missing spend row means no spend or no Facebook sync yet, never a confirmed $0.
+**Headline numbers: `getCampaignKpis`** with `{ "campaignId": "...", "start"?: ..., "end"?: ... }`. Send both `start` and `end` for a date range; with either missing it covers all time. `"isPrimaryOnly": true` returns only the primary metrics. Returns one `{ id, type, value, unit }` row per metric, covering ad performance (spend, impressions, hook rate, hold rate, CTR, from synced Facebook data, so ROAS is revenue divided by spend), the funnel, automations and results. Rate metrics with a target band also carry `benchmark: { min, good, great }` in the same unit. A metric whose value would be zero is left out rather than returned as 0. So a missing spend row means no spend or no Facebook sync yet, never a confirmed $0.
 
 **Grading: `getCampaignBenchmarks`** (no input) returns `{ id, label, unit, description, formula, benchmark }` for every metric id. Call it once and reuse it; it is the same for every campaign. Grade a value green at or above `good`, yellow at or above `min`, red below `min`; `great` is a stretch level (null for ROAS). `benchmark` is null when a metric has no target band. The bands are fleet percentiles (P25/P50/P75 of campaigns with over 500 visitors), rounded, not per organization; ROAS is anchored at 1x break-even.
 

package/{skills → plugin/skills}/feast/references/workflows/creators.md

@@ -69,7 +69,7 @@ The ads that bring applicants in are tool-drivable end to end:
    The same tool is how you reschedule and how you record what happened. `startTime` set to a date texts the creator a confirmation and alerts the approver; `null` clears the time and texts the creator asking for a new one. `startTime` is rejected while the row is `pending_approval` and in any call that passes `status: "approved"`, so approve first, then set the time in a second call (`status: "pending_approval"` clears the time itself; don't pass `startTime` with it). `status` also accepts `confirmed`, `visited`, `missed`, `issue` and `cancelled`; of these only `cancelled` texts the creator. `locationId` moves the visit to another location with a creator program and texts no one, so tell the creator yourself. `notes` sets staff notes shown on the scanner, never sent to the creator. Pass `sideEffects: false` to make any update silent (same field writes, but no creator text, no allowance spend, no post-approval automation), which is what you want when correcting a record after the fact rather than making the decision now.
 3. The creator books, visits, and submits content on their own; none of that is driven from here.
 4. `listCreatorSubmissions` with `{ "status": "submitted" }` (and `"revision_requested"`): the content review queue. Submissions are stored outside the queryable data model, so this tool is the only way to read them.
-5. `decideCreatorSubmission`: `approved`, `rejected`, `revision_requested`, or `under_review`. **Approving texts the creator too**, unless you pass `skipApprovalText: true` (use that only for silent record corrections). `revision_requested` always texts: it sends your `feedbackMessage` verbatim plus a resubmit link, so write it as something the creator will read, not an internal note. **Always pass `approvalType` explicitly when approving**, because an omitted one means `"ad"`: `"ad"` means the content may run in paid ads, stamps the board's bonus on the submission and marks it pending (paid later through `createInfluencerPayout`), and is rejected when the board's bonus is $0; `"organic"` is for content only on their own channels, and earns no payout. Re-approving an approved submission is rejected, except upgrading an `organic` approval to `ad`.
+5. `decideCreatorSubmission`: `approved`, `rejected`, `revision_requested`, or `under_review`. **Approving texts the creator too**, unless you send `skipApprovalText: true` (use that only for silent record corrections). `revision_requested` always texts: it sends your `feedbackMessage` verbatim plus a resubmit link, so write it as something the creator will read, not an internal note. **Always send `approvalType` explicitly when approving**, because an omitted one means `"ad"`: `"ad"` means the content may run in paid ads, stamps the board's bonus on the submission and marks it pending (paid later through `createInfluencerPayout`), and is rejected when the board's bonus is zero; `"organic"` is for content only on their own channels, and earns no payout. Re-approving an approved submission is rejected, except upgrading an `organic` approval to `ad`.
 
 ### Paying the bonus
 

package/{skills → plugin/skills}/feast/references/workflows/guests.md

@@ -26,7 +26,7 @@ The recipient is always named by id, never by phone number, and the type must ma
 
 - `describeData` with no arguments returns the index of every queryable object type plus the full query grammar; narrowed by schema or object type it returns full column detail (type, enum values, nullability, description, and the link names `pivot` and `join` take). Pass `includeGrammar: false` once you have the grammar. Never guess column names.
 - `queryData` is read-only and always scoped to the organization; never filter on organizationId yourself.
-- Writing a query: `commands` run in order (`filter`, `pivot`, `join`, `aggregate`), and `pivot` and `join` must come before any `aggregate`. A filter leaf is one column, written as the column name prefixed with `$`; combine leaves with `{ "type": "and" | "or", "filters": [...] }`. Use `{ "strings": [...] }` for any-of rather than a large `or`. Pass `args.fields` to return only the columns you need on wide object types, and page by passing the returned `nextCursor` back as `args.cursor` (no `nextCursor` means no more rows).
+- Writing a query: `commands` run in order (`filter`, `pivot`, `join`, `aggregate`), and `pivot` and `join` must come before any `aggregate`. A filter leaf is one column, written as the column name prefixed with `$`; combine leaves with `{ "type": "and" | "or", "filters": [...] }`. Use `{ "strings": [...] }` for any-of rather than a large `or`. Send `args.fields` to return only the columns you need on wide object types, and page by sending the returned `nextCursor` back as `args.cursor` (no `nextCursor` means no more rows).
 - Example, opted-in members with more than 5 visits, newest first:
   ```json
   { "schemaName": "core", "objectTypeName": "guest",

package/plugin/skills/feast/references/workflows/videos.md

@@ -0,0 +1,14 @@
+# Video ads (Bevyl)
+
+## Making a video
+
+One video is one `projectId`, from Generate to the finished MP4. The loop:
+
+1. **`getVideoPromptOptions({ campaignId })`**. `defaultPrompt` is what Content Studio would send: four plain-text sections (Campaign, Concept, Creative direction, CTA), each a heading line then its text. `campaign`, `concept`, `direction` and `cta` list the alternatives for each section (`{ id, label, text }`). Concepts carry the reference video they came from (`videoUrl`, `description`), and directions a `suggestedFormat`. Show the human the prompt you plan to send. Swap a section for another option's text or rewrite it as they ask.
+2. **`generateVideo`** with `campaignId`, `prompt` (sent to Bevyl verbatim, 5,000 characters at most) and `format` (`voiceover`, `talking-head`, `trending-sounds` with a `trendId`, or `no-audio`; the chosen direction's `suggestedFormat` is the default). Pass `angleId` from `listCampaignVideos` to add a version to an existing angle; otherwise a new angle is named from the Concept's first line, or from `angleTitle`. Footage is every clip already synced to Bevyl unless you pass `brollKeys` (S3 keys from `listMedia` scope `creativeLibraryBroll`). **This spends Bevyl credits: only with the human's explicit go-ahead.**
+3. **`getVideo({ projectId })`** about every 30 seconds. `pipeline.status` moves uploading, processing, creating, rendering, exporting, then `ready` (`exportUrl` is the MP4) or `failed` (`message` says why). A first video takes several minutes.
+4. Send the human `exportUrl` to watch. For one change, **`requestVideoEdit`** with only that change in `note` (credits again; `getVideo` goes back to rendering). When they approve it, **`approveVideo({ projectId })`** saves the MP4 to the campaign's creative library and returns its `libraryKey`.
+
+## Reference scripts
+
+`listReferenceScripts` returns the reference ad scripts Content Studio offers as Concept presets for Bevyl videos, each distilled from an ad that performed: `description` (what the video shows), `videoUrl` (a public MP4 preview), `structure` (the ordered beats), `keyPhrases` (lines to adapt, with `<placeholders>` filled from the campaign's facts) and `concept` (the exact text Content Studio sends to Bevyl). Copy the structure and pacing, not the words. The list is the same for every organization. Use one to explain a concept option or to write a concept of your own for `prompt`.