Brainerce

View saved version →

---
name: brainerce-analytics
description: 'Answer how much, how many, what is best and what is the trend for a Brainerce store, using the right reporting tool instead of counting rows by hand. Use when the merchant asks about revenue, sales, total orders, average order value, best or worst sellers, how this month compares to last, whether a sale worked, how many customers, or what people think of a product. Turns a plain question into the correct statistics call and answers with a number plus what it means. Also owns retention, coupon performance, stock velocity, traffic and connection health. For store owners, not developers. Not for the morning check-in (brainerce-daily-summary), acting on one order (brainerce-order-handling) or a health sweep (brainerce-store-health). Keywords: revenue, sales, how much, how many, total, average order value, AOV, best sellers, trend, compare, month over month, growth, conversion, retention, repeat customers, stock velocity, traffic, ratings, reviews, report, analytics.'
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: '1.0.0'
---

⛔ **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.

Turn a merchant's question into the right reporting call, and give back a number that means something.

## Core principle

A number without a comparison is not an answer. "You made 12,400 this month" leaves the merchant no wiser than before they asked. "12,400 this month, up from 9,800 last month" is the answer they were actually looking for. Always fetch the comparison period.

And never count by hand. Paging `list_orders` to sum revenue is slow, is capped, and quietly gives a wrong total when the results run past the first page. The statistics tools exist because that failure is easy to miss.

## When to use this skill first

- Money: revenue, sales, totals, average order value.
- Counts: how many orders, how many customers, how many of a product sold.
- Rankings: best sellers, worst sellers, top customers.
- Trends and comparisons: this month against last, is it growing, did the sale work.
- Product sentiment: ratings and what reviewers said.

## When NOT to use this skill first

- General "how is it going" first thing in the morning: use `brainerce-daily-summary`.
- One order, one customer, one action: use `brainerce-order-handling`.
- Finding problems rather than measuring: use `brainerce-store-health`.
- Setting up a promotion, as opposed to measuring one: use `brainerce-launch-a-sale`.

---

## Question to tool

| The merchant asks                                                     | Call                                                                                                                                                                                                                                                                                |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "How much did I make", "revenue this month", "how are sales"          | `get_store_analytics_summary`                                                  

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: brainerce-checkout-flows
description: 'Get the non-negotiable Brainerce sequences right: checkout, registration and email verification, login, password reset, cart persistence, inventory reservation and order confirmation. Use when a developer is building or debugging any of those, or asks why is my order not appearing, the payment succeeded but nothing happened, my reservation expired, the cart empties on refresh, or what order do these calls go in. These flows are fixed regardless of framework, and improvising one produces orders that never complete and stock that never releases. For developers. Do not choose this for the signature of a single method, use brainerce-sdk. Do not choose this to plan a whole storefront, use brainerce-storefront-build. Do not choose this for a merchant asking where a specific customer order is, use brainerce-order-handling. Keywords: checkout, payment, order confirmation, handlePaymentSuccess, waitForOrder, reservation, cart persistence, login, email verification, reset password, OAuth callback.'
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: '1.1.0'
---

Implement the sequences that have to happen in a fixed order, in the fixed order.

## Core principle

These flows are not conventions and they are not style. Each step exists because the step after it depends on state the step before it created. Reordering them, or dropping a step that looks redundant, produces failures that are silent at build time and expensive at runtime: payments taken with no order attached, stock held forever, customers stranded on a spinner.

Framework is irrelevant here. The sequence is the same in Next.js, Remix, Astro, Nuxt and plain React.

## When to use this skill first

- Building checkout, cart, auth or order confirmation.
- "What order do these calls go in".
- Debugging: payment succeeded but no order, reservation expired mid-checkout, cart empties on refresh, verification email never arrives, OAuth callback lands nowhere.
- Anything where the calls look individually right and the outcome is wrong.

## When NOT to use this skill first

- One method's arguments or return type: use `brainerce-sdk`.
- Planning or scaffolding the whole storefront: use `brainerce-storefront-build`.
- Auditing what is already built: use `brainerce-integration-verify`.
- A merchant asking about a real customer order in their shop: use `brainerce-order-handling`, which is a different tool surface entirely.

---

## The flows, and where each one is written down

`references/business-flows.md` is the authoritative sequence list. Read the relevant flow there before writing code, not after the first bug.

| Flow                   | Reference                          | The step people drop                                                                                         |
| ---------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Checkout end to end    | `references/checkout.md`           | Confirming the order after payment returns, rather than assuming payment success means order created         |
| Payment                | `references/payment.md`            | ONE `client.startPayment()` call for every provider, with no provider-specific code     |
| Order confirmation     | `references/order-confirmation.md` | `completePaymentReturn` (it waits for the order), then `handlePaymentSuccess`; plus the `/payment-complete` page |
| Cart                   | `references/cart.md`               | Persistence across reloads and across login                                                                  |
| Inventory reservation  | `references/inventory.md`          | Showing the countdown, and releasing the hold when the customer leaves                                       |
| Registration and login | `references/auth.md`               | The 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 9 — file references are metadata, not package contents.

