Update to Brainerce

{
  "description": "Answer how much, how many, what is best and what is the trend for a Brainerce store, using the right reporting tool instead of counting rows by hand. Use when the merchant asks about revenue, sales, total orders, average order value, best or worst sellers, how this month compares to last, whether a sale worked, how many customers, or what people think of a product. Turns a plain question into the correct statistics call and answers with a number plus what it means. Also owns retention, coupon performance, stock velocity, traffic and connection health. For store owners, not developers. Not for the morning check-in (brainerce-daily-summary), acting on one order (brainerce-order-handling) or a health sweep (brainerce-store-health). Keywords: revenue, sales, how much, how many, total, average order value, AOV, best sellers, trend, compare, month over month, growth, conversion, retention, repeat customers, stock velocity, traffic, ratings, reviews, report, analytics.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 1171
    },
    {
      "relative_path": "assets/icon.png",
      "size_in_bytes": 3208
    }
  ],
  "name": "brainerce-analytics",
  "skill_md_contents": "---\nname: brainerce-analytics\ndescription: 'Answer how much, how many, what is best and what is the trend for a Brainerce store, using the right reporting tool instead of counting rows by hand. Use when the merchant asks about revenue, sales, total orders, average order value, best or worst sellers, how this month compares to last, whether a sale worked, how many customers, or what people think of a product. Turns a plain question into the correct statistics call and answers with a number plus what it means. Also owns retention, coupon performance, stock velocity, traffic and connection health. For store owners, not developers. Not for the morning check-in (brainerce-daily-summary), acting on one order (brainerce-order-handling) or a health sweep (brainerce-store-health). Keywords: revenue, sales, how much, how many, total, average order value, AOV, best sellers, trend, compare, month over month, growth, conversion, retention, repeat customers, stock velocity, traffic, ratings, reviews, report, analytics.'\ncompatibility: ChatGPT, Claude Code, Claude Desktop, Cursor\nmaintainer: Brainerce\nmetadata:\n  author: Brainerce\n  version: '1.0.0'\n---\n\n⛔ **Before you call anything a dashboard task, look for `search_tools` in your tool list.** Some connections carry a small curated list PLUS a way to reach everything else. Where `search_tools` exists, search for what the merchant asked for and call any hit through the `call_read_tool` / `call_write_tool` / `call_destructive_tool` it names. The dashboard is the honest answer only when your list has no `search_tools`, or the search comes back empty. A few things are refused through it deliberately (payment provider setup, refunds and recording payments, gift cards), which is why an empty result there is a real answer rather than a gap.\n\nTurn a merchant's question into the right reporting call, and give back a number that means something.\n\n## Core principle\n\nA 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.\n\nAnd 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.\n\n## When to use this skill first\n\n- Money: revenue, sales, totals, average order value.\n- Counts: how many orders, how many customers, how many of a product sold.\n- Rankings: best sellers, worst sellers, top customers.\n- Trends and comparisons: this month against last, is it growing, did the sale work.\n- Product sentiment: ratings and what reviewers said.\n\n## When NOT to use this skill first\n\n- General \"how is it going\" first thing in the morning: use `brainerce-daily-summary`.\n- One order, one customer, one action: use `brainerce-order-handling`.\n- Finding problems rather than measuring: use `brainerce-store-health`.\n- Setting up a promotion, as opposed to measuring one: use `brainerce-launch-a-sale`.\n\n---\n\n## Question to tool\n\n| The merchant asks                                                     | Call                                                                                                                                                                                                                                                                                |\n| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| \"How much did I make\", \"revenue this month\", \"how are sales\"          | `get_store_analytics_summary`                                                                                                                                                                                                                                                       |\n| \"How many orders\", \"how many are still unpaid\", \"breakdown by status\" | `get_orders_stats`                                                                                                                                                                                                                                                                  |\n| \"What is my average order\", \"are people spending more\"                | `get_average_order_value`                                                                                                                                                                                                                                                           |\n| \"What sells best\", \"top products\", \"what should I restock\"            | `get_top_selling_products`                                                                                                                                                                                                                                                          |\n| \"How many orders are unfulfilled right now\"                           | `get_orders_by_status`. ⛔ Counts the **last 30 days only**, and returns counts and percentages with no ids and no dates. Say the window when you quote the number, and never use it to find the oldest order: that is `list_orders` with `sortBy: \"createdAt\"`, `sortOrder: \"asc\"` |\n| \"What came in today\", \"the last few orders\"                           | `get_recent_orders`                                                                                                                                                                                                                                                                 |\n| \"How many products do I have\"                                         | `count_products`                                                                                                                                                                                                                                                                    |\n| \"Who are my best customers\", \"how many customers\"                     | `list_customers`                                                                                                                                                                                                                                                                    |\n| \"What has this customer spent\"                                        | `get_customer`, then `get_customer_orders`                                                                                                                                                                                                                                          |\n| \"How is this product rated\", \"what do people say\"                     | `get_product_review_stats`, then `list_product_reviews`                                                                                                                                                                                                                             |\n| \"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                                                                                                                                                         |\n\n⛔ 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.\n\n## The deeper reads, full connector only\n\nSince 2026-09-15 the full connector (Claude Code, Cursor, Claude Desktop) answers the questions the summary tools cannot. None of these are on the ChatGPT app's curated list, so check your tool list before promising one.\n\n| The merchant asks                                                                 | Call                                                                                                                                                                                                                                    |\n| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| \"Do customers come back\", \"what is my repeat rate\"                                | `get_customer_stats`. ⛔ Only `newCustomers` follows the period; the other figures are all-time, and say so                                                                                                                              |\n| \"How many of the people who bought in March bought again\"                         | `get_cohort_retention`. ⛔ A window flagged not `mature` is a cohort that is too recent, not churn                                                                                                                                       |\n| \"Is the promo code working\", \"which codes get used\"                               | `get_coupon_performance`: lifetime figures, no period filter. Automatic rules are not coupons                                                                                                                                           |\n| \"Is the buy-two-get-one rule doing anything\"                                      | `get_discount_rules_performance`: lifetime, automatic rules only                                                                                                                                                                        |\n| \"How is my stock overall\", \"what is low\"                                          | `get_inventory_summary` for the four numbers now; `get_inventory_for_products` for the named items                                                                                                                                      |\n| \"How fast does this sell\", \"when will I run out\"                                  | `get_stock_velocity` (units per day over 7, 30 or 90 days, only products that sold at least one unit), combined with `get_product_inventory` for days of cover                                                                           |\n| \"Where are my visitors from\", \"mobile or desktop\", \"how many drop off at checkout\" | `get_storefront_traffic` for the summary, then `get_storefront_traffic_breakdown` with `breakdown` set to country, source, device, funnel, engagement or live                                                                            |\n| \"Is my storefront connected\", \"why does the channel show an error\"                | `get_connection_health`: every channel and installed app with last ping and last error; no secrets                                                                                                                                      |\n| \"Is the loyalty club paying off\"                                                  | `get_loyalty_analytics` (30, 90 or 365 days): points issued and redeemed, liability, members by tier, the referral funnel; `null` when there is no programme                                                                             |\n| \"Are my webhooks working\", \"did my integration stop getting orders\"                | `get_webhook_health`, then `list_webhook_deliveries` on the failing subscription                                                                                                                                                         |\n\nThere is no `analytics:read` scope; analytics tools use `orders:read` (or the read scope of the resource they report on). So a key or grant with `orders:read` reaches revenue, order stats, retention and customer stats, `coupons:read` and `discount-rules:read` reach the two performance reads, `inventory:read` reaches the stock reads, `loyalty:read` the loyalty analytics, `settings:read` webhook health, and `store:read` the analytics summary, traffic and connection health. A refusal on one of these is a missing scope on the connection, not a missing feature.\n\n## Getting the period right\n\n- Read the store's timezone-sensitive settings and currency from `get_store` before quoting any figure. Never assume dollars.\n- 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.\n- 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.\n\n## Answer shape\n\nLead with the number. Then the comparison. Then one observation, if there is a real one.\n\n**Use this shape:**\n\n> ✓ 12,430 ILS across 58 orders in November so far.\n>\n> 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.\n>\n> Most of the growth is Ceramic Mug, which went from 12 units to 31.\n\n**Ranking, use this shape:**\n\n> ✓ Your top sellers over the last 30 days, by units:\n>\n> 1. Ceramic Mug, 31 sold, 2,015 ILS\n> 2. Linen Scarf, 18 sold, 2,340 ILS\n> 3. Wool Hat, 14 sold, 1,120 ILS\n>\n> 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\".\n\n**Not enough data, use this shape:**\n\n> 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.\n\n## Rules\n\n- Always fetch a comparison period. A bare number is not an answer.\n- Use the store's currency from `get_store`.\n- State the exact dates you used.\n- Say when the sample is too small for a percentage rather than reporting a 200% rise off two orders.\n- Never sum a paged list by hand.\n- Do not invent a cause for a change. \"Revenue is up 27%\" is a fact; \"because of your Instagram post\" is a guess. `get_storefront_traffic_breakdown` with `breakdown: \"source\"` shows where visitors came from, which is evidence, not a cause; nothing here reads ad spend.\n- Read only. If the merchant reacts to a number by wanting to act, hand off rather than acting here.\n- If a tool returns nothing for the period, say the period was empty. Do not silently widen the window to find something.\n\n## Cross-skill connections\n\n- The general morning briefing rather than a specific question: `brainerce-daily-summary`.\n- The merchant wants to act on a slow seller by discounting it: `brainerce-launch-a-sale`.\n- They want to restock a best seller: `brainerce-product-onboarding`.\n- The numbers point at a problem rather than a trend: `brainerce-store-health`.\n\nRoute once, and do not bounce back and forth.\n"
}