@feastalytics/cli 0.1.15 → 0.1.17

package/feast/SKILL.md

@@ -1,105 +1,131 @@
 ---
 name: feast
-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.
+description: Operate a Feastalytics organization (campaigns, automations, funnels, members-program rewards, the wallet pass, creator sourcing, Meta ads, texting, onboarding, and read-only data queries) through the Feastalytics tools, either the `feast` CLI or the Feastalytics MCP server. 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", "text this guest back", "query my guests", "update the members program", or any request to script, batch or automate Feastalytics operations. Reach for it even when the user doesn't name the CLI or the MCP server: if the task is reading or changing Feastalytics data, these are the tools.
 ---
 
-# Feast CLI
+# Feast
 
-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.
+Drive the Feastalytics platform with the same tool surface the in-app AI agent uses: campaigns, automations, funnels, members program, creator sourcing, Meta ads, texting, onboarding and data queries. Every tool hits 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.
+The live tool list is the source of truth for *which* tools exist and *what* they accept. Read it 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.
 
-Some environments hand you the CLI already installed, already authenticated, and pinned to one organization. If `feast tools` runs, you're set — otherwise, installing, logging in, and staying current are in `references/setup.md`.
+## Two ways in
 
-## The core loop: discover → describe → call
+The same tools, with the same names and inputs, are reachable two ways. Use whichever this session has.
 
-Don't guess tool names or input shapes. Introspect the live CLI:
+| | MCP server | `feast` CLI |
+|---|---|---|
+| How you know you have it | Tools such as `listCampaigns` and `listOrganizations` are in your tool list | `feast tools` runs |
+| See every tool | Your tool list | `feast tools` |
+| One tool's input schema | Its entry in your tool list | `feast describe <tool>` |
+| A schema that says "Named type X. Call describeSchema…" | Call `describeSchema` with `{ "names": ["X"] }` | `feast describe <tool>` prints it in full |
+| Which organizations you can act on | `listOrganizations` | `feast whoami` |
+| Choose the organization | The `organizationId` argument on each call | `--org <organizationId>` |
+| Call a tool | Call it directly with its input | `feast call <tool> --org <id> --input '<json>'` (or `--input-file <path>`) |
 
-```bash
-feast tools                 # list every available tool, its domain, and whether it mutates
-feast describe <tool>       # full description + input JSON schema for one tool
-feast call <tool> --org <organizationId> --input '<json>'
-```
+Setting either one up (installing the CLI, logging in, connecting the MCP server) is in `references/setup.md`. Some environments hand you either one already connected and pinned to one organization; if a read such as `listCampaigns` works, you are set.
+
+The rest of this skill and every workflow file names tools and their JSON input only. Translate to your transport with the table above.
+
+## The core loop: discover, read the schema, call
 
-Always `describe` an unfamiliar tool before calling it — the schema tells you the exact required fields, and the CLI validates your `--input` against it locally before sending anything, so a bad payload fails fast with a clear message instead of a confusing server error.
+Don't guess tool names or input shapes. Before calling an unfamiliar tool, read its input schema (and, over MCP, `describeSchema` for any named type it points to). The schema tells you the exact required fields. The CLI also validates input locally before sending, so a bad payload fails with the field named; over MCP the server validates and returns the same kind of error as a tool error.
 
-That schema is also the boundary for what's worth asking the user about. Before sending a clarifying question, check whether the tool you're about to call has a field for the answer — a question about something the schema can't accept (a limit, a repeat rule, anything not in `describe`'s output) wastes a message and never gets used. Only ask about what the call in front of you can actually configure.
+That schema is also the boundary for what's worth asking the user about. Before sending a clarifying question, check whether the tool you're about to call has a field for the answer. A question about something the schema can't accept (a limit, a repeat rule, anything not in the schema) wastes a message and never gets used. Only ask about what the call in front of you can actually configure.
 
 ## Organizations: never let the API guess
 
-Most tools act on one organization, and which one must be explicit: pass it with `--org <organizationId>`. Acting on the wrong restaurant is worse than stopping to ask, so the CLI refuses rather than guessing when the target is ambiguous.
+Most tools act on one organization, and which one must be explicit. Acting on the wrong restaurant is worse than stopping to ask.
 
-If you weren't given an organization id, or a command reports you belong to several, `references/setup.md` has how to resolve one.
+- If the user names an organization, resolve it to its id (`listOrganizations` or `feast whoami`) and pass that id.
+- If the user belongs to exactly one, it is used automatically.
+- If they belong to several and you don't say which, the call is refused with a list of their organizations rather than silently picking one. Show the list and confirm which one they mean.
 
 ## Reads vs. writes
 
-Query tools (listing, describing, reading) are safe and read-only. Mutation tools (create, update, clone, delete, apply) change production data.
+Query tools (listing, describing, reading) are safe and read-only; over MCP they carry a read-only hint. Mutation tools (create, update, clone, delete, apply, send) change production data.
 