View saved version →

---
name: brainerce-content-and-navigation
description: 'The words on a Brainerce storefront that are not product copy: static pages, FAQs, footers, the header and its navigation links, announcement bars, the blog, and the SEO around them. Use when the merchant asks where do I write my About page, how do I add a shipping policy, can I add a banner at the top, or how do I get found on Google. Says which pieces exist, where each is configured, and which a storefront must read before anything shows up. Also owns the contact form. Content, blog and contact-form tools are OAuth-only and absent from the ChatGPT app, and navigation has no tool at all, so it gives exact dashboard routes rather than pretending. For store owners and for developers wiring content in. Do not choose this for products, categories or tags, use brainerce-store-architecture. Do not choose this for product specs, use brainerce-custom-fields. Keywords: pages, about page, policy page, terms, FAQ, footer, header, navigation, menu, announcement bar, blog, contact form, SEO, meta description, sitemap.'
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: '1.0.0'
---

⛔ **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.

Get the non-product words onto a storefront, and be exact about what the platform does and does not do for you.

## Core principle

Everything in this skill is **data, not a rendered page**. Brainerce stores the words and exposes them through the SDK; the storefront decides where they appear. A merchant who writes an FAQ and sees nothing on their site does not have a broken FAQ, they have a storefront that is not asking for it yet.

That distinction is the answer to most questions here, so lead with it rather than burying it.

⛔ **Check your tool list before you say this cannot be done, because the answer differs by connection.**

- **On the ChatGPT app**, which carries a curated list, none of it is reachable. There is no content tool, no page tool and no blog tool on it. Give the dashboard route and never report a content change as done.
- **On the full connector**, content and blog tools do exist: `list_content`, `get_content`, `create_content`, `update_content`, `publish_content`, `unpublish_content` and `delete_content` for the six content types, and `list_blog_posts`, `get_blog_post`, `create_blog_post`, `update_blog_post`, `publish_blog_post`, `unpublish_blog_post` and `delete_blog_post` for the blog.
- ⛔ **Every one of those is OAuth-only.** A merchant connected with a `brainerce_` API key gets "This tool requires OAuth authentication and is not available via API key" from all of them, and no amount of retrying changes it. On an API-key connection the dashboard route below is the whole answer.

There is still **no navigation tool of any kind**, on any connection. A menu is the category tree plus a Header content entry, and that holds everywhere.

## When to use this skill first

- "Where do I write my About page / shipping policy / terms".
- "Can I put a banner across the top of my site".
- "How do I change my menu", "how do I add a link to the header".
- "Where does my blog live", "how do I publish an article".
- "How do I get found on Google", "where is my meta description".
- A developer wiring pages, footers or announcements into a storefront.

## When NOT to use this skill first

- Products,

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: brainerce-custom-fields
description: 'Work with Brainerce custom fields, also called metafields: the structured extra data a product carries beyond its built-in fields. Use when the merchant says add a spec to my products, where do I put materials or care instructions, I need a size guide link on every item, let customers type an engraving, or make this filterable on my shop. Covers the definition versus value split, which of the fifteen types to pick, and the two flags that decide whether a field is buyer-facing or filterable. Writes values only over an OAuth connection; on an API key the metafield tools refuse outright. Creating a definition is a dashboard step either way, and this skill says so rather than pretending. For store owners, and for developers reading fields on a storefront. Do not choose this to decide whether a property should be a custom field at all, that is brainerce-store-architecture. Keywords: custom fields, metafields, specs, materials, care instructions, engraving, storefront filter, product attributes.'
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: '1.0.0'
---

⛔ **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.

Put structured data on products correctly, and be honest about the half of it that lives in the dashboard.

## Core principle

A custom field is two separate things, and confusing them is the single most common failure here.

- A **definition** is the field itself: its name, its type, its allowed values, whether shoppers can fill it in, whether it can be filtered by. It is created once, in the dashboard, and applies across the store.
- A **value** is what one product holds for that definition. Values are per product, and optionally per variant.

**This connector writes values. It cannot create definitions.** Say that out loud the moment it matters, rather than attempting a write that fails.

## ⛔ Not every "custom field" is this one

Brainerce has three, and they are unrelated systems with different tools behind them. Reading the merchant's words as this one when they mean another is how you end up saying a feature does not exist.

