> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sourcemedium.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SM Dashboard Builder

> Build accurate BI dashboards from SourceMedium BigQuery data with validated metric contracts and SQL receipts.

Build BI dashboards from SourceMedium warehouse data with correctness first — the agent discovers your data, locks down metric definitions, validates SQL, then renders the dashboard. Default output is a portable standalone HTML file that opens in any browser.

## Prerequisites

The install command requires `npx`, which comes with Node.js 18+. Run `node -v` to check. If you see "command not found," install Node.js from [nodejs.org](https://nodejs.org) first.

Install [SM BigQuery Analyst](/ai-analyst/agent-skills/sm-bigquery-analyst) first if you need setup verification or access troubleshooting — the dashboard builder assumes BigQuery access is already working.

## Install

```bash theme={null}
npx skills add source-medium/skills --skill sm-dashboard-builder
```

Install both skills together:

```bash theme={null}
npx skills add source-medium/skills --skill sm-bigquery-analyst
npx skills add source-medium/skills --skill sm-dashboard-builder
```

If your agent does not support automatic install through the `skills` CLI, copy the skill folder into that agent's configured skills directory.

## Update

If you installed an earlier copy, update both skills before building dashboards:

```bash theme={null}
npx skills update sm-bigquery-analyst -y
npx skills update sm-dashboard-builder -y
```

***

## Quick Start (Copy/Paste)

<Tip>
  Copy the block below and paste it into your coding agent to build your first dashboard.
</Tip>

```
Use the SourceMedium Dashboard Builder skill to create an executive overview
dashboard for my project sm-[your-tenant-id].

Include:
- Net revenue, orders, and AOV scorecards for the last 30 days
- Revenue trend by day
- Revenue breakdown by channel

Discover available tables and validate all queries before building.
Produce dashboard.html with SQL receipts and a dashboard_manifest.json.
```

***

## What It Does

**Metric definitions before SQL** — before writing any query, the agent defines each metric: the formula, the source table, the time level (daily, per-order, per-customer), and for ratios like AOV or ROAS, the numerator and denominator. This prevents the most common BI mistake — summing a rate metric across rows and getting a wrong answer.

**BI-safe SQL** — SELECT-only, fully qualified tables, bounded time filters, dry-run validated, one query per dashboard tile. Most queries cost well under a dollar at standard BigQuery rates.

**Manifest-driven output** — builds a `dashboard_manifest.json` that records every tile's metric definition, SQL receipt, row count, dry-run bytes, and QA status. The manifest is validated before rendering, so errors surface before the dashboard is built.

**Portable HTML dashboard** — `dashboard.html` embeds chart specs, query results, SQL receipts, and QA notes. Open it in any browser — no server, no login required.

**BI tool handoff** — produces Metabase SQL cards, Looker Studio queries, or app-ready data contracts when a BI tool is the target instead of standalone HTML.

**No guessed metrics** — if a requested metric isn't available in your data, it appears as a note in the dashboard rather than a substituted or fabricated number.

***

## Example Prompts

### Executive overview dashboard

```
Build an HTML executive dashboard for the last 30 days.

Tiles:
- Scorecards: net revenue, orders, AOV, new customers, ad spend, MER
- Trend: net revenue and orders by day
- Breakdown: revenue by channel

Discover available tables and stores first. Validate all queries.
Output dashboard.html and dashboard_manifest.json.
```

### Marketing performance dashboard

```
Build a marketing performance dashboard for the last 30 days.

Tiles:
- Scorecards: ad spend, platform ROAS, blended MER, CAC
- Trend: spend and platform-reported revenue by platform
- Breakdown: campaign type performance for each platform

Note: TikTok GMV Max campaigns should be separated from standard campaigns.
```

### Metabase handoff

```
Create Metabase-ready SQL cards for CAC, MER, ad spend, and revenue by
channel for the last 30 days. Include field definitions, expected
visualization type, and layout order.
```

### Hybrid dashboard (your data + SourceMedium)

```
Build a dashboard that joins my inventory table
[your-project].[your-dataset].inventory_snapshots to SourceMedium orders.

Show:
- Revenue by SKU
- Sell-through rate by product category
- Inventory days-on-hand for top products

Document the join keys and run a cardinality check before joining.
```

***

## What You Get

| Output                    | Description                                                                                              |
| ------------------------- | -------------------------------------------------------------------------------------------------------- |
| `dashboard.html`          | Open in any browser — no server required. Embeds chart specs, query results, and SQL receipts.           |
| `dashboard_manifest.json` | Source of truth for the dashboard: metric definitions, SQL receipts, row counts, and QA status per tile. |
| SQL receipts              | One copy/paste BigQuery query per tile, with dry-run byte estimate and freshness check.                  |
| Notes section             | Metric definitions, data caveats, freshness date, and QA status — visible in the dashboard footer.       |

***

## After Building

### View your dashboard

Open `dashboard.html` in any browser — Chrome, Safari, Firefox, Edge. If your agent built it in a project folder, look there. You can share the file directly or host it anywhere that serves static files.

### Validate before sharing

Run strict validation before sharing any dashboard externally:

```
Validate dashboard_manifest.json in strict mode before I share this.
```

The agent will check metric definitions, SQL safety, row counts, dry-run bytes, ratio denominator checks, and chart field matching.

### Update a dashboard

```
Update dashboard.html to add a product revenue breakdown tile for the
top 10 SKUs by net revenue last 30 days.
```

### Port to Metabase

```
Convert dashboard_manifest.json to Metabase SQL cards and a layout plan
I can recreate in Metabase.
```

### Debug a tile

If a chart looks wrong:

```
The revenue trend chart looks off. Show me the SQL receipt for that tile,
rerun the query, and compare the result to the revenue sanity check query.
```

If the numbers still look wrong after debugging, share the SQL receipt and a screenshot of the chart with support.

***

## Related

<CardGroup cols={2}>
  <Card title="SM BigQuery Analyst" icon="database" href="/ai-analyst/agent-skills/sm-bigquery-analyst">
    For setup verification, raw analysis, and hybrid data joins.
  </Card>

  <Card title="SQL Query Library" icon="code" href="/data-activation/template-resources/sql-query-library">
    SourceMedium SQL templates and patterns.
  </Card>

  <Card title="Metric Catalog" icon="book-open" href="/data-activation/data-tables/sm_metadata/dim_semantic_metric_catalog">
    180+ pre-defined metrics with calculations.
  </Card>

  <Card title="Table Docs" icon="table" href="/data-activation/data-tables/sm_transformed_v2/index">
    Schema-level documentation for core tables.
  </Card>
</CardGroup>