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 sellers, 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. For store owners, not developers. Do not choose this for the general morning check-in, use brainerce-daily-summary. Do not choose this to act on a specific order, use brainerce-order-handling. Do not choose this for a health sweep of drafts and stuck orders, use brainerce-store-health. Keywords: revenue, sales, how much, how many, total, average order value, AOV, best sellers, top products, trend, compare, month over month, growth, conversion, ratings, reviews, report, statistics, analytics."
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: "1.0.0"
---

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` |
| "How many orders", "how many are still unpaid", "breakdown by status" | `get_orders_stats` |
| "What is my average order", "are people spending more" | `get_average_order_value` |
| "What sells best", "top products", "what should I restock" | `get_top_selling_products` |
| "How many orders are unfulfilled right now" | `get_orders_by_status` |
| "What came in today", "the last few orders" | `get_recent_orders` |
| "How many products do I have" | `count_products` |
| "Who are my best customers", "how many customers" | `list_customers` |
| "What has this customer spent" | `get_customer`, then `get_customer_orders` |
| "How is this product rated", "what do people say" | `get_product_review_stats`, then `list_product_reviews` |
| "Did the sale work" | `get_store_analytics_summary` for the sale window and the window before it, plus `list_discount_rules` to confirm the dates |

⛔ Do not answer a totals question by listing orders and adding them up. `list_orders` is a search tool. Its results are paged, so a hand count silently under-reports as soon as the period is busy, and the merchant has no way to tell.

## Getting the period right

- Read the store's timezone-sensitive settings and currency from `get_store` before quoting any figure. Never assume dollars.
- Turn "this month" and "last week" into explicit dates and state them in the answer, so the merchant can tell you if they meant something else.
- Fetch the comparison period in the same breath as the main one. It is one more call and it is what makes the answer useful.

## Answer shape

Lead with the number. Then the comparison. Then one observation, if there is a real one.

**Use this shape:**

> ✓ 12,430 ILS across 58 orders in November so far.
>
> That is up from 9,810 across 47 orders in the same stretch of October, so about 27% more revenue and a slightly higher average order.
>
> Most of the growth is Ceramic Mug, which went from 12 units to 31.

**Ranking, use this shape:**

> ✓ Your top sellers over the last 30 days, by units:
>
> 1. Ceramic Mug, 31 sold, 2,015 ILS
> 2. Linen Scarf, 18 sold, 2,340 ILS
> 3. Wool Hat, 14 sold, 1,120 ILS
>
> Worth noting: Linen Scarf brings in more money than Ceramic Mug despite selling fewer, so if you are deciding what to promote, it is not the same answer as "what sells most".

**Not enough data, use this shape:**

> There were only 3 orders in that window, so a percentage change would be misleading. Here are the raw numbers instead: 3 orders, 210 ILS, against 2 orders and 145 ILS the week before.

## Rules

- Always fetch a comparison period. A bare number is not an answer.
- Use the store's currency from `get_store`.
- State the exact dates you used.
- Say when the sample is too small for a percentage rather than reporting a 200% rise off two orders.
- Never sum a paged list by hand.
- Do not invent a cause for a change. "Revenue is up 27%" is a fact; "because of your Instagram post" is a guess, and this connector has no marketing data.
- Read only. If the merchant reacts to a number by wanting to act, hand off rather than acting here.
- If a tool returns nothing for the period, say the period was empty. Do not silently widen the window to find something.

## Cross-skill connections

- The general morning briefing rather than a specific question: `brainerce-daily-summary`.
- The merchant wants to act on a slow seller by discounting it: `brainerce-launch-a-sale`.
- They want to restock a best seller: `brainerce-product-onboarding`.
- The numbers point at a problem rather than a trend: `brainerce-store-health`.

Route once, and do not bounce back and forth.

Referenced files: 2

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.0.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` | Handling the provider callback and the return path separately |
| Order confirmation | `references/order-confirmation.md` | `handlePaymentSuccess` followed by `waitForOrder`; without the wait the page renders before the order exists |
| 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 six-digit email verification step, forgot and reset password, and the OAuth callback |

## The four failures worth naming up front

**"Payment succeeded but no order appeared."** The confirmation page rendered before the order existed. Payment success and order creation are not the same event and they do not land at the same moment. Call `handlePaymentSuccess`, then `waitForOrder`, then render. A confirmation page that reads the order straight out of the URL will work in testing and fail under real latency.

**"Stock is held and never comes back."** The reservation was created and never released. Reservations expire on their own, but a customer who abandons checkout should not wait out the timer, and the countdown has to be visible or they will not understand why the item vanished.

**"The cart empties when the page reloads."** Cart state was kept only in memory. Persistence is part of the flow, not an optimisation, and the cart also has to survive a customer logging in mid-session.

**"Customers cannot finish signing up."** Email verification with a six-digit code is a required step, and it is the single most commonly omitted piece of a Brainerce auth build. Registration without it produces accounts that exist and cannot be used.

## Rules

- Follow the reference sequence exactly. If a step looks redundant, it is load-bearing for something further down.
- Never treat a payment provider's success signal as proof the order exists.
- Always show the reservation countdown to the customer, and release the hold on abandonment.
- Build email verification, forgot password and reset password even if the brief did not mention them. They are mandatory features, not extras.
- Build the OAuth button area and callback handling even when the store currently has no providers configured. The area hides itself, and the store owner turns providers on later without touching the code.
- Never store an auth token in the browser without a backend-for-frontend in front of it.
- Prices are strings. Parse before arithmetic, including inside totals on the confirmation page.
- When debugging, walk the sequence in order and find the first step that did not happen. The visible symptom is almost never at the broken step.

## Response shape

> The order is missing because the confirmation page renders before it exists. Payment success and order creation are two separate events.
>
> The sequence has to be:
>
> 1. Provider returns to your confirmation route
> 2. `handlePaymentSuccess` with the payment reference
> 3. `waitForOrder`, which polls until the order is really there
> 4. Only then render the order
>
> Right now step 3 is missing, so under real network latency you render an empty page. It passes in testing because local round trips are fast enough to hide it.

## Reference files in this skill

`business-flows.md`, `checkout.md`, `payment.md`, `order-confirmation.md`, `cart.md`, `inventory.md`, `auth.md`.

These are snapshots of the Brainerce MCP server's own content. When that server is connected (Claude Code, Cursor, or the CLI), `get-business-flows` and `get-sdk-docs` serve the same material live. In ChatGPT it is not connected, and these files are the source of truth.

## Cross-skill connections

- Method signatures and types: `brainerce-sdk`.
- Planning the whole build: `brainerce-storefront-build`.
- Checking a finished build against the mandatory list: `brainerce-integration-verify`.

Route once, and do not bounce back and forth.

Referenced files: 9

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 put a banner across the top, how do I change my menu, where does my blog live, or how do I get found on Google. Says which pieces exist, where each is configured, and which a storefront must be built to read before anything shows up. Nothing here is reachable from this connector, so it gives exact dashboard routes instead of 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, banner, blog, articles, SEO, meta description, Google, sitemap."
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: "1.0.0"
---

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.

⛔ **None of this is reachable from this connector.** There is no content tool, no page tool, no blog tool and no navigation tool on the Brainerce ChatGPT surface. Give the dashboard route, and never report a content change as done.