- **Product custom fields (metafields)** — extra data on a product. This skill.
- **Checkout custom fields** — questions the shopper answers while buying: a gift message, a company tax id, a delivery note. Managed under Checkouts.
- **Order custom fields** — the store's own fields on one order: a reference number, a PO number, a licence key. Managed under Orders, and handled by `brainerce-order-handling` with `list_order_custom_fields` / `set_order_custom_fields`.

"Add a field so I can record the supplier's reference on each order" is the third, not the first. Nothing in this skill will find it.

## ⛔ Check the connection before you start: this skill needs OAuth

`list_product_metafields`, `get_product_metafield` and `set_product_metafield` are **OAuth-only**. On a connection made with a `brainerce_` API key every one of them fails with "This tool requires OAuth authentication and is not available via API key". That is the whole working sequence below, so on an API-key connection **nothing in this skill runs** and retrying will not help.

If that is the error you get back, do not read it as a missing field, a wrong `definitionId` or a broken store. Say the connection cannot reach custom fields, and t

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: brainerce-daily-summary
description: 'Give a Brainerce store owner one short morning briefing: what sold, what came in overnight, what needs attention today. Use when the merchant says how is the store doing, what happened yesterday, catch me up, morning report, daily summary, any orders overnight, or what do I need to deal with today. Assembles sales figures, order counts and low-stock warnings into a single readable answer instead of three separate tool dumps. For store owners, not developers. Do not choose this for one specific metric or a trend question such as which product sells best or how does this month compare to last, use brainerce-analytics. Do not choose this for a full audit of drafts, expired promotions and stuck orders, use brainerce-store-health. Do not choose this to act on a particular order, use brainerce-order-handling. Keywords: daily summary, morning report, briefing, catch me up, overnight, how is the store doing, today, yesterday, standup, dashboard.'
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: '1.0.0'
---

Produce the one message a store owner wants with their first coffee: what happened, what it means, what to do next.

## Core principle

This is a briefing, not a data dump. The merchant asked one question, so give one answer. Numbers only earn their place if the merchant could act on them or would notice their absence. Never open with a wall of raw tool output.

## When to use this skill first

- "How is the store doing", "catch me up", "what did I miss".
- "Any orders overnight", "what happened yesterday".
- "What do I need to deal with today".
- Any opening message that is a general check-in rather than a specific question.

## When NOT to use this skill first

- One metric or a comparison: "what is my average order value", "how does this week compare to last": use `brainerce-analytics`.
- A deliberate sweep for problems across the whole store: use `brainerce-store-health`.
- Anything about one named order or customer: use `brainerce-order-handling`.

---

## Assemble the briefing

Call these, and do not stop at the first one that returns something interesting.

1. **`get_orders_stats`** for order counts and totals by status. This is the spine of the briefing: how many came in, how many are waiting on you.
2. **`get_store_analytics_summary`** for revenue over the period. Pair it with the previous period so the number has a direction, not just a size.
3. **`get_recent_orders`** for what actually came in, so you can name a real order rather than only a count.
4. **`get_orders_by_status`** for the shape of the backlog. ⛔ It answers "roughly how many are waiting" and nothing else: a count and a percentage per status, with **no order ids and no dates**, counting only the **last 30 days**. It cannot tell you which order has waited longest, and an order stuck since before that window is not in its numbers at all.
   For the oldest waiting order, which is the line the merchant actually acts on, call `list_orders` with `sortBy: "createdAt"` and `sortOrder: "asc"`. It returns `orderNumber`, `customerName` and `createdAt` per row and has no date window. The `status` filter takes one status at a time; the waiting-on-you states are `PENDING`, `PROCESSING`, `PAID` and `ON_HOLD`.
5. **`get_product_inventory`** on the products that matter, to catch anything about to run out. `get_top_selling_products` first tells you which products those are; a best seller at two units left is worth a line, a slow mover at two units left is not.

Read the store's currency and locale from `get_store` before you write any money figure.

## Shape the answer

Three parts, in this order, and keep the whole thing short enough to read on a phone.

1. **What happened.** Orders and revenue for the period, with a comparison so the merchant knows whether it is good.
2. **What needs you.** Unfulfilled orders, anything pending, stock about to run out. Thi

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: brainerce-email-campaigns
description: 'Send a marketing email to a Brainerce store''s customers safely: pick the audience, write or reuse the email, check who it reaches, then send or schedule it. Use when the merchant says email my customers, send a newsletter, announce the sale by email, email my VIP buyers, save this as a template, schedule an email for Friday, who would get this email, or make a customer segment. Covers saved customer segments, campaign templates, drafting, the recipient count check and the send itself. A send reaches real people and cannot be recalled, so this skill puts the count check and the merchant''s yes before it. For store owners, not developers. Do not choose this for the signup welcome coupon or for a promotion itself (brainerce-launch-a-sale), for a fundraising drive (a donation campaign), or for transactional order emails. Keywords: email campaign, newsletter, email blast, segment, audience, template, schedule send, mailing list, send email to customers.'
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: '1.0.0'
---

