@feastalytics/cli 0.1.8 → 0.1.9

package/dist/cli.js

@@ -8955,7 +8955,7 @@ var CLI_MANIFEST = {
     {
       "id": "applyAutomationTemplate",
       "domain": "automations",
-      "description": "Applies an automation template and creates automations. Only use when the campaign or members program has no existing flows; otherwise use editFlow to modify.",
+      "description": "Applies an automation template and creates automations. Only use when the campaign or members program has no existing flows; otherwise edit the existing flows through the draft loop (createAutomationDraft + stageAutomationEdits) or batchEditAutomations.",
       "type": "mutation",
       "path": [
         "api",
@@ -10742,7 +10742,7 @@ var CLI_MANIFEST = {
     {
       "id": "cloneCampaign",
       "domain": "campaigns",
-      "description": "Clones an existing campaign including its funnel screens, automations, and offers. Requires sourceCampaignId, newCampaignName, and referrer (subdomain from organization.subdomains2).",
+      "description": "Clones an existing campaign including its funnel screens, automations, and offers. Requires sourceCampaignId, newCampaignName, and referrer (subdomain from organization.subdomains2). Cloned automations keep the source campaign's reservation links \u2014 after cloning, rewrite any reservation link in the new campaign's automations to the new campaign's shorthand.",
       "type": "mutation",
       "path": [
         "api",
@@ -10772,6 +10772,30 @@ var CLI_MANIFEST = {
         "$schema": "http://json-schema.org/draft-07/schema#"
       }
     },
+    {
+      "id": "countParentAutomationRecipients",
+      "domain": "automations",
+      "description": "How many distinct members already received an automation \u2014 the audience size a receiveAutomation-triggered child would reach if backfilled with applyToHistorical: true. Call this before any backfill, tell the user the number, and warn when it exceeds 1000; only backfill after they confirm. Read-only and safe to call while deciding.",
+      "type": "query",
+      "path": [
+        "api",
+        "automation",
+        "countParentAutomationRecipients"
+      ],
+      "inputJsonSchema": {
+        "type": "object",
+        "properties": {
+          "parentAutomationId": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "parentAutomationId"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
     {
       "id": "createAutomationDraft",
       "domain": "automations",
@@ -12905,7 +12929,7 @@ var CLI_MANIFEST = {
     {
       "id": "createCreativeStrategy",
       "domain": "creators",
-      "description": "Generate a creator strategy. An awareness strategy is built from a fixed template and is saved before this returns, with generationStatus complete and a null jobId. A CTA strategy is generated by an LLM in the background \u2014 this returns immediately with generationStatus generating, so poll getCreativeStrategy with the returned strategyId until it reads complete or failed before using the brief. The jobId and jobType that come back track the same run, but no tool exposes the job, so getCreativeStrategy is the only progress you can read. Edit the result with updateCreativeStrategy. Passing a strategyId that is not a draft is rejected rather than overwritten.",
+      "description": "Generate a creator strategy. An awareness strategy is built from a fixed template and is saved before this returns, with generationStatus complete and a null jobId. A CTA strategy is generated by an LLM in the background \u2014 this returns immediately with generationStatus generating, so poll getCreativeStrategy with the returned strategyId until it reads complete or failed before using the brief. The jobId and jobType that come back track the same run through getJob, but getCreativeStrategy is the simpler poll \u2014 reach for getJob only when the strategy reads failed and you want the job's errorMessage. Edit the result with updateCreativeStrategy. Passing a strategyId that is not a draft is rejected rather than overwritten.",
       "type": "mutation",
       "path": [
         "api",
@@ -12941,7 +12965,6 @@ var CLI_MANIFEST = {
                   }
                 },
                 "required": [
-                  "restaurantName",
                   "restaurantNeighborhood",
                   "differentiatorsText",
                   "mustTryItemsText"
@@ -13055,6 +13078,31 @@ var CLI_MANIFEST = {
         "$schema": "http://json-schema.org/draft-07/schema#"
       }
     },
+    {
+      "id": "createInfluencerPayout",
+      "domain": "creators",
+      "description": "Charges the organization's card to pay a creator's content bonus. NEVER call this on your own initiative or as part of an automated flow \u2014 every call needs the client's explicit, fresh approval to pay this specific creator, given to you directly; a standing instruction or an inferred intent does not count. The endpoint enforces its own preconditions and refuses otherwise: the visit must have a content submission approved as a paid ad (decideCreatorSubmission with approvalType 'ad' \u2014 organic approvals earn no payout), and no payout may already exist for the visit in any active status \u2014 one payout per visit, so a second call while one is pending, funding, onboarding, or paid is rejected. The bonus amount comes from the location's board config, grossed up so the org covers the Stripe fee. After the charge, Stripe webhooks carry it to the creator (FUNDED \u2192 onboarding if needed \u2192 PAID) with no further action from you; follow progress in queryData creators.creatorPayout.",
+      "type": "mutation",
+      "path": [
+        "api",
+        "stripe",
+        "createInfluencerPayout"
+      ],
+      "inputJsonSchema": {
+        "type": "object",
+        "properties": {
+          "eventId": {
+            "type": "string",
+            "description": "The creator visit's eventId (creatorVisitApplication.eventId) whose approved paid-ad submission is being paid out."
+          }
+        },
+        "required": [
+          "eventId"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
     {
       "id": "createMembersProgramReward",
       "domain": "membersProgram",
@@ -13264,7 +13312,7 @@ var CLI_MANIFEST = {
     {
       "id": "deleteFunnel",
       "domain": "campaigns",
-      "description": "Tears down a campaign's funnel: deletes the campaign-specific screens and resets the campaign override (clears initialScreenId, postSignupScreen, overrideByScreenId, and variants), returning the campaign to the choose-template state. Inverse of chooseFunnelTemplate.",
+      "description": "Tears down a campaign's funnel: deletes the campaign-specific screens and resets the campaign override (clears initialScreenId, postSignupScreen, overrideByScreenId, and variants), returning the campaign to the choose-template state. Inverse of applyFunnelTemplate.",
       "type": "mutation",
       "path": [
         "api",
@@ -13604,6 +13652,34 @@ var CLI_MANIFEST = {
         "$schema": "http://json-schema.org/draft-07/schema#"
       }
     },
+    {
+      "id": "getJob",
+      "domain": "core",
+      "description": "Poll one background job by id. Any tool that queues work returns a { jobId, jobType } pair \u2014 publishAds and the CTA path of createCreativeStrategy both do \u2014 and both values are required here, because a job id alone is not addressable. Returns { job: null } while the row hasn't landed yet, so treat null as in-flight and keep polling; status moves PENDING, RUNNING, then COMPLETED or FAILED with an errorMessage. A publish job's output reports each declared effect as done, skipped or error with a human-readable detail \u2014 including whether the program's approver was texted \u2014 and that outcome is reported nowhere else, so read it rather than assuming the effects ran. The job's input and per-step generated text are stripped by default; includeFullPayload returns both.",
+      "type": "query",
+      "path": [
+        "api",
+        "jobs",
+        "get"
+      ],
+      "inputJsonSchema": {
+        "type": "object",
+        "properties": {
+          "jobType": {},
+          "jobId": {
+            "type": "string"
+          },
+          "includeFullPayload": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "jobId"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
     {
       "id": "getMediaUploadUrl",
       "domain": "core",
@@ -13973,7 +14049,7 @@ var CLI_MANIFEST = {
     {
       "id": "listAutomationTemplates",
       "domain": "automations",
-      "description": "Lists available automation templates for retention (members program) or acquisition (campaign) systems. Use loadTemplateAutomations to preview before applying. Only apply templates when the campaign or members program has no existing flows.",
+      "description": "Lists available automation templates for retention (members program) or acquisition (campaign) systems. Use listTemplateAutomations to preview before applying. Only apply templates when the campaign or members program has no existing flows.",
       "type": "query",
       "path": [
         "api",
@@ -14013,7 +14089,7 @@ var CLI_MANIFEST = {
     {
       "id": "listCampaigns",
       "domain": "core",
-      "description": "List all campaigns",
+      "description": "The organization's acquisition campaigns, newest first. Start here to resolve a campaignId: the `id` field (a UUID) is what every other campaign tool takes, NOT the nested Meta campaign id. Also carries each campaign's name, shorthand (used in reservation links), publish state, and referrers. Read one campaign's full configuration with getCampaign.",
       "type": "query",
       "path": [
         "api",
@@ -14023,6 +14099,34 @@ var CLI_MANIFEST = {
       ],
       "inputJsonSchema": null
     },
+    {
+      "id": "listCreatives",
+      "domain": "creators",
+      "description": "The generated recruitment creatives for an organization, optionally narrowed to one offer. Each carries an imageKey resolving to the rendered variant that was picked, and selectedImageUrl for the same object as a URL \u2014 pass imageKey to planAds as a libraryAsset reference rather than choosing among the composite fields yourself. imageUrl is the base render and is not the ad asset. staleCreativeIds lists creatives generated from an older version of their offer, and is only populated when offerId is given.",
+      "type": "query",
+      "path": [
+        "api",
+        "dfy",
+        "listCreatives"
+      ],
+      "inputJsonSchema": {
+        "anyOf": [
+          {
+            "not": {}
+          },
+          {
+            "type": "object",
+            "properties": {
+              "offerId": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          }
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
     {
       "id": "listCreatorApplications",
       "domain": "creators",
@@ -14241,6 +14345,46 @@ var CLI_MANIFEST = {
         "$schema": "http://json-schema.org/draft-07/schema#"
       }
     },
+    {
+      "id": "markCreativesPublished",
+      "domain": "creators",
+      "description": "Record which Meta ad a recruitment creative was published in. The linkRecruitmentOffer effect on publishAds records this as part of the publish, so after an effect-declared publish there is nothing left to mark \u2014 call this only when ads were created outside publishAds or a publish's effect reported an error. Pass every creative that went into the ad \u2014 a dynamic ad rotates several at once, so they all take the same fbAdId. Without a record the creatives keep offering to be published again.",
+      "type": "mutation",
+      "path": [
+        "api",
+        "dfy",
+        "markCreativesPublished"
+      ],
+      "inputJsonSchema": {
+        "type": "object",
+        "properties": {
+          "creatives": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "creativeId": {
+                  "type": "string"
+                },
+                "fbAdId": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "creativeId",
+                "fbAdId"
+              ],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": [
+          "creatives"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      }
+    },
     {
       "id": "planAds",
       "domain": "ads",
@@ -14284,7 +14428,7 @@ var CLI_MANIFEST = {
     {
       "id": "populateCampaign",
       "domain": "campaigns",
-      "description": "Finalizes a campaign that was created with isCreating true. Optionally attaches a promotion/offer image to the campaign. Does NOT set up funnel screens \u2014 the user picks a funnel template from the funnel editor after finalization.",
+      "description": "Finalizes a campaign that was created with isCreating true. Optionally attaches a promotion/offer image to the campaign. Does NOT set up funnel screens \u2014 follow with applyFunnelTemplate, or the user picks a template in the funnel editor.",
       "type": "mutation",
       "path": [
         "api",
@@ -14380,7 +14524,7 @@ var CLI_MANIFEST = {
     {
       "id": "publishAds",
       "domain": "ads",
-      "description": "Publish a plan produced by planAds. Pass back the variables, overrides and planHash that planAds returned, unchanged. The server re-derives the tree and refuses to publish if it no longer matches the hash, so re-plan and show the human the difference if that happens. This returns as soon as the work is queued \u2014 poll jobs.get with the returned jobId and jobType to follow it. Everything is created paused; use setAdCampaignStatus to start it. Requires an explicit confirm.",
+      "description": "Publish a plan produced by planAds. Declare what should be recorded once the ads exist through effects, and the worker runs them as part of the job \u2014 a recruitment publish must pass linkRecruitmentOffer with its offerId and creativeIds, which stamps the creatives, stamps the offer that the monthly sourcing cap and the dashboard's spend both read, and texts the program's approver that sourcing is live; omitting it is refused rather than silently skipped. Doing it afterwards through a separate call is a step that can be missed, and missing it is silent. Pass back the variables, overrides and planHash that planAds returned, unchanged. The server re-derives the tree and refuses to publish if it no longer matches the hash, so re-plan and show the human the difference if that happens. This returns as soon as the work is queued \u2014 poll getJob with the returned jobId and jobType to follow it, and read the job's effect outcomes rather than assuming they ran. Everything is created paused; use setAdCampaignStatus to start it. Requires an explicit confirm.",
       "type": "mutation",
       "path": [
         "api",
@@ -14420,11 +14564,56 @@ var CLI_MANIFEST = {
             "type": "boolean",
             "const": true
           },
-          "campaignId": {
-            "type": [
-              "string",
-              "null"
-            ]
+          "effects": {
+            "type": "array",
+            "items": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "linkFeastCampaign"
+                    },
+                    "campaignId": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "campaignId"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "linkRecruitmentOffer"
+                    },
+                    "offerId": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "creativeIds": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "offerId",
+                    "creativeIds"
+                  ],
+                  "additionalProperties": false
+                }
+              ]
+            }
           },
           "reviewedPlan": {}
         },
@@ -20205,7 +20394,7 @@ Example - opted-in members with more than 5 visits, newest first:
     {
       "id": "updateAutomationFlow",
       "domain": "automations",
-      "description": "Update a flow's metadata (the group that holds automations). Pass flowId plus the new title (required), and optionally description and isCampaignCheckDisabled. Does not touch the automations inside the flow \u2014 use batchEditAutomations for those.",
+      "description": "Update a flow's metadata (the group that holds automations). Pass flowId plus the new title (required), and optionally description and isCampaignCheckDisabled. Does not touch the automations inside the flow \u2014 stage those through the draft loop, or batchEditAutomations for an immediate live write.",
       "type": "mutation",
       "path": [
         "api",

package/feast/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: feast
-description: Operate a Feastalytics organization from the terminal — list, create, and update campaigns, automations, offers, funnels, and members-program rewards — via the `feast` CLI. Use this skill whenever the user wants to inspect or change Feastalytics data outside the dashboard — "list my campaigns", "create an automation for org X", "what offers does this location have", "clone this campaign", "update the members program", or any request to script/batch/automate Feastalytics operations. Reach for it even when the user doesn't say "CLI" — if the task is reading or changing Feastalytics campaign/automation/offer/reward data, this is the tool.
+description: Operate a Feastalytics organization from the terminal — campaigns, automations, funnels, members-program rewards, the wallet pass, creator sourcing, Meta ads, onboarding, and read-only data queries — via the `feast` CLI. Use this skill whenever the user wants to inspect or change Feastalytics data outside the dashboard — "list my campaigns", "create an automation for org X", "approve this creator", "publish the recruitment ad", "query my guests", "update the members program", or any request to script/batch/automate Feastalytics operations. Reach for it even when the user doesn't say "CLI" — if the task is reading or changing Feastalytics data, this is the tool.
 ---
 
 # Feast CLI
 
-Drive the Feastalytics platform from the terminal. The `feast` CLI exposes the same tool surface the in-app AI agent uses (campaigns, automations, offers, funnels, members program) as plain commands that hit the production API as the logged-in user.
+Drive the Feastalytics platform from the terminal. The `feast` CLI exposes the same tool surface the in-app AI agent uses (campaigns, automations, funnels, members program, creator sourcing, Meta ads, onboarding, data queries) as plain commands that hit the production API as the logged-in user.
 
 The CLI is the source of truth for *which* tools exist and *what* they accept — always discover that at runtime rather than assuming, because the tool set grows as new endpoints are tagged. Your job is to pick the right tool, scope it to the right organization, and hand it valid input.
 
@@ -79,7 +79,7 @@ Query tools (listing, describing, reading) are safe and read-only. Mutation tool
 - Before running one, the CLI resolves the organization server-side and prints its name, so a wrong `--org` shows up as the wrong restaurant rather than an opaque id. Read that line.
 - **There is no confirmation prompt.** A mutation runs the moment you call it. Nothing asks twice, and nothing undoes it.
 
-That last point matters most for the tools that reach the real world rather than just the database. Buying a phone number bills the account. Approving a creator visit or deciding a submission sends that person a text immediately and cannot be recalled. Publishing a campaign puts it live, and pricing a recurring promotion creates real Stripe products. Saving automation edits changes what guests receive. Treat those as irreversible, and get the user's intent straight *before* the call, because there is no gate after it.
+That last point matters most for the tools that reach the real world rather than just the database. Buying a phone number bills the account. Approving a creator visit or deciding a submission sends that person a text immediately and cannot be recalled. Paying a creator's bonus charges the organization's card. Publishing a campaign puts it live, and pricing a recurring promotion creates real Stripe products. Activating a Meta campaign spends real ad budget. Saving automation edits changes what guests receive. Treat those as irreversible, and get the user's intent straight *before* the call, because there is no gate after it. (The one schema-level exception: `publishAds` requires `confirm: true` in its input — but that's you confirming, not the CLI asking.)
 
 Prefer reading before writing: e.g. `listCampaigns` to find the right `campaignId` before `updateCampaign`, or `describe`/`listAutomationFlows` before creating a flow.
 
@@ -97,18 +97,19 @@ Many tasks are multi-step and have a required ordering the app normally enforces
 
 | Doing this | Read |
 |---|---|
-| Creating, cloning or configuring a campaign; offers in the strategy backlog | `references/workflows/campaigns.md` |
+| Creating, cloning or configuring a campaign; promotions | `references/workflows/campaigns.md` |
 | Anything touching automations — creating, editing, simulating, promoting a draft | `references/workflows/automations.md` |
 | Editing funnel screens, applying a funnel template, staging a new screen | `references/workflows/funnels.md` |
 | Writing Meta ad copy — guest-facing or creator recruitment | `references/workflows/facebook.md` |
-| Creator sourcing — approving applicants, reviewing their content, conversations | `references/workflows/creators.md` |
+| Publishing, pausing, budgeting or diagnosing Meta ads | `references/workflows/ads.md` |
+| Creator sourcing — approving applicants, reviewing content, creatives, payouts | `references/workflows/creators.md` |
 | Members-program rewards; reading or saving the wallet pass configuration | `references/workflows/members-program.md` |
-| Working the onboarding taskboard; brand identity | `references/workflows/onboarding.md` |
-| Searching guests/members and their activity | `references/workflows/guests.md` |
+| Working the onboarding taskboard; brand identity; phone, media, invites, billing | `references/workflows/onboarding.md` |
+| Searching guests/members; querying anything via the data catalog | `references/workflows/guests.md` |
 
-Read more than one when a task spans them — a new campaign usually means `campaigns.md` plus `automations.md` and `funnels.md`.
+Read more than one when a task spans them — a new campaign usually means `campaigns.md` plus `automations.md` and `funnels.md`, and publishing a recruitment ad means `creators.md` plus `facebook.md` and `ads.md`.
 
-Some things are deliberately **not exposed**: replying to a guest or a creator by SMS, firing an automation at a live member, reward update/delete, pass image generation, and most of the creator pipeline beyond the two approval decisions. The workflow files say which. Don't fabricate a call for a workflow whose tools aren't listed by `feast tools` — tell the user that part isn't available yet.
+Some things are deliberately **not exposed**: replying to a guest or a creator by SMS, firing an automation at a live member, pass image generation, ad-copy generation (write it yourself), and publishing creator content as partnership ads. The workflow files say which. Don't fabricate a call for a workflow whose tools aren't listed by `feast tools` — tell the user that part isn't available yet.
 
 ## Link to what you touched
 
@@ -120,13 +121,13 @@ That file has the dashboard routes with their panel and tab names, the guest-fac
 
 ## Worked example
 
-User: "add a $5-off offer to the Plum location in my Plum Vietnamese org."
+User: "add a Free Dessert reward members can redeem for 100 points in my Plum Vietnamese org."
 
 ```bash
-feast whoami                                    # find the Plum Vietnamese org id
-feast describe dfyCreateOffer                    # learn the offer input shape
-feast call dfyGetMenuHierarchy --org <orgId> --input '{"locationId":"<id>"}'   # find the location/menu ids
-feast call dfyCreateOffer --org <orgId> --input '{ ... }'                       # create it (confirms first)
+feast whoami                                     # find the Plum Vietnamese org id
+feast describe createMembersProgramReward        # learn the input shape (type: item vs name)
+feast call listMembersProgramRewards --org <orgId>   # avoid duplicating an existing reward or catalog item
+feast call createMembersProgramReward --org <orgId> --input '{"type":"name","name":"Free Dessert","pointsCost":100}'
 ```
 
 The pattern generalizes: identify the org, learn the tool, resolve any referenced ids, then act.

package/feast/references/domains.md

@@ -23,13 +23,25 @@ Typical flow: `createCampaign` (set `isCreating: true` if you'll finish it with
 - **Authoring:** `createAutomationFlow` makes a flow; `batchEditAutomations` creates/updates/deletes automations in one atomic batch (create ops **require** a `flowId`); `updateAutomationFlow` / `deleteAutomationFlow` manage the flow itself; `simulateAutomations` dry-runs a flow with no real sends. See `workflows/automations.md` for the ordering and the trigger/condition/send-time rules.
 - Templates: `listAutomationTemplates` → `listTemplateAutomations` (preview) → `applyAutomationTemplate`. Only apply a template to a campaign/members-program that has no existing flows.
 
-## Offers (DFY strategy)
+## Offers and promotions
 
-Offers live in the organization's strategy backlog. `dfyCreateOffer` needs a `framework` — one of `free`, `combo`, or `experience` — a name, headline, description, and `items` (`[{ name, price }]`). `offerPrice` is null for the `free` framework. Browse the menu to source real item names/prices with `dfyGetMenuHierarchy` (needs a `locationId`). `dfyListOffers` shows the current backlog with status and priority.
+Promotions live on the campaign record (`getCampaign` / `updateCampaign`), and real menu items come from `queryData` on `interface.catalogItem`.
 
 ## Members program (retention)
 
-The retention counterpart to campaigns: rewards and pass configuration for returning guests. Members-program automations are the flows with no `campaignId` (`scope: "membersProgram"` above).
+The retention counterpart to campaigns: rewards and pass configuration for returning guests. Members-program automations are the flows with no `campaignId` (`scope: "membersProgram"` above). Rewards are fully manageable (`listMembersProgramRewards` / `createMembersProgramReward` / `updateMembersProgramReward` / `deleteMembersProgramReward`), and the wallet pass is a read-modify-write document (`getPassConfiguration` / `updatePassConfiguration`) — see `workflows/members-program.md`.
+
+## Creator sourcing
+
+Restaurants recruit local content creators to visit and post. One config per location (`getInfluencerBoardConfig`), an approval queue of applications, content review, and bonus payouts — see `workflows/creators.md`. Recruitment *ads* publish through the Meta ads surface (`workflows/ads.md`).
+
+## Meta ads
+
+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`.
+
+## 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/feast/references/workflows/ads.md

@@ -0,0 +1,50 @@
+# Publishing and steering Meta ads
+
+> Part of the Feastalytics CLI workflows. Confirm a tool exists with `feast tools` before relying on it, and get its exact fields from `feast describe <tool>` — this file gives the *meaning* and *ordering* the schema can't.
+
+Publishing is CLI-drivable end to end: resolve a template, plan, publish, activate. The planner is the only door in — **never hand-assemble Meta campaign parameters**; `publishAds` re-derives everything from the template variables and refuses anything else.
+
+For the *words* in the ads, read `facebook.md` first — copywriting is its own discipline with its own failure modes.
+
+### The model: template → plan → publish → activate
+
+- A **template** is a server-owned recipe. `listAdTemplates` returns each one with its variables, budget range, and which plan paths may be overridden. Each variable that names a `producedBy` tool is telling you exactly where its value comes from — treat that as the shopping list.
+- **`planAds`** resolves template + variables into the exact tree of campaigns, ad sets and ads that would be created. It creates nothing on Meta and changes no Feastalytics data. It returns the tree, a `planHash`, the fully defaulted variables, and validation issues.
+- **`publishAds`** takes those variables, overrides and hash back *unchanged*, re-derives the tree server-side, and refuses on a mismatch — so a stale plan fails loudly instead of publishing something the human never saw. Everything is created **paused**.
+- **`setAdCampaignStatus`** `ACTIVE` starts a campaign Feastalytics published, cascading to every ad set and ad. This is the moment real money starts moving — explicit user confirmation first, every time.
+
+### The loop
+
+1. `listAdTemplates` — pick the template, read each variable's `producedBy`.
+2. Gather variables with those tools: `ads_get_ad_accounts`, `ads_get_user_pages`, `ads_get_ig_accounts`, `listCreatives`, `getCampaign`, etc. Prefer a Page with `usedByOrganization: true` — the token reaches other businesses' Pages and nothing stops you publishing from the wrong one.
+3. `planAds` — fix every issue with severity `error` and re-plan. Summarize the resulting tree (campaign name, budget, targeting, ad count) for the user before going further; the plan is the thing they're approving.
+4. `publishAds` with the returned `variables`, `overrides` and `planHash` unchanged, plus:
+   - `confirm: true` — the schema demands it; this is the only tool with a schema-level confirm.
+   - an `idempotencyKey` you generate. Reuse the same key when retrying the *same* publish — a duplicate key returns the earlier job instead of publishing twice. Never reuse one for a new publish.
+   - `effects` — see below.
+5. Poll `getJob` with the returned `jobId` + `jobType` until `COMPLETED` or `FAILED`. `{ job: null }` means not landed yet — keep polling. **Read the job's effect outcomes** — each declared effect reports `done`, `skipped` or `error` with a human-readable detail, and effect failures do not fail the job (the ads already exist by then), so this is the only place you find out.
+6. `setAdCampaignStatus` to go live, after the user says go. Check the preflight counts in the response.
+
+### Effects: the write-back is declared, not called afterwards
+
+Bookkeeping that must happen once the ads exist travels *inside* the publish as `effects`, and the worker runs it as part of the job — because a follow-up call you're supposed to remember is a follow-up call that gets missed, silently.
+
+- **A recruitment publish must declare `linkRecruitmentOffer`** with its `offerId` and `creativeIds` — the server refuses the publish without it. The effect stamps the creatives as published (no separate `markCreativesPublished` call needed), stamps the offer that the monthly sourcing cap and the dashboard's spend both read, and texts the program's approver that sourcing is live.
+- **`linkFeastCampaign`** records the published Meta campaign onto a Feast campaign, which is what makes its ads panel and KPIs see the spend.
+
+`markCreativesPublished` is the fallback for ads created outside `publishAds`, or for repairing a publish whose effect reported `error`.
+
+### Which template
+
+- **`directOffer`** — guest-facing offer ads for a campaign. Copy rules: the `adCopy` half of `facebook.md`.
+- **`recruitment`** — creator-recruitment ads. An always-on trickle with an enforced budget floor and ceiling. Creatives come from `createRecruitmentCreatives` → `listCreatives` (pass each creative's `imageKey` as a `libraryAsset` reference); copy rules: the `recruitmentAdCopy` half of `facebook.md`; program context: `creators.md`.
+- **`addAds`** — add fresh creatives to an ad set that is already running. Copy the settings the new ads must match from an existing ad via `ads_get_ad_entities` — its description carries the exact field-by-field recipe, and Meta will happily publish a mismatched ad rather than reject it.
+
+### Reading and steering what's live
+
+- `ads_get_ad_entities` — read campaigns/ad sets/ads on an account, creatives attached. The diagnostic read for everything below.
+- `ads_update_entity` — rename, re-budget, or pause. Budgets are integer cents and **replace** the current value; read first, confirm the number with the human. Creatives are immutable at Meta — new copy or media means a new ad (the `addAds` template).
+- `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.
+- `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.
+
+> **Not exposed:** ad-copy generation (write it yourself — `facebook.md`), creative *content* editing on Meta (immutable there), and publishing creator content as partnership ads.

package/feast/references/workflows/automations.md

@@ -2,7 +2,7 @@
 
 > Part of the Feastalytics CLI workflows. Confirm a tool exists with `feast tools` before relying on it, and get its exact fields from `feast describe <tool>` — this file gives the *meaning* and *ordering* the schema can't.
 
-**Now fully authorable from the CLI** (create / edit / delete / dry-run). This is the richest workflow — the ordering is simpler than the app's, but the domain rules below are what separate a professional flow from a carrier-blocked mess. Follow them when creating, and use them as a checklist when reviewing.
+**Fully authorable** (create / edit / delete / dry-run). This is the richest workflow — the ordering is simpler than the app's, but the domain rules below are what separate a professional flow from a carrier-blocked mess. Follow them when creating, and use them as a checklist when reviewing.
 
 ### The model: automations live inside flows
 

package/feast/references/workflows/campaigns.md

@@ -26,21 +26,10 @@ The one-shot text→campaign endpoints (`createWithOffer` / `parseCampaignDescri
 
 ---
 
-## Creating offers (strategy backlog)
+## Offers and promotions
 
-Fully doable from the CLI. Offers live in the organization's strategy backlog (the offer queue), sourced from real menu data.
-
-1. `getOrganization` → get the **`locationId`** (from `locations`) — offer tools key on the location, **never** the organizationId.
-2. `dfyGetMenuHierarchy` with that `locationId` — browse real menu items and prices.
-3. `dfyListOffers` — see the current backlog; avoid duplicates.
-4. `dfyCreateOffer` — create it. `dfyUpdateOffer` / `dfyDeleteOffer` to revise.
-
-Every offer picks one **framework**:
-
-- **`free`** — give away a low-cost item (appetizer, side, drink, small dessert) with no purchase. Maximizes signups. `offerPrice: null`; `items` = the single free item at its menu price. Headline: "A Complimentary [Item]" / "Free [Item]".
-- **`combo`** — bundle to lift the ticket. *Pattern A* "Buy X, Get Y Free" (`offerPrice` = purchased item only) — best for quick-service. *Pattern B* fixed-price bundle "[Item] & [Item] for $XX" (`offerPrice` = bundle price) — preserves brand equity for upscale.
-- **`experience`** — a curated multi-item tasting/pairing/prix-fixe with **no discount** (`offerPrice` = sum of item prices). MUST have 2+ items.
-
-`dfyCreateOffer` needs `name` (internal label, no restaurant name), `headline` (states what the guest gets + price, using real item names), a short `description` (context the headline can't carry), `framework`, `items` (`[{name, price}]` from the menu), `offerPrice`, and `locationId`. Always frame as "offers," never "discounts" or "deals."
+- A campaign's **promotions** are part of the campaign record: read them with `getCampaign`, edit them with `updateCampaign` (including a promotion's `staffInstructions`, and prices — noting the Stripe-products warning in `updateCampaign`'s description).
+- **Real menu data** for grounding any offer or promotion copy comes from `queryData` on `interface.catalogItem` — POS-agnostic, hierarchical via `parentId`/`catalogItemLink`.
+- When you write guest-facing offer language anywhere, frame it as an "offer," never a "discount" or "deal."
 
 ---

package/feast/references/workflows/creators.md

@@ -50,6 +50,17 @@ A window's `block` is one of two shapes: `once`, with a `utcStart` and `utcEnd`;
 
 `updateCreativeStrategy` is the revision step. Two things to get right: omitting `strategyId` **creates a new strategy** instead of editing the one you meant, and it replaces the fields you send rather than merging them — so read first, apply your edits to the full `concepts` array, and send the whole thing back. Generating into a strategy that isn't still a draft is rejected rather than silently overwritten.
 
+### Recruitment creatives and the recruitment ad
+
+The ads that bring applicants in are CLI-drivable end to end:
+
+1. `createRecruitmentCreatives` with the `campaignId` — it resolves (or creates) the campaign's recruitment offer itself, which is what groups the creatives and carries the monthly sourcing cap. Each run calls an image model per missing type; `force` deletes and regenerates the whole set, so don't pass it casually.
+2. `listCreatives` — each creative's `imageKey` is the reference `planAds` takes as a `libraryAsset`; `staleCreativeIds` flags creatives generated from an older version of their offer.
+3. Publish through the `recruitment` template in `ads.md`, declaring the **`linkRecruitmentOffer` effect** — the publish is refused without it. The effect stamps the creatives, links the offer (which the sourcing cap and dashboard spend read), and texts the program's approver that sourcing is live.
+4. Copy rules for the ad live in `facebook.md` (`recruitmentAdCopy` — the creator-facing half; conflating it with guest copy is the classic failure).
+
+`markCreativesPublished` is only the fallback for recording ads created outside `publishAds` or repairing an effect that reported `error`.
+
 ### The decision loop
 
 1. `listCreatorApplications` — the approval queue, newest first, across every location. Takes no arguments. Use this rather than querying the data model: it carries **`instagramFollowerCount`**, which is usually the deciding factor and isn't reachable any other way.
@@ -60,6 +71,10 @@ A window's `block` is one of two shapes: `once`, with a `utcStart` and `utcEnd`;
 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`. **This texts the creator too.** `revision_requested` sends your `feedbackMessage` verbatim plus a resubmit link, so write it as something the creator will read, not an internal note. Approving queues their bonus payout. `approvalType` defaults to `"ad"` (the content may run in paid ads) and is rejected when the board's bonus is $0 — use `"organic"` when it's just for their own channels.
 
+### Paying the bonus
+
+`createInfluencerPayout` charges the organization's card and starts the creator's bonus on its way. **Never call it on your own initiative** — every call needs the client's explicit, fresh approval to pay this specific creator; a standing instruction doesn't count. The endpoint enforces its own preconditions (an ad-approved submission, no payout already active for the visit — one per visit), the amount comes from the board config grossed up to cover the Stripe fee, and after the charge Stripe webhooks carry it to the creator with no further action from you. Follow progress in `queryData` `creators.creatorPayout`, joined to the visit on `visitEventId`.
+
 ### Conversations
 
 `listCreatorConversations` is the "who is waiting on a reply" queue: every creator's SMS thread with `hasUnread`, the last message body and direction, and a derived `visitStatus` chip that's more reliable than reading raw columns.
@@ -68,8 +83,8 @@ A window's `block` is one of two shapes: `once`, with a `utcStart` and `utcEnd`;
 
 ### Everything else: queryData
 
-The `creators` schema exposes `creator` (the person, one row shared across all their applications) and `creatorVisitApplication` (one application/visit). Join on `creator.influencerId = creatorVisitApplication.userId`. Use it for anything the tools above don't answer — no-shows, per-location counts, repeat creators. Content submissions and payouts are **not** in the catalog.
+The `creators` schema exposes `creator` (the person, one row shared across all their applications), `creatorVisitApplication` (one application/visit), and `creatorPayout` (one initiated bonus payout, joined to the visit on `visitEventId`). Join person to visit on `creator.influencerId = creatorVisitApplication.userId`. Use it for anything the tools above don't answer — no-shows, per-location counts, repeat creators, payout history. Content submissions are **not** in the catalog; `listCreatorSubmissions` is the only read.
 
-> **Not exposed:** launching the program, launching recruitment ads, scheduling or cancelling a visit, marking a visit attended, paying a bonus, and publishing creator content to Facebook. Those stay in the app — so you can configure a program, set its booking windows and write its brief from here, but a human still has to launch it.
+> **Not exposed:** replying to a creator's texts or marking a conversation read (the dashboard owns creator messaging), the dashboard's launch-program button itself (its bookkeeping rides the recruitment publish effect — see above), and publishing a creator's submitted content as a partnership ad.
 
 ---

package/feast/references/workflows/facebook.md

@@ -2,7 +2,7 @@
 
 > Part of the Feastalytics CLI workflows. Confirm a tool exists with `feast tools` before relying on it, and get its exact fields from `feast describe <tool>` — this file gives the *meaning* and *ordering* the schema can't.
 
-Two jobs live under Meta ads: **writing the ad copy** and **publishing the ad**. Only the first is CLI work today.
+Two jobs live under Meta ads: **writing the ad copy** and **publishing the ad**. This file is the copywriting half; the publish loop (templates, planning, effects, activation) lives in `ads.md`.
 
 **You write the copy yourself.** The dashboard has a "generate copy" button behind an LLM call; there is no CLI equivalent and you shouldn't want one, because it would be you calling an HTTP endpoint in order to call a model. The copy lands on a plain field of the campaign record, so saving it is trivial and covered at the bottom of this file. Everything between here and there is the part that's actually hard.
 
@@ -34,7 +34,7 @@ Generic copy is the failure mode, and specifics are the entire job. The differen
 1. `getOrganization` — brand name, cuisine, and the subdomains in `subdomains2[].subdomain`.
 2. `getCampaign` — `name`, `description`, `bannerConfig`, `promotions`, `referrers`, `shorthand`.
 3. `listFunnelScreens` `{ "referrer": "<subdomain>", "campaignId": "<id>" }` — **the actual landing-page copy the guest sees after the click.** This is your source of truth for congruence: the trip from ad to landing page should feel like one continuous thing, not a bait-and-switch. Copy that promises something the landing page doesn't deliver burns the click.
-4. `dfyListOffers` / `dfyGetMenuHierarchy` — real item names and real prices, not approximations of them.
+4. `queryData` on `interface.catalogItem` — real menu item names and real prices, not approximations of them. It's hierarchical; walk the tree with `parentId` or `catalogItemLink`.
 
 The landing page URL is `https://{referrer}.feastalytics.com/campaign/{campaignId}`, using a referrer from the campaign's own `referrers` rather than just the org's first subdomain.
 
@@ -185,7 +185,7 @@ That's a customer offer wearing a creator ad's clothes. Every one of "free meal"
 
 `foodCreditCents`, `creatorPayoutCents` and `minFollowerCount` on `recruitmentAdCopy` record the terms your copy actually stated. The dashboard compares them against the live creator board config and flags the copy as drifted when they diverge — so if you write "$30 tab" and leave them unset, nobody finds out when the credit later changes to $50 and the ad starts lying.
 
-**You can't read the creator board config from the CLI.** Ask the user for the dining credit, the bonus and the follower minimum, write those exact numbers into the copy, and mirror them into these fields (in **cents** for the two money fields). Don't guess them.
+**Read the creator board config with `getInfluencerBoardConfig` first** — the dining credit, the bonus and the follower minimum live there and nowhere else. Write those exact numbers into the copy, and mirror them into these fields (in **cents** for the two money fields). Don't guess them, and don't ask the user for numbers the config already has.
 
 The creator landing page is `/creator-landing` on the org's subdomain with `orgId`, `locId`, `campaignId` and UTM params — fiddly enough that you should reuse the existing `recruitmentAdCopy.landingPageUrl` when the campaign already has copy, rather than reconstructing it.
 
@@ -199,10 +199,10 @@ One `updateCampaign` call writes `adCopy` or `recruitmentAdCopy`. Run `feast des
 
 ## Publishing
 
-**Not yet possible from the CLI.** Creating the ad in Meta — ad account, page, budget, targeting, creative — stays in the dashboard for now. Write the copy, then hand the user the campaign's `ads` panel (or `creative-strategy` for recruitment) to publish it.
+**CLI-drivable — read `ads.md`.** The loop is `listAdTemplates` → gather variables → `planAds` → `publishAds` (with its effects) → `getJob` → `setAdCampaignStatus`, and that file carries the ordering, the idempotency-key discipline, and the effect declarations that make the publish self-bookkeeping.
 
 ---
 
-> **Not exposed:** ad copy generation (write it yourself, per above), marking copy as pushed to Meta, and everything to do with creating, editing or pausing a live Meta ad. Read `references/links.md` before writing the dashboard link you hand over.
+> **Not exposed:** ad copy generation (write it yourself, per above). Read `references/links.md` before writing any dashboard link you hand over.
 
 ---

package/feast/references/workflows/funnels.md

@@ -4,7 +4,7 @@
 
 **Applying a funnel template** expands a whole screen tree server-side in one call: `applyFunnelTemplate` (needs the campaign's funnel unset — a fresh campaign — and resolves the referrer from the campaign). `deleteFunnel` tears one down.
 
-**Editing individual funnel screens is now CLI-drivable** through a **draft → preview → promote** loop. You never apply edits locally: you stage them on an off-prod draft, preview the result at a stable URL, then save. Tools: `listFunnelScreens`, `createFunnelDraft`, `stageFunnelEdit`, `stageFunnelScreen`, `getFunnelDraft`, `listFunnelDrafts`, `discardFunnelDraft`, `saveFunnelEdits`.
+**Individual funnel screens are edited** through a **draft → preview → promote** loop. You never apply edits locally: you stage them on an off-prod draft, preview the result at a stable URL, then save. Tools: `listFunnelScreens`, `createFunnelDraft`, `stageFunnelEdit`, `stageFunnelScreen`, `getFunnelDraft`, `listFunnelDrafts`, `discardFunnelDraft`, `saveFunnelEdits`.
 
 ### The loop
 
@@ -15,8 +15,11 @@
    - `{ "type": "create", "renderable": { "id": "<new-uuid>", ... }, "targetId": "<sibling id>", "position": "before" | "after" | "inside" }` — generate a fresh UUID.
    - `{ "type": "delete", "id": "<renderableId>" }` and `{ "type": "move", "id": "...", "targetId": "...", "position": "..." }`.
    **Need a brand-new screen?** `stageFunnelScreen` `{ "draftId": "...", "title": "...", "description"? }` stages an empty screen on the draft and returns its **permanent `screenId`** — the id is assigned at staging time, not at save, so you can immediately `stageFunnelEdit` content into it and reference it from navigation/buttons on other screens; nothing gets re-keyed at promote. On a campaign draft the screen is campaign-scoped unless you pass `"campaignScoped": false`. The screen only exists on the draft (and in draft-scoped `listFunnelScreens`/previews) until `saveFunnelEdits` promotes it, which reports it in `createdScreenIds`.
-4. **Preview** (no CLI call): open `https://{referrer}.feastalytics.com/preview/{draftId}/{campaignId}` (drop `/{campaignId}` for a members-program draft). It renders the whole funnel as a flow diagram with the draft's edits applied. Screenshot it, then iterate — re-run `listFunnelScreens` **with the `draftId`** to read the funnel *with* the staged edits, stage more, re-preview — until it's right.
-5. **`saveFunnelEdits`** `{ "draftId": "..." }` — **promotes to prod** (mutation, confirms first): applies the draft's edits to the live funnel and marks the draft `promoted`. To abandon instead, `discardFunnelDraft`.
+4. **Preview** — two ways, use whichever fits how you can look at things:
+   - `previewFunnelDraft` renders every screen to a **PDF** (one screen per page, mobile viewport) and returns a short-lived download URL — the option that works when you can read files but not browse.
+   - The live preview page `https://{referrer}.feastalytics.com/preview/{draftId}/{campaignId}` (drop `/{campaignId}` for a members-program draft) renders the funnel as a flow diagram with the edits applied — the link to hand the user.
+   Iterate: re-run `listFunnelScreens` **with the `draftId`** to read the funnel *with* the staged edits, stage more, re-preview — until it's right.
+5. **`saveFunnelEdits`** `{ "draftId": "..." }` — **promotes to prod, with no confirmation prompt**: applies the draft's edits to the live funnel and marks the draft `promoted`. To abandon instead, `discardFunnelDraft`.
 
 `saveFunnelEdits` can also take an inline `{ "referrer", "campaignId", "edits": [ { "screenId", "edit" } ] }` array instead of a `draftId` — a one-shot save with no persisted draft (you lose the preview step, so prefer the draft loop when the change is visual).
 

package/feast/references/workflows/guests.md

@@ -2,9 +2,19 @@
 
 > Part of the Feastalytics CLI workflows. Confirm a tool exists with `feast tools` before relying on it, and get its exact fields from `feast describe <tool>` — this file gives the *meaning* and *ordering* the schema can't.
 
-**Reading is now available** via `searchUsers`. It returns a page of recent member activity — one event per member, each carrying the member's `serialNumber` plus the event (type, time, related object).
+`searchUsers` returns a page of recent member activity — one event per member, each carrying the member's `serialNumber` plus the event (type, time, related object).
 
 - Filter with `query` (free-text name), `eventTypes` (e.g. `sentText`, `receivedText`, `scan`, `order`, `rewardAwarded`, `rewardRedeemed`, `checkout`, the `*Attribution` types), `progressMinBound`/`progressMaxBound` (visit-count range), `isUnread: true` (members with unanswered inbound texts), `orderBy` (ASC|DESC by event time).
 - Paginate with `limit` (default 100) and `cursor` (pass back the `cursor` from the previous call; an undefined cursor means no more pages).
 
 **Replying by SMS is NOT exposed, deliberately.** The send primitive enforces opt-out, quiet-hours, dedup, and rate limits *downstream* (not at the endpoint), and opt-in is currently gated only by a UI control. If a reply capability is ever exposed, it must run with confirmation and must not bypass those guardrails. For now, tell the user that replying to guests is done in the app.
+
+## Everything else: the data catalog
+
+`searchUsers` answers "recent activity, one event per member." Every other read question about guests — and about orders, menu items, texts, reservations, creator visits, payouts — goes through **`describeData` → `queryData`**:
+
+- `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. Never guess column names.
+- `queryData` is read-only and always scoped to the calling organization — never filter on organizationId yourself.
+- Six schemas: `interface` (POS-agnostic orders, order items, menu `catalogItem`s, `location`s, reservations — same shape whichever POS the org runs), `core` (guests/members), `events` (user events), `texting` (SMS logs), `creators` (visits and payouts), `attribution` (campaign attribution). Prefer `interface` for anything POS-shaped.
+
+Typical uses: visit counts and cohorts, order history for one guest, menu items with real prices for grounding copy, text delivery history, creator payout status.

package/feast/references/workflows/members-program.md

@@ -8,18 +8,19 @@
 The retention counterpart to campaigns — flows with no `campaignId`.
 
 - **Automations are authorable** (see the automations workflow): use `listAutomationFlows` with `{ "scope": "membersProgram" }`, then the same create/edit loop. Remember the members-program 30-day `awardReward` default.
-- **Rewards are now readable and creatable.** `listMembersProgramRewards` returns every reward with its catalog `name`, `staffInstructions`, and `pointsCost` (fields are `null` when unset). `createMembersProgramReward` takes `{ "name", "staffInstructions"?, "pointsCost"? }` and does the catalog-item dance for you: an existing catalog item with that exact name is reused (updating its `staffInstructions` if you passed any), otherwise one is created, then the reward row is linked to it.
-- **The `pointsCost` fork matters.** A reward with `pointsCost` set is redeemed *by the member with points* and is never auto-awarded. Omit `pointsCost` for automation-awarded rewards — and then actually pair the reward with an `awardReward` automation (see the automations workflow), or it will never reach anyone. `listMembersProgramRewards` deliberately has no `hasAutomation` flag: cross-reference `listAutomations` for `awardReward` actions carrying the reward's `itemId` to find orphans.
-- Reward **update/delete are not exposed** yet — those still need the app.
+- **Rewards are fully manageable.** `listMembersProgramRewards` returns every reward with its catalog item's `name`, `staffInstructions`, `pointsCost` and `source` — the item is resolved across the Feast, Toast, Square and Clover catalogs, and a `null` name means it no longer exists in any of them.
+- **Creating takes one of two shapes.** `{ "type": "item", "itemId" }` promotes an existing catalog item — prefer it whenever the item already exists in the POS. `{ "type": "name", "name" }` looks the name up across all four catalogs and creates a new Feast item only if nothing matches; **the match is exact, so a near-miss silently duplicates a menu item the restaurant already has** — check `listMembersProgramRewards` or the catalog first. A name shared by several items returns a CONFLICT listing candidates so you can pass `itemId` instead. `staffInstructions` only exist on Feast items and are rejected for POS-sourced ones.
+- **The `pointsCost` fork matters.** A reward with `pointsCost` set is redeemed *by the member with points* and is never auto-awarded. Omit `pointsCost` for automation-awarded rewards — and then actually pair the reward with an `awardReward` automation (see the automations workflow), or it will never reach anyone. To find orphans, cross-reference `listAutomations` for `awardReward` actions carrying the reward's `itemId`.
+- `updateMembersProgramReward` corrects a reward in place — `pointsCost: null` converts a points reward into an automation-granted one. `deleteMembersProgramReward` is the orphan cleanup; it leaves the catalog item alone (it may be a real menu item) and doesn't claw back anything already redeemed.
 
 ---
 
 ## Wallet pass configuration
 
-The pass (the wallet membership card) is now CLI-readable and -writable as a whole document.
+The pass (the wallet membership card) is read and written as a whole document.
 
 - **`getPassConfiguration`** `{}` — returns the latest live configuration: `sections`, `features`, `locations`, `metadata`, and its `version`.
-- **`updatePassConfiguration`** — **a full-document save, not a patch.** Anything you omit is dropped from the new version. The only safe workflow is read → modify the returned document → save the complete result. Saving appends a new version (history is preserved server-side), and a visible change triggers a re-push of the pass to every member's wallet — so this confirms before running and deserves the same care as a live send.
+- **`updatePassConfiguration`** — **a full-document save, not a patch.** Anything you omit is dropped from the new version. The only safe workflow is read → modify the returned document → save the complete result. Saving appends a new version (history is preserved server-side), and a visible change triggers a re-push of the pass to every member's wallet — there is no confirmation prompt, so treat it with the same care as a live send.
 - Pass **image generation** (punch-card strips etc.) is not exposed — image workflows still need the app.
 
 ---

package/feast/references/workflows/onboarding.md

@@ -8,12 +8,27 @@
 `getTaskboard` is the single "what needs fixing or finishing" surface: one `entries` list discriminated by `kind`. `task` entries are the org's onboarding tasks; `issue` entries are live-computed misconfigurations with a `fixHint`. Scope with `{"scope":{"type":"onboarding"}}` for tasks only, `{"type":"task","task":{"taskId":"..."}}` for one task, or leave the default `all`.
 
 - **Start from `completionInstructions`, not guesswork.** Every task entry says exactly what completes it and whether it needs a human in a browser. Trust it over inferring from the task name.
-- **Split the work accordingly.** Tasks like campaigns, automations, funnel fixes, and rewards are completable through the workflows above — do them. Tasks that need OAuth (Facebook, POS), purchases (phone number), device setup, image uploads, or in-restaurant staff training cannot be done from the CLI: hand the user that task's **`completionUrl`** — a page where they complete exactly that task. Paste the URL directly in your reply; in the dashboard chat it opens the task next to the conversation, and in a terminal it's clickable.
+- **Split the work accordingly.** Campaigns, automations, funnel fixes, rewards, brand identity, the phone number, image uploads and the onboarding form are all completable through CLI tools — do them. Tasks that need OAuth (Facebook, POS), physical device setup, or in-restaurant staff training cannot be: hand the user that task's **`completionUrl`** — a page where they complete exactly that task. Paste the URL directly in your reply; in the dashboard chat it opens the task next to the conversation, and in a terminal it's clickable.
 - **Never claim a task complete or try to mark one.** Statuses are derived from live data by a recompute (triggered by every taskboard read, ~30s lag) — do the underlying work, then re-read the taskboard to confirm the checkmark flipped.
 - Working through onboarding = repeat: `getTaskboard` (scope `onboarding`) → do the CLI-doable incomplete required tasks → hand over completionUrls for the rest → re-read to verify.
 
----
+## The onboarding form
+
+Some tasks read self-reported answers rather than observed data — launch date, funnel direction, per-step `isComplete` markers. `getOnboardingForm` reads them (`null` when the org has no form yet); `updateOnboardingForm` writes them. **Nested step objects are replaced, not merged** — read first and send back the whole step you're editing (`data` is the exception and is merged). Setting `pos.details.type` to `"other"` provisions a manual-entry POS location as a side effect.
+
+Two POS setup tasks complete off `updateOrganization` instead: `staffInstructions.scan` completes *Members Program Visits POS setup*, and `.prepaid` is additionally required for *Campaign POS setup* when the promotion allows pre-pay. `staffInstructions` is replaced wholesale — send every key you want to keep.
 
 ## Establishing brand identity
 
-**Not exposed to the CLI yet.** Brand setup (logo, colors, fonts, subdomain look) writes to several untagged endpoints, and the intelligent part — auto-extracting a usable palette from a scraped brand with WCAG-contrast derivation and logo selection — lives entirely in the browser, not the API. A brand-import endpoint exists only as a raw scrape (unfiltered logos/colors). If asked, tell the user brand setup isn't CLI-drivable yet.
+1. `searchGooglePlaces` — resolve the restaurant to its Google Place. Include the city in the query; only trust `confidentMatch` when it's non-null, otherwise show the candidates and let the customer pick.
+2. `createBrandIdentity` — the branded site: a subdomain, layout config, and a full default screen tree. The subdomain is claimed **across all organizations** and gates everything funnel-shaped downstream, so confirm the name with the customer first. Get `logoUrl` via `getMediaUploadUrl`.
+3. `updateBrandIdentity` — business data, theme, tracking pixel IDs, OpenTable links, and the Google Place link. It deep-merges, so send only what you're changing. **Setting `googleConfig.placeId` enqueues a review/photo scrape; changing an existing placeId orphans everything scraped under the old one** — confirm before replacing.
+
+Browser-only: the brand *import* intelligence — auto-extracting a usable palette and logo from a scraped site lives in the app, not the API. If the customer wants that flow, hand them the dashboard.
+
+## Plumbing the taskboard leans on
+
+- **Phone number** — `searchAvailablePhoneNumbers` (free, search by the restaurant's own postal code or coordinates — proximity beats a memorable area code) then `purchaseAndConfigurePhoneNumber`, which **bills the account irreversibly**. Establish where the restaurant actually is before buying.
+- **Media** — `getMediaUploadUrl` (PUT the bytes to the presigned URL, then reference the returned key), `listMedia`, `deleteMedia`. This is how logos and offer images get in from the CLI.
+- **Team** — `inviteUser` sends a real email immediately and **defaults to OWNER** (full billing access) — always pass `role` explicitly; VIEWER is read-only, SCANNER is for staff running the scanner app.
+- **Billing** — `getBillingStatus`, read-only: `hasAccess` answers "can they use the product," `needsPayment` flags the states worth acting on. Every billing write stays in the dashboard.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feastalytics/cli",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "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": {