## 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, categories, tags, variants: `brainerce-store-architecture`.
- Product specs and structured data on products: `brainerce-custom-fields`.
- Per-product SEO slug and meta description while adding a product: `brainerce-product-onboarding`.
- The SDK calls that fetch any of this: `brainerce-sdk`.
- Building the storefront that renders it: `brainerce-storefront-build`.

---

## The two places words live

### Content

The dashboard's **Content** section holds reusable pieces. Edit once, and every storefront reading that entry updates. Six kinds:

| Type | What it is for |
|---|---|
| **FAQ** | A list of question and answer pairs |
| **Footer** | Footer columns, links, copyright, social links |
| **Header** | Logo, navigation links, and a call to action |
| **Announcement** | The bar across the top: sales, shipping cut-offs, holiday notices |
| **Rich text** | A block of formatted copy a storefront can drop anywhere |
| **Page** | A full static page: About, Shipping Policy, Terms |

Create with **New content**, pick the type, write it. Every entry is **Draft** or **Published**, and only published entries reach a storefront.

### Blog

**Blog** publishes articles. **New post**, write, publish. Brainerce stores the article and exposes it; the layout belongs to the storefront.

### Which one

- Part of the furniture of the site, so footer, header, announcement bar, FAQ block: **Content**.
- An article with a date: **Blog**.
- A description of something you sell: neither, that is a product.

## Navigation, precisely

**There is no visual navigation builder in Brainerce.** Merchants ask for one, so say what there is instead of implying a page they will go looking for.

A storefront menu comes from two sources, and they do different jobs:

1. **The category tree.** Parent and child categories are the browsable structure: "Mobile" with "iPhone" and "Samsung" under it. Each category has its own landing page and a breadcrumb on every product in it. A storefront fetches the tree and renders it. This is where the shape of the menu is decided, and it is a catalog decision, so `brainerce-store-architecture` owns it.

2. **A Header content entry.** The `HEADER` type carries an optional logo, a list of navigation items as label plus URL pairs, and an optional call to action. This is where links that are not categories go: About, Contact, the blog, a landing page.

So "add Contact to my menu" is a Header entry edit, and "add Laptops to my menu" is a category. Ask which kind of link it is before answering.

## Static pages

A **Page** entry carries a slug in lower-kebab form, a title, the body, and its own SEO block: title, description and social image. That is what an About page, a Shipping Policy or a Terms page is.

The storefront still has to route it. A Page entry is not automatically live at `/about`; the storefront reads the entry and decides. If a merchant has published a page and cannot reach it, that is a storefront routing gap, not a content problem.

⛔ **Merchant-authored HTML is not sanitized by the server**, deliberately, because some merchants embed things a strict sanitizer would strip. Rich text bodies, page bodies and FAQ answers all arrive raw. A storefront rendering them must sanitize before injecting, and this is worth saying to a developer unprompted.

## Announcements

The `ANNOUNCEMENT` type carries the message, a severity of info, warning or success, whether it can be dismissed, an optional start and end time, and an optional call to action.

Two things to tell a merchant:

- The **start and end times are filtered by the storefront**, not enforced by the server. A storefront that ignores them shows the banner forever.
- **Unpublish rather than delete** when a sale ends. See the next section for why.

## ⛔ Deleting is permanent, and storefronts fall back to nothing

Delete a content entry and it is gone. A storefront that expected it renders whatever it was built to show when there is nothing, which is usually nothing at all. Deleting a blog post is permanent too.

The reversible move is **Unpublish**. Recommend it every time a merchant says "take this down", and only mention delete if they say they want it gone for good.

## Blog SEO, and what happens automatically

Every post carries:

| Field | What it controls |
|---|---|
| **Slug** | The address, `/blog/summer-care-guide`. Auto-derived from the title, editable |
| **SEO title** | The headline in search results; falls back to the post title |
| **SEO description** | The snippet under it; 150 to 160 characters works |
| **OG image** | The image shown when shared; falls back to the cover image |

Static Pages carry the same three SEO fields.

**Renaming a slug is safe.** The old address redirects with a 301 to the new one, so the ranking it earned is not lost. Merchants hesitate over this; tell them it is fine.

Published posts go into the sitemap on their own, and Brainerce pings search engines the moment a post goes live, so nothing needs submitting by hand.

## Getting found on Google

### What a Brainerce storefront does by itself

A storefront built from the current template, or built by following the integration guide, ships with a sitemap covering products, categories, posts and pages; schema.org structured data on products so prices and star ratings can appear in results; instant indexing so a new post is crawled in minutes; and automatic 301 redirects when a slug is renamed.

One caveat that applies to all four: **they live in the storefront, not the platform.** A site built before those features existed, or built by hand without the guide, may be missing some. If in doubt, that is a question for whoever built the storefront.

### What Brainerce does not do

Say these plainly, because merchants assume otherwise:

- Brainerce does **not** run ads. Everything here is organic search.
- Brainerce does **not** guarantee a ranking, and nobody can.
- Brainerce does **not** submit the site to Google. Verifying the domain is the owner's job.

### The three things only the merchant can do

1. **Write the homepage meta description.** In **Settings**, the **Homepage SEO** card. Fifty to 160 characters saying what the shop sells and for whom. Without it Google picks text off the page at random. There is a Create with AI button.
2. **Verify the domain in Google Search Console.** Add the domain in Search Console, choose the HTML tag method, copy the tag. In Brainerce go to **Apps, then Google and YouTube**, pick the sales channel, open the **Merchant Center** tab, and paste it into **Google site verification**. ⛔ It is NOT in the sales-channel settings, which is where everyone looks first. The storefront renders the tag within a few minutes, then click Verify.
3. **Give every product a slug and a meta description.** Both live on the product. The **SEO column** on the Products page scores each one and offers one-click fixes, including AI-written descriptions and image alt text.

### SEO Autopilot

⛔ **Not switched on yet.** A store-wide SEO audit with a ranked issue list is documented ahead of release, and merchants sometimes ask for it by name. If it is not in the sidebar, nothing is broken. What exists today is the per-product SEO score in the products table, which is a different and smaller thing.

## Response shape

> Your About page goes in **Content**, as a Page entry. New content, pick Page, give it the slug `about`, write the body, and fill in the SEO title and description while you are there.
>
> Two things to know. It saves as a Draft, so publish it or nothing sees it. And a Page entry is data: your storefront has to be built to fetch and route it, so if `/about` still 404s after publishing, that is a change on the storefront side rather than something to fix here.
>
> To get it into the menu, add it as a link in your **Header** content entry.
>
> I cannot do any of that from this conversation, so those are steps for you in the dashboard.

## Rules

- Never report a content, page, blog or navigation change as done. There is no tool for any of it here.
- Lead with "this is data, your storefront renders it" whenever a merchant reports that something does not appear.
- Recommend Unpublish, not Delete. Deletion is permanent and storefronts fall back to nothing.
- Do not invent a navigation builder. It is the category tree plus a Header entry.
- Give the exact dashboard route, including the tab. The Search Console tag in particular is somewhere nobody guesses.
- Write the negative space. If a merchant asks for something Brainerce does not do, ads or ranking guarantees or SEO Autopilot today, say so rather than answering with generic advice that reads like a yes.
- Tell developers that page, rich text and FAQ HTML is unsanitized, before they render it.

## Reference files in this skill