Get an email to the right customers without a mistake the merchant cannot undo. Everything before the send is reversible. The send is not.

## Core principle

A sent email is read by a person and cannot be recalled. So the order is fixed: decide who, write it, count who it reaches, tell the merchant the number, and only then send. Never skip the count, and never send on a merchant's general wish ("email everyone about the sale") without showing them the recipient number first.

## Find the tools

Most of these are not in the tool list you can see in ChatGPT. Find them with `search_tools` and run them with `call_read_tool`, `call_write_tool` or `call_destructive_tool`. Search with the platform's nouns, not the merchant's words: `campaign`, `campaign audience`, `campaign template`, `customer segment`, `campaign schedule`, `campaign block`. "Newsletter" in a search finds the signup welcome offer, not this.

Segment and template tools need a signed-in dashboard user (OAuth). An API key is refused with a message that says so.

## When NOT to use this skill

- "A code for people who sign up to my newsletter": that is the newsletter welcome offer, a coupon, under `brainerce-launch-a-sale`.
- A fundraising drive with a goal and a donation page: a donation campaign (`create_donation_campaign`), not an email.
- Order confirmation, shipping and password emails: those are transactional templates, not campaigns.
- A discount or sale itself: `brainerce-launch-a-sale`.

---

## Step 1: who gets it

Pick one of two audiences.

- **A saved segment**, for a group the merchant will want again ("repeat buyers", "customers who have not ordered in 90 days"). Look first with `list_customer_segments`. If none fits, build one.
- **A hand-picked list** of customer ids (`audienceType` SELECTION) or a one-off filter (`audienceType` FILTER with `audienceFilterJson`).

### Building a segment

A segment is a condition tree: `{ kind: "group", operator: "AND" | "OR", conditions: [...] }`, where each leaf is `{ kind: "condition", field, op, value }`. The tool description lists every field and the operators it accepts. Use only those: an unknown field or operator is refused, not guessed.

1. **`preview_customer_segment`** with the tree. It returns how many customers match and up to five names, and saves nothing. Always run it first.
2. Tell the merchant the number in plain words ("that is 214 customers") and ask if it looks right.
3. **`create_customer_segment`** with a name. The name must be unique in the store.

⛔ A tree that matches nobody, or everybody, is almost always a wrong condition. A segment of 0 is not a result to save: check the field and the value.

## Step 2: the email

- **Start from a saved template** when the merchant has one: `list_campaign_templates`, then `get_campaign_template` for the body. Saving a new one is

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: brainerce-integration-verify
description: "Audit a Brainerce storefront against the mandatory-feature checklist and the critical rules, and report what is missing, present but unreachable, or wrong. Use when a developer says is my integration complete, check my Brainerce build, did I miss anything, review this before launch, why is this feature not working, or before shipping a storefront to a real store owner. Walks the actual code rather than trusting that a file exists, with particular attention to the features that are almost always skipped. For developers. Do not choose this to build something new, use brainerce-storefront-build. Do not choose this for one method's signature, use brainerce-sdk. Do not choose this for the correct order of a checkout or login sequence while writing it, use brainerce-checkout-flows. Do not choose this for a merchant auditing their shop's products and promotions, that is brainerce-store-health. Keywords: verify, audit, checklist, did I miss anything, pre-launch, mandatory features, critical rules, ready to ship."
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: '1.0.0'
---

Check a Brainerce integration honestly, feature by feature, against what is actually required.

## Core principle

Reachable in the running UI, or it does not count. A component that exists in the repo but no route renders is not an implemented feature, and reporting it as one is how storefronts ship with no password reset. Walk the code and trace each feature to something a customer can actually get to.

## When to use this skill first

- "Is my integration complete", "did I miss anything", "check this before launch".
- Handing a build to a real store owner.
- "This feature is not working and I do not know why".
- After following `brainerce-storefront-build`, as the closing step.

## When NOT to use this skill first

- Building something new: use `brainerce-storefront-build`.
- One method's signature: use `brainerce-sdk`.
- Getting a sequence right while writing it: use `brainerce-checkout-flows`.
- A shop owner auditing products and promotions in their store: that is `brainerce-store-health`, a merchant skill on a different tool surface.

---

## How to run the audit

### 1. Establish what is required

`references/required-features.md` is the checklist. Each entry is marked either MANDATORY or BUILD when the store has it enabled. Count them from the file rather than from memory, because entries get added: a number quoted here would be stale within the week. It is a functional coverage list, not a page list or a file tree, so audit each entry as a capability a customer can reach however the build lays it out. The sequences each feature has to follow are in `skills/brainerce-checkout-flows/references/business-flows.md`, and the rules that cause incidents in `skills/brainerce-storefront-build/references/critical-rules.md`, which is where each of those lives (this skill keeps no copy of either). Read them at those paths, or call `get-business-flows` and `get-critical-rules` when the MCP server is connected.

