From 80a1315bd7227648bec511fa180468fc8881e980 Mon Sep 17 00:00:00 2001
From: James Williams <james.williams@getdx.com>
Date: Mon, 6 Jul 2026 15:07:28 -0600
Subject: [PATCH 1/3] Update template and instructions for creating/updating
 reports

---
 skills/dx-cli/references/report-creation.md    | 5 ++++-
 src/commands/studio/report-blank-template.yaml | 3 ++-
 src/commands/studio/reports.test.ts            | 2 ++
 src/commands/studio/reports.ts                 | 3 +++
 4 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/skills/dx-cli/references/report-creation.md b/skills/dx-cli/references/report-creation.md
index bdbd3d3..632cc58 100644
--- a/skills/dx-cli/references/report-creation.md
+++ b/skills/dx-cli/references/report-creation.md
@@ -87,7 +87,8 @@ viewer_emails: []
 edit_access_type: read_only
 editor_emails: []
 tiles:
-  - title: "Table"
+  - key: "tile1"
+    title: "Table"
     sql: |-
       SELECT 1 AS value
     chart_type: table
@@ -115,6 +116,8 @@ Provide `editor_emails` only when `edit_access_type` is `specific_users`.
 
 ### Tiles
 
+Each tile `key` must be unique for the report.
+
 Supported tile `chart_type` values are `line`, `pie`, `stacked_bar`, `scatter`, and `table`.
 
 `line`, `stacked_bar`, and `scatter` chart configs require `xAxis` and `yAxes`; `pie` chart configs require `labelColumn` and `valueColumn`; `table` chart configs can be `{}`.
diff --git a/src/commands/studio/report-blank-template.yaml b/src/commands/studio/report-blank-template.yaml
index 09df0b9..c294717 100644
--- a/src/commands/studio/report-blank-template.yaml
+++ b/src/commands/studio/report-blank-template.yaml
@@ -23,7 +23,8 @@ editor_emails: []
 
 # Supported chart_type values: line, pie, stacked_bar, scatter, table
 tiles:
-  - title: ""
+  - key: "tile1"
+    title: ""
     sql: |-
       SELECT 1 AS value
     chart_type: table
diff --git a/src/commands/studio/reports.test.ts b/src/commands/studio/reports.test.ts
index b71858e..02bfcee 100644
--- a/src/commands/studio/reports.test.ts
+++ b/src/commands/studio/reports.test.ts
@@ -83,6 +83,7 @@ describe("studio reports command", () => {
     tiles: [
       {
         id: "tile_line",
+        key: "tile1",
         title: "Weekly deploys",
         sql: "SELECT week_start, deploys FROM deployments",
         chart_type: "line",
@@ -93,6 +94,7 @@ describe("studio reports command", () => {
       },
       {
         id: "tile_table",
+        key: "tile2",
         title: "Recent deploys",
         sql: "SELECT * FROM deployments LIMIT 10",
         chart_type: "table",
diff --git a/src/commands/studio/reports.ts b/src/commands/studio/reports.ts
index 7dc5d78..f1fffba 100644
--- a/src/commands/studio/reports.ts
+++ b/src/commands/studio/reports.ts
@@ -309,6 +309,7 @@ export function reportsCommand() {
 
 type StudioReportTile = {
   id: string;
+  key: string;
   title: string | null;
   sql: string | null;
   chart_type: string;
@@ -336,6 +337,7 @@ type StudioReport = {
 };
 
 type StudioReportTilePayload = {
+  key: string;
   title: string | null;
   sql: string | null;
   chart_type: string;
@@ -624,6 +626,7 @@ function studioReportToYaml(report: StudioReport): string {
     edit_access_type: report.edit_access_type,
     editor_emails: [],
     tiles: report.tiles.map((tile) => ({
+      key: tile.key,
       title: tile.title,
       sql: tile.sql,
       chart_type: tile.chart_type,

From 0fc75665771bd496176345b101853ea545c2d098 Mon Sep 17 00:00:00 2001
From: James Williams <james.williams@getdx.com>
Date: Mon, 6 Jul 2026 15:14:23 -0600
Subject: [PATCH 2/3] update changelog

---
 CHANGELOG.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 24ecb0d..0aba1ec 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Updated
+
+Document newly required `key` value for `tiles` when creating and updating reports via `dx studio reports`.
+
 ## 0.5.3 - 2026-06-26
 
 ### Updated

From c9bbecf94d448b6c98db5cb5e1ba71f8deb08413 Mon Sep 17 00:00:00 2001
From: James Williams <james.williams@getdx.com>
Date: Mon, 6 Jul 2026 15:37:52 -0600
Subject: [PATCH 3/3] update text

---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0aba1ec..d0d9cfd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Updated
 
-Document newly required `key` value for `tiles` when creating and updating reports via `dx studio reports`.
+Document new `key` value for `tiles` available when creating and updating reports via `dx studio reports`.
 
 ## 0.5.3 - 2026-06-26