-- Mutations require `--org` explicitly.
-- 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.
+- Always name the organization explicitly for a mutation.
+- On the CLI, a mutation prints the organization's name to stderr before it runs (`Acting on organization <id> as <ROLE>`), so a wrong `--org` shows up as the wrong restaurant. Read that line.
+- **Nothing asks twice.** The CLI has no confirmation prompt, and an MCP client may or may not ask the user to approve a call depending on its settings. A mutation runs the moment it is called, 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. 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.)
+That last point matters most for the tools that reach the real world rather than just the database:
 
-Prefer reading before writing: e.g. `listCampaigns` to find the right `campaignId` before `updateCampaign`, or `describe`/`listAutomationFlows` before creating a flow.
+- `sendText` texts a guest or creator immediately, one person per call, with no scheduling and no undo.
+- Approving or denying a creator visit (`updateCreatorVisit`) or deciding a submission (`decideCreatorSubmission`) texts that person. `updateCreatorVisit` can preview its texts with `dryRun: true` or skip them with `sideEffects: false`; `decideCreatorSubmission` can skip its text with `skipApprovalText`.
+- Paying a creator's bonus (`createInfluencerPayout`) charges the organization's card.
+- `awardReward` puts a real reward in a member's wallet pass, and a retried call grants a second one.
+- `inviteUser` sends a real email.
+- Buying a phone number bills the account.
+- 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. For a text, show the user the exact message and get their go-ahead first. The one schema-level gate is `publishAds`, which requires `confirm: true` in its input; that is you confirming, not anyone asking.
+
+Prefer reading before writing: `listCampaigns` to find the right `campaignId` before `updateCampaign`, or `listAutomationFlows` before creating a flow.
 
 ## Building good input
 
-`--input` takes a JSON string (or `--input-file <path>` for larger payloads). Construct it from the schema you got via `describe`. When a tool references another entity by id (a campaign id, location id, flow id), look that id up first with the relevant list/read tool rather than inventing it.
+Input is a JSON object built from the tool's schema. When a tool references another entity by id (a campaign id, location id, flow id), look that id up first with the relevant list or read tool rather than inventing it.
 
-For the domain-specific meaning of fields — how automations chain, what a funnel screen contains, how offers are structured — consult the guidance in `references/domains.md` when the schema alone isn't enough.
+For the domain meaning of fields (how automations chain, what a funnel screen contains, how offers are structured), consult `references/domains.md` when the schema alone isn't enough.
 
 ## Workflows
 
-Many tasks are multi-step and have a required ordering the app normally enforces. The most important rule: **automations live inside flows — always find a flow (`listAutomationFlows`) or create one (`createAutomationFlow`) before adding automations; never create an orphan automation.** The same "resolve the parent/ids first, then act" shape recurs across campaigns, funnels, and offers.
+Many tasks are multi-step and have a required ordering the app normally enforces. The most important rule: **automations live inside flows. Always find a flow (`listAutomationFlows`) or create one (`createAutomationFlow`) before adding automations; never create an orphan automation.** The same "resolve the parent and ids first, then act" shape recurs across campaigns, funnels and offers.
 
-**Before acting on any multi-step task, read the workflow file for it.** Each one carries the required call ordering and the domain rules that make the result good rather than merely valid — neither of which is in the tool schemas. Read it first; don't reconstruct the sequence from tool descriptions.
+**Before acting on any multi-step task, read the workflow file for it.** Each one carries the required call ordering and the domain rules that make the result good rather than merely valid, and neither is in the tool schemas. Read it first; don't reconstruct the sequence from tool descriptions.
 
 | Doing this | Read |
 |---|---|
 | Creating, cloning or configuring a campaign; promotions | `references/workflows/campaigns.md` |
-| Anything touching automations — creating, editing, simulating, promoting a draft | `references/workflows/automations.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 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` |
-| 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` |
+| 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` |
-| Searching guests/members; querying anything via the data catalog | `references/workflows/guests.md` |
+| Searching guests and members, texting a guest back, querying anything through the data catalog | `references/workflows/guests.md` |
 
-Every row names one file, and one file is the whole answer for that row — pick the row that matches what you're doing and read only it. The two ad-copy rows are mutually exclusive: you are writing to guests or to creators, never both in one piece of copy.
+Every row names one file, and one file is the whole answer for that row. Pick the row that matches what you're doing and read only it. The two ad-copy rows are mutually exclusive: you are writing to guests or to creators, never both in one piece of copy.
 