When the Brainerce MCP server is connected (Claude Code, Cursor, or the CLI), `get-required-features` with the connection id returns the list tailored to that store's live configuration. Prefer that. In ChatGPT there is no connection, so use the reference file and say that the audit is against the general checklist rather than that specific store.

⛔ **Mandatory features must exist even when the store has them switched off today.** They auto-hide, and the owner turns them on months later without touching the code. A build that omits them is not complete, it is a delayed outage. Do not mark a feature as not applicable because the store currently has it disabled.

### 2. Walk the code, feature by feature

For each item, find the code, then find the route or component that makes it reachable. Both, not either.

Pay closest attention to the o

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: brainerce-launch-a-sale
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.'
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: '1.0.0'
---

⛔ **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.

Take a merchant from "put this on sale" to a promotion that is live, correct, and described back to them accurately.

## Core principle

You 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.

## When to use this skill first

- The merchant wants money taken off something: a product, a category, an order total, or shipping.
- The merchant asks for a discount code to hand out.
- The merchant wants a promotion scheduled for a date range or a named shopping event.
- The merchant asks whether a sale they set up is running.

## When NOT to use this skill first

- "How much did the sale make", "did the promotion work", "what is my revenue this week": use `brainerce-analytics`.
- "Find promotions I forgot to turn off", "audit the store": use `brainerce-store-health`.
- "The order should have had the discount on it": that is an order question, use `brainerce-order-handling`.
- ⛔ **"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.

---

## Step 1: automatic discount, or a code? Decide this before anything else

Two different things are called a discount, and they behave differently for the shopper.

|                    | Automatic discount                                                | Coupon                                                                |
| ------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------- |
| Tool               | `create_discount_rule`                                            | `create_coupon`                                     

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: brainerce-order-handling
description: 'Work a single Brainerce order from question to action: look it up, understand its state, then fulfil, move its status or cancel it. Use when the merchant says where is order 1042, this customer is asking about their order, mark this as shipped, add tracking, or cancel this one. Includes when NOT to touch an order, and the pay-before-fulfill gate that blocks shipping an unpaid order. Also owns manual orders, status labels, shipping labels and the contact-form inbox; those, plus refunds and returns, are on the full connector and not the ChatGPT app, so check the tool list. For store owners, not developers. Do not choose this for counts and totals across many orders, use brainerce-analytics or brainerce-daily-summary. Do not choose this to sweep for stuck orders across the whole store, use brainerce-store-health. Keywords: order, fulfil, ship, tracking number, cancel order, order status, where is my order, refund, return, mark as paid, manual order, status label, shipping label, inquiry, order custom fields.'
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: '1.0.0'
---

⛔ **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.

Handle one order well: read it fully, act only where acting is right, and tell the merchant exactly what the customer will now see.

## Core principle

Order actions are visible to a real customer within seconds. Fulfilling sends an email. Cancelling cannot be undone from here. So the order gets read in full before anything changes, and the merchant is told what the customer will receive before you send it, not after.

## When to use this skill first

- A named or numbered order: "where is 1042", "this one has not shipped".
- A customer question routed through the merchant: "she is asking where her parcel is".
- An action on one order: mark shipped, add tracking, move status, cancel.
- "What has this customer bought before".
- "Put an order in for this phone customer", "invoice this business customer".
- "Did anyone write to us", "answer this customer's message".
- "Buy a label for this order", "where is her parcel".

## When NOT to use this skill first

- Counts, totals or trends across many orders: use `brainerce-analytics`, or `brainerce-daily-summary` for the morning view.
- Sweeping the store for orders stuck in one state: use `brainerce-store-health`.
- The order should have had a discount and did not: check the promotion in `brainerce-launch-a-sale`.

---

## Step 1: find and read the order

- Order number or id: `get_order`.
- Vaguer than that: `list_orders`, or `get_recent_orders` for "the one that came in this morning".
  `list_orders` takes `page`, `limit`, `search`, `status`, `sortBy` and `sortOrder`. ⛔ There is **no date filter and no customer filter**, and `search` only matches the external order id, not a name or an email. `status` takes one status at a time. To reach the oldest of a state, pass `sortBy: "createdAt"` with `sortOrder: "asc"`.
- A customer's history, so "what has this person bought before": `get_customer` to identify them, then `get_customer_orders`. That pair is the route, because a customer is not something `list_orders` can filter on.

