Update to Brainerce

{
  "description": "Set up a sale, promotion or discount on a Brainerce store and confirm it is actually live. Use when the merchant says take 20% off, run a sale, create a discount code, set up a voucher, or schedule a Black Friday deal. The core of this skill is the choice between an automatic discount that applies by itself in the cart and a coupon code the shopper has to type, because getting that wrong is the mistake merchants notice. Also covers loyalty points, earning rules, badges and paid plans, and gift cards: a gift card is stored value the customer spends, not a discount, never a coupon. For store owners, not developers. Do not choose this to review a past promotion, use brainerce-analytics, or to hunt for expired ones, use brainerce-store-health. Do not choose this to set up shipping zones or what shipping costs, use brainerce-store-architecture. Keywords: sale, discount, promo code, coupon, voucher, BOGO, free shipping offer, Black Friday, loyalty, points, earning rules, membership, gift card.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 1086
    },
    {
      "relative_path": "assets/icon.png",
      "size_in_bytes": 3208
    }
  ],
  "name": "brainerce-launch-a-sale",
  "skill_md_contents": "---\nname: brainerce-launch-a-sale\ndescription: 'Set up a sale, promotion or discount on a Brainerce store and confirm it is actually live. Use when the merchant says take 20% off, run a sale, create a discount code, set up a voucher, or schedule a Black Friday deal. The core of this skill is the choice between an automatic discount that applies by itself in the cart and a coupon code the shopper has to type, because getting that wrong is the mistake merchants notice. Also covers loyalty points, earning rules, badges and paid plans, and gift cards: a gift card is stored value the customer spends, not a discount, never a coupon. For store owners, not developers. Do not choose this to review a past promotion, use brainerce-analytics, or to hunt for expired ones, use brainerce-store-health. Do not choose this to set up shipping zones or what shipping costs, use brainerce-store-architecture. Keywords: sale, discount, promo code, coupon, voucher, BOGO, free shipping offer, Black Friday, loyalty, points, earning rules, membership, gift card.'\ncompatibility: ChatGPT, Claude Code, Claude Desktop, Cursor\nmaintainer: Brainerce\nmetadata:\n  author: Brainerce\n  version: '1.0.0'\n---\n\n⛔ **Before you call anything a dashboard task, look for `search_tools` in your tool list.** Some connections carry a small curated list PLUS a way to reach everything else. Where `search_tools` exists, search for what the merchant asked for and call any hit through the `call_read_tool` / `call_write_tool` / `call_destructive_tool` it names. The dashboard is the honest answer only when your list has no `search_tools`, or the search comes back empty. A few things are refused through it deliberately (payment provider setup, refunds and recording payments, gift cards), which is why an empty result there is a real answer rather than a gap.\n\nTake a merchant from \"put this on sale\" to a promotion that is live, correct, and described back to them accurately.\n\n## Core principle\n\nYou are helping someone run their shop. They do not think in entity names, rule types or ISO timestamps, so do not make them. Ask about the sale in the words they used, then translate. Never report a promotion as created until a listing tool has shown it back to you.\n\n## When to use this skill first\n\n- The merchant wants money taken off something: a product, a category, an order total, or shipping.\n- The merchant asks for a discount code to hand out.\n- The merchant wants a promotion scheduled for a date range or a named shopping event.\n- The merchant asks whether a sale they set up is running.\n\n## When NOT to use this skill first\n\n- \"How much did the sale make\", \"did the promotion work\", \"what is my revenue this week\": use `brainerce-analytics`.\n- \"Find promotions I forgot to turn off\", \"audit the store\": use `brainerce-store-health`.\n- \"The order should have had the discount on it\": that is an order question, use `brainerce-order-handling`.\n- ⛔ **\"Set up my shipping rates\", \"how much do I charge to ship to Europe\", \"which countries do I deliver to\".** That is shipping configuration, not a promotion, and it is `brainerce-store-architecture`. This skill only handles free shipping as an **offer** on top of rates that already exist. If the merchant has no shipping rates set up at all, a `SHIPPING_DISCOUNT` has nothing to discount, so send them there first and come back.\n\n---\n\n## Step 1: automatic discount, or a code? Decide this before anything else\n\nTwo different things are called a discount, and they behave differently for the shopper.\n\n|                    | Automatic discount                                                | Coupon                                                                |\n| ------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------- |\n| Tool               | `create_discount_rule`                                            | `create_coupon`                                                       |\n| Shopper experience | Price drops by itself in the cart                                 | Shopper must type a code at checkout                                  |\n| Who gets it        | Everyone the rule targets                                         | Only people who have the code                                         |\n| Merchant says      | \"20% off all jackets\", \"sale next week\", \"free shipping over 200\" | \"a code for my newsletter\", \"SPRING20\", \"a voucher for this customer\" |\n\n**The default is the automatic discount.** When the merchant says \"give 10% off everything next week\" and never mentions a code, they mean the price drops on its own. Reach for `create_discount_rule`.\n\n**Use `create_coupon` only when** the merchant asks for a code, names a code word, or wants something they can hand to specific people.\n\n**When it genuinely could be either, ask one short question before creating anything:**\n\n> Quick check before I set this up: should the 20% come off by itself for everyone, or do you want a code that customers type in at checkout?\n\n⛔ Never create a coupon and then describe it as an automatic discount. A merchant who is told \"the discount is live\" and then sees full prices on their own storefront has been given a wrong answer, not an imprecise one.\n\n### A gift card is neither of these, and \"voucher\" can mean either\n\n\"Voucher\" is the word that collides. A merchant who wants a code that takes money off is asking for a coupon; a merchant who wants to hand someone **stored value they can spend** (a birthday present, a goodwill gesture after a bad delivery, a refund the customer takes in credit) is asking for a **gift card**, and a coupon is not a substitute. Ask which one they mean before creating anything, because the two behave differently on the merchant's own books: a coupon is a discount and lowers the order total and the tax on it, while a gift card is a **means of payment** that leaves the order total and its tax exactly where they are and reduces only what the payment provider is charged. It also sits on the store's balance sheet as a liability until it is spent.\n\n### Telling customers about it, and who a rule applies to\n\nTo announce a sale by email, or to send a code to a group of customers, use `brainerce-email-campaigns`: it covers choosing the audience, the recipient count and the send. A discount rule does not email anyone by itself.\n\nA rule's `conditions` is `{ matchType: \"all\" or \"any\", rules: [{ type, operator, value }] }`. An unknown condition `type` is refused, because the engine would otherwise treat it as met and apply the rule to every cart. The tool description lists the valid types and operators; copy them rather than inventing one such as `item_count` or `is_vip`. Dates must have `endsAt` after `startsAt`.\n\nGift cards have their own tools, separate from everything above: `list_gift_cards`, `get_gift_card`, `get_gift_card_liability`, `issue_gift_card`, `reissue_gift_card`, `adjust_gift_card_balance`, `set_gift_card_status`, `bulk_set_gift_card_status`, `set_gift_cards_enabled` and `verify_gift_card_ledger`. If a gift-card tool is not reachable on this connection, say that plainly and stop; do not issue a coupon in its place and call it a gift card.\n\nTwo things worth telling the merchant in their own words: a card can only be spent in the currency it was issued in, and a card larger than the basket is not used up: only what the order owed comes off, and the rest stays on the card for next time.\n\n## Step 2: gather what the promotion needs\n\nAsk only for what is missing, and only what changes the result.\n\n- **What is on sale.** Everything, a category, specific products, or the order total. Use `list_products` or `list_categories` to resolve names the merchant used into real ones. If a name matches nothing, say so and offer the closest matches rather than picking one.\n- **How much.** A percentage or a fixed amount. Read the store's currency from `get_store` rather than assuming; do not say dollars to a merchant selling in shekels or euros.\n- **When.** A start and an end. \"Next week\" and \"for the weekend\" need turning into real dates, so state the dates you are using in your confirmation and let the merchant correct them.\n- **Limits, only if the merchant raises them.** Usage caps, per-customer caps, a budget ceiling, whether it can stack with other offers.\n\nDo not invent limits the merchant did not ask for, and do not ask about every optional field. A promotion with sensible defaults that they can adjust beats an interrogation.\n\n## Step 3: create it\n\n**Automatic discount:** call `create_discount_rule`. Pick the type from what the merchant described:\n\n- `PRODUCT_DISCOUNT`: money off specific products or a category.\n- `ORDER_DISCOUNT`: money off the order total.\n- `BUY_X_GET_Y` and `BUY_X_GET_X`: buy one get one, and its variants.\n- `VOLUME_DISCOUNT`: quantity pricing. Each tier is `{ minQuantity, method, value }`, and `method` is `percentage`, `fixed_price` (a per-unit ceiling: `minQuantity` unlocks it, `value` is what one unit then costs) or `fixed_price_set` (a set price: `minQuantity` is the set size, `value` is the total for that whole set, repeating with any remainder at full price). \"3 for 499\" is `fixed_price_set`. Set as `fixed_price` it would mean 499 per single unit, which discounts nothing on a cheaper product.\n- `SHIPPING_DISCOUNT`: free or reduced shipping.\n- `BUNDLE`: a set of products priced together.\n\n**Coupon:** call `create_coupon` with the code the merchant chose. Codes are normalised to uppercase, so tell them the code as it will actually appear. If they want to know what the coupon would take off a real order before announcing it, `preview_coupon_for_order` computes it without applying anything.\n\n## Step 4: verify before you claim it worked\n\nCall `list_discount_rules` (or `list_coupons` for a code) and confirm the thing you just created is there with the status you expect. A creation call that returned without an error is not the same as a promotion the shopper will see.\n\nIf it is scheduled rather than active, say so plainly. Merchants read \"live\" as \"working right now\".\n\n## Step 5: tell the merchant, in their words\n\n**Automatic discount, use this shape:**\n\n> ✓ Your 20% off sale on Winter Jackets is set up and starts Monday 3 November, ending Sunday 9 November.\n>\n> Customers do not need a code. The lower price shows up on its own in the cart.\n>\n> Want me to turn it on now instead of Monday, or add anything else to it?\n\n**Coupon, use this shape:**\n\n> ✓ Your discount code SPRING20 is live now and runs until 31 March. It takes 20% off the order.\n>\n> Customers have to type SPRING20 at checkout for it to apply, so it only reaches the people you share it with.\n>\n> Want me to check what it would take off a typical order?\n\n**Could not do it, use this shape:**\n\n> I could not set that up: there is no category called \"Wintre Jackets\" in your store. The closest ones are Winter Jackets and Jackets. Which did you mean?\n\n## Rules\n\n- Verify with a listing tool before you say it is live. Every time.\n- Say \"code\" out loud whenever a coupon is involved, and say \"no code needed\" whenever it is a discount rule. The distinction is the whole point.\n- Use the store's real currency from `get_store`, and give dates as dates rather than \"next week\".\n- If the merchant asks for a discount on something that does not exist, name the closest real matches and stop. Do not put the sale on a product you guessed at.\n- Turning an existing promotion off is `toggle_discount_rule`, and it is worth offering when a merchant sounds worried about how much a sale is costing.\n- `delete_coupon` and `delete_discount_rule` exist on the full connector but are not on the ChatGPT app's curated list. If they are not in your tool list, say removal is done in the Brainerce dashboard. Either way, offer `toggle_discount_rule` first: switching off is reversible and deleting is not.\n- Never describe stacking behaviour you did not set. If the merchant asks whether the new sale combines with an existing one, read the rules back with `list_discount_rules` rather than guessing.\n\n## Loyalty points, rewards and tiers\n\nA loyalty programme is the other way merchants take money off, and it is a different mechanism from both a discount rule and a coupon: shoppers earn points on what they spend and redeem them for rewards, with tiers giving better earn rates to bigger spenders. On the full connector:\n\n- `get_loyalty_program` reads the current setup and `get_loyalty_overview` gives the headline numbers. `upsert_loyalty_program` turns it on and sets the per-order earn rate.\n- `list_loyalty_earning_rules`, `create_loyalty_earning_rule`, `update_loyalty_earning_rule` and `delete_loyalty_earning_rule` are the flat bonuses: a fixed number of points once per customer for SIGNUP, REVIEW_SUBMITTED or SOCIAL_SHARE, one rule per action.\n- `list_loyalty_members`, `get_loyalty_member` and `list_loyalty_transactions` answer \"how many points does this customer have\" and \"where did they come from\".\n- `adjust_loyalty_points` credits or debits one member by hand, which is the goodwill gesture merchants ask for after a complaint.\n- `list_loyalty_rewards`, `create_loyalty_reward`, `update_loyalty_reward` and `delete_loyalty_reward` are what points can be spent on.\n- `list_loyalty_tiers`, `create_loyalty_tier`, `update_loyalty_tier` and `delete_loyalty_tier` are the Bronze/Silver/Gold ladder. `recalculate_loyalty_tiers` re-evaluates every member today instead of tonight; it demotes as well as promotes, with no preview and no undo, so say that before running it.\n- `list_loyalty_badges`, `create_loyalty_badge`, `update_loyalty_badge` and `delete_loyalty_badge` are display-only milestones (orders placed, lifetime spend, referrals, reviews) with no points and no discount value.\n- `list_membership_plans`, `create_membership_plan`, `update_membership_plan` and `delete_membership_plan` are paid clubs: a subscription a shopper buys for a points multiplier. ⛔ A plan defines a recurring charge to real customers, the price is not snapshotted per subscriber (raising it re-prices everyone at their next cycle), and `isActive: false` stops new sign-ups without cancelling anyone. Read `list_membership_plans` first and confirm price, interval and currency with the merchant before creating or changing one.\n- `list_loyalty_referrals` and `reject_loyalty_referral` handle the referral funnel, including FLAGGED referrals for review; rejecting one reverses the referrer's points and cannot be undone.\n- `get_loyalty_widget_settings` and `upsert_loyalty_widget_settings` configure the embeddable points panel; `allowedDomains` replaces the whole list, so read it first.\n- `get_loyalty_analytics` is points issued and redeemed, liability, members by tier and the referral funnel for a period.\n\n### ⛔ Read this before activating a club\n\nA loyalty club earns points through the per-order rate on the program and the flat earning rules (signup, review, social share). A club with neither configured earns nothing. That exact state has shipped before and read to the merchant as \"loyalty is broken\": ACTIVE, members joining, zero points anywhere. So after `upsert_loyalty_program` creates the club, either confirm the per-order rate is what the merchant wants or create at least one earning rule (SIGNUP is the usual first one), and say which you did. Two more reasons a club shows no points: points from a new order are pending for the programme's pending window, and an order paid through a test-mode provider earns nothing by design.\n\nAn assistant can create the club, its earning rules, badges and paid plans, but it cannot cancel a member's paid subscription; the member does that from their own account. Say so when a merchant asks you to \"cancel her membership\": deactivating the plan stops new sign-ups and nothing else.\n\nTwo constraints, both worth checking before you promise anything:\n\n- ⛔ **Every loyalty tool is OAuth-only.** On a `brainerce_` API-key connection they all refuse with \"This tool requires OAuth authentication and is not available via API key\".\n- **None of them are on the ChatGPT app's curated list.** If they are not in your tool list, loyalty is a dashboard job, under Customers, then Loyalty.\n\nDo not describe points as a discount. A shopper earning 5% back in points is not the same offer as 5% off, the money leaves the merchant at a different time, and merchants who conflate the two get a surprise.\n\n## Cross-skill connections\n\n- Setting up shipping zones and rates, as opposed to discounting shipping: `brainerce-store-architecture`.\n- Performance of a promotion after the fact: `brainerce-analytics`.\n- Sweeping the store for expired or forgotten promotions: `brainerce-store-health`.\n- A specific order that should have been discounted: `brainerce-order-handling`.\n\nRoute once, and do not bounce back and forth.\n"
}