- `references/content-shapes.md`: the payload shape of each of the six content types, the sanitisation rule, and how a menu is assembled from the category tree plus the header entry. For developers.

## Cross-skill connections

- The category tree that is half the menu: `brainerce-store-architecture`.
- Structured data attached to products: `brainerce-custom-fields`.
- Per-product SEO while adding a product: `brainerce-product-onboarding`.
- The SDK calls that fetch content and posts: `brainerce-sdk`.
- Routing and rendering it in a storefront, including sanitisation: `brainerce-storefront-build`.

Route once, and do not bounce back and forth.

Referenced files: 3

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, make this filterable on my shop, or set the country of origin on these. Covers the definition versus value split, which of the fifteen types to pick, the two flags that decide whether a field is buyer-facing or filterable, and the common data shapes. Writes values through the connector; definitions are a dashboard step 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, personalisation, storefront filter, product attributes, structured data."
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: "1.0.0"
---

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.

## When to use this skill first

- "Add materials / wattage / country of origin / care instructions to my products".
- "I need a size guide link on every item".
- "Let customers type what they want engraved".
- "Make this filterable on my storefront".
- "What custom fields should a jewellery shop have".
- Reading custom fields off a product in storefront code.

## When NOT to use this skill first

- Deciding whether the property should be a custom field, a variant, a category or a tag: `brainerce-store-architecture` owns that call.
- Adding a whole product: `brainerce-product-onboarding`.
- Pages, menus, policies and blog: `brainerce-content-and-navigation`.
- The SDK shape of `product.metafields` in storefront code: `brainerce-sdk`.

---

## The definition, and why it is not here

A definition is created under **Products, then Custom Fields** in the Brainerce dashboard. Creating one sets:

- **Name**, which is also where the key comes from. "Warranty Info" becomes the key `warranty_info`.
- **Type**, one of fifteen. See `references/field-types.md`.
- **Allowed Values**, which turns free input into a constrained list.
- **Customer Input**, which makes the field buyer-facing.
- **Show in storefront filters**, which exposes it as a shopper-facing facet.

None of that is reachable from this conversation, and it is deliberate: a definition is catalog schema, and one bad definition reshapes the product editor for every product and every connected sales channel.

> **If Custom Fields is missing from the merchant's sidebar**, it is a module that can be switched off for a store, not a missing feature. Settings, then Modules.

## ⛔ The definitionId boundary, and how to work inside it

`set_product_metafield` needs a `definitionId`. There is no tool here that lists definitions. A `definitionId` can only be read off a product that **already carries a value for that field**, and it comes back from:

- `list_product_metafields` on a product, which returns every value on it with its definition attached. This is the primary route.
- `get_product`, whose `metafields` array carries `definitionId`, `definitionKey`, `definitionName`, `type` and `value` per entry.
- `list_products`, which carries the same array on each product in the page.

So the honest shape of what this connector can do:

- ✅ **Copy a field onto more products.** One product has `care_instructions`? Read its `definitionId` and set that field on fifty others.
- ✅ **Correct or update a value** anywhere the field is already in use.
- ❌ **Use a definition nobody has used yet.** The merchant created it in the dashboard this morning and no product carries it: its id is not discoverable from here. Ask them to set it once on any product in the dashboard, then this connector can do the rest.
- ❌ **Create the definition.** Dashboard.

Never guess a `definitionId`. Never construct one from the key. Read it.

## The working sequence

### Setting a value on one product

1. `list_products` to find the product, if you do not have its id.
2. `list_product_metafields` on it. Two things come out of this: whether the field is already set, and the `definitionId` you need.
3. If the field is not on this product, find a product that does carry it and read the id from there. `list_products` returns metafields per product, so one page often answers it.
4. `get_product_metafield` before overwriting, so you can tell the merchant what the old value was.
5. `set_product_metafield`.

### Setting the same field across many products

1. Read the `definitionId` once, as above.
2. `list_products` filtered to the set the merchant means, by category or tag rather than by guessing names.
3. Call `set_product_metafield` **one product at a time**, and report as you go. There is no bulk write on this surface, and a half-finished batch that reports success is worse than a slow one.
4. Say the count at the end, and name any product you skipped and why.

### Reading values in storefront code

Values come back on the product as a `metafields` array, one entry per field, each carrying `definitionKey`, `definitionName`, `type` and `value`. Render **by type**, not as text: a Gallery is a list, a Yes/No is a boolean, a URL is a link. The `getProductMetafieldValue(product, key)` helper exported from the SDK parses numbers, booleans and dates for you. `brainerce-sdk` has the exact shapes.

## The two flags that change what a field is

Both are dashboard settings on the definition, and both are worth naming precisely because merchants ask for the behaviour without knowing the flag.

**Customer Input.** Turns the field into an input on the product page that the shopper fills in before adding to cart. The value is saved as a line-item detail on the order, visible in the order detail view next to the product. This is engraving, a monogram, a gift message printed on the item, a colour the shopper picks. It is also the mechanism that keeps a property out of the variant matrix without taking the choice away from the shopper.

⛔ Not the same as checkout custom fields. Anything collected once for the whole order (delivery notes, gift wrapping, a tax id) is a checkout field, a different feature in a different place.

**Show in storefront filters.** Exposes the field as a facet shoppers filter by, alongside category, brand and price. Available for **Select, Multi-select and Yes/No only**. Not free text, not numbers, not any other type. A merchant who wants to filter by wattage has to model it as a Select with bands rather than a Number, and that decision has to be made before the values are entered, because changing a definition's type later means re-entering every value.

Filter values combine as AND across fields and OR within a field.

## Common shapes worth suggesting

Grouped by what merchants actually ask for. Type choices matter: `references/field-types.md` has all fifteen with when each is right.

| The ask | Field | Type | Flags |
|---|---|---|---|
| "What is it made of" | Materials | Multi-select | Filterable |
| "How do I wash it" | Care instructions | Long Text | None |
| "How big is it" | Dimensions | Dimension | None |
| "How heavy" | Weight | Weight | None |
| "Where was it made" | Country of origin | Select | Filterable |
| "Is it certified" | Certifications | Multi-select | Filterable |
| "Is it kosher / organic / vegan" | One Yes/No per claim | Yes/No | Filterable |
| "Link to the size guide" | Size guide URL | URL | None |
| "New, refurbished or open box" | Condition | Select | Filterable |
| "Let them engrave it" | Engraving text | Text | Customer Input |
| "Let them pick the metal colour" | Metal colour | Select with allowed values | Customer Input |
| "Show a spec sheet" | Specifications | JSON | None |

Two habits worth pushing:

- **One claim per Yes/No field** rather than a Multi-select of claims, when the merchant wants each to be its own filter toggle.
- **Select over Text** whenever the merchant can name the values today. Free text cannot be filtered, and a catalog of free text accumulates "Cotton", "cotton" and "100% cotton" as three different things.

## Response shape

> ✓ Care instructions are now set on all 12 linen shirts.
>
> I read the field id off Linen Shirt Oxford, which already had it, then wrote the same text to the other eleven.
>
> One skipped: Linen Shirt Sample is a draft, so I left it alone. Want it done too?

**When the definition does not exist yet:**