Read the whole order before proposing anything. Its current status determines which actions are even sensible, and the line items determine what y

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: brainerce-product-onboarding
description: 'Add a product to a Brainerce store properly, from creating it through to category, tags, stock and publishing. Use when the merchant says add a product, list this item, put this in the shop, set up my new range, copy an existing product, or fix the stock count on something. Also covers duplicating a product, publishing the whole catalog to a storefront, stock corrections and stock history. For store owners, not developers. A price or description edit on a set-up product needs no sequence. Not for reviews (brainerce-analytics), finding drafts (brainerce-store-health) or variant versus custom field (brainerce-store-architecture). Keywords: add product, new product, create product, stock count, inventory, restock, categorise, tags, publish, publish all, duplicate product, bulk import, CSV import, product images, alt text, stock history, sale price dates.'
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: '1.0.0'
---

⛔ **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.

Get a new product from "I have this thing to sell" to a listing customers can actually find and buy.

## Core principle

A created product is not a finished product. A merchant who is told "done" and then finds the item invisible on their own storefront, uncategorised, or with no stock, has been misled. Walk the whole sequence, and say which parts you skipped.

## When to use this skill first

- "Add a product", "I have something new to sell", "list this".
- "Set up my new range" or several products at once.
- "Make another one like this": duplicating an existing listing.
- "Fix the stock on X", "I counted 40 of these".

## When NOT to use this skill first

- Changing a price or a description on an existing, fully set up product: just do it, no sequence needed.
- "What do people think of this product", ratings and reviews: use `brainerce-analytics`.
- "Find products I left as drafts": use `brainerce-store-health`.
- "Put this product on sale": use `brainerce-launch-a-sale`.
- "Should size be a variant or an option", or any question about how the catalog should be modelled before the product exists: use `brainerce-store-architecture`.

---

## The sequence

Do these in order. Later steps depend on earlier ones, and skipping one is how products end up invisible.

### 1. Look before you create

Call `list_products` with the name the merchant gave. If something close already exists, say so and ask whether they want a new product or an edit to that one. Creating a near-duplicate is easy to do and annoying to undo, and on the ChatGPT app there is no delete tool to clean it up with.

If the merchant wants something very like an existing product, `duplicate_product` is faster and less error prone than retyping everything. Duplicate first, then edit the differences with `update_product`.

### 2. Create it

Call `create_product`. Ask for what is missing rather than filling it in yourself:

- **Name** and **price**, always. Read the currency from `get_store`; do not assume.
- **Description**: offer to draft one, but show it to the merchant before it goes live. This is their voice, on their storefront.
- **A photo the merchant attached to the chat**: on the ChatGPT app there is no route for it. The receiving field was withdrawn on 2026-09-23 after the submission portal refu

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: brainerce-sdk
description: 'Look up the real shape of the Brainerce storefront SDK: method names, arguments, return types and the TypeScript definitions behind them. Use when a developer asks what does this SDK method take, what comes back from it, what is the type of a product or an order, how do I fetch products with variants, which method loads a category, or is there a method for this at all. This is the reference, so reach for it whenever you are about to write a Brainerce call and are not certain of its exact signature. For developers. Do not choose this for the ordered sequence a checkout or login has to follow, use brainerce-checkout-flows. Do not choose this to plan or scaffold a whole storefront, use brainerce-storefront-build. Do not choose this for admin or dashboard operations such as creating a product as a merchant, those are merchant skills. Keywords: SDK, method, signature, arguments, return type, TypeScript types, interface, BrainerceClient, getProducts, types, API reference, does this method exist.'
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: '1.1.0'
---

Be certain about a Brainerce SDK call before writing it.

## Core principle

An invented method is the most expensive mistake available here. It compiles, it reads well, it fails at runtime in front of a customer, and it is hard to spot in review because it looks exactly like a real call. So: if a method is not in these references, it does not exist. Say so and offer the closest real one rather than producing something plausible.

## When to use this skill first

- "What arguments does this take", "what comes back".
- "What is the type of a product, an order, a cart line".
- "Is there a method for X".
- Any moment you are about to write a Brainerce call and are not certain of the exact name or shape.

## When NOT to use this skill first

- The order of operations for checkout, login, password reset or inventory reservation: use `brainerce-checkout-flows`. Signatures are here; sequences are there, and a correct call in the wrong order still breaks.
- Planning or scaffolding a storefront: use `brainerce-storefront-build`.
- Auditing an existing integration: use `brainerce-integration-verify`.
- Merchant-side operations through the admin connector: those are the merchant skills, and they use a different tool surface entirely.

---

## How to use the references