-Read more than one file when a task genuinely spans steps — a new campaign usually means `campaigns.md` plus `automations.md` and `funnels.md`. Read each one as you reach that step rather than gathering them up front: a file stays in context for the rest of the session, so one you open speculatively is re-read on every later turn.
+Read more than one file when a task genuinely spans steps. A new campaign usually means `campaigns.md` plus `automations.md` and `funnels.md`. Read each one as you reach that step rather than gathering them up front: a file stays in context for the rest of the session, so one you open speculatively is re-read on every later turn.
 
-When the ask is a question rather than a change — where something lives, what a field means, which link to send — read the single file the table names and answer from it.
+When the ask is a question rather than a change (where something lives, what a field means, which link to send), read the single file the table names and answer from it.
 
-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.
+Some things have no tool: 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 tool that isn't in the tool list; tell the user that part has to be done in the dashboard.
 
 ## Link to what you touched
 
-Work you do through the CLI lands somewhere in the product, and a link is a cheap thing to offer — so offer them freely. After a turn where you created, changed, or published something, close with a short markdown list: where to see it, where to edit it, where to preview it. Not because anyone has to go check your work, but because opening the thing is usually the next step anyway. When someone asks where a thing lives or how to set it up, lead with the link rather than click-by-click directions.
+Work you do through these tools lands somewhere in the product, and a link is a cheap thing to offer, so offer them freely. After a turn where you created, changed or published something, close with a short markdown list: where to see it, where to edit it, where to preview it. Opening the thing is usually the next step anyway. When someone asks where a thing lives or how to set it up, lead with the link rather than click-by-click directions.
 
-**You don't know these URLs — read `references/links.md` before you write one.** The dashboard's shape is not the one you'd extrapolate from the guest-facing links elsewhere in this skill, so a URL that looks obviously right is the exact case to check. A wrong link is worse than no link: it looks authoritative and 404s.
+**You don't know these URLs. Read `references/links.md` before you write one.** The dashboard's shape is not the one you'd extrapolate from the guest-facing links elsewhere in this skill, so a URL that looks obviously right is the exact case to check. A wrong link is worse than no link: it looks authoritative and 404s.
 
-That file has the dashboard routes with their panel and tab names, the guest-facing pages on the organization's own subdomain, the preview route that completes the funnel draft loop, and which query params actually suppress analytics versus merely tagging a visit as a preview.
+That file has the dashboard routes with their panel and tab names, the guest-facing pages on the organization's own subdomain, the preview route that completes the funnel draft loop, and which query params suppress analytics versus merely tagging a visit as a preview.
 
 ## Worked example
 
 User: "add a Free Dessert reward members can redeem for 100 points in my Plum Vietnamese org."
 
+1. Find the organization's id with `listOrganizations` (CLI: `feast whoami`), unless you were given it.
+2. Read the `createMembersProgramReward` schema to learn the input shape (`type: "item"` vs `type: "name"`).
+3. Call `listMembersProgramRewards` to avoid duplicating an existing reward or catalog item.
+4. Call `createMembersProgramReward` with `{ "type": "name", "name": "Free Dessert", "pointsCost": 100 }`.
+
+On the CLI, step 4 is:
+
 ```bash
-feast whoami                                     # only if you weren't given the org id already
-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}'
+feast call createMembersProgramReward --org <organizationId> --input '{"type":"name","name":"Free Dessert","pointsCost":100}'
 ```
 
-The pattern generalizes: identify the org, learn the tool, resolve any referenced ids, then act.
+The pattern generalizes: identify the organization, learn the tool, resolve any referenced ids, then act.
 
 ## When something fails
 
-- "Not logged in / session expired", or `feast` isn't on PATH → `references/setup.md`.
-- "You belong to multiple organizations" → pick one with `--org`; `references/setup.md` has how to find the id.
-- "Input does not match the tool schema" → re-read `feast describe <tool>` and fix the named fields.
-- A tool you expected isn't listed by `feast tools` → it may not be exposed yet; don't fabricate a call, tell the user.
+- Not logged in, session expired, `feast` isn't on PATH, or the MCP server asks you to authenticate: `references/setup.md`.
+- "You belong to multiple organizations": pick one and pass it explicitly (see Organizations above).
+- The input doesn't match the schema: re-read the tool's schema (and any named type) and fix the named fields.
+- A tool you expected isn't in the tool list: don't fabricate a call; tell the user that part has to be done in the dashboard.

package/feast/references/domains.md

@@ -1,10 +1,10 @@
 # Feastalytics domain model
 
-Background for constructing tool input correctly. This is the conceptual map; the authoritative field list for any tool always comes from `feast describe <tool>`.
+Background for constructing tool input correctly. This is the conceptual map; the authoritative field list for any tool always comes from its input schema.
 
 ## Organizations
 