> I cannot create the field itself from here, only fill it in. Custom field definitions are made in the dashboard, under Products then Custom Fields.
>
> Create one called Country of origin, type Select, with your countries as the allowed values, and turn on Show in storefront filters so shoppers can narrow by it. Set it on any one product while you are there.
>
> Once one product carries it, come back and I will set it across the rest.

## Rules

- Definitions are dashboard, values are here. Never imply otherwise, and never attempt a write for a field you have no `definitionId` for.
- Read the `definitionId`; do not construct it from the key.
- `get_product_metafield` before overwriting, so the merchant hears what changed rather than only what it changed to.
- A write is an upsert with no undo, and it enqueues a sync to every connected sales channel. Treat it as a change to a live catalog, not a note.
- One product at a time, reporting as you go. There is no bulk write here.
- Filterable means Select, Multi-select or Yes/No. Do not promise a filter on a Text or Number field.
- The value is validated against the definition's type, so a date has to look like a date and a URL like a URL. A rejection is the definition disagreeing with the value, not a broken tool.
- This connector cannot remove a value. Point at the dashboard rather than writing an empty string, which leaves the field set to nothing rather than unset.

## Reference files in this skill

- `references/field-types.md`: all fifteen types, what each is for, and which support filtering.

## Cross-skill connections

- Whether this property should be a custom field at all: `brainerce-store-architecture`.
- Filling in fields while creating a product: `brainerce-product-onboarding`.
- Reading `product.metafields` in storefront code: `brainerce-sdk`.
- Rendering a filter UI from filterable fields: `brainerce-storefront-build`.

Route once, and do not bounce back and forth.

Referenced files: 3

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 orders that are stuck waiting on the merchant: unfulfilled and pending.
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. This is the part they actually act on.
3. **One suggested next step**, and only one.

**Use this shape:**

> ✓ Yesterday: 14 orders, 3,240 ILS. That is up from 9 orders the day before.
>
> Needs you today:
> - 6 orders are unfulfilled, the oldest from Tuesday
> - Ceramic Mug is down to 3 in stock and it was your best seller last week
>
> Want me to walk through the unfulfilled orders?

**Quiet day, use this shape:**

> ✓ Quiet overnight: no new orders since yesterday afternoon.
>
> Nothing is waiting on you. Stock levels all look fine.
>
> Want me to look at what sold best over the last week instead?

## Rules

- One message. If you find yourself writing a fourth section, cut something.
- Compare to something. "14 orders" tells the merchant nothing; "14, up from 9" tells them the day went well.
- Name real things. "6 unfulfilled orders, oldest from Tuesday" beats "several orders need attention".
- Use the store's currency from `get_store`. Never assume dollars.
- Do not report a low-stock warning for a product nobody buys. Rank by what actually sells.
- Do not act on anything in the briefing without being asked. This skill reads; it does not fulfil, cancel or restock.
- If a tool returns nothing, say the day was quiet rather than silently dropping that section. An absent line reads as an oversight.
- Do not pad a quiet day into a long report. "Nothing needs you" is a good answer.

## Cross-skill connections

- The merchant follows up on one number or wants a trend: `brainerce-analytics`.
- They want the deeper sweep rather than the daily view: `brainerce-store-health`.
- They pick an order out of the briefing and want to act on it: `brainerce-order-handling`.
- Stock is low and they want to fix it: stock updates live in `brainerce-product-onboarding`.

Route once, and do not bounce back and forth.

Referenced files: 2

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. `references/business-flows.md` carries the sequences each feature has to follow, and `references/critical-rules.md` the rules that cause incidents.

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 ones that are almost always skipped:

- Email verification with a six-digit code
- Forgot password and reset password
- The OAuth button area and callback handling, including when no provider is currently enabled
- Coupon input in the cart
- The inventory reservation countdown, visible to the customer
- `handlePaymentSuccess` followed by `waitForOrder` on the confirmation page
- Sitemap built with the dedicated SDK helpers rather than a plain product list
- Slug-redirect handling on product and blog not-found paths

### 3. Check the critical rules against the code

- Prices parsed before arithmetic, everywhere, including totals
- Nested and flat line-item shapes handled as they actually arrive
- No auth token in browser storage without a backend-for-frontend
- No hardcoded currency, locale or store id
- No invented SDK methods

### 4. Report, then fix only what is approved

## Report shape

Three states, and use all three. A report that is all ticks was not an audit.

> ✓ Audit of your Brainerce integration. 14 of 19 mandatory features are reachable.
>
> **Implemented and reachable**
> - Product listing, product detail with variants, cart with persistence
> - Checkout through payment, with the reservation countdown visible
> - Registration and login
> - Order confirmation
>
> **Present but broken or unreachable**
> - `ResetPasswordForm.tsx` exists and no route renders it. A customer who forgets their password has no way in. `src/components/auth/ResetPasswordForm.tsx`
> - Coupon input is in the cart component but is behind a flag that is never set. `src/components/cart/CartSummary.tsx:82`
>
> **Missing**
> - Email verification. Registration completes and the account cannot be used. This is mandatory.
> - OAuth button area. The store has no providers today, so it looks unnecessary, but the owner enabling Google later would need a code change.
> - Sitemap uses `getProducts({ limit: 1000 })`, which the API caps at 100. Your sitemap silently lists 100 products.
>
> **Critical rule violations**
> - `src/lib/totals.ts:14` adds `item.price` without parsing. Prices are strings, so this concatenates.
>
> Want me to start with email verification? It is the one that blocks real customers today.

## Rules

- Trace every feature to something reachable. A file is not a feature.
- Cite file paths and line numbers. An audit without references cannot be acted on.
- Use all three states. "Present but unreachable" is the most useful finding and the one a shallow check misses.
- Never mark a mandatory feature not applicable because the store has it disabled.
- Report before fixing, and fix only what the developer approves.
- Say what you could not check, and why. An audit that quietly skipped the payment path is worse than one that says it did.
- Order findings by what blocks a real customer today, not by checklist order.

## Cross-skill connections

- Building what the audit found missing: `brainerce-storefront-build`.
- Getting a sequence right while fixing it: `brainerce-checkout-flows`.
- A method signature you need mid-fix: `brainerce-sdk`.

Route once, and do not bounce back and forth.

Referenced files: 5

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, put the winter range on sale, launch a promotion, create a discount code, set up a voucher, offer free shipping over a threshold, or schedule a Black Friday or holiday 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. For store owners, not developers. Do not choose this to review how a past promotion performed, use brainerce-analytics. Do not choose this to hunt for expired or forgotten promotions across the store, use brainerce-store-health. Keywords: sale, discount, promotion, promo code, coupon, voucher, percent off, money off, BOGO, buy one get one, free shipping, bundle, Black Friday, clearance, markdown."
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: "1.0.0"
---

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

---

## 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` |
| Shopper experience | Price drops by itself in the cart | Shopper must type a code at checkout |
| Who gets it | Everyone the rule targets | Only people who have the code |
| Merchant says | "20% off all jackets", "sale next week", "free shipping over 200" | "a code for my newsletter", "SPRING20", "a voucher for this customer" |

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

**Use `create_coupon` only when** the merchant asks for a code, names a code word, or wants something they can hand to specific people.

**When it genuinely could be either, ask one short question before creating anything:**

> 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?

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

## Step 2: gather what the promotion needs

Ask only for what is missing, and only what changes the result.

