Dashboard ManagementCAUTION

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: dashboard-management
description: >-
  Create, lay out, organize, or share Analytics dashboards and panels: sources, placement, folders, verification. Use to create a dashboard or to move, reorder, or lay out panels; a small edit of one existing panel needs no skill.
---

# Dashboard Management

Dashboards are the canonical SQL-backed Analytics resources. New dashboards, saved analyses, reports, and bespoke extensions are represented as dashboard artifacts—not as separate user-facing Analytics objects. Legacy analysis tables and actions remain available only for compatibility.

## Storage

Current storage:

| Table              | Purpose                                      |
| ------------------ | -------------------------------------------- |
| `dashboards`       | Explorer and SQL dashboard records           |
| `dashboard_folders` | Personal and shared SQL dashboard folders  |
| `dashboard_views`  | Saved filter presets per dashboard           |
| `dashboard_shares` | Standard framework share grants              |
| `dashboard_folder_shares` | Standard folder share grants          |
| `dashboard_revisions` | Bounded dashboard history snapshots       |
| `analyses`         | Saved ad-hoc analysis records                |
| `analysis_revisions` | Bounded analysis history snapshots        |
| `analysis_shares`  | Standard framework share grants for analyses |

Legacy settings keys such as `u:<email>:dashboard-*`, `u:<email>:sql-dashboard-*`, `o:<orgId>:sql-dashboard-*`, and `adhoc-analysis-*` are still read as a fallback and copied into SQL on access. Do not create new dashboard settings rows.

## Dashboard folders

Dashboard folders are SQL-backed, access-scoped containers for organizing SQL
dashboards from `/dashboards`:

- `personal` folders are private to their owner.
- `shared` folders are organization-visible and require an active organization.
- Use `list-dashboard-folders`, `create-dashboard-folder`, and
  `set-dashboard-folder` for folder reads and membership changes.
- A folder never expands dashboard access. A personal folder can contain only
  an owned private dashboard; a shared folder can contain only an org-visible
  dashboard. Use the normal dashboard sharing actions separately.

For organization-wide consolidation, use `migrate-analytics-artifacts` first
with `dryRun: true`. The write requires an organization owner/admin and the
exact confirmation token `MIGRATE_ANALYTICS_ARTIFACTS`. It materializes
organization-scoped legacy settings, creates dashboard blocks for saved
analyses and standalone extensions, archives exact duplicates, copies shares,
and removes legacy settings keys only after SQL rows are materialized. Source
rows remain recoverable. Private member-only rows are intentionally outside
this organization-scoped operation.

Use `mutate-dashboard` for existing dashboard edits. It resolves the current
user/org context, validates the resulting config, writes the SQL-backed record,
syncs collab, and returns a compact result with a `verified` flag. Use
`update-dashboard` for new full-config saves, UI full-config saves, or explicitly requested low-level
JSON-pointer edits.

Every meaningful dashboard save snapshots the previous state into
`dashboard_revisions`. Use `list-dashboard-revisions` to inspect available undo
points and `restore-dashboard-revision` to restore one; restore snapshots the
current state first, then syncs open dashboard editors.

Saved analyses follow the same undo model with `analysis_revisions`,
`list-analysis-revisions`, and `restore-analysis-revision`.

Never use `db-patch`, raw SQL, or settings-key edits to create or modify a
dashboard config. Those bypass the dashboard action's access checks, SQL
validation, collab sync, and verification. If a dashboard action fails
because the argument shape was wrong, fix that action's arguments and retry
once — do not switch to db-patch or raw SQL.

### GitHub folder sync

A linked folder mirrors its SQL dashboards to `<path>/<dashboardId>.json` in a
GitHub repo. Read `docs/dashboard-github-folder-sync.md` before changing or
explaining it.

- Run `preview-dashboard-folder-github-sync` before any sync. It writes nothing.
- `apply-dashboard-folder-github-sync` pulls from GitHub. It writes only the
  panels, order, and settings that changed on the GitHub side.
- `export-dashboard-folder-to-github` opens one PR with the app's changes. It
  refuses while an earlier export PR is still open.
- `configure-dashboard-folder-github-sync` links or unlinks a folder. It stores
  no credentials.
- A unit changed on both sides is a conflict. It is reported and not applied.
  Do not resolve it by overwriting either side without asking the user.
- Explorer dashboards, sharing, and deletions never sync. A synced dashboard
  cannot be permanently deleted; archive it or unlink its folder first.

## Valid Panel Sources

`panel.source` is a backend selector, not a table name. It must be one of:

| Source        | Query shape                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| `bigquery`    | Literal warehouse SQL. Table names belong inside the SQL string.                                         |
| `ga4`         | JSON descriptor for the Google Analytics Data API.                                                       |
| `amplitude`   | JSON descriptor for an Amplitude query.                                                                  |
| `first-party` | Read-only SQL over this template's `analytics_events` table, usually via `query-agent-native-analytics`. |

Do not use `app-db` as a dashboard source. For first-party events collected through `/track`, use `source: "first-party"` or the `query-agent-native-analytics` action rather than raw internal `db-query`.

AI-generated first-party panels are dashboard-time-bound by default. Set
`config.time

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (6)

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

Default the agent to archive when the user says "delete" / "remove" / "get rid of" a dashboard. Reach for hard delete only when the user explicitly says "permanently", "for good", or similar. List que

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Dashboard Management](https://modelsatlas.com/skills/builderio/dashboard-management/badge.svg)](https://modelsatlas.com/skills/builderio/dashboard-management/)

Not your listing, or something out of date? Claim or update your listing.