From 7a5171d4ba6fee8db28dd2089faaaf4822e0acfe Mon Sep 17 00:00:00 2001
From: Nikita Andreev <73538828+fiharet34@users.noreply.github.com>
Date: Fri, 7 Aug 2026 15:56:33 +0100
Subject: [PATCH] Make seller-copilot marketplace-aware: add Shopee Brasil
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds Shopee coverage to the skill merged in #27, as one marketplace-aware skill
rather than a second one. The two marketplaces are independent datasets that may
not be mixed in a single query, and a seller does not always say which they
mean — so deciding is the first step of the work, and it has to live where the
question lands. A separate Shopee skill would only ever be reached by someone
who already said "Shopee".

references/which-marketplace.md holds the decision logic and the capability
comparison; SKILL.md gains a Step 0 that settles the marketplace before any
analysis and asks rather than defaulting when it cannot be inferred. Nine
shopee- prefixed procedures cover what Shopee data actually supports. The
fifteen Mercado Livre references are untouched, byte-identical to what merged.

Shopee coverage is narrower and the skill says so rather than approximating: no
keyword data, no seasonality or long-run trend before May 2026, no buy-box,
badge tiers rather than a medal ladder, no fulfilment attributes, no
cancellation rate, no brand share, item-level pricing only, and no fee data so
no real margin. One capability runs the other way — Shopee has a per-item
weekly sales series that Mercado Livre lacks.

Verified by a 22-item pack through a real agent CLI, scored by trace assertions
rather than judge scores because a judge cannot see which tool was called:
routing 8/8, ambiguity 2/3, both-marketplace 3/3, capability boundaries 8/8. The
Mercado Livre quality pack was re-run to confirm the description trim did no
harm — six comparable items moved 4.67 to 4.50, four of them unchanged, inside
the retest band this project has seen on repeat runs.

The one failure is a request whose phrasing matches a focused skill's triggers
closely enough that the focused skill answers it directly; since every focused
skill is Mercado Livre only, an ambiguous question can be answered from Mercado
Livre data without the seller being asked which marketplace they meant. This
skill never loads in that path, so it cannot intervene.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 skills/seller-copilot/SKILL.md                | 112 ++++++++++++++----
 .../shopee-assortment-and-price-gaps.md       |  84 +++++++++++++
 .../references/shopee-category-evaluation.md  |  92 ++++++++++++++
 .../references/shopee-competitor-profile.md   |  94 +++++++++++++++
 .../references/shopee-discover-competitors.md |  98 +++++++++++++++
 .../references/shopee-find-new-products.md    |  97 +++++++++++++++
 .../references/shopee-item-momentum.md        |  84 +++++++++++++
 .../references/shopee-market-structure.md     | 100 ++++++++++++++++
 .../references/shopee-pricing.md              |  85 +++++++++++++
 .../references/shopee-validate-product.md     |  83 +++++++++++++
 .../references/which-marketplace.md           | 100 ++++++++++++++++
 11 files changed, 1008 insertions(+), 21 deletions(-)
 create mode 100644 skills/seller-copilot/references/shopee-assortment-and-price-gaps.md
 create mode 100644 skills/seller-copilot/references/shopee-category-evaluation.md
 create mode 100644 skills/seller-copilot/references/shopee-competitor-profile.md
 create mode 100644 skills/seller-copilot/references/shopee-discover-competitors.md
 create mode 100644 skills/seller-copilot/references/shopee-find-new-products.md
 create mode 100644 skills/seller-copilot/references/shopee-item-momentum.md
 create mode 100644 skills/seller-copilot/references/shopee-market-structure.md
 create mode 100644 skills/seller-copilot/references/shopee-pricing.md
 create mode 100644 skills/seller-copilot/references/shopee-validate-product.md
 create mode 100644 skills/seller-copilot/references/which-marketplace.md

diff --git a/skills/seller-copilot/SKILL.md b/skills/seller-copilot/SKILL.md
index 0ee9fc3..d73e16b 100644
--- a/skills/seller-copilot/SKILL.md
+++ b/skills/seller-copilot/SKILL.md
@@ -1,25 +1,27 @@
 ---
 name: seller-copilot
 description: >