-The top-level tenant. Nearly every tool is scoped to one organization via `--org`. An org has one or more POS locations (Toast/Square/Clover); many tools that operate on menus or offers need a `locationId`, which you get from `getOrganization` (it returns the org's `locations`) — not the organization id.
+The top-level tenant. Nearly every tool is scoped to one organization (see Organizations in `SKILL.md`). An org has one or more POS locations (Toast/Square/Clover); many tools that operate on menus or offers need a `locationId`, which you get from `getOrganization` (it returns the org's `locations`), not the organization id.
 
 ## Campaigns (acquisition)
 
@@ -13,7 +13,9 @@ A campaign is an acquisition effort. It bundles:
 - **automations** (see below) scoped to that campaign,
 - **promotions/offers** attached to it.
 
-Typical flow: `createCampaign` (set `isCreating: true` if you'll finish it with `populateCampaign`), then `populateCampaign`, then choose a funnel template. `cloneCampaign` duplicates an existing one (funnel + automations + offers) — it needs the source campaign id and a `referrer` (a subdomain from the org's `subdomains2`).
+`listCampaigns` resolves a `campaignId`: use each summary's `id` (a UUID), not the nested Meta campaign id. Summaries also carry the name, `shorthand` (used in reservation links), publish state and referrers; `getCampaign` has the full configuration.
+
+Typical flow: `createCampaign`, then always `populateCampaign` (a new campaign stays hidden from the dashboard until it is populated), then choose a funnel template. `cloneCampaign` duplicates an existing one (funnel, automations and offers); it needs the source campaign id and a `referrer` (a subdomain from the org's `subdomains2`).
 
 ## Automations and flows
 
@@ -29,16 +31,16 @@ Promotions live on the campaign record (`getCampaign` / `updateCampaign`), and r
 
 ## 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). 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`.
+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`).
+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`.
+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.
+`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/links.md

@@ -1,16 +1,16 @@
 # Linking to your work
 
-Most of what you create or change through the CLI has a stable URL in the product. Handing one over is cheap and saves the user hunting through the dashboard for the thing you just made — opening it is usually their next step anyway.
+Most of what you create or change through these tools has a stable URL in the product. Handing one over is cheap and saves the user hunting through the dashboard for the thing you just made; opening it is usually their next step anyway.
 
-So offer links freely: after a turn where you created, changed, or published something, close with a short markdown list — usually two to four, covering where to see it, where to edit it, and where to preview it. When someone asks where a thing lives or how to set it up, lead with the link rather than describing where to click. It's an affordance, not a checkpoint; nobody has to go verify your work.
+So offer links freely: after a turn where you created, changed, or published something, close with a short markdown list, usually two to four, covering where to see it, where to edit it, and where to preview it. When someone asks where a thing lives or how to set it up, lead with the link rather than describing where to click. It's an affordance, not a checkpoint; nobody has to go verify your work.
 
-You can build almost every URL below from ids you already have. `<organizationId>` is the same value you pass to `--org`. Campaign, flow and draft ids come back from the tool call you just made. Only `<subdomain>` needs a lookup.
+You can build almost every URL below from ids you already have. `<organizationId>` is the organization id you pass on every call. Campaign, flow and draft ids come back from the tool call you just made. Only `<subdomain>` needs a lookup.
 
-Angle brackets below mark a value **you** substitute. A finished link contains no brackets, no braces and no backticks — if you emit `{{...}}` or a bare `<campaignId>`, the link is broken.
+Angle brackets below mark a value **you** substitute. A finished link contains no brackets, no braces and no backticks. If you emit `{{...}}` or a bare `<campaignId>`, the link is broken.
 
 ## Dashboard
 
-Everything an authenticated user sees hangs off `https://feastalytics.com/<organizationId>/app`. Note the shape: the organization id is a **path segment**, not a subdomain — there is no `app.feastalytics.com`.
+Everything an authenticated user sees hangs off `https://feastalytics.com/<organizationId>/app`. Note the shape: the organization id is a **path segment**, not a subdomain. There is no `app.feastalytics.com`.
 
 ```
 /                                        home
@@ -31,22 +31,22 @@ Members-program panels: `overview`, `funnel`, `automations`, `pass-builder`, `re
 
 Settings tabs: `account`, `general`, `members`, `integrations`, `notifications`, `usage`, `scanning`, `texting`, `subscription`. Point people at `/settings/integrations` when a task needs a POS or Meta connection you can't make for them.
 
-Funnels are always edited inside a panel, never on a page of their own — a campaign's `funnel-v2` panel, or the members program's `funnel` panel.
+Funnels are always edited inside a panel, never on a page of their own: a campaign's `funnel-v2` panel, or the members program's `funnel` panel.
 
 ### Onboarding task pages
 
-Task entries from `getTaskboard` come with a ready-made `completionUrl` — always prefer pasting that over constructing a URL. The shape behind it: `https://feastalytics.com/tasks/<organizationId>` is the org's standalone task list, and `https://feastalytics.com/tasks/<organizationId>/<taskId>` opens one task's completion UI directly (chrome-less; works in the dashboard's agent preview panel and as a normal browser link). These are the links to hand over when a task needs the human — OAuth connections, phone purchase, device setup.
+Task entries from `getTaskboard` come with a ready-made `completionUrl`. Always prefer pasting that over constructing a URL. The shape behind it: `https://feastalytics.com/tasks/<organizationId>` is the org's standalone task list, and `https://feastalytics.com/tasks/<organizationId>/<taskId>` opens one task's completion UI directly (chrome-less; works in the dashboard's agent preview panel and as a normal browser link). These are the links to hand over when a task needs the human: OAuth connections, phone purchase, device setup.
 
 ### Automation previews
 
-These two hang off the **root**, not off `/<organizationId>/app` — the organization id is the first path segment:
+These two hang off the **root**, not off `/<organizationId>/app`. The organization id is the first path segment:
 
 ```
 https://feastalytics.com/automation-preview/<organizationId>/<flowId>
 https://feastalytics.com/automation-preview/<organizationId>/<flowId>?draftId=<draftId>
 ```
 
-Without `draftId` it dry-runs the live flow as a text-message thread. With one, the same page diffs the draft's staged changes against live — added messages tinted, removed struck through, edited showing the old copy above the new — which is the link to hand someone before you promote.
+Without `draftId` it dry-runs the live flow as a text-message thread. With one, the same page diffs the draft's staged changes against live (added messages tinted, removed struck through, edited showing the old copy above the new), which is the link to hand someone before you promote.
 
 A `flowId` contains `:` and `;` and **must be percent-encoded** in the path. Easier: `createAutomationDraft` and `stageAutomationEdits` both return `previewUrls`, already built and encoded, one per flow the draft touches. Use those rather than assembling your own.
 
@@ -73,10 +73,10 @@ The `/preview/<draftId>` route is the payoff of the draft → preview → promot
 
 ## Worked example
 
-After creating a campaign and applying a funnel template. Every id below is substituted — this is what a finished message looks like, with nothing left to fill in:
+After creating a campaign and applying a funnel template. Every id below is substituted. This is what a finished message looks like, with nothing left to fill in:
 
 ```markdown
-Done — "Fall Prix Fixe" is live as a draft.
+Done. "Fall Prix Fixe" is live as a draft.
 
 - [Open the campaign](https://feastalytics.com/3e8cb27c-6e54-444b-859f-66dbae0e711b/app/campaigns/e8ccc852-6555-4a9a-b48b-127d687bb34a)
 - [Edit the funnel](https://feastalytics.com/3e8cb27c-6e54-444b-859f-66dbae0e711b/app/campaigns/e8ccc852-6555-4a9a-b48b-127d687bb34a?panel=funnel-v2)

package/feast/references/setup.md

@@ -1,31 +1,45 @@
 # Setup, auth, and organizations
 
-One-time and troubleshooting material: getting the `feast` CLI installed and logged in, keeping it and this skill current, and working out which organization to act on. The day-to-day loop lives in `SKILL.md`; you only need this file when something isn't working yet.
+One-time and troubleshooting material: connecting the Feastalytics MCP server or installing and logging in to the `feast` CLI, keeping the CLI and this skill current, and working out which organization to act on. The day-to-day loop lives in `SKILL.md`; you only need this file when something isn't working yet.
 
-Some environments hand you a CLI that is already installed and authenticated, and pin you to a single organization. Nothing in this file applies there — if `feast tools` runs and your commands are going to the right restaurant, you are already set up.
+Some environments hand you the tools already connected and authenticated, pinned to a single organization. Nothing in this file applies there: if a read such as `listCampaigns` works and your calls are going to the right restaurant, you are already set up.
 
-## Installing
+## The MCP server
+
+The hosted server is at `https://mcp.feast-api.com/mcp` (streamable HTTP, OAuth). The user adds it once in their MCP client, for example:
+
+```bash
+claude mcp add --transport http feast https://mcp.feast-api.com/mcp   # Claude Code
+```
+
+In other clients (Claude Desktop, claude.ai, Cursor) it is a custom connector with that URL. The first call opens a browser to the Feastalytics login, then a consent page naming the client; after that the client refreshes the session itself. A session lasts 30 days from that login, then the user logs in again. If tool calls start failing with an authentication error, ask the user to reconnect the server in their client.
+
+You can't add the server for the user from inside a conversation. Tell them the URL and where to add it.
+
+## The `feast` CLI
+
+### Installing
 
 The `feast` CLI must be installed and on PATH:
 
 ```bash
-npm install -g @feastalytics/cli    # or run ad-hoc with: npx @feastalytics/cli <command>
+npm install -g @feastalytics/cli    # or run ad hoc with: npx @feastalytics/cli <command>
 ```
 
-If the global install fails on permissions, don't retry with `sudo` — tell the user and fall back to `npx @feastalytics/cli@latest`.
+If the global install fails on permissions, don't retry with `sudo`. Tell the user and fall back to `npx @feastalytics/cli@latest`.
 
-## Authenticating
+### Authenticating
 
-Authenticate once — tokens are cached in `~/.config/feast-cli/credentials.json` and refreshed automatically:
+Authenticate once. Tokens are cached in `~/.config/feast-cli/credentials.json` and refreshed automatically:
 
 ```bash
 feast login                        # opens a browser to authorize (default)
-feast login --password [username]  # headless / CI: username + password prompt, no browser
+feast login --password [username]  # headless or CI: username and password prompt, no browser
 ```
 
-If a command reports you're not logged in or the session expired, re-run `feast login`.
+If a command reports you're not logged in or the session expired, run `feast login` again.
 
-## Staying current
+### Staying current
 
 Neither the CLI nor this skill updates itself. When a command prints an update notice on stderr:
 
@@ -36,24 +50,31 @@ Update available: feast 0.1.1 → 0.2.0
 update both, then tell the user in one line that you did:
 
 ```bash
-npm install -g @feastalytics/cli@latest      # only if `feast` is already on PATH from a global install
+npm install -g @feastalytics/cli@latest      # only if `feast` is on PATH from a global install
 npx skills add feastalytics/cli -g -a '*' -y # refresh this skill from the repo
 ```
 
-If you've been invoking the CLI through `npx` rather than a global install, skip the `npm install -g` and use `npx @feastalytics/cli@latest <command>` for the rest of the session instead — `npx` reuses a cached copy otherwise.
+If you've been invoking the CLI through `npx` rather than a global install, skip the `npm install -g` and use `npx @feastalytics/cli@latest <command>` for the rest of the session instead (`npx` reuses a cached copy otherwise).
 
-Update the skill whenever you update the CLI: the two ship from the same repo but on different triggers, so a new CLI version usually means this skill's guidance has moved too.
+Update the skill whenever you update the CLI: the two ship from the same repo but on different triggers, so a new CLI version usually means this skill's guidance has moved too. The MCP server always serves the current tools, so over MCP only the skill needs refreshing.
 
-## Which organization
+## Playbook skills
 
-Most tools act on one organization. A user often belongs to several, so which one you target matters and must be explicit.
+Feastalytics publishes further skills that build on this one (campaign diagnosis and other playbooks). They come from the API, not from GitHub, and installing them takes the CLI:
 
 ```bash
-feast whoami                # shows the logged-in user and every org (with names) they can act on
+feast skill list                       # what is published for your organization
+feast skill install feast-playbooks    # install or refresh one into ~/.claude/skills/
 ```
 
-Pass the target org with `--org <organizationId>`:
+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.
+
+## Which organization
+
+Most tools act on one organization. A user often belongs to several, so which one you target matters and must be explicit.
 
-- If the user names an org, resolve it to its id with `feast whoami` and pass that id.
-- If the user belongs to exactly one org, the CLI uses it automatically — no flag needed.
-- If they belong to more than one and you omit `--org`, the CLI refuses and lists the orgs rather than silently picking one. That's intentional: acting on the wrong org is worse than stopping to ask. When this happens, surface the list to the user and confirm which one they mean.
+- See every organization the user can act on, with names and their role: `listOrganizations` over MCP, `feast whoami` on the CLI.
+- Pass the target as the `organizationId` argument (MCP) or `--org <organizationId>` (CLI).
+- If the user names an organization, resolve it to its id from that list and pass the id.
+- If the user belongs to exactly one organization, it is used automatically.
+- If they belong to more than one and you don't pass one, the call is refused with the list of their organizations rather than silently picking one. That's intentional: acting on the wrong organization is worse than stopping to ask. Show the user the list and confirm which one they mean.

package/feast/references/workflows/ad-copy-creator.md

@@ -1,45 +1,43 @@
 # Creator-recruitment ad copy (`recruitmentAdCopy`)
 
-> 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.
-
 This is the creator-facing half of Meta ad copy: `recruitmentAdCopy`, which sells a paid collaboration to a content creator shopping for brand deals.
 
-**Writing to guests instead? Read `ad-copy-guest.md` and not this file.** `adCopy` sells the offer and the food to a hungry local scrolling past — a different audience and a completely different pitch. Conflating the two is the failure mode in this area, and it has happened repeatedly. A creator is not a customer; the food is their perk, not the pitch. If you catch yourself writing "claim your voucher" here, stop and start over.
+**Writing to guests instead? Read `ad-copy-guest.md` and not this file.** `adCopy` sells the offer and the food to a hungry local scrolling past. That is a different audience and a completely different pitch. Conflating the two is the failure mode in this area, and it has happened repeatedly. A creator is not a customer; the food is their perk, not the pitch. If you catch yourself writing "claim your voucher" here, stop and start over.
 
-For the creator program itself — applicants, visits, briefs, the decision loop — read `creators.md`. Publishing the finished ad is a separate job with its own loop — read `ads.md`.
+For the creator program itself (applicants, visits, briefs, the decision loop), read `creators.md`. Publishing the finished ad is a separate job with its own loop: read `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.
+**You write the copy yourself.** The dashboard has a "generate copy" button behind an LLM call; there is no tool for it and you shouldn't want one, because it would be you calling an 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.
 
 ## Variations: write a set, not a single
 
-Meta's Advantage+ creative optimization tests combinations of headlines and primary texts against each other, so you're writing a *set* — several headlines and several primary texts that genuinely differ.
+Meta's Advantage+ creative optimization tests combinations of headlines and primary texts against each other, so you're writing a *set*: several headlines and several primary texts that genuinely differ.
 
 **Genuinely** is the load-bearing word. There is no required count. Three sharp variations that each take a real angle beat five where two are padding, and a set of near-identical rewrites teaches the optimizer nothing. Write as many as the collab actually supports. Judge it, and stop when the next variation would be filler.
 
-The other reason to write more than one is that the restaurant may want to pick, and people form opinions by seeing alternatives rather than by being handed a single answer. So offering the set is usually the right move — but you have taste, and you should use it. Recommend the one you'd launch and say why. Cut the weak ones before anyone sees them rather than padding them in to look thorough. Three you'd defend beats five you wouldn't.
+The other reason to write more than one is that the restaurant may want to pick, and people form opinions by seeing alternatives rather than by being handed a single answer. So offering the set is usually the right move, but you have taste, and you should use it. Recommend the one you'd launch and say why. Cut the weak ones before anyone sees them rather than padding them in to look thorough. Three you'd defend beats five you wouldn't.
 
 ## The audience
 
-**Local food and lifestyle content creators** on Instagram and TikTok — someone scrolling for brand collabs, not a hungry person hunting a deal. The ad is decoupled from any consumer campaign the restaurant is running, *even if one is running right now*. Your job is to get the right creator to tap "Learn More" on a landing page that explains the collab in full — not to close the deal inside the ad.
+**Local food and lifestyle content creators** on Instagram and TikTok: someone scrolling for brand collabs, not a hungry person hunting a deal. The ad is decoupled from any consumer campaign the restaurant is running, *even if one is running right now*. Your job is to get the right creator to tap "Learn More" on a landing page that explains the collab in full, not to close the deal inside the ad.
 
-## Absolute rules — this is exactly where past generations went wrong
+## Absolute rules: this is exactly where past generations went wrong
 
 - **Never mention an offer, deal, voucher, promotion, discount, "claiming" anything, or pre-paying.** This is a collaboration, not a customer offer.
 - **Don't pitch the food the way you'd pitch it to a diner.** The food is the perk; the collab is the pitch.
-- **No customer-facing language** — "claim your voucher", "come hungry", "limited time offer", "this week only", "tap below to save".
-- **Don't reuse the campaign's guest-facing framing** — banner copy, promotions, offer headlines. None of it belongs here, however good it is.
+- **No customer-facing language**: "claim your voucher", "come hungry", "limited time offer", "this week only", "tap below to save".
+- **Don't reuse the campaign's guest-facing framing**: banner copy, promotions, offer headlines. None of it belongs here, however good it is.
 - **If there's a cash bonus, never imply it's automatic or guaranteed.** It is earned only if the restaurant selects the creator's reel to run as a paid ad. Phrasings like "earn a $100 bonus", "get a $100 bonus when you post", or "$100 bonus if you nail the brief" read as guaranteed-on-completion, and they have caused real creators to demand a bonus they hadn't earned. Always frame it conditionally: "a chance to earn", "up to", "if your reel gets picked to run as an ad".
 
 ## What to pitch
 
 - The restaurant is booking local food/lifestyle creators to come in, eat on the house, and post a short reel.
-- **The creator gets:** a dining credit (order whatever they want), a creative brief with style direction but no script — they stay authentic — and, when acquisition is enabled, their reel boosted as a paid partnership ad alongside the restaurant's Instagram, which is free promotion to thousands of local foodies plus followers and engagement on their own page. Where a bonus exists, add it conditionally.
-- **The creator gives:** one 30–60 second vertical reel (Instagram Reel / TikTok), filmed during the visit, submitted within 72 hours.
+- **The creator gets:** a dining credit (order whatever they want), a creative brief with style direction but no script (they stay authentic), and, when acquisition is enabled, their reel boosted as a paid partnership ad alongside the restaurant's Instagram, which is free promotion to thousands of local foodies plus followers and engagement on their own page. Where a bonus exists, add it conditionally.
+- **The creator gives:** one 30 to 60 second vertical reel (Instagram Reel / TikTok), filmed during the visit, submitted within 72 hours.
 - **Eligibility:** an active food/lifestyle creator with a minimum local-area follower count on Instagram or TikTok.
 
-## Angles — rotate across the set
+## Angles: rotate across the set
 
-With a bonus: **get paid** ("Get paid to eat at X") → **free food + free promotion**, both sides of the exchange → **local creator call-out** ("Local foodies on IG — we want you") → **grow your page**, the boost and the new followers → **straightforward collab pitch**, no fluff: free meal + paid post + bonus.
+With a bonus: **get paid** ("Get paid to eat at X") → **free food + free promotion**, both sides of the exchange → **local creator call-out** ("Local foodies on IG, we want you") → **grow your page**, the boost and the new followers → **straightforward collab pitch**, no fluff: free meal + paid post + bonus.
 
 Without a bonus, swap the first for **free food collab** ("Eat on us at X"), and grow-your-page for **brand partnership** (a collaboration, not a giveaway) or **behind-the-scenes** (be part of the restaurant's story).
 
@@ -49,7 +47,7 @@ Take as many of these as the collab genuinely supports rather than filling a quo
 
 Talk like a brand DM'ing a creator about a collab, not like a restaurant running an ad. Confident, peer-to-peer, slightly insider: "We're partnering with…", "We're booking creators for…", "Looking for local foodies who…".
 
-Specifics over fluff — name the dollar amounts, the deliverable (one reel, 30–60s), the eligibility. Emoji fine in moderation (📸 🎥 🍴), don't spam. **Separate every sentence with a blank line (two newlines)** — each sentence has to stand alone visually, because a paragraph is a wall and a wall gets skipped.
+Specifics over fluff: name the dollar amounts, the deliverable (one reel, 30 to 60s), the eligibility. Emoji fine in moderation (📸 🎥 🍴), don't spam. **Separate every sentence with a blank line (two newlines)**. Each sentence has to stand alone visually, because a paragraph is a wall and a wall gets skipped.
 
 **GOOD primary text:**
 
@@ -58,36 +56,36 @@ Plum Vietnamese is booking local food creators this month. 📸
 
 You get a $30 tab on us, a creative brief, and a chance to earn a $100 bonus if your reel gets run as a paid ad.
 
-We'll also boost it as a partnership ad — free promo to thousands of local foodies. 1,000+ local IG/TikTok followers to apply.
+We'll also boost it as a partnership ad: free promo to thousands of local foodies. 1,000+ local IG/TikTok followers to apply.
 ```
 
-**GOOD headlines:** `Get paid to post about Plum` · `Local creators — eat free, post a reel` · `Foodies w/ 1,000+ followers, read this 👀`
+**GOOD headlines:** `Get paid to post about Plum` · `Local creators: eat free, post a reel` · `Foodies w/ 1,000+ followers, read this 👀`
 
-**BAD — do not generate this:**
+**BAD (do not generate this):**
 
 ```
-Free meal at Plum Vietnamese this week! Claim your voucher and come hungry — you won't want to miss this deal. 🍴
+Free meal at Plum Vietnamese this week! Claim your voucher and come hungry, you won't want to miss this deal. 🍴
 ```
 
-That's a customer offer wearing a creator ad's clothes. Every one of "free meal", "claim your voucher", "come hungry" and "this deal" is independently disqualifying. Note what the good version does instead: it names the restaurant as the one doing the booking, states the exchange in plain numbers, and gates on follower count — so the wrong reader self-selects out in the first line.
+That's a customer offer wearing a creator ad's clothes. Every one of "free meal", "claim your voucher", "come hungry" and "this deal" is independently disqualifying. Note what the good version does instead: it names the restaurant as the one doing the booking, states the exchange in plain numbers, and gates on follower count, so the wrong reader self-selects out in the first line.
 
-## The terms are baked into the copy — record them
+## The terms are baked into the copy: record them
 
-`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.
+`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.
 
-**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.
+**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.
+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.
 
 ## Saving it
 
-One `updateCampaign` call writes `recruitmentAdCopy`. Run `feast describe updateCampaign` for the fields — alongside the headlines and primary texts it wants the landing page URL, the creative mix, a timestamp, and optional indices for the variation you're recommending.
+One `updateCampaign` call writes `recruitmentAdCopy`. Read `updateCampaign`'s input schema for the fields: alongside the headlines and primary texts it wants the landing page URL, the creative mix, a timestamp, and optional indices for the variation you're recommending.
 
-**The one thing the schema won't tell you: `update.adCopy` replaces the whole object rather than merging into it.** Read the campaign with `getCampaign` first and send back everything you want kept, not just what changed.
+**The one thing the schema won't tell you: `update.recruitmentAdCopy` replaces the whole object rather than merging into it.** Read the campaign with `getCampaign` first and send back everything you want kept, not just what changed.
 
 ## Publishing
 
-**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.
+**Drivable through the tools; 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.
 
 ---