- **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.
- **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.
- **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.
- **Limits, only if the merchant raises them.** Usage caps, per-customer caps, a budget ceiling, whether it can stack with other offers.

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

## Step 3: create it

**Automatic discount:** call `create_discount_rule`. Pick the type from what the merchant described:

- `PRODUCT_DISCOUNT`: money off specific products or a category.
- `ORDER_DISCOUNT`: money off the order total.
- `BUY_X_GET_Y` and `BUY_X_GET_X`: buy one get one, and its variants.
- `VOLUME_DISCOUNT`: cheaper per unit at higher quantities.
- `SHIPPING_DISCOUNT`: free or reduced shipping.
- `BUNDLE`: a set of products priced together.

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

## Step 4: verify before you claim it worked

Call `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.

If it is scheduled rather than active, say so plainly. Merchants read "live" as "working right now".

## Step 5: tell the merchant, in their words

**Automatic discount, use this shape:**

> ✓ Your 20% off sale on Winter Jackets is set up and starts Monday 3 November, ending Sunday 9 November.
>
> Customers do not need a code. The lower price shows up on its own in the cart.
>
> Want me to turn it on now instead of Monday, or add anything else to it?

**Coupon, use this shape:**

> ✓ Your discount code SPRING20 is live now and runs until 31 March. It takes 20% off the order.
>
> Customers have to type SPRING20 at checkout for it to apply, so it only reaches the people you share it with.
>
> Want me to check what it would take off a typical order?

**Could not do it, use this shape:**

> 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?

## Rules

- Verify with a listing tool before you say it is live. Every time.
- 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.
- Use the store's real currency from `get_store`, and give dates as dates rather than "next week".
- 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.
- 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.
- This connector cannot delete a coupon or a discount rule. If the merchant wants one gone rather than switched off, say that removal is done in the Brainerce dashboard.
- 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.

## Cross-skill connections

- Performance of a promotion after the fact: `brainerce-analytics`.
- Sweeping the store for expired or forgotten promotions: `brainerce-store-health`.
- A specific order that should have been discounted: `brainerce-order-handling`.

Route once, and do not bounce back and forth.

Referenced files: 2

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, cancel this one, the customer changed their mind, or what has this person bought before. Includes the rules for when NOT to touch an order. For store owners, not developers. Do not choose this for counts and totals across many orders such as how many orders today or revenue this week, use brainerce-analytics or brainerce-daily-summary. Do not choose this to sweep for stuck orders across the whole store, use brainerce-store-health. This connector cannot issue refunds or record payments. Keywords: order, fulfil, fulfill, ship, shipped, tracking number, cancel order, order status, customer asking, where is my order, refund, order history, delivery."
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: "1.0.0"
---

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

## 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` filtered by status, date or customer, or `get_recent_orders` for "the one that came in this morning".
- A customer's history: `get_customer` to identify them, then `get_customer_orders`.

Read the whole order before proposing anything. Its current status determines which actions are even sensible, and the line items determine what you are about to tell a customer.

If more than one order matches what the merchant said, list the candidates and ask. Do not pick.

## Step 2: choose the action from the state, not from the phrasing

| Merchant says | State | Do |
|---|---|---|
| "mark it shipped", "it went out today" | Paid, unfulfilled | `fulfill_order` with tracking if they have it |
| "move it to processing", "put it back to pending" | Any | `update_order_status` |
| "cancel it", "she changed her mind" | Not yet fulfilled | `cancel_order` |
| "cancel it" | Already fulfilled and shipped | Stop. See below. |
| "refund her" | Any | Not possible here. See below. |
| "mark it paid", "the cash arrived" | Any | Not possible here. See below. |

## When NOT to touch an order

These are the cases where doing what was asked is the wrong move.

- **Already fulfilled and shipped, and the merchant says cancel.** Cancelling does not recall a parcel. Say what cancelling would and would not do, and ask what they actually want: a return, a refund, or a note to the courier. Do not cancel and let them discover the parcel is still in transit.
- **The merchant asks for a refund.** This connector cannot issue one. Say so plainly and point at the Brainerce dashboard. Do not cancel the order as a substitute; a cancellation is not a refund and the customer's money does not move.
- **The merchant asks to mark an order as paid.** Also not available here, also a dashboard task. Do not move the status to something adjacent and imply the payment is recorded.
- **The order is already in the state being asked for.** Say it is already there rather than calling the tool again and reporting success.
- **The merchant is guessing which order they mean.** Confirm first. There is no undo on a cancellation.
- **Anything involving the customer's address.** This connector cannot edit addresses. Dashboard task.

## Step 3: act, then say what the customer sees

Fulfilment and status changes send customer-facing email. That is the part the merchant most needs to know about, and the part they are most often surprised by.

**Fulfilled, use this shape:**

> ✓ Order 1042 is marked fulfilled with tracking number RR123456789IL.
>
> Ronit has been emailed the tracking link automatically.
>
> Anything else on this order?

**Cancelled, use this shape:**

> ✓ Order 1042 is cancelled and the two Ceramic Mugs are back in stock.
>
> Ronit has been emailed the cancellation. Her payment is not refunded by this, so if money needs to go back you will need to do that from the Brainerce dashboard.

**Declining, use this shape:**

> Order 1042 already shipped on Tuesday, so cancelling it here would not stop the parcel. It would only mark the order cancelled and put the stock back, while the box is still on its way to Ronit.
>
> Do you want me to leave it as is while you arrange a return, or is there something else going on with it?

**Cannot do it, use this shape:**

> I cannot issue refunds from here. That one is done in the Brainerce dashboard, under the order.
>
> I can cancel the order if that is useful, but that is a separate thing: it stops the order and restocks the items, and it does not move any money.

## Rules

- Read the order with `get_order` before you change it. Always.
- Confirm which order before any destructive action. Cancellation has no undo.
- Say out loud when an action emails the customer, before you take it if there is any doubt.
- Never substitute an adjacent action for one that is unavailable. A cancel is not a refund; a status change is not a payment record.
- One order at a time. There is no bulk action here, and there should not be one.
- Use the store's currency from `get_store` when quoting totals.
- If a fulfilment appears to have partly succeeded, read the order again rather than fulfilling twice. A second fulfilment can mean a second notification to the customer.

## Cross-skill connections

- Totals and trends across orders: `brainerce-analytics`.
- The morning view of what needs attention: `brainerce-daily-summary`.
- A store-wide sweep for orders stuck in one state: `brainerce-store-health`.
- Restocking after a cancellation: `brainerce-product-onboarding`.

Route once, and do not bounce back and forth.

Referenced files: 2

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, I have something new to sell, 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 near-identical product and correcting inventory after a stock take. For store owners, not developers. Do not choose this to change price or description on a product that already exists and is set up, that is a quick edit and needs no sequence. Do not choose this for reading reviews or ratings, use brainerce-analytics. Do not choose this to find products that were left as drafts, use brainerce-store-health. Do not choose this to decide variant versus custom field, use brainerce-store-architecture. Keywords: add product, new product, list an item, create product, upload product, stock count, inventory, restock, categorise, tags, publish, duplicate product, product variants."
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: "1.0.0"
---

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 this connector cannot delete the mistake.

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.
- **Images**: if the merchant has image URLs, pass them; the platform downloads and stores the images rather than linking to someone else's server.
- **Variants**: sizes, colours, materials. Ask if the product obviously has them ("a t-shirt" almost certainly does) and do not silently create a single-variant product for something that needs five.