- `references/type-definitions.md` is the full TypeScript surface. Search it for the type name before describing any shape.
- `references/sdk-setup.md`: creating and configuring the client, and the options it takes.
- `references/sdk-products.md`: catalog reads, variants, modifier groups, the real product shape.
- `references/sdk-content.md`: pages, blog and content reads.
- `references/sdk-tax.md`: tax handling and how totals are presented, including where a gift card goes in the order summary. It is a means of payment, not a discount, so it sits BELOW the total with an "Amount due" row and never inside the discount block.
- `references/sdk-gift-cards-admin.md`: the eight admin gift-card methods, the scope each needs, and the one rule that matters most here: a storefront must never hold `gift_cards:issue`. A storefront redeems (`applyGiftCard`, `removeGiftCard`, `checkGiftCardBalance`) and needs no API key to do it.
- `references/sdk-account-cart-and-offers.md`: the account address book and OAuth links, order bumps and bundles, recommendations and nudges, the cart badge and lifecycle hooks, pre-checkout stock validation, locale discovery, `trackEvent`, and guest download retrieval. Each entry names the modes it works in, because several of these throw outside one specific mode.

When the Brainerce MCP server is connected (Claude Code, Cursor, or the CLI), `get-sdk-docs` and `get-type-definitions` serve the same content live and reflect the installed SDK version. Prefer them there. In ChatGPT there is no such connec

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 9 — file references are metadata, not package contents.

View saved version →

---
name: brainerce-store-architecture
description: 'Decide how a Brainerce catalog should be structured, and audit an existing one: what becomes a variant, what becomes a custom field, what becomes a category, what becomes a tag. Use when the merchant asks how should I organise my shop, should this be a variant or an option, categories or tags, or I have too many variants to manage. Also owns store settings (currency, language, going live), shipping zones, rates, labels, sales-channel publishing, subscriptions, apps, email domains, webhooks and backups. Free shipping as a standing rate lives here; as a promotion it does not. For store owners and developers deciding a data model. Do not choose this to add one product, that is brainerce-product-onboarding. Do not choose this for custom fields in depth, use brainerce-custom-fields. Do not choose this for pages or menus, use brainerce-content-and-navigation. Keywords: catalog structure, variant explosion, categories vs tags, shipping zones, sales channels, go live, currency, subscriptions, email domain, webhooks.'
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: '1.0.0'
---

⛔ **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.

Get the catalog model right the first time, or find out exactly where an existing one went wrong.

## Core principle

A Brainerce store has five different mechanisms for "this product has a property", and they are not interchangeable. Picking the wrong one is cheap on day one and expensive on day two hundred, because the fix means touching every product. So the modelling question comes before the create call, always.

The single test that resolves most of it: **does this property have its own stock count, its own price, or its own SKU?** If yes it is a variant. If no it is something else, and the rest of this skill says which.

## When to use this skill first

- "How should I organise my shop", "what is the right structure for this".
- "Should size be a variant or an option", "variant or custom field".
- "Categories or tags", "how do I build my menu".
- "I am about to add my first products" and nothing exists yet.
- "I have 400 variants on one product and I cannot manage it".
- "Review my catalog", "is my structure sensible".

## When NOT to use this skill first

- Adding one product now, the model already settled: `brainerce-product-onboarding`.
- Custom fields in depth, including writing values: `brainerce-custom-fields`.
- Pages, navigation copy, policies, blog, SEO: `brainerce-content-and-navigation`.
- A read-only sweep for drafts, empty stock and stuck orders: `brainerce-store-health`.
- Building the storefront code that renders any of this: `brainerce-storefront-build`.

---

## The five mechanisms

Where a tool is named below, "full connector" means Claude Code, Cursor and Claude Desktop connected to the Admin MCP, which lists every tool; the ChatGPT app carries a curated list, and each section says which of its tools are on it.

| Mechanism                       | What it is                                                                           | Own stock? | Where it is set up                                          |
| ------------------------------- | ------------------------------------------------------------------------------------ | ---------- | ----------------------------------------

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: brainerce-storefront-build
description: "Build a storefront on Brainerce, a headless commerce platform, in whatever framework the project already uses. Use when a developer says build me a store, scaffold a storefront, I have a Brainerce connection id, wire up the shop, add commerce to this site, or start a Brainerce project. Covers the ordered build path from store capabilities through catalog, cart and checkout, and the rules that cause production incidents when skipped. For developers. Brainerce is framework agnostic: Next.js, Remix, Astro, Nuxt and plain React all work. Do not choose this for merchant tasks such as adding a product or running a sale, those are brainerce-product-onboarding and brainerce-launch-a-sale. Do not choose this for one SDK method's exact signature, use brainerce-sdk. Do not choose this for the checkout sequence, use brainerce-checkout-flows. Do not choose this for content pages or blog, use brainerce-content-and-navigation. Keywords: storefront, headless commerce, scaffold, build a store, connection id, vc_, integrate."
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: '1.2.0'
---

Build a working Brainerce storefront: the right calls, in the right order, with the failures that bite in production already avoided.

## Core principle

Brainerce is headless and framework agnostic. It supplies commerce; the project supplies the framework, the routing and the design. Never rewrite someone's stack to suit an example. Customise design, copy and layout freely; do not customise SDK call sequences, business flows or auth handling, because those are where correctness lives.

## When to use this skill first

- "Build a storefront", "scaffold a shop", "add commerce to this site".
- The developer has a `vc_` connection id and wants to start.
- Wiring catalog, cart or product pages into an existing app.
- "What do I have to build for this to be a complete store".

## When NOT to use this skill first

- The exact signature, arguments or return shape of one SDK method: use `brainerce-sdk`.
- The checkout, auth, cart persistence or inventory reservation sequence: use `brainerce-checkout-flows`.
- Auditing a build that already exists against the required checklist: use `brainerce-integration-verify`.
- Anything a shop owner does in the dashboard rather than in code: use the merchant skills.
- Static pages, footers, the header's navigation links, announcements and the blog: use `brainerce-content-and-navigation`, which also carries the payload shapes and the sanitisation rule.

---

## Before the first line of code

**Connect last, not first.** Every storefront call is scoped by a connection id that looks like `vc_...`, and nothing in the code depends on which store it points at: pages, routing, cart, checkout and every SDK call are identical either way, and only one environment variable differs. So do not open the conversation by demanding an id, and do not stop for one mid-build. Read the user's intent, settle the framework, the routing and the design, build the whole storefront reading the id from its environment variable, and get a real id at exactly one moment: when the build is done and the storefront should load real data. How you get it is decided by what you can do, not by preference:

- **In ChatGPT with the Brainerce app installed:** call `list_sales_channels`; reuse a channel that fits, otherwise call `create_sales_channel`. That first call is what opens ChatGPT's own sign-in window, once. If the person has no Brainerce account yet, that same window creates the account and the store (they type the store name and click Allow), closes, and the tool returns the id. Nobody visits a dashboard and nobody copies anything. Then tell them which variable to put it in.
- **With a shell:** scaffold with `--defer-connection` and finish with `npm run connect` inside the project (details under "Don't burn the run").
- **Neither:** ask in o

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 12 — file references are metadata, not package contents.

View saved version →

---
name: brainerce-store-health
description: "Sweep a Brainerce store for the things that quietly go wrong and hand the merchant a short list of what to fix. Use when the merchant says check my store, is everything ok, spring clean, audit the shop, what am I missing, anything broken, or I have not looked at this in a while. Finds products left as drafts, items out of stock, promotions that expired or were never switched off, orders stuck waiting on someone, and on the full connector dead webhooks, bounced emails and a missing backup schedule. For store owners, not developers. Not for the morning check-in (brainerce-daily-summary), one metric or trend (brainerce-analytics), one known order (brainerce-order-handling), or how the catalog is structured rather than its state (brainerce-store-architecture). Keywords: store health, audit, check my store, spring clean, tidy up, what is broken, drafts, out of stock, expired discount, stuck orders, housekeeping, review my shop."
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: '1.0.0'
---

⛔ **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.

Find the quiet problems a busy merchant stops seeing, and give them an ordered list of what to do about it.

## Core principle

The output is a to-do list, not a report. Every line should name a real thing, say why it costs the merchant something, and be actionable. A finding with no consequence attached gets ignored, and rightly so.

Read only. This skill diagnoses. Fixing happens after the merchant picks something.

## When to use this skill first

- "Check my store", "is everything ok", "anything broken".
- "Spring clean", "tidy up the shop", "audit this".
- "I have not looked at this in months".
- "What am I missing".

## When NOT to use this skill first

- The routine "how did yesterday go": use `brainerce-daily-summary`.
- One number or a trend: use `brainerce-analytics`.
- One known order: use `brainerce-order-handling`.
- How the catalog is STRUCTURED rather than what state it is in, so variant explosion, a flat category tree, tags doing a category's job: use `brainerce-store-architecture`. This sweep is about state; that one is about shape.

---

## The four sweeps, and a fifth on the full connector

Run all four, and the fifth when its tools are in your list. A sweep that finds nothing is still worth one line, because "no drafts left hanging" is information.

One call comes before them on a store that has taken no orders yet, or whenever the question is "what am I missing before I can sell": `get_store_setup_status`. It returns the six setup steps (store name, sales channel, products published to a channel, shipping, payment provider, tax) with done or not done and a `nextAction` for each, and a payment provider in test mode counts as not done. Report its first undone step at the top of the list, above anything the four sweeps find, because a store that cannot take an order has no other problem worth fixing first.

### 1. Products that are not really for sale

- `list_products` filtered to draft status: products the merchant created and forgot to publish. These are invisible to customers and the merchant usually believes they are live.
- `list_products` plus `get_product_inventory` on what comes back: items at zero stock. Cross-check against `get_top_selling_products`, because a best se

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.