-  Deeper Mercado Livre (Brasil) seller analyses on JoomPulse data, beyond what a
-  single skill in this repo answers: real margins and ML fees ("minha margem
-  real", "how much do I actually make", "taxas do ML"); pricing and price wars
-  ("qual preço cobrar", "estou caro?"); is a product worth selling ("devo vender
-  este produto", "vale a pena"); finding new products ("o que vender agora");
-  vetting a supplier catalogue and import-vs-domestic ("vale a pena importar");
-  fixing a listing that does not sell ("meu anúncio não vende", "melhorar meu
-  anúncio"); who my competitors are and where I lose to them ("quem são meus
-  concorrentes", "onde estou perdendo", "o que eles vendem que eu não vendo");
-  market structure ("quem domina a categoria"); trends and when to stock
-  ("quando estocar", "sazonalidade"). Also takes vague or multi-part requests
-  ("me ajuda a crescer", "por onde começo") and asks one or two questions first.
-  Sales and revenue are JoomPulse estimates, not real transactions.
+  Deeper Mercado Livre (Brasil) and Shopee Brasil seller analyses on JoomPulse
+  data, beyond what a single skill in this repo answers: real margins and fees
+  ("minha margem real", "taxas do ML"); pricing and price wars ("qual preço
+  cobrar", "estou caro?"); is a product worth selling ("vale a pena vender
+  isso"); finding new products ("o que vender agora"); vetting a supplier and
+  import-vs-domestic ("vale a pena importar"); a listing that does not sell
+  ("meu anúncio não vende"); who my competitors are and where I lose to them
+  ("quem são meus concorrentes", "onde estou perdendo"); market structure ("quem
+  domina a categoria"); trends and when to stock ("quando estocar",
+  "sazonalidade"). Covers both marketplaces, including Shopee ("vender na
+  Shopee", "minha loja na Shopee"), and asks which one when unclear. Also takes
+  vague or multi-part requests ("me ajuda a crescer", "por onde começo") and
+  asks one or two questions first. Sales and revenue are JoomPulse estimates,
+  not real transactions.
 ---
 
 # Seller Copilot
 
-This skill is the **consultant front door** for Mercado Livre (Brasil) sellers working
-with JoomPulse data. It handles two kinds of request that a single focused skill does not:
+This skill is the **consultant front door** for sellers working with JoomPulse data, on
+**both marketplaces it covers — Mercado Livre (Brasil) and Shopee Brasil**. It handles two
+kinds of request that a single focused skill does not:
 
 1. **Vague or compound questions** — "help me grow my store", "por onde começo", "analisa
    minha operação" — where the seller does not yet know which analysis they need.
@@ -34,7 +36,12 @@ consolidated, verdict-first answer**.
 
 ## When to use another skill instead
 
-If the request maps cleanly onto a single focused skill in this repo, use that skill —
+**Only for Mercado Livre.** Every focused skill in this repo is Mercado Livre only, so
+handing a **Shopee** question to one returns Mercado Livre data to a Shopee seller — a wrong
+answer that looks right. For Shopee there is nothing to defer to: do the analysis here, from
+the `references/shopee-*` files.
+
+For a Mercado Livre request that maps cleanly onto a single focused skill, use that skill —
 it is faster and more direct. In particular:
 
 - One category's opportunity snapshot → **category-opportunity-index**
@@ -64,10 +71,15 @@ MCP setup before it can analyse marketplace data.
 
 ## Scope
 
-- **Mercado Livre (Brasil) only.** The analyses here cover Mercado Livre Brasil. If the
-  seller asks about another marketplace, say that it falls outside what **this skill**
-  does — do not claim JoomPulse holds no data for it, which may not be true — and still
-  answer the Mercado Livre part in full, rather than refusing the whole request.
+- **Mercado Livre (Brasil) and Shopee Brasil.** Both are covered, with different depth —
+  see [which-marketplace.md](references/which-marketplace.md). Any other marketplace falls
+  outside what this skill does; say so and still answer the in-scope part in full.
+- **Never mix the two marketplaces in one query, table or total.** They are separate
+  datasets with different grains and estimate methods; a combined figure is a wrong number,
+  not a fuller picture. Comparing them means two analyses side by side, in prose.
+- **Shopee coverage is narrower.** No keyword data, no seasonality or long-run trend
+  (history begins May 2026), no buy-box, no medals, no fee data. Name the gap rather than
+  answering it from Mercado Livre.
 - **Sales, orders, revenue and GMV are JoomPulse estimates**, not real transactions.
 - **Real marketplace history**, by contrast: price, rating and review counts, and a seller's
   reputation, medal, cancellation rate and completed-sales counters. Do not label these
@@ -86,6 +98,24 @@ MCP setup before it can analyse marketplace data.
 
 ## How to use this skill
 
+### Step 0 — Settle the marketplace first
+
+Before any analysis, know which marketplace the question is about. Getting this wrong wastes
+the whole analysis and hands the seller figures for a market they do not sell on.
+
+- The seller said so → take them at their word.
+- An identifier beginning **`MLB`**, or a `mercadolivre.com.br` link → Mercado Livre. A **bare
+  10–11 digit number**, or a `shopee.com.br` link → Shopee.
+- The request only makes sense on one of them — buy-box, medals, keywords, fulfilment
+  programme are Mercado Livre concepts → Mercado Livre.
+- **Otherwise ask, in one short question, before querying.** Do not guess and do not default
+  to Mercado Livre because it is the richer dataset.
+
+Read [which-marketplace.md](references/which-marketplace.md) whenever the answer is not
+immediate, the seller mentions both, or the request assumes a capability one marketplace
+lacks. It carries the full capability comparison and how to handle a genuine both-marketplace
+request.
+
 ### Step 1 — Classify the request
 
 Place it in exactly one of these:
@@ -135,6 +165,10 @@ Pick the **minimal set** that answers the question. Read the matching file in
 `references/` and follow its procedure. Run them in this same conversation, one after
 another; there is no need to announce the internal steps to the seller.
 
+**The tables below are for Mercado Livre.** For a Shopee request, use the Shopee table further
+down instead — the procedures differ, and the Mercado Livre files assume mechanics and data
+Shopee does not have.
+
 **What to sell**
 
 | The question | Read |
@@ -172,6 +206,24 @@ another; there is no need to announce the internal steps to the seller.
 | Rank the sellers / brands in a category | the **top-sellers-in-category**, **top-brand-position-tracker** skills |
 | What changed since last period? | the **category-monitor**, **product-change-monitor** skills — each needs a previous snapshot from the seller |
 
+**Shopee**
+
+Use these instead of everything above when the marketplace is Shopee. There are no focused
+Shopee skills to defer to.
+
+| The question | Read |
+|---|---|
+| Is this category worth entering? | `references/shopee-category-evaluation.md` |
+| Who dominates this category? How concentrated is it? | `references/shopee-market-structure.md` |
+| What should I sell? | `references/shopee-find-new-products.md` |
+| Is *this specific* item worth selling? | `references/shopee-validate-product.md` |
+| How has this item been selling over time? | `references/shopee-item-momentum.md` |
+| Who are my competitors? | `references/shopee-discover-competitors.md` |
+| Tell me about this shop | `references/shopee-competitor-profile.md` |
+| What do they sell that I don't? How do prices compare? | `references/shopee-assortment-and-price-gaps.md` |
+| What price should I charge? | `references/shopee-pricing.md` |
+| Keywords, seasonality, when to stock, buy-box, medals, fees, margin | **Not available on Shopee** — name the gap, offer the nearest real alternative, and never answer it from Mercado Livre data. See [which-marketplace.md](references/which-marketplace.md) |
+
 **Caveats that must survive a handoff**
 
 Handing work to a focused skill is usually the right call — it is faster and more direct. But a
@@ -219,7 +271,25 @@ the refined request — no need to re-classify unless the topic changed.
 ## Reference files
 
 Each file documents one analysis procedure. Read the one you need; they are not meant to
-be read all at once.
+be read all at once. Files prefixed `shopee-` are Shopee Brasil; the rest are Mercado Livre.
+
+- [Which marketplace?](references/which-marketplace.md) — how to decide, what each
+  marketplace can and cannot answer, and how to handle a request spanning both. **Read this
+  first whenever the marketplace is not obvious.**
+
+**Shopee Brasil**
+
+- [Category evaluation](references/shopee-category-evaluation.md),
+  [market structure](references/shopee-market-structure.md),
+  [find new products](references/shopee-find-new-products.md),
+  [validate a product](references/shopee-validate-product.md),
+  [item momentum](references/shopee-item-momentum.md),
+  [discover competitors](references/shopee-discover-competitors.md),
+  [shop profile](references/shopee-competitor-profile.md),
+  [assortment and price gaps](references/shopee-assortment-and-price-gaps.md),
+  [pricing](references/shopee-pricing.md).
+
+**Mercado Livre (Brasil)**
 
 - [Margin and fees](references/margin-and-fees.md) — net margin from public ML fee tables
   plus seller-supplied costs; what each fee takes.
diff --git a/skills/seller-copilot/references/shopee-assortment-and-price-gaps.md b/skills/seller-copilot/references/shopee-assortment-and-price-gaps.md
new file mode 100644
index 0000000..4eeafdd
--- /dev/null
+++ b/skills/seller-copilot/references/shopee-assortment-and-price-gaps.md
@@ -0,0 +1,84 @@
+# Assortment and price gaps on Shopee
+
+What competitors sell that the seller doesn't, and how the two price ranges line up. Two
+questions that are usually asked together and should be answered together.
+
+## What to ask for
+
+- **The seller's own range** — their shop, or a list of what they sell. Without it there is no
+  gap analysis; ask rather than guessing.
+- **The competitor set** — from [shopee-discover-competitors.md](shopee-discover-competitors.md) if not already
+  established, or a shop the seller names.
+- **The category** to bound the comparison.
+
+## Method — the gap side
+
+1. Pull the competitor's items in the bounded category.
+2. Pull the seller's own items in the same category.
+3. **Sort the gaps by estimated revenue, not by count.** A gap only matters if the missing item
+   actually earns. Twenty missing products that sell nothing are not a finding.
+4. For each candidate gap, sanity-check demand the way
+   [shopee-validate-product.md](shopee-validate-product.md) does before recommending it. A gap is not
+   automatically an opportunity.
+
+**Three items a competitor earns well from, which the seller could plausibly source, is a better
+answer than forty items they cannot.**
+
+## Method — the price side
+
+Use the **whole distribution**, not the average. An average is dragged around by outliers and
+hides where the market actually transacts.
+
+- Where do the seller's prices sit against the competitor's range — below, inside, above?
+- Where in the range do **units** actually move? That is the meaningful band, and it is often not
+  the cheapest end.
+- **Read the price history** before advising. An item whose price has drifted steadily downwards
+  is in a race to the bottom, and the advice changes from "match the price" to "compete on
+  something other than price".
+
+Price history is available as intervals — a price and the span it held — and is **item-level
+only**, so never claim a particular variant, size or colour moved.
+
+## Interpreting the two together
+
+- **A gap at a price band the seller already serves** — the easiest win; they know the buyer.
+- **A gap at a band they don't serve** — a real decision, not a quick add. Say what entering that
+  band would require.
+- **No gaps, but a price disadvantage** — the answer is pricing, not assortment. Hand off to
+  [shopee-pricing.md](shopee-pricing.md) rather than inventing assortment advice.
+- **Gaps everywhere and no price disadvantage** — usually means the competitor is simply larger.
+  Say so; "add forty products" is not advice.
+
+## Procedure
+
+1. Bound the category and **pin one level**.
+2. Read the competitor's items and the seller's, in that same bounded scope.
+3. Difference the two ranges; sort candidates by estimated revenue.
+4. Build the price distribution for both sides and locate where units move.
+5. Check the price history of the contested items.
+6. Validate the top gap candidates before recommending them.
+
+## Output
+
+**Verdict first:** the single gap worth acting on, and whether the seller's pricing is helping or
+hurting.
+
+Then two views — the gap table (item, estimated sales and revenue, price, why it matters) and the
+price comparison showing both ranges and where units concentrate. Cap the gap table at ten rows
+by default, state the total, and **never pad it to reach a round number**.
+
+State the estimate disclaimer once. Use full BRL precision. Show `—` for unavailable values.
+
+## Boundaries
+
+- **Without the seller's own range there is no gap analysis.** Ask for it; do not assume a
+  catalogue.
+- **Sales and revenue are estimates** from rounded counters; prices are real. Do not rank gaps on
+  small estimated differences.
+- **Tracked items only** — a competitor may carry products that have never sold and are therefore
+  invisible here, so the assortment view is a lower bound, not their full catalogue.
+- **No per-variant view.** A competitor's size or colour range is not visible; do not infer it.
+- **No catalogue or buy-box**, so "the same product" is a judgement about comparable items rather
+  than a platform fact. Say which items you treated as comparable.
+- **A gap is not automatically an opportunity** — the seller may be unable to source it, or may
+  have dropped it deliberately. Ask before assuming it is an oversight.
diff --git a/skills/seller-copilot/references/shopee-category-evaluation.md b/skills/seller-copilot/references/shopee-category-evaluation.md
new file mode 100644
index 0000000..c4a81b2
--- /dev/null
+++ b/skills/seller-copilot/references/shopee-category-evaluation.md
@@ -0,0 +1,92 @@
+# Evaluate a Shopee category
+
+Is this category worth entering? Judged on demand, competition and room to earn — not on size
+alone.
+
+## What to ask for
+
+- **The category**, at whatever depth the seller has in mind, or a list to compare.
+- If free text matches several plausible categories, **list the candidates with their level and
+  let the seller pick** — never guess between unrelated categories. Shopee's Brazilian taxonomy
+  does not group things the way sellers often expect; electronics in particular is split across
+  several separate top-level categories rather than sitting under one.
+
+## The two constraints that shape every answer here
+
+**Only three levels of category analytics exist.** Anything deeper is counted at its
+third-level ancestor. So "find me a tiny sub-niche" is not answerable at the analytics level —
+say so, and offer the item-level view in [shopee-find-new-products.md](shopee-find-new-products.md) instead,
+which does reach deeper.
+
+**Every level carries its whole subtree.** A parent's figures already contain all of its
+children's, by construction. **Adding levels together counts the same sales several times over
+— roughly threefold.** Confine any total, ranking or comparison to a single level, and say
+which level you used.
+
+## The screening rubric
+
+Judge a category on four things:
+
+- **Opportunity tier** — the composite signal of an under-exploited category, combining
+  concentration, saturation and earnings per seller. High is the shortlist; low is a warning.
+- **Concentration** — how tightly GMV is held across sellers. Low or medium means the field is
+  open. See [shopee-market-structure.md](shopee-market-structure.md) for what the index does and does not mean.
+- **Earnings per seller** — reported as a tier judged against other categories under the same
+  top-level parent, which is more useful than an absolute figure. Prefer the tier.
+- **Growth month over month** — the only growth signal available.
+
+**Do not carry over absolute currency thresholds from another marketplace.** Shopee Brasil is a
+different market with a different size distribution and a different badge-award rate, so a
+revenue floor that means "substantial" elsewhere means something else here. Judge a category
+**relative to its siblings** — other categories at the same level under the same parent — and
+say that is the comparison you made. If you need an absolute floor, derive it from the sibling
+distribution in the same answer rather than asserting one.
+
+Use it as a rubric, not a checklist: a category can miss one criterion and still be worth
+entering if the seller has a specific edge. Say which criterion it misses and what the edge
+would have to be.
+
+## Confirm from more than one angle
+
+- **Seller mix** — how much of the category is held by official (Mall) and preferred shops
+  versus regular sellers. A category that is mostly regular sellers is still developing.
+- **Cross-border share** — how much of the category is served from outside Brazil. A high share
+  changes who the seller is really competing with, and on what lead time.
+- **Item counts and how they moved** — a category adding items faster than it adds revenue is
+  getting more crowded, not more attractive.
+
+## Procedure
+
+1. Resolve the category and confirm its level.
+2. Pull the latest month's figures for that category **at one pinned level**, and the previous
+   month for the month-over-month read.
+3. Rank or compare candidates **by the rubric, not by revenue alone**, against same-level
+   siblings.
+4. Check the seller mix and cross-border share before concluding.
+5. **Confirm the month on the rows you got back.** A marker for "current period" is unreliable
+   here — read the date rather than trusting the marker.
+
+## Output
+
+**Verdict first, in plain language** — enter, enter with a condition, or avoid — then the
+opportunity view: the category against its siblings on demand, concentration, earnings per
+seller and growth, banded so the shape reads at a glance. When comparing several categories,
+rank them and say which one you would pick and why.
+
+Say which level you compared at. Never fabricate a missing value — show `—`. State the estimate
+disclaimer once. Use full BRL precision.
+
+## Boundaries
+
+- **Revenue and order figures are estimates**, rebuilt from Shopee's rounded public sold
+  counters. Small differences between categories are noise.
+- **Month-over-month is the only trend available.** There is no longer-run trend and no
+  seasonal shape — the history begins in May 2026 and is too short. If asked whether a category
+  is seasonal, say the data cannot answer it yet rather than reading a season into two or three
+  months.
+- **Three levels only.** Do not imply a deeper niche read than exists.
+- **Brand concentration is not computable** — coverage is a lower bound, so a category that
+  looks brand-free may simply have untracked brands.
+- Screening well is not the same as being winnable: a well-screening category can still contain
+  a locked-up niche, and one the seller knows nothing about is riskier than a slightly worse one
+  they understand.
diff --git a/skills/seller-copilot/references/shopee-competitor-profile.md b/skills/seller-copilot/references/shopee-competitor-profile.md
new file mode 100644
index 0000000..be2d902
--- /dev/null
+++ b/skills/seller-copilot/references/shopee-competitor-profile.md
@@ -0,0 +1,94 @@
+# Profile a Shopee shop
+
+Read one shop — a competitor's, or the seller's own — and say what the numbers mean together. A
+profile that lists nine metrics without a read has not answered the question.
+
+## What to ask for
+
+- **The shop**, by Shopee link, username, shop identifier, or name.
+- Whether they want the **whole store** or the shop **within one category**. These are different
+  reads and the figures differ; see below.
+
+## Whole-store versus in-category — decide first
+
+The shop profile is **whole-store**: every rollup covers all categories the shop sells in. For
+how a shop performs *inside one category*, that is a different read — see
+[shopee-discover-competitors.md](shopee-discover-competitors.md), which carries category-scoped figures.
+
+Getting this wrong produces confidently wrong answers: a generalist shop can look enormous
+store-wide while being a minor presence in the niche the seller cares about. **Say which read you
+did**, every time.
+
+The two cannot be joined in one query. If the answer needs both, that is two reads, integrated in
+prose.
+
+## What to read, and what is real
+
+Mark provenance as you report — this profile mixes real observations with estimates:
+
+- **Badge tier** — official (Shopee Mall), preferred (verified), or regular. **Real**, and
+  mutually exclusive. There is no medal ladder, no reputation score and no reputation history on
+  Shopee; **inventing any of these is fabrication.**
+- **Shop rating and review count** — **real**. Note this is the shop-level rating, distinct from
+  the ratings of individual items.
+- **Follower count** — **real**.
+- **Location** — **real**. A Brazilian state, or a marker showing the shop ships cross-border.
+- **Shop age**, from its creation date — **real**.
+- **Item counts** — how many tracked items, how many with sales, how many carry video, how many
+  ship cross-border, how many brands. Real counts, but **over tracked items only**.
+- **Average price and average order value** — average price is real; **average order value is an
+  estimate**, since it is weighted by the estimated sold figures.
+- **How its items are trending** — counts of items growing, stable and falling. **Estimates.**
+
+Do not blanket-label the profile as estimated: the badge tier, ratings, review and follower
+counts are exactly the figures a seller should be able to trust, and calling them estimates pushes
+them to discount the firmest evidence in the profile. Equally, do not present the trend counts or
+average order value as observed.
+
+## Interpretation
+
+The figures matter less than the combination:
+
+- **Many items but few with sales** — a shop listing widely and converting narrowly. The
+  headline item count overstates it.
+- **A high share of falling items** — losing grip, whatever the size. An opening.
+- **Small, young, with most items growing** — the one to watch; they have found something.
+- **A strong rating on a thin review count** is not yet evidence. Say so rather than treating it
+  as equivalent to a strong rating on thousands.
+- **Official tier with a modest catalogue** — a brand operating its own store, not a reseller.
+  Competing with it means competing with the brand.
+- **Cross-border** — a different cost base and delivery promise; note it, because it changes what
+  "matching their price" would cost the seller.
+
+## Procedure
+
+1. Resolve the shop; confirm which one when the name is ambiguous rather than picking.
+2. Decide whole-store or in-category, and say which.
+3. Read the profile, marking provenance per figure.
+4. Where the question is competitive, put the figures beside the category norms from
+   [shopee-market-structure.md](shopee-market-structure.md) so "large" means something.
+5. For the shop's actual assortment, read its items — see
+   [shopee-assortment-and-price-gaps.md](shopee-assortment-and-price-gaps.md).
+
+## Output
+
+**Verdict first:** what kind of operator this is, and what it means for the seller.
+
+Then the profile table — badge tier, location, age, rating and reviews, followers, item counts,
+price and order value, trend mix — with provenance marked. Close with the interpretation, not
+just the numbers.
+
+State the estimate disclaimer once. Use full BRL precision. Show `—` for unavailable values.
+
+## Boundaries
+
+- **No revenue history per shop.** There is no monthly or weekly revenue series for a Shopee
+  shop, so "how much did this shop make last month" is not answerable directly. The nearest real
+  route is summing the estimated revenue of its items — say that is what you did and that it is an
+  estimate built from item rows.
+- **No cancellation rate**, no reputation ladder, no medal history.
+- **No stored history for the shop profile** — it is a snapshot. Period-over-period comparison
+  needs a previous snapshot the seller supplies.
+- **Counts cover tracked items only** — items that have never sold are invisible, so every count
+  is a lower bound.
+- **Brand counts are a lower bound** and brand share is not computable.
diff --git a/skills/seller-copilot/references/shopee-discover-competitors.md b/skills/seller-copilot/references/shopee-discover-competitors.md
new file mode 100644
index 0000000..0b3164e
--- /dev/null
+++ b/skills/seller-copilot/references/shopee-discover-competitors.md
@@ -0,0 +1,98 @@
+# Discover Shopee competitors
+
+Find who the seller actually competes with, and characterise **how** each one competes. A ranked
+list of the biggest shops is a different, less useful answer.
+
+## What to ask for
+
+- **The category or niche**, and — if they have one — the seller's own shop or an item of theirs
+  to anchor the comparison.
+
+## Shopee's advantage here, and its one catch
+
+The sellers-in-category view is a **full census**: every shop with tracked items in the category
+appears, not a truncated leaderboard. So "how many sellers am I really up against" has a real
+answer, subject to the tracking rule below.
+
+**The catch: a shop appears once per category it sells in, at every ancestor level.** Reading
+without pinning a single category therefore counts the same shop repeatedly and inflates
+everything. **Always pin exactly one category** and say which level it was.
+
+## The ranking problem — say which axis you used
+
+**There is no revenue-within-a-category figure for Shopee shops.** This is the single most
+important limitation of this analysis, because "top sellers by revenue in this category" is what
+sellers usually ask for.
+
+What exists instead, per shop within the category:
+
+- **How many of its items sell there** — the closest proxy for presence
+- **Review count within the category** — the closest proxy for accumulated volume
+- **Average price and average order value within the category**
+- **Rating within the category**
+- **How many brands it carries there**
+
+So rank by item presence or by review count, **state which axis you chose and why**, and do not
+call the result a revenue ranking. If the seller specifically wants revenue, say the figure does
+not exist at category level and offer the item-level route: sum the estimated revenue of that
+shop's items in the category, labelled as an estimate built from item rows.
+
+## Category-scoped versus store-wide — do not mix them
+
+Each shop row carries **two families of figures**: its stats *within this category*, and its
+*whole-store* totals repeated on every row.
+
+**Never rank an in-category list by a store-wide figure.** A large generalist shop with a
+marginal presence in the niche will top the list on store-wide numbers while being irrelevant to
+the seller. When a store-wide figure is genuinely useful — to show that a rival is a giant elsewhere
+— label it explicitly as store-wide.
+
+## Four kinds of competitor
+
+Segment them, because the advice differs:
+
+- **Direct** — comparable items, comparable price band. The immediate fight.
+- **Potential** — same category, different price band. They become direct if either side moves.
+- **Adjacent** — serving the same need from a neighbouring category.
+- **Rising** — small but growing quickly. **These matter most**: they catch demand shifts before
+  the established shops, and they are invisible in any list ranked by size.
+
+## What to read per competitor
+
+Badge tier (official / preferred / regular), location — including whether they are cross-border —
+rating and review count, price band, item count in the category, and how many of their items are
+growing versus falling.
+
+## Procedure
+
+1. Resolve the category; **pin one level** and say which.
+2. Pull the seller census for that category.
+3. Rank on a stated axis; never a store-wide field.
+4. Segment into the four kinds above.
+5. For the handful that matter, pull the full shop profile separately — see
+   [shopee-competitor-profile.md](shopee-competitor-profile.md). The two views cannot be joined in one query,
+   so this is a second read, and the shop-level numbers are whole-store unless stated.
+
+## Output
+
+**Verdict first:** who the seller is actually competing with, and which one to watch.
+
+Then the competitor table — shop, badge tier, location, items in category, rating, review count,
+price band, and the competitor type — with the ranking axis named in the caption. Follow with a
+short note on the rising shops.
+
+State the estimate disclaimer once. Use full BRL precision. Show `—` for unavailable values.
+Link shops by their username where present; there is no JoomPulse dashboard link for Shopee rows.
+
+## Boundaries
+
+- **No revenue-per-category figure exists.** Always say which axis the ranking used.
+- **No buy-box or catalogue** — "who else sells this exact product" is not answerable. Compare
+  comparable items and say so.
+- **No seller medals or reputation ladder** — badge tier is official, preferred or regular, and
+  nothing finer. Inventing a medal, a reputation score or a tier ladder is fabrication.
+- **No cancellation rate** for Shopee shops.
+- **The census covers tracked items only** — shops whose items have never sold do not appear, so
+  the count is a lower bound.
+- A shop's ranking is an estimate built on rounded counters — do not overstate small differences
+  between adjacent rows.
diff --git a/skills/seller-copilot/references/shopee-find-new-products.md b/skills/seller-copilot/references/shopee-find-new-products.md
new file mode 100644
index 0000000..4e959a1
--- /dev/null
+++ b/skills/seller-copilot/references/shopee-find-new-products.md
@@ -0,0 +1,97 @@
+# Find products to sell on Shopee
+
+A shortlist of concrete candidates, each checked before it is recommended. **Not a list of
+bestsellers** — bestsellers are the most contested shelves, and handing a new seller the top of
+the category is handing them the hardest fight.
+
+## What to ask for
+
+- **The category or niche**, and any constraint that narrows it: budget, price band, whether
+  they want to import.
+- If nothing is named, ask for a category. Do not pick one.
+
+## Where the item view helps
+
+Category analytics stop at three levels, but the **item view reaches deeper** — items carry
+their own category path several levels down. So a niche that is invisible in
+[shopee-category-evaluation.md](shopee-category-evaluation.md) can still be worked here. Say which you used.
+
+## What to read per candidate
+
+- **Estimated units and revenue over the last 30 days**, and the item's estimated lifetime
+  monthly average. The gap between the two is the momentum read.
+- **A direction flag** comparing the current rate against the item's own lifetime average —
+  growing, stable or falling. Unlike some marketplaces, this is a legitimate item-level signal
+  here; use it.
+- **Price** — real, not estimated.
+- **Rating and review count** — real. Reviews are also the closest thing to a demand history.
+- **Favourites** — a soft interest signal with no direct equivalent elsewhere.
+- **Shop tier** — official, preferred or regular — and whether the item ships cross-border.
+- **Content signals** — photo count, whether the item has video.
+- **When the item was created**, and **when it was last seen**. An item not seen recently may
+  simply be gone; do not present a stale row as a live opportunity.
+
+## The four checks
+
+Every candidate must pass all four. A shortlist that passes three of four is not a shortlist;
+it is a list of things that will disappoint.
+
+1. **Real demand** — estimated sales at a level worth the effort, not a handful of units.
+2. **Beatable competition** — the shelf is not held by official shops with thousands of reviews
+   the seller cannot match for a year.
+3. **A reachable price band** — where units actually move, not the cheapest or the most
+   expensive corner.
+4. **Room to differentiate** — weak ratings, thin content, or no brand, so a better offer has
+   somewhere to land.
+
+Say which check each rejected candidate failed. **An empty shortlist is a real answer** — say
+the category has nothing worth entering rather than lowering the bar to fill rows.
+
+## Coverage — state this once
+
+The item data is **not a census of Shopee**. Only items with at least one lifetime sale are
+tracked. So "how many items exist in this niche" is a lower bound, and an absent item is not
+evidence the product is unsold — it may simply be untracked.
+
+Sold counters are **rounded by Shopee into buckets** before JoomPulse sees them. Treat small
+differences between candidates as noise, and do not rank on a gap of a few units.
+
+## What cannot seed a shortlist here
+
+- **No keyword or search-demand data exists for Shopee.** If the seller asks for the most
+  searched terms, say the data does not exist for this marketplace rather than substituting a
+  competition count, which measures something else entirely.
+- **No seasonal signal.** "What should I stock for the season" cannot be answered from Shopee
+  history yet.
+- Any date or event you supply from your own knowledge — a shopping festival, a holiday — is an
+  **external claim** and must be marked as such, including inside a table cell.
+
+## Procedure
+
+1. Resolve the category; confirm the level and say which you used.
+2. Pull candidate items, ranked by estimated recent sales or revenue.
+3. Apply the four checks; drop anything that fails one.
+4. For survivors worth a closer look, read the week-by-week history — see
+   [shopee-item-momentum.md](shopee-item-momentum.md) — to tell a rising item from one already fading.
+5. Check the last-seen date before presenting anything.
+
+## Output
+
+**Verdict first:** the candidates worth pursuing, and the single one you would start with.
+
+Then the shortlist table — item, price, estimated recent sales and revenue, direction, rating
+and review count, shop tier — with a one-phrase reason per row saying what made it stand out.
+
+State the estimate disclaimer once. Use full BRL precision. Show `—` for missing values. Link
+items in Shopee's own item-link form; there is no JoomPulse dashboard link for Shopee rows.
+
+## Boundaries
+
+- **Sales and revenue are estimates** from rounded counters; price and reviews are real.
+- **A stock budget does not translate into units.** A budget constrains the seller's **unit
+  cost**, which the marketplace does not show — only selling prices. Use selling price as an
+  upper-bound proxy, say so, and ask for unit cost before implying what the budget buys.
+- **No supplier, landed cost or fee data** — so a candidate is a demand-and-competition verdict,
+  never a profitability one. Say that plainly.
+- Kits and bundles are harder to read than single items — say so rather than treating a kit like
+  a simple product.
diff --git a/skills/seller-copilot/references/shopee-item-momentum.md b/skills/seller-copilot/references/shopee-item-momentum.md
new file mode 100644
index 0000000..ddf9197
--- /dev/null
+++ b/skills/seller-copilot/references/shopee-item-momentum.md
@@ -0,0 +1,84 @@
+# Item momentum on Shopee
+
+How one item has been selling over time. Shopee carries a **week-by-week series per item**,
+which is genuinely richer than what the other marketplace offers — but only if its limits are
+stated, because the series looks more precise than it is.
+
+**This file covers momentum, not seasonality.** See the boundary at the end.
+
+## What to ask for
+
+- **The item**, by Shopee link or item identifier.
+- **The window** — default to everything available, which is not long.
+
+## The one thing to get right: the weekly figure is smoothed, not measured
+
+Shopee publishes only a **rolling roughly-monthly sold counter**. The weekly series is that
+counter rescaled to a week, with single-week gaps filled from neighbouring weeks.
+
+Consequences, all of which must reach the answer whenever weekly numbers are shown:
+
+- It is a **smoothed estimate, not a true weekly count**. A run of identical weekly values is an
+  artefact of the rescaling, not a remarkably steady product.
+- **A single week means very little.** Read the shape across several weeks; do not build a story
+  on one bar.
+- **Small week-to-week differences are noise.** Do not describe a 3% move as a change.
+- The underlying counter is **rounded into buckets**, so the precision implied by an exact number
+  is false. Round in the answer rather than quoting spurious digits.
+
+Describe it as "estimated weekly sales, smoothed from Shopee's rolling counter" the first time
+it appears. Never present it as observed weekly transactions.
+
+## What else forms the picture
+
+**Price history.** Available as intervals — a price and the span it held — rather than a daily
+value. Expand it against the weekly series to see whether a sales change followed a price
+change. **It is item-level only:** per-variant price history is not available, so never claim a
+particular size or colour moved in price.
+
+**Review history.** Recorded as **change points**, not as one row per day: a row appears when
+the count or rating moved. Two consequences: the series is sparse and gaps mean "no change", not
+"no data"; and **counts must never be added together across rows** — each row already carries the
+running total, so summing them multiplies the truth.
+
+Review accumulation is the closest thing to an independent demand check, since it does not come
+from the same rounded counter as the sales estimate. Where the two disagree, say so.
+
+**The item's own direction flag** — current rate against its lifetime average — is a quick read
+that agrees or disagrees with the series. When it disagrees, trust the series and say why.
+
+## Procedure
+
+1. Resolve the item; confirm it is still being observed.
+2. Pull the weekly series across the available window and read its **shape**, not its points.
+3. Overlay the price intervals and check whether moves line up with price changes.
+4. Pull the review change points as an independent cross-check.
+5. State the window explicitly, including that it begins in May 2026 at the earliest.
+
+## Output
+
+**Verdict first:** is this item rising, flat or fading, and how confident you are given the
+smoothing.
+
+Then the series — weeks against estimated units and revenue, with price shown alongside so the
+reader can see cause and effect — plus a short note on what the review history says.
+
+Mark the estimate disclaimer once, and label the weekly figure as smoothed the first time it
+appears. Any date or event you supply yourself — a shopping festival, a holiday — is an
+**external claim** and must carry a marker saying so, including inside a table cell.
+
+Show `—` for weeks with no observation. Do not interpolate visually and do not join across a gap
+as though it were measured.
+
+## Boundaries
+
+- **This cannot tell you whether a product is seasonal.** Shopee history begins in May 2026 —
+  well under a year — and there are no seasonal fields at all. A rise across the available window
+  is momentum, not a season. If the seller asks when to stock, say the history is too short to
+  establish a seasonal pattern, and offer the momentum read instead. **Do not infer a season from
+  a few months, and do not import a seasonal shape from another marketplace.**
+- **No year-on-year comparison** is possible for the same reason.
+- **Weekly values are smoothed and interpolated**, not measured.
+- **No per-variant history** — price and sales are item-level only.
+- **Review rows are change points**; never sum them.
+- Price is real; sales and revenue are estimates.
diff --git a/skills/seller-copilot/references/shopee-market-structure.md b/skills/seller-copilot/references/shopee-market-structure.md
new file mode 100644
index 0000000..9dc2172
--- /dev/null
+++ b/skills/seller-copilot/references/shopee-market-structure.md
@@ -0,0 +1,100 @@
+# Market structure on Shopee
+
+How a Shopee category is built: how big, how concentrated, who holds it, and which way it is
+moving. This answers "can I compete here", which is a different question from "is there demand
+here".
+
+## What to ask for
+
+- **The category**, at whatever depth the seller has in mind.
+
+## The concentration measure — read this before quoting it
+
+Shopee concentration is an **index computed across all sellers' shares**, running from 0 to 1
+and banded low / medium / high. It is **not** "the share held by the largest seller", and the
+two are not interchangeable.
+
+This matters because the obvious sentence — *"the top seller holds more than half the
+category"* — is **not** something this figure can support. A category can score high on the
+index because a handful of mid-sized sellers split it, with no single dominant player at all.
+
+So:
+
+- Describe it as **how tightly the category is held across all sellers**, not as one seller's
+  share.
+- If the seller specifically wants the leading seller's share, that has to come from ranking
+  the sellers themselves — see [shopee-discover-competitors.md](shopee-discover-competitors.md) — and say
+  that is a different measurement.
+- **Never compare this index against a concentration figure from another marketplace.** They
+  are computed differently; the numbers are not on the same scale.
+
+## What else to read
+
+**Size and shape.** Estimated revenue and orders, how many sellers have sales, how many items
+carry them, and the average order value.
+
+**Seller mix.** Official (Shopee Mall) shops, preferred (verified) shops, and regular sellers,
+as shares. A category dominated by official shops is a harder entry than the raw seller count
+suggests; one that is mostly regular sellers is still open.
+
+**Where the sellers are.** The location split — the largest Brazilian states, cross-border
+sellers, and everything else. A high cross-border share means competing against different
+economics and different lead times, which changes the advice even when the headline numbers
+look attractive.
+
+**Movement.** Month over month only. Say so.
+
+## Interpretation
+
+The combinations matter more than any single figure:
+
+- **Sizeable, low concentration, growing** — the best case; room to enter.
+- **Sizeable but tightly held** — entering means taking share from established sellers. Possible
+  only with a stated edge.
+- **Small but accelerating, with sellers arriving** — often more attractive than a large static
+  category, especially for a seller who can move quickly.
+- **Sizeable and shrinking** — the trap. The size looks reassuring; the direction is what
+  matters.
+
+## Procedure
+
+1. Resolve the category and **pin one level**. Every ancestor level repeats its whole subtree,
+   so mixing levels inflates the totals several times over.
+2. Read the latest month at that level, plus the previous month for movement.
+3. Read the seller mix and location split.
+4. Where the question is about who holds the category, rank the sellers themselves rather than
+   inferring it from the concentration index.
+5. **Confirm the month on the returned rows** rather than trusting a "current period" marker.
+
+## Screening several categories at once
+
+Ranked lists across categories have three failure modes worth guarding against:
+
+1. **Every row must come from returned data.** Never top a list up to a round number — if six
+   categories meet the filters, return six and say so.
+2. **Show the composite.** If the ranking combines concentration, growth and earnings per
+   seller, name the components and give each one's value per row. An unexplained ranking cannot
+   be argued with.
+3. **Compare like with like** — same level, same month. A level-3 category against a level-1
+   category is not a comparison.
+
+## Output
+
+**Verdict first:** is this a category the seller can compete in, and why.
+
+Then size, concentration band, seller mix and location split, and the month-over-month move.
+Band the concentration so the shape reads at a glance, and say which level and month the figures
+describe.
+
+State the estimate disclaimer once. Use full BRL precision. Show `—` for unavailable values.
+
+## Boundaries
+
+- **Revenue and order figures are estimates** from rounded public counters.
+- **Month over month is the only movement available.** No longer-run trend, no seasonal shape —
+  the history starts in May 2026. Two or three months is not a trend; say so rather than
+  implying direction.
+- **Brand concentration is not computable** — brand coverage is a lower bound, so a brand-share
+  figure would be misleading. Do not produce one.
+- Concentration describes the category, not the difficulty of any individual product — an open
+  category can still contain a locked-up niche.
diff --git a/skills/seller-copilot/references/shopee-pricing.md b/skills/seller-copilot/references/shopee-pricing.md
new file mode 100644
index 0000000..b666c2a
--- /dev/null
+++ b/skills/seller-copilot/references/shopee-pricing.md
@@ -0,0 +1,85 @@
+# Pricing on Shopee
+
+What to charge, and why. The answer is a **band with a reason**, not a single number.
+
+## What to ask for
+
+- **The item or the niche** being priced.
+- **Their unit cost**, if they want the floor respected. JoomPulse does not hold it, and without
+  it there is no floor — say so rather than pricing into a loss.
+
+## Method
+
+**1. Build the distribution, not the average.** Pull comparable items in the same category niche
+and look at the whole spread of prices. An average is pulled around by outliers and hides where
+the market actually transacts.
+
+**2. Find where units move.** Weight the distribution by estimated sales, not by item count. Ten
+listings at a price nobody buys do not define the market; two that sell define it better. The
+band where units concentrate is the sweet spot, and it is frequently **not** the cheapest end —
+the bottom of a Shopee category is often occupied by items that do not sell.
+
+**3. Read the direction of travel.** Price history shows whether the niche is drifting downward.
+A steady slide is a race to the bottom, and joining it is rarely the right advice. Where you find
+one, say so plainly and pivot the recommendation toward what else could differentiate — content,
+rating, bundle, delivery promise.
+
+**4. Place the seller.** Above the band, inside it, or below. Each has a different implication,
+and "below" is not automatically good — an unusually low price on Shopee invites the assumption
+that something is wrong with the item.
+
+**5. Respect the floor.** **Never recommend a price below the seller's break-even.** If they have
+not supplied a unit cost, say the floor is unknown and give the market band without a
+recommendation to move.
+
+## Prefer a cost change to a price change
+
+Where the margin is thin, cutting price is the fastest way to make it thinner. If the seller can
+move their unit cost, freight, or packaging instead, that protects the position without
+surrendering revenue. Say which lever you are recommending and why.
+
+## The fee problem — state it every time
+
+**JoomPulse holds no Shopee fee or commission data.** So a price recommendation here is a
+**market-position** recommendation, not a profitability one. You can say where a price sits
+against the competition and where units move; you cannot say what the seller keeps.
+
+Do not fill the gap by borrowing another marketplace's fee model — the structures differ, and a
+margin computed that way is a wrong number wearing the appearance of a breakdown. Say what is
+missing and, if the seller supplies their own all-in cost including platform deductions, work
+from that instead.
+
+## Procedure
+
+1. Resolve the item or niche; **pin one category level** for the comparison set.
+2. Pull comparable items with their prices and estimated sales.
+3. Build the sales-weighted distribution and locate the band where units concentrate.
+4. Pull price history for the contested items and check the direction of travel.
+5. Place the seller's current price, if known, against the band.
+6. Apply the floor if a cost was supplied; otherwise say the floor is unknown.
+
+## Output
+
+**Verdict first:** the recommended band, with the trade-off at each end stated — what the seller
+gains and gives up at the top and the bottom.
+
+Then the distribution — price bands against estimated units and revenue, so the reader can see
+where the market actually is — and the seller's position within it. Note the direction of travel
+if there is one.
+
+State the estimate disclaimer once. Use full BRL precision, Brazilian convention. Show `—` for
+unavailable values.
+
+## Boundaries
+
+- **Prices are real; sales are estimates** from rounded counters. The weighting is therefore
+  approximate — do not present a sweet spot to the nearest real.
+- **No fee, commission or margin data for Shopee.** A price recommendation with no margin check
+  is advice the seller cannot safely act on; say what is missing every time.
+- **No per-variant pricing** — history is item-level, so never recommend a price for a specific
+  size or colour.
+- **No live prices.** Figures come from periodic observation, so a competitor may have repriced
+  since. Say how current the data is.
+- **No promotion or campaign visibility** — a price observed during a Shopee campaign period may
+  not be the seller's standing price, and the data does not distinguish the two. Flag this where
+  a price looks anomalously low.
diff --git a/skills/seller-copilot/references/shopee-validate-product.md b/skills/seller-copilot/references/shopee-validate-product.md
new file mode 100644
index 0000000..7bd1bae
--- /dev/null
+++ b/skills/seller-copilot/references/shopee-validate-product.md
@@ -0,0 +1,83 @@
+# Validate one Shopee product
+
+A go/no-go on a single item the seller is considering. The job is to **fail fast and cheaply** —
+most candidates should not survive.
+
+## What to ask for
+
+- **The item**, by Shopee link, item identifier, or a clear product description.
+- **Their unit cost**, if they want anything said about profitability. JoomPulse does not hold it.
+- A bare 10–11 digit identifier is a Shopee item; one beginning `MLB` belongs to the other
+  marketplace and should be routed there instead.
+
+## The two axes
+
+Judge demand against competition, and read the quadrant:
+
+- **High demand, low competition** — the case worth pursuing. Rare; check it twice.
+- **High demand, high competition** — the case sellers most often misread as good. Viable only
+  with a **named** edge: a lower landed cost, a differentiated version, an underserved variant.
+  "I'll try harder" is not an edge.
+- **Low demand, low competition** — usually empty rather than open. Ask why nobody is there.
+- **Low demand, high competition** — avoid.
+
+## What to read
+
+**Demand.** Estimated units and revenue over the recent window, and the item's estimated
+lifetime monthly average. Then the week-by-week series — see
+[shopee-item-momentum.md](shopee-item-momentum.md) — because a healthy 30-day figure on a fading item is a
+trap the snapshot alone will not show.
+
+**Competition.** How many sellers offer comparable items in the same category niche, what they
+charge, their ratings and review counts, and the mix of official, preferred and regular shops
+among them. A shelf held by official shops with thousands of accumulated reviews is a slow fight
+regardless of demand.
+
+**Room to differentiate.** Rating weakness, thin photography, absent video, no brand, or a price
+band with an obvious gap.
+
+## The tie-breakers
+
+Where the two axes leave it borderline, these can turn a "possible" into an "avoid":
+
+- **Review accumulation of the leaders.** Reviews compound; a leader with a very large count has
+  an advantage a new listing cannot close quickly. There is no shortcut to it on Shopee.
+- **Badge tier of the incumbents.** Official (Mall) shops carry visibility a regular seller does
+  not start with. Note it as a structural disadvantage, not a verdict.
+- **Cross-border presence.** If the shelf is largely served from outside Brazil, the seller is
+  competing on a different cost base and a different delivery promise.
+
+## Procedure
+
+1. Resolve the item and confirm it is still live — check when it was last observed. A product
+   that has not been seen recently may be gone.
+2. Read demand: recent estimates, lifetime average, and the direction flag.
+3. Pull the week-by-week series before concluding anything about direction.
+4. Read the competitive shelf in the same category niche.
+5. If unit cost was supplied, say what it implies **only as far as the data allows** — see the
+   boundary below.
+
+## Output
+
+**Verdict first** — go, go with a condition, or avoid — with a confidence level and the single
+reason that decided it.
+
+Then the evidence: demand figures with their direction, the competitive picture, and the
+differentiation opening if one exists. Close with what would change the verdict.
+
+State the estimate disclaimer once. Use full BRL precision. Show `—` for missing values.
+
+## Boundaries
+
+- **Sales and revenue are estimates** from Shopee's rounded public counters. A difference of a
+  few units between two items is noise, not a ranking.
+- **This is a demand-and-competition verdict, not a profitability one.** JoomPulse holds no
+  Shopee fee, commission, supplier or landed-cost data. Even with the seller's unit cost you can
+  compare cost against *selling price* — you cannot compute a real margin, because the platform's
+  own deductions are unknown. Say that rather than presenting a margin.
+- **Do not turn a caution into a go because the seller wants one.**
+- **No buy-box or catalogue on Shopee**, so "how many sellers offer this exact product" is not a
+  question the data answers — every row is a separate item. Compare comparable items instead,
+  and say that is what you did.
+- **The item set is not a census** — only items with at least one lifetime sale are tracked, so
+  the competitive count is a lower bound.
diff --git a/skills/seller-copilot/references/which-marketplace.md b/skills/seller-copilot/references/which-marketplace.md
new file mode 100644
index 0000000..d25a45c
--- /dev/null
+++ b/skills/seller-copilot/references/which-marketplace.md
@@ -0,0 +1,100 @@
+# Which marketplace?
+
+JoomPulse covers **two separate marketplaces**: Mercado Livre (Brasil) and Shopee Brasil. They
+are independent datasets with different coverage, different history and different mechanics.
+Deciding which one a request belongs to is the **first** step of every analysis, before any data
+is read.
+
+Read this file whenever the marketplace is not obvious, whenever the seller mentions both, or
+whenever a request assumes something one marketplace has and the other does not.
+
+## How to decide
+
+**1. Did the seller say?** "Shopee" means Shopee. "Mercado Livre", "MeLi", "ML" or "Mercado
+Libre" means Mercado Livre. Take them at their word.
+
+**2. Does an identifier give it away?**
+
+- An identifier beginning **`MLB`** is Mercado Livre.
+- A **bare 10–11 digit number** is a Shopee item or shop. Mercado Livre identifiers are never
+  bare numbers, so a long unprefixed number is itself a strong Shopee signal.
+- A `mercadolivre.com.br` link is Mercado Livre; a `shopee.com.br` link is Shopee.
+- If an identifier is not found on the marketplace you assumed, **check the other one before
+  telling the seller it does not exist.**
+
+**3. Does the request only make sense on one of them?** Anything about the buy-box, catalogue
+position, seller medals, a fulfilment programme or search keywords is Mercado Livre — those
+mechanics and that data do not exist on Shopee.
+
+**4. Otherwise, ask.** One short question, before querying anything: which marketplace, and
+mention that both are available. **Do not guess and do not default.** Guessing wrong wastes the
+analysis and produces figures for a market the seller does not sell on.
+
+## The rule that must never break
+
+**Never mix data from the two marketplaces in one query, one table, or one total.**
+
+They are separate pipelines with different grains and different estimate methods. A combined
+figure is not a bigger picture, it is a wrong number. This applies to totals, averages, rankings
+and charts alike.
+
+## When the seller genuinely wants both
+
+Comparing the two is a legitimate request — "should I sell this on Shopee or Mercado Livre?" — and
+the answer is **two separate analyses reported side by side in prose**, never merged.
+
+- Run each marketplace's own procedure, using that marketplace's reference files.
+- Present them as two panels with their own captions, clearly labelled.
+- **Compare orders of magnitude and direction, not exact numbers**, and say that is what you are
+  doing. The two estimate methods differ enough that a precise-looking gap between them is not
+  trustworthy.
+- Say plainly where a comparison cannot be made at all, rather than filling the gap — for example
+  there is no like-for-like seasonal comparison, because only one marketplace has the history.
+
+## What each marketplace can answer
+
+Where a request lands on a capability the chosen marketplace lacks, **name the gap and offer the
+nearest real alternative** — never substitute the other marketplace's figure.
+
+| Analysis | Mercado Livre | Shopee |
+|---|---|---|
+| Category evaluation, market structure | yes | yes, three category levels only |
+| Finding products, validating a product | yes | yes |
+| Competitor discovery and profiling | yes | yes |
+| Assortment and price gaps, pricing | yes | yes |
+| Item history week by week | no | **yes — Shopee only** |
+| Margin and fees | yes | **no fee data at all** |
+| Keywords and search demand | yes | **does not exist** |
+| Seasonality, when to stock, long-run trend | yes | **no — history starts May 2026** |
+| Buy-box / catalogue comparison | yes | **no such mechanic** |
+| Listing diagnosis against a competitor set | yes | partly — no fulfilment or shipping attributes |
+| Seller medals and reputation ladder | yes | **badge tiers only**, no ladder |
+| Cancellation rate | yes | **not available** |
+| Brand rankings and share | yes | **coverage unreliable — do not compute share** |
+| Import versus domestic | yes | partly — cross-border flag only |
+| Supplier vetting | yes | yes, using Shopee demand data |
+
+## Which files to read once decided
+
+- **Mercado Livre** → the unprefixed reference files, and the focused Mercado Livre skills in
+  this repo where one already does the job.
+- **Shopee** → the `shopee-` prefixed reference files.
+
+**The focused skills in this repo are Mercado Livre only.** Every one of them scopes itself to
+Mercado Livre, so handing a Shopee question to one returns Mercado Livre data for a Shopee
+seller — a wrong answer that looks right. For Shopee there is no focused skill to defer to: use
+the `shopee-` references and do the analysis here.
+
+## Things that differ enough to catch you out
+
+- **Concentration is not the same measurement.** Mercado Livre reports the leading seller's
+  share; Shopee reports an index across all sellers. Never compare the two values, and never
+  carry the "top seller holds half the shelf" phrasing to Shopee.
+- **Badge schemes differ.** Mercado Livre has a medal ladder; Shopee has three mutually exclusive
+  tiers and no ladder. Inventing Shopee medals is fabrication.
+- **Category depth differs** — Shopee analytics stop at three levels, Mercado Livre goes deeper.
+- **Absolute thresholds do not transfer.** A revenue floor that means "substantial" on one
+  marketplace means something else on the other, even though both are in BRL. Judge a category
+  against its own marketplace's siblings.
+- **Both are Brazil**, so currency, language and the local retail calendar are the same. The
+  differences are about data, not locale.