Add headset-bridge-toolkit plugin with Bridge reporting skills

.claude-plugin/marketplace.json

@@ -9,6 +9,15 @@
       "name": "headset",
       "source": "./",
       "description": "Connects Claude Code to Headset's hosted MCP server"
+    },
+    {
+      "name": "headset-bridge-toolkit",
+      "source": "./plugins/headset-bridge-toolkit",
+      "description": "Buyer-ready reports from your Bridge sell-through data: account reviews, restock risk, and a weekly pulse.",
+      "version": "1.0.0",
+      "author": {
+        "name": "Headset"
+      }
     }
   ]
 }

README.md

@@ -4,11 +4,26 @@ Bring your [Headset](https://headset.io) retailer data into Claude Code. Ask abo
 
 ## Installation
 
+Add the marketplace once, then install the plugin that fits how you use Headset:
+
 ```
 /plugin marketplace add Headset/claude-code
 /plugin install headset@Headset
 ```
 
+| Plugin | For | What you get |
+|---|---|---|
+| `headset` | Anyone with a Headset account | Connects Claude Code to Headset's hosted MCP server — ask about your data in plain language |
+| `headset-bridge-toolkit` | Brands and vendors using Headset Bridge | Buyer-ready report skills on top of the MCP connection: account reviews, restock risk, and a weekly pulse |
+
+To install the Bridge toolkit instead of (or alongside) the base plugin:
+
+```
+/plugin install headset-bridge-toolkit@Headset
+```
+
+Update anytime with `/plugin marketplace update Headset`.
+
 ## Setup
 
 On first use, Claude Code will prompt you to authenticate with Headset via OAuth. No API keys to manage — once you approve access, you're connected.

plugins/headset-bridge-toolkit/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "headset-bridge-toolkit",
+  "version": "1.0.0",
+  "description": "Turn Headset Bridge sell-through data into buyer-ready reports: retailer account reviews, restock risk, and a weekly sell-through pulse.",
+  "author": {
+    "name": "Headset",
+    "email": "support@headset.io"
+  },
+  "homepage": "https://www.headset.io",
+  "keywords": ["headset", "bridge", "cannabis", "sell-through", "retail-analytics"],
+  "mcpServers": {
+    "headset": {
+      "type": "http",
+      "url": "https://mcp.headset.io",
+      "oauth": {
+        "clientId": "tsZq8k6XeiZiXMPCTQT9pt0Ia9zzMqDN",
+        "callbackPort": 5420
+      }
+    }
+  }
+}

plugins/headset-bridge-toolkit/README.md

@@ -0,0 +1,33 @@
+# Headset Bridge Toolkit
+
+Turn your Headset Bridge connection into buyer-ready deliverables. This plugin gives Claude three skills built on live Bridge sell-through and inventory data from your connected retail partners.
+
+## What's included
+
+| Skill | Who it's for | What it does |
+|---|---|---|
+| **bridge-account-review** | Sales reps / account managers | A polished one-pager for a buyer meeting at a specific store: performance, category mix vs your other doors, top SKUs, shopper demographics, restock asks, and talking points. |
+| **bridge-restock-risk** | Sales reps / account managers | Velocity-based restock report: what's out or nearly out while still selling, ranked by estimated revenue at risk, grouped per store for easy forwarding. |
+| **bridge-weekly-pulse** | Brand / ops leadership | A two-minute Monday brief: week-over-week revenue with the swing explained, movers and decliners, discount watch, and risk carried into the new week. Offers to schedule itself every Monday. |
+
+The skills share the plugin's `references/` files for the Bridge data conventions and Headset report style, keeping every skill honest about Bridge data quirks (raw POS taxonomy, per-store product IDs, partial periods, real stockout logic) and consistent with Headset's visual identity in every report.
+
+## Setup
+
+1. **Connect the Headset MCP.** In Claude Code, the plugin registers the Headset MCP server (`https://mcp.headset.io`) automatically via its manifest; complete authentication when prompted. On claude.ai and Claude Desktop, if the Headset connector does not appear after installing the plugin, add it manually (Settings → Connectors → `https://mcp.headset.io`); on organization installs, an admin can add the Headset MCP as a connection in the same Access bundle or scope as the plugin.
+2. **Bridge must be enabled on your Headset account.** The Headset MCP exposes tools based on your account's products. This plugin uses the Bridge tool set; if your account is Insights- or Retailer-only, the skills will let you know rather than running on the wrong data.
+3. That's it. The skills discover your stores through your Bridge connections; nothing else to configure.
+
+## Usage
+
+Just ask naturally:
+
+- "Prep an account review for my meeting at Star Buds Riverside"
+- "What's running low across my stores?"
+- "Run my weekly pulse"
+
+## Notes
+
+- Bridge data covers **your products at your connected stores**. It is not market-level data.
+- Reports are self-contained HTML files styled to Headset's brand.
+- All figures involving margin are quality-checked against cost coverage before they're shown.

