> For the complete documentation index, see [llms.txt](https://docs.buzzy.buzz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buzzy.buzz/the-building-blocks/mcp/buzzy-builder-mcp/adapt-commerce-insights.md).

# Adapt Commerce Insights

Use Commerce Insights as the source for a separate dashboard app. This guide provides a distributor-dashboard brief and verification steps. It is an adaptation recipe, not a report of an already implemented distributor app.

{% embed url="<https://www.youtube.com/watch?v=nqgOC2shmrY>" %}
Watch the template overview
{% endembed %}

## Before you begin

Complete [Getting started with Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp/getting-started.md). Use a Buzzy workspace with MCP access, a compatible coding agent, and a git repository for the working artifacts. Preview [Commerce Insights](https://app.buzzy.buzz/app/b5499125dd62dcbe09aca12c).

Have a short definition of the reporting question, intended users and data sources. Use synthetic records for initial verification.

## 1. Inspect the source without changing it

```
Use Buzzy Builder MCP and its current guides. Bootstrap this repository.
Inspect Commerce Insights, source app b5499125dd62dcbe09aca12c:
https://app.buzzy.buzz/editor/edit/b5499125dd62dcbe09aca12c
Do not modify the source. Summarize its data relationships, chart bindings,
shared filters, roles and integrations. Identify assumptions that may not fit
a distributor. Show the findings before proposing target changes.
```

Confirm that the report describes the actual source artifacts. Do not infer a field’s meaning from its display label alone.

## 2. Agree the reporting contract

Write down the business definition before changing a chart:

| Decision       | Example question                                            |
| -------------- | ----------------------------------------------------------- |
| Revenue        | Gross or net? How are returns and cancelled orders treated? |
| Reporting date | Order date, invoice date or payment date? Which time zone?  |
| Currency       | One reporting currency or separate totals?                  |
| Territory      | Assigned to an account, order or salesperson?               |
| Access         | Can a territory user see other territories?                 |
| Refresh        | What source owns each value, and when is it updated?        |

Leave unanswered decisions visible. Do not allow the agent to silently choose financially meaningful calculations.

## 3. Create a separate target and plan the adaptation

```
Plan a separate distributor dashboard based on Commerce Insights. Preserve the
source template. Use our agreed reporting definitions. Map product categories
to product families and add the agreed territory model where needed.
List keep/remove/replace/add decisions, affected filters and charts, access
rules, and source-connection work. Identify any requested generation steps
and their cost path. Show the plan for review before making target changes.
```

Follow the current Builder MCP guide’s artifact order and review stages. Record the target app ID and editor URL. Every write should target that app.

## 4. Implement one reporting slice

Start with revenue by territory for an agreed period. Establish the target records and relationships before wiring the view. Use direct artifact editing where appropriate. If the workflow calls for Buzzy-managed generation, review its separate cost requirements first.

After saving each coherent change, ask the agent to re-read the persisted artifacts and inspect the target runtime. Check labels, units, empty states and filter behaviour together.

## 5. Verify with independently calculated results

Build a small synthetic fixture with known expected totals. Include normal orders, a cancelled order, a return, two territories and a reporting-date boundary. Calculate the expected totals using your accepted business definition.

| Check             | Pass condition                                                 |
| ----------------- | -------------------------------------------------------------- |
| Unfiltered result | Totals match the fixture’s expected values                     |
| Territory filter  | Relevant charts include only eligible territory records        |
| Date boundary     | Inclusion matches the agreed field and time zone               |
| Combined filters  | The same eligible subset drives each relevant chart            |
| No matches        | A clear empty state appears without misleading totals          |
| Clear filters     | The original unfiltered result returns                         |
| Restricted user   | Disallowed records cannot be read through the app’s data paths |

Capture the input fixture, expected and observed totals, role used, target URL and screenshots. Screenshots alone do not prove the calculations or permissions.

## Troubleshooting

If totals disagree, inspect duplicate records, date selection, units and status exclusions before changing the chart. If one chart ignores a shared filter, inspect its bindings and query inputs. If data fails to load, distinguish a source-connection failure from an empty result.

## Cost and next steps

Direct artifact adaptation uses the connected agent’s applicable allowance and does not require Buzzy generation credits. API-key usage, Buzzy-managed generation and deployment are separate. See [AI usage and pricing](https://docs.buzzy.buzz/working-with-buzzy/buzzy-ai/ai-tokens-and-pricing).

Once the first reporting slice passes, expand to additional metrics and representative volumes. Follow the existing [deployment publishing guide](https://docs.buzzy.buzz/working-with-buzzy/buzzy-deployment-and-app-stores/publish-to-deployment), then repeat the checks on the published target.

## Explore the template series

Read the [article overview](https://www.buzzy.buzz/post/commerce-insights-builder-mcp/) or explore the [complete Builder MCP template series](https://www.buzzy.buzz/post/build-from-templates-builder-mcp/).