### 3. Put it somewhere customers will find it

Call `list_categories`, then place the product in a real category. If nothing fits, `create_category` makes one, but check the list first; stores accumulate near-duplicate categories fast.

### 4. Tag it

Call `list_tags` before `create_tag`. Reuse an existing tag over creating "Summer" next to "summer" and "Summer 2026". Tags are how the merchant will filter and how sales get targeted later.

### 5. Set stock

Call `set_product_stock`. A product with no stock is not buyable, and a merchant who thinks they have listed something for sale will not check. If the merchant has not said how many, ask; do not default to a number.

`get_product_inventory` reads back what is actually there, and is the tool for a stock take correction as well.

### 6. Offer to publish, do not assume

Products can exist as drafts. Tell the merchant which state it is in and ask before making it visible. "Do you want this live on the storefront now, or held as a draft while you add photos?" is one sentence and prevents both of the bad outcomes.

## Response shape

> ✓ Ceramic Mug is created at 65 ILS, in Kitchen, tagged handmade and gift, with 40 in stock.
>
> It is currently a draft, so customers cannot see it yet.
>
> Want me to publish it, or would you rather add photos first?

**Partly done, use this shape:**

> ✓ Ceramic Mug is created at 65 ILS with 40 in stock.
>
> Two things I did not do: it is not in a category yet, and it has no images. Uncategorised products are hard for customers to find.
>
> Want me to put it in Kitchen?

## Rules

- Never say "added to your store" for a draft. Say it is a draft and what that means.
- Check `list_products` before creating, and `list_tags` and `list_categories` before creating those. Duplicates cannot be deleted from here.
- Ask for stock rather than defaulting to zero or to some number you picked.
- Show generated descriptions to the merchant before publishing. This is their shop's voice.
- `create_product` reaches an external origin when it downloads images from URLs, and running it twice creates two products, not one. If a call is ambiguous about whether it went through, check with `list_products` rather than re-running it.
- `update_product` replaces the fields it touches rather than merging into them. Read the current product with `get_product` before an edit so you know what you are about to overwrite.
- Several products at once: do them one at a time and report as you go. This connector has no bulk create, and a half-finished batch is worse than a slow one.
- This connector cannot delete a product. Say so if the merchant asks, and point at the Brainerce dashboard.

## Cross-skill connections

- Putting the new product on sale: `brainerce-launch-a-sale`.
- Reviews and ratings on it: `brainerce-analytics`.
- Finding old drafts and out-of-stock items across the store: `brainerce-store-health`.
- Deciding variant versus custom field, or category versus tag: `brainerce-store-architecture`.
- Filling in a custom field on the new product: `brainerce-custom-fields`.

Route once, and do not bounce back and forth.

Referenced files: 2

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

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 connection, and these snapshots are the source of truth.

## Rules

- **Quote the reference, do not paraphrase from memory.** If your recollection and the file disagree, the file wins.
- **Prices are strings.** Parse them before arithmetic. This is the single most common bug in Brainerce integrations and it survives review because the code looks right.
- **Never invent a method.** "I do not see a method for that; the closest is X, which does Y" is a good answer. A confidently wrong method name is not.
- **Do not flatten a nested shape** because it would be more convenient. Line items in particular are nested in some responses and flat in others; check which one you have.
- **Currency, locale and store id come from the store**, never from a constant in the code.
- **Say which SDK version the reference reflects** if the developer is debugging behaviour that does not match. A snapshot can lag a published release, and `npm view @brainerce/sdk version` settles it in one command.

## Response shape

> `client.getProducts(options)` takes:
>
> - `limit` and `page` for pagination. The API caps `limit` at 100, so do not use this to build a sitemap; there is a dedicated helper for that.
> - `categorySlug`, `tag`, `search` for filtering.
> - `locale` when the store is multi-language.
>
> It returns `{ data: Product[], meta: { page, limit, total, totalPages } }`.
>
> Note `Product.price` is a string, so parse it before any arithmetic.

**Method does not exist, use this shape:**

> There is no `getProductBySku` in the SDK. The closest is `getProducts({ search })`, which matches on SKU among other fields, so you would filter the result. If you need an exact SKU lookup, that is worth confirming with the Brainerce team rather than working around it.

## Cross-skill connections

- Sequences rather than signatures: `brainerce-checkout-flows`.
- Building a whole storefront: `brainerce-storefront-build`.
- Checking a finished integration: `brainerce-integration-verify`.

Route once, and do not bounce back and forth.

Referenced files: 7

View saved version →

---
name: brainerce-store-architecture
description: "Decide how a Brainerce catalog should be structured, and diagnose one that is already wrong. Use when the merchant asks how should I organise my shop, should this be a variant or an option, categories or tags, how do I set up my menu, my product list is a mess, or I have hundreds of variants I cannot manage. Answers the modelling question before anything is created: what becomes a variant, what becomes a custom field, what becomes a category, what becomes a tag. Also audits an existing catalog and returns an ordered improvement plan. For store owners, and for 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, menus or blog, use brainerce-content-and-navigation. Keywords: catalog structure, variants or options, variant explosion, too many variants, categories vs tags, hierarchy, menu structure, product model, organise my shop, catalog audit."
compatibility: ChatGPT, Claude Code, Claude Desktop, Cursor
maintainer: Brainerce
metadata:
  author: Brainerce
  version: "1.0.0"
---

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

| Mechanism | What it is | Own stock? | Where it is set up |
|---|---|---|---|
| **Variant** (from an attribute) | One row per combination, each with its own price, SKU and inventory | Yes | Dashboard variant editor, or `variants` on `create_product` |
| **Modifier group** | A choice at checkout that changes the price but not what you ship | No | Dashboard, Products then Modifiers |
| **Custom field** (metafield) | Structured data on the product; 15 types; can be buyer-facing or a storefront filter | No | Definition in the dashboard, value from chat |
| **Category** | The product's one permanent home in the menu tree | n/a | `create_category`, or the dashboard |
| **Tag** | A flat label that cuts across the tree | n/a | `create_tag`, or the dashboard |

## Want X, use Y

| The merchant wants | The right mechanism |
|---|---|
| Shoppers pick between options and each option is counted, priced and shipped separately | Variant |
| Shoppers pick an add-on that changes the total but not what leaves the warehouse | Modifier group |
| Shoppers type or choose something personal, and it should print on the order | Custom field with Customer Input turned on |
| Shoppers narrow the product list by a property | Custom field of type Select, Multi-select or Yes/No, with storefront filters turned on |
| A spec that only needs to be displayed, never chosen or filtered | Custom field of any type |
| A permanent place in the navigation menu | Category, nested under a parent |
| A collection that cuts across the menu, or a seasonal grouping | Tag |
| Who manufactured it | Brand |
| A different price in another country | Regional pricing, dashboard |
| The same catalog sold in more than one place | Sales channels |

Two of those rows are the ones merchants get wrong, and they have their own rules below.

---

## Rule 1, the variant rule

**A variant exists only for a property that changes price, stock or SKU. Everything else is a custom field.**

The reason is arithmetic. Variants are the Cartesian product of their attributes, so every attribute multiplies. Three attributes with 6, 5 and 15 values is 450 rows, and each row wants its own price, its own SKU and its own stock number. Nobody maintains 450 rows. The catalog stops being edited, stock drifts, and the storefront starts offering combinations that do not exist.