plugins/headset-bridge-toolkit/references/bridge-data-conventions.md

@@ -0,0 +1,74 @@
+# Bridge Data Conventions
+
+Shared rules for every skill in this plugin. Follow these before and while querying the Headset Bridge tools (`bridge_find_connections`, `bridge_sales_totals`, `bridge_sales_by_dimension`, `bridge_sales_trend`, `bridge_get_inventory`, `bridge_search_dimension_values`). Getting these right is the difference between numbers a customer trusts and numbers that look broken.
+
+## 1. Scope: this is a vendor-side view
+
+A Bridge account sees only its own products' sales and inventory at the retailer stores it is connected to. It does NOT see the store's full menu, other vendors' products, or market share. Frame every output as "your brands at your connected stores." Never imply market-level coverage.
+
+Always start by calling `bridge_find_connections` to get the active connections. Every `storeIds` filter must use the `retailerStoreId` values it returns. When the user names a store, resolve it with the `query` parameter; if more than one connection matches, ask which one they mean.
+
+## 2. Taxonomy is raw retailer POS data. Normalize it.
+
+Categories and units come straight from each retailer's point of sale, so the same concept appears under many spellings, and the mix differs per store. Real examples: "Edibles", "Edible", "Edibles Gummies", "Gummies" all coexist; pre-rolls appear as "Pre-Roll", "Pre-Rolls", "Preroll", "Pre-Roll Pack Full Flower", and more; eighths appear as "3.5 Grams", "3.5", and "3.5g".
+
+Rules:
+
+- Before filtering on any brand, category, vendor, product, or unit the user names, call `bridge_search_dimension_values` and use ALL matching canonical values, OR-joined in the filter.
+- When presenting category rollups, aggregate raw categories into canonical groups before showing them. Use these case-insensitive substring rules, applied in this exact order, first match wins:
+  1. Excluded: category contains "employee", "promo", or "sample". Drop these rows entirely.
+  2. Pre-Rolls: contains "pre-roll" or "preroll".
+  3. Vapor: contains "vape", "vapes", "cartridge", or "disposable".
+  4. Edibles: contains "edible", "gummies", "gummy", "mints", "chocolate", or "tincture".
+  5. Concentrates: contains "concentrate", "extract", "rosin", "resin", "budder", "sugar", or "rso".
+  6. Flower: contains "flower", "popcorn", or "shake" (catches Infused Flower, Flower Popcorn, Flower Shake, Shake, Infused Shake).
+  7. Other: anything left, including Capsules.
+
+  The order is load-bearing: "Infused Pre-Rolls" must land in Pre-Rolls, not Flower, and "Live Resin Cartridge" must land in Vapor, not Concentrates.
+- Exclude "Employee/Promo Samples" categories (and any item priced under $1) from average-price, margin, and top-seller calculations. Include them nowhere unless the user asks about samples.
+- Never show a customer a raw category list with obvious duplicates. That reads as broken data.
+
+## 3. Product IDs are per-store
+
+The same SKU has a different `product_id` and often a slightly different name at each retailer ("Cl - Cresco - Pineapple Express - Live Resin Cartridge - 1g" vs "Cresco - Live Resin Cartridge Pineapple Express - 1g"). `store_count` on product rows is almost always 1 for this reason.
+
+For any cross-store product comparison, build a match key instead of relying on `product_id`: brand + normalized product name + unit group. Normalize names by lowercasing, stripping vendor prefixes (such as "Cl - "), punctuation, pack-size text in parentheses, and reordering-insensitive token comparison. Match conservatively; when unsure whether two rows are the same SKU, treat them as different and say so.
+
+## 4. Partial periods will lie to you
+
+Trend queries include the in-progress day, week, and month. Any week-over-week or month-over-month comparison must use complete periods only. Either exclude the current partial period or clearly annotate it ("week in progress"). Never present a partial period as a decline.
+
+## 5. Stockout and reorder logic
+
+`stockout_count` in grouped inventory counts every zero-on-hand SKU, including long-discontinued ones, so it wildly overstates risk (a store can show 1,100+ "stockouts"). Never quote it as reorder risk.
+
+Real signals, from per-product inventory rows:
+
+- Active stockout that matters: `on_hand_units` = 0 AND `avg_daily_units` >= 0.25 (it was selling within the trailing 28 days).
+- Critical low stock: in stock, `weeks_of_supply` <= 2, `avg_daily_units` >= 0.25.
+- Revenue at risk: `avg_daily_units` x `price` x 14 days is a fair two-week estimate. Label it as an estimate.
+- Overstock: `minWeeksOfSupply` >= 12 with meaningful on-hand value.
+
+Bridge data is descriptive. Do not present computed reorder quantities as recommendations; present velocity and days of supply and let the customer decide.
+
+## 6. Measures worth knowing
+
+- `total_revenue` is net of discounts; `total_gross_sales` is pre-discount. Discount rate = `total_discounts` / `total_gross_sales`. Discount rates of 30%+ are common in some markets and are a story, not an error.
+- Check `pct_revenue_with_cost` before quoting margin or profit. Below ~0.9, caveat that cost coverage is incomplete.
+- `avg_item_price` is per item sold, not per transaction.
+
+## 7. Demographics and channels
+
+`customer_age_group` (generations), `customer_gender`, `order_source` (Walk In, Dutchie, IHeartJane, kiosk, e-commerce, etc.), and `is_medical` are available as dimensions and filters. Null and "Unknown" buckets exist (typically a few percent of revenue); group them as "Unknown" and compute share-of-known percentages. Only one dimension per call: to cross two (say category by age group), loop the dimension call with a filter per value of the other.
+
+## 8. Practical querying
+
+- Date windows use Looker expressions: "last 30 days", "this month", "2026-06-01 to 2026-07-01", "last 13 weeks".
+- Explicit ranges of the form "YYYY-MM-DD to YYYY-MM-DD" are END-EXCLUSIVE: the second date is not included. A Monday-to-Sunday week is "monday_date to next_monday_date" (the week of Jul 13 to 19, 2026 is "2026-07-13 to 2026-07-20"). After pulling totals for an explicit range, validate against the matching bucket of a `bridge_sales_trend` pull at the same grain; a mismatch means the range is wrong.
+- Transient MCP errors (connection lost) happen occasionally; retry the call once before reporting a problem.
+- Independent queries should be issued in parallel to keep reports fast.
+- Avoid `current_user_accounts`; it can return an enormous payload and is not needed for these workflows.
+
+## 9. Entitlements
+
+The Headset MCP exposes different tool sets depending on what the authenticated account has enabled. This plugin requires the Bridge tool set (`bridge_*` tools). If those tools are not available after the Headset connector is authenticated, do not retry or improvise with other Headset tools; tell the user plainly that the connected Headset account does not have Bridge enabled and that they should reconnect with a Bridge-enabled account or contact Headset. If the account also exposes Insights or Retailer tools, those are separate products; use them only where a skill explicitly says so.

