docs(tsuga-build-dashboard): document query alias key format

.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Tsuga toolkit for AI coding agents: one plugin with the tsuga CLI driver, live-platform investigation, dashboards, incident workflows, OpenTelemetry instrumentation, Collector, signal-choice, telemetry debug, and audit skills.",
-    "version": "0.8.2"
+    "version": "0.8.3"
   },
   "plugins": [
     {

plugins/tsuga/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tsuga",
   "description": "Tsuga observability plugin: the `tsuga` CLI driver (commands, TQL syntax, aggregation bodies, counter math, deep links, cloud/k8s translators); live-platform investigation for service health, errors, latency, and monitor coverage; dashboard building; incident orchestration; OpenTelemetry SDK, Collector, OTTL, signal-choice, telemetry debug, and audit skills; and meta-skills for building and validating skill bundles.",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "author": {
     "name": "Tsuga Engineering",
     "email": "engineering@tsuga.com"

plugins/tsuga/skills/tsuga-build-dashboard/SKILL.md

@@ -79,6 +79,7 @@ Key structural rules:
 - `owner` must be a team ID — resolve with `tsuga teams list`
 - Each graph requires a unique `id`, a `visualization` object, and a `layout` object
 - `query-value` does not support `groupBy` — the API silently drops it
+- Name each series in the legend via `visualization.aliases.queries`, keyed by the query's zero-based index as a string (`"0"`, `"1"`, ...) — NOT `formula`'s `"q1"`/`"q2"`; wrong keys are silently ignored (see `references/widget-reference.md`)
 - List-style widgets take a single `query` string. Variants: `list` (logs matching a Tsuga query), `list-log-patterns` (logs clustered into patterns), `list-connection` (datastore rows via `connectionId` + read-only SQL)
 - Include dashboard-level env + team filters when they are relevant to the dashboard audience:
 

plugins/tsuga/skills/tsuga-build-dashboard/references/widget-reference.md

@@ -25,6 +25,21 @@ Max 15 queries per widget. `formula` references queries by position: `"q1"` = fi
 
 **Never send an empty `name` or `description` (`""`)** — the API rejects it with a 400 (`must NOT have fewer than 1 characters`). When a widget has no label (common for notes), **omit the key entirely** rather than passing `""`. (For aggregate/query-body rules — `count` not valid on `metrics`, Unix-seconds `timeRange`, etc. — see `tsuga-cli`.)
 
+### Series names in the legend (`aliases`)
+
+Every series renders with an auto-generated label like `Count on (<filter>)` unless you name it. To set legible legend names, add `aliases` to the visualization:
+
+```json
+"aliases": {
+  "queries": {"0": "Humans", "1": "AI agents", "2": "Automation"},
+  "formula": "Programmatic %"
+}
+```
+
+- `aliases.queries` is keyed by each query's **zero-based index as a string** — `"0"` is the first query in `queries`, `"1"` the second, and so on.
+- ⚠️ this key is NOT the `formula` syntax. `formula` references queries as `"q1"`, `"q2"`; `aliases.queries` uses `"0"`, `"1"`. Using `"q1"` as an alias key is silently ignored and the generated label stays.
+- Works on every aggregation widget (`timeseries`, `top-list`, `pie`, `bar`, `gauge`, ...). On `table`, aliases are set per column instead (see the `table` section).
+
 ---
 
 ## `timeseries`