**The worked example, and it is the one to reach for.** A jewellery store sells a ring in several diamond sizes, several metal colours, and every ring size.

- **Diamond size is a variant.** A bigger stone costs more. Price changes, so it earns its own row.
- **Metal colour is a custom field, not a variant.** Same price, same stone, same SKU in most catalogs. Make it a Select custom field with Customer Input turned on, so the shopper still chooses it on the product page.
- **Ring size is a custom field, not a variant.** Same reasoning, and it is the attribute that multiplies hardest.

That takes the product from 450 unmaintainable rows to 6 real ones plus two fields.

**The honest exception, and say it out loud.** If the merchant genuinely holds separate stock per metal colour, boxed and on a shelf, then colour changes stock and it IS a variant after all. The rule is the test, not the answer. Ask "if a customer buys the gold one, which number goes down" before deciding.

### Spotting a variation explosion

You are looking at one when any of these is true:

- A product has more variant rows than the merchant could plausibly count in a stock take.
- Most variant rows carry the same price. A property that never changes the price is not earning its row.
- Whole blocks of rows sit at zero stock and always have, because those combinations were generated but never existed.

The fix to propose: keep the one attribute that moves the price, and demote the others to custom fields with Customer Input. Say plainly that this is a rebuild of that product rather than an edit, and that the variant editor is a dashboard job.

## Rule 2, the navigation rule

**A hierarchical menu is parent and child categories. Tags are for filtering across the tree, never for hierarchy.**

"Mobile" as a parent, with "iPhone" and "Samsung" as children, is how a shopper walks down to what they want. Each category gets its own landing page and a breadcrumb on every product in it. Two or three levels is the practical limit; `create_category` accepts `parentId` and the storefront is built around depth two.

Tags are flat by design. They have no landing page and no children. `summer-sale`, `gift-under-50` and `bestseller` are tags because they cut sideways across the menu and because they change with the season, while the menu should not.

The test: **would removing this label leave the product with no home in the menu?** If yes it is a category. If the product still has a home and this was just another way to group it, it is a tag.

A product normally sits in one category. Putting it in several creates duplicate navigation entries and a breadcrumb that cannot decide what it is.

### Spotting a flat catalog

- `list_categories` returns many categories and none of them has a parent. A store with thirty top-level categories has a menu nobody can read.
- The same words appear as both a category and a tag.
- Tags carry the structural nouns ("phones", "laptops") while categories carry the seasonal ones. That is the two mechanisms swapped.

---

## Review mode, auditing a catalog that already exists

Read only. Diagnose, present the plan, then let the merchant pick. Do not restructure anything mid-audit.

1. **`count_products`** first, so you know whether a sample or the whole catalog is being judged, and say which.
2. **`list_products`**, paging through it. Each product comes back with its variants and its custom-field values, so this is where variation explosion and empty modelling both show up. Note the variant count per product and whether the prices differ across those variants.
3. **`list_categories`**, for the tree. Count how many have a parent. None with a parent on a large catalog is the flat-catalog finding.
4. **`list_tags`**, and compare the names against the category names. Overlap is the swapped-mechanism finding.
5. **`list_product_metafields`** on a few representative products, to see which custom fields are actually in use and which products are missing the ones their neighbours have.

Then report against the four failure modes, most costly first:

- **Too many variants on a product**, with the number and which attribute is not earning its rows.
- **A flat category list**, with the tree you would propose.
- **Tags doing a category's job**, naming the specific tags.
- **A property that should be a custom field and is not recorded anywhere**, which is usually the one costing the merchant filter traffic.

**Use this shape:**

> ✓ I went through 240 products. Three things worth changing, most costly first:
>
> 1. **Solitaire Ring has 300 variants** and 280 of them are the same price. Only diamond size moves the price. Metal colour and ring size should be custom fields the shopper picks on the page, which takes it to 6 rows.
> 2. **All 34 of your categories are top level.** There is no menu to walk down. I would nest them under Rings, Necklaces and Earrings.
> 3. **`rings` and `necklaces` exist as tags as well as categories.** The tags are doing nothing the categories do not, and they split your filters in two.
>
> Also fine: every product has a category, and your custom fields are used consistently across the Rings range.
>
> Number 2 is the one I can do from here. Want me to build that tree?

## Planning mode, before the first product exists

Four questions, then a structure. Do not create anything until the merchant has seen the plan.

1. **What are you selling, and roughly how many lines?**
2. **For one typical product, what does a shopper choose before buying?** List every choice.
3. **Which of those choices changes the price, or is counted separately in your stockroom?** Those are the variants. Everything else on the list is a custom field.
4. **How would a shopper browse to it if they did not use search?** That answer is the category tree.

Then hand back: the category tree with parents and children, the attribute or attributes that become variants, the custom fields with their types and whether each is buyer-facing or filterable, and any modifier groups. Say which parts you can build now and which are dashboard steps.

## What can be done from here, and what cannot

**From this conversation:**

- `create_category` with `parentId`, so the whole tree can be built from chat.
- `create_tag`, after `list_tags` to avoid a near-duplicate.
- `create_product`, including its `variants` array.
- `update_product` to move products between categories. ⛔ `categories` REPLACES the set while `categoryNames` is additive, so read the product first and know which one you want.
- `set_product_metafield` to write a custom-field value, but only for a field some product already carries. See `brainerce-custom-fields` for why.

**Dashboard only, and say so rather than improvising:**

- Creating a custom-field definition, and its type, its allowed values, its Customer Input flag and its storefront-filter flag.
- Attributes and the variant editor beyond what `create_product` accepts.
- Modifier groups, in every respect.
- Regional pricing.
- Deleting anything at all.

## Rules

- Answer the modelling question before creating anything. A product created under the wrong model is a rebuild, not an edit.
- Never propose a variant for a property that does not change price, stock or SKU. Say the arithmetic out loud when refusing.
- Never propose a tag where the merchant described a menu.
- Read before you write. `list_categories` and `list_tags` first, every time, because this connector cannot delete the near-duplicate you create.
- Give the number. "Too many variants" is ignored; "300 variants, 280 at the same price" is acted on.
- When the plan needs a dashboard step, name the exact place, and do not imply you did it.

## Reference files in this skill

- `references/mechanisms.md`: all five mechanisms at field level, including the attribute display types, the modifier group selection and free-quantity rules, and the two custom-field flags. Read it when an argument turns on a detail rather than on the choice.

## Cross-skill connections

- Custom fields in depth, including writing values: `brainerce-custom-fields`.
- Pages, navigation copy, policies and blog: `brainerce-content-and-navigation`.
- Creating the products once the model is settled: `brainerce-product-onboarding`.
- Rendering any of this in a storefront: `brainerce-storefront-build`.
- The exact SDK shape of a category tree or a metafield: `brainerce-sdk`.

Route once, and do not bounce back and forth.

Referenced files: 3

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

**Get the connection id.** Every storefront call is scoped by one. It looks like `vc_...`. Without it there is nothing to build against, so ask for it before doing anything else rather than scaffolding against a placeholder.