plugins/headset-bridge-toolkit/references/headset-report-style.md

@@ -0,0 +1,60 @@
+# Headset Report Style
+
+Shared visual and voice rules for every HTML deliverable this plugin produces. These reports carry the Headset brand into a customer's buyer meetings; they must look and sound the part.
+
+## Deliverable format
+
+Produce a single self-contained HTML file: all CSS and JS inline, images as data URLs. Chart.js from cdnjs.cloudflare.com is allowed for charts. Never use localStorage or sessionStorage. Deliver the file using the platform's file output/presentation mechanism (for example, writing to the outputs directory and presenting the file). For reports the user will revisit or update (the weekly pulse, a standing account review), also persist it in the platform's persistent/recurring artifact store when that capability is available.
+
+## Typography
+
+Body and headings: Poppins, loaded from Google Fonts, with fallback stack `'Poppins', 'Inter', 'Montserrat', system-ui, sans-serif`. Never a serif or display font. Do not attempt to recreate the Headset logo or wordmark; a plain-text footer line is the correct brand presence (see Footer).
+
+## Color
+
+Anchor on the Insights palette for data, use orange only as a spotlight, keep everything else quiet.
+
+Core UI:
+- Text / headers: `#14172E` (dark navy)
+- Secondary text: `#666666`
+- Page background: `#F8FBFB` or white; card backgrounds white with `#CCCCCC` hairline borders or a subtle shadow
+- Data-section card tint: `#F0F0FA`
+
+Charts and data:
+- Primary series: `#232E83` (deep blue), secondary: `#6862C7`
+- Additional series, in order: `#C2BEFF`, `#258682`, `#61C2BC`, `#B4E8E4`
+- Comparison / context data: grays `#848383`, `#B4B4B4`, `#D9D9D9`
+- Highlight (the one thing the reader must notice): `#F15D22` orange. One or two elements per report, no more. If every bar is orange, nothing is.
+
+Accents:
+- This is a Bridge product: `#87005B` (deep magenta) may be used sparingly for the report masthead accent or section dividers. Not for chart series.
+- Positive deltas / success states: `#3EB280`. Negative deltas: use `#F15D22` sparingly or `#87005B`; never invent a red.
+
+Aesthetic: rounded corners (8-12px), generous whitespace, subtle shadows over hard edges, one accent per view. The report should still look right in three years.
+
+## Layout pattern
+
+1. Masthead: report title, store or scope, date range, generated date. Thin magenta or blue accent rule.
+2. KPI row: 3-5 stat tiles (big number, small label, delta vs prior period with arrow and color).
+3. Charts and tables in cards, one idea per card, with a one-line takeaway headline above each ("High Supply drove the week's growth", not "Revenue by brand").
+4. Callout card (orange-tinted background `#FEF3EC`) for the single most important action item.
+5. Footer.
+
+## Voice
+
+Confident, trusted, friendly. Reassuring first, factual always. Rules that are non-negotiable in generated report copy:
+
+- Never use em dashes. Use commas, periods, parentheses, or colons instead.
+- Lead with what it means, then the number that proves it. Every chart gets a takeaway headline in plain language.
+- Specifics over adjectives: "up 14% at Star Buds Riverside" beats "strong growth."
+- No hype vocabulary (revolutionary, game-changing, best-in-class), no hedges on things the data proves ("we think", "it seems"), no corporate filler ("leverage", "move the needle").
+- Respect the reader's expertise; do not explain industry basics. Do explain a metric definition when misreading it would mislead (for example, that revenue is net of discounts).
+- Numbers: currency with thousands separators, no decimals above $1,000; percentages to one decimal; units as whole numbers.
+
+## Footer
+
+Every report ends with a quiet footer line in `#666666`, Poppins:
+
+"Powered by Headset Bridge data · Generated [date] · [date range covered]"
+
+Add, where relevant: "Sales and inventory reflect your products at your connected retail partners."