**Read the store's actual capabilities.** Payment providers, OAuth providers, whether discounts and multi-language are on, which shipping is configured: these differ per store and they decide which parts of the UI have to exist. When the Brainerce MCP server is connected (Claude Code, Cursor, or the CLI), `get-store-capabilities` and `list-store-products` return this live. In ChatGPT there is no such connection, so ask the developer what the store has rather than assuming a default.

## The build order

Do these in sequence. Each step assumes the one before it.

1. **Client setup.** One configured client, created once, reused. See `references/setup.md`.
2. **Catalog.** Listing, filtering, a product detail page that handles variants and modifier groups rather than assuming a flat product. See `references/products.md`.
3. **Cart.** Persistence across reloads is not optional; a cart that empties on refresh reads as a broken shop.
4. **Auth.** Registration, the six-digit email verification, login, forgot and reset password, and the OAuth buttons if the store has providers configured.
5. **Checkout.** The one sequence you must not improvise. `brainerce-checkout-flows` owns it.
6. **Order confirmation.** The step most often left half-built, and the one the customer judges you on.
7. **Discoverability.** Sitemap from the SDK helpers, robots, structured data, slug-redirect handling. See `references/seo.md`. This is a real requirement, not a nice to have: the listing API caps its page size, so a sitemap built from a plain product list silently truncates.
8. **Localisation**, if the store runs more than one language. See `references/i18n.md`.

## Rules that cause incidents when skipped

Read `references/critical-rules.md` in full before writing SDK code. The ones that catch people most often:

- **Prices come back as strings.** Parse before arithmetic. String concatenation instead of addition is a real bug that ships.
- **Never store an auth token in the browser** without a backend-for-frontend in front of it.
- **Never hardcode currency, locale or store id.** Read them from the store.
- **Do not invent SDK methods.** If it is not in the reference, it does not exist, and a plausible-looking call that 404s at runtime is worse than asking.
- **Line items are nested in some shapes and flat in others.** Check which one you have rather than assuming.

## Mandatory features

Some features have to be reachable in the finished build even when the store has them switched off today. They hide themselves at runtime and the owner enables them later, so a build that omits them breaks the day the owner turns the feature on. Coupon input in the cart, email verification, password reset, the OAuth button area and the reservation countdown are the ones most often missed.

`brainerce-integration-verify` carries the full checklist. Run it before you call the build done.

## Response shape

> ✓ Catalog and product pages are wired to your Brainerce store.
>
> Built: product listing with category filter, product detail with variant selection and modifier groups, cart with persistence across reloads.
>
> Not built yet, and all three are on the mandatory list: checkout, auth with email verification, order confirmation.
>
> Checkout next? It has a fixed sequence and I want to get it right rather than fast.

## Reference files in this skill

- `references/setup.md`: client creation and configuration.
- `references/products.md`: catalog, variants, modifier groups, product shape.
- `references/critical-rules.md`: the rules above, in full, with examples.
- `references/seo.md`: sitemap helpers, robots, structured data, slug redirects.
- `references/i18n.md`: multi-language routing and locale resolution.

These are snapshots taken from the Brainerce MCP server's own content. When that server is connected, prefer its live tools, which reflect the specific store. In ChatGPT it is not, and these files are the source of truth.

## Cross-skill connections

- One method's exact shape: `brainerce-sdk`.
- Checkout, auth, cart and reservation sequences: `brainerce-checkout-flows`.
- Auditing what you built: `brainerce-integration-verify`.
- Content entries, navigation and blog, including the fact that page and rich-text HTML arrives unsanitized: `brainerce-content-and-navigation`.
- Rendering custom fields and building a filter UI from the filterable ones: `brainerce-custom-fields`.

Route once, and do not bounce back and forth.

Referenced files: 7

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, and orders stuck waiting on someone. For store owners, not developers. Do not choose this for the routine morning check-in on yesterday's numbers, use brainerce-daily-summary. Do not choose this for a specific metric or trend, use brainerce-analytics. Do not choose this to act on one known order, use brainerce-order-handling. Do not choose this to audit how the catalog is structured rather than its state, use 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"
---

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

Run all four. A sweep that finds nothing is still worth one line, because "no drafts left hanging" is information.

### 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 seller at zero is urgent and a slow mover at zero is housekeeping.
- Products with no category. Uncategorised items are hard for customers to reach even when published.

### 2. Promotions nobody is watching

- `list_discount_rules` and `list_coupons`. Look for two different problems, and do not merge them:
  - **Expired**: past its end date and cluttering the list. Low priority.
  - **Still running and probably should not be**: no end date, or an end date that already passed while the rule stayed enabled, or a promotion the merchant set up for an event that is over. This one costs money every day, so it goes at the top.

### 3. Orders waiting on somebody

- `get_orders_by_status` for unfulfilled and pending. Rank by age. An unfulfilled order from three weeks ago is a customer who has probably given up.
- `get_recent_orders` to see whether the backlog is growing or is a one-off.

### 4. Signals from customers

- `list_product_reviews` filtered to low ratings, and `get_product_review_stats` on the products that sell most. A best seller whose rating has slipped is worth knowing about before it shows up in the revenue.

## Shape the answer

Order by cost to the merchant, not by category. Put money-losing first, customer-facing second, housekeeping last. Cap the list; five real problems beat thirty observations.

**Use this shape:**

> ✓ I went through your store. Four things worth your time, most costly first:
>
> 1. **A 30% sale is still running on Summer Dresses.** It has no end date and it started in June. Every order since then has been discounted. Want me to switch it off?
> 2. **Six orders are unfulfilled**, the oldest from 4 November. That customer has been waiting eleven days.
> 3. **Ceramic Mug is out of stock** and it was your best seller last week. Every day it stays at zero is lost sales.
> 4. **Three products are still drafts**: Linen Scarf, Wool Hat, Gift Box. Customers cannot see them.
>
> Also fine: no expired coupons cluttering things up, and your review ratings are all above 4.
>
> Which of these do you want to start with?

**Clean store, use this shape:**

> ✓ Your store looks in good shape. No drafts left hanging, nothing out of stock, no promotions running past their date, and no orders sitting unfulfilled for more than a day.
>
> The one thing I would keep an eye on: Ceramic Mug is down to 4 in stock and it sells about 3 a day.

## Rules

- Read only. Do not fix anything during the sweep, even something obviously wrong. Report, then let the merchant choose.
- Every finding needs a consequence. "Three drafts" is a fact; "three drafts customers cannot see" is a reason to care.
- Rank by cost. An overrunning discount outranks an untidy tag list, always.
- Name real items and real dates. Vague findings get ignored.
- Say what came back clean. Otherwise the merchant cannot tell whether you checked.
- Cap the list at around five items and offer to go deeper. A thirty-item audit gets closed.
- Do not report the same thing twice under two headings.
- This connector cannot delete anything, so never offer to clear out old items. Switching a promotion off is possible with `toggle_discount_rule`; removing it is a dashboard task.

## Cross-skill connections

- The merchant picks a promotion to switch off or change: `brainerce-launch-a-sale`.
- They pick an order out of the list: `brainerce-order-handling`.
- They want to restock or publish a draft: `brainerce-product-onboarding`.
- They want to understand a trend the sweep hinted at: `brainerce-analytics`.
- The sweep keeps hitting the same structural problem, such as one product with hundreds of variants: `brainerce-store-architecture`.

Route once, and do not bounce back and forth.

Referenced files: 2