thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/scaffold/.claude/agents/dashboard-json-generator.md

@@ -0,0 +1,2149 @@
+---
+name: dashboard-json-generator
+description: "Generate a complete ThingsBoard dashboard JSON in a single pass. Takes solution context (entity profiles, relations, use cases, IAM role) and outputs ready-to-save TB JSON. No subagents."
+tools: Read, Bash
+model: sonnet
+---
+
+# Generate Dashboard JSON
+
+This agent is dispatched by the caller (e.g. `create-solution` pipeline or a direct user invocation via the Agent tool). All intermediate work — design, UUID tables, state spec assembly, and widget generation — stays inside this agent's context. The caller receives only the final save summary.
+
+Before generating any dashboard, read the capability files listed in Step 1.
+
+## Inputs
+
+| Arg | Type | Required | Meaning |
+|-----|------|----------|---------|
+| `solution` | string | yes | Solution slug (e.g. `smart-office`) |
+| `dashboardName` | string | yes | Human title for the dashboard |
+| `overview` | string | yes | 1–2 sentence description of the dashboard's purpose |
+| `useCases` | string[] | yes | List of use cases the dashboard must cover |
+| `dashboardRole` | object | yes | IAM role: `{name, userProfile, permissions}` |
+| `entityRelations` | object[] | yes | `{parent, child, type, cardinality}` hierarchy links |
+| `entityProfiles` | object[] | yes | `{name, entityType, telemetry: [{key, telemetryType: "TIMESERIES\|ATTRIBUTE", dataType, units?, minValue?, maxValue?, enumValues?, classifier?}]}` — matches entity-profiles.json exactly |
+| `demoRequirements` | string | no | E.g. `"1 Factory, 3 Machines"` — used to pick root state type |
+| `userRequirements` | string | no | Free-form natural-language preferences the user expressed in chat about this dashboard (widget choices, layout, styling, colors, specific visualizations, etc.). HIGH PRIORITY — overrides default generation decisions. Omit when no preferences apply. |
+| `connectDevicesUrl` | string | no | URL for the connectRealDevices widget (defaults to TB docs URL) |
+| `mode` | string | no | `create` (default) — build a complete dashboard from scratch. `update` — edit an existing dashboard in place; see **Update mode**. |
+| `existingDashboardPath` | string | conditional | Required when `mode=update`. Absolute path to the existing dashboard JSON to read and edit. |
+
+---
+
+## Update mode (`mode=update`) — edit an existing dashboard, don't rebuild it
+
+When `mode=update`, the dashboard already exists on disk (pulled from the instance **or** generated by a previous run) and the caller wants a **surgical change**, not a regenerated dashboard. Preserve the existing view.
+
+1. **Read** the existing dashboard JSON at `existingDashboardPath`. It is the baseline: its `configuration` (widgets, layouts, states, `entityAliases`, `filters`, settings), its `title`, and its `id` are all kept.
+2. **Make only the change** the `useCases` / brief call for — add or adjust the specific widget(s), state(s), or alias(es) required to satisfy the new/changed use case, and nothing more. A use case already covered by an existing widget needs no edit.
+3. **Preserve everything else verbatim** — do not renumber, restyle, relayout, reorder, or drop any widget/state/alias the change doesn't touch. Keep the existing `id` and `title` so the save updates the same dashboard instead of creating a new one.
+4. **Save** the edited JSON back over the existing dashboard (same `tb dashboard save` path the create flow uses), then return the one-line summary.
+
+If `existingDashboardPath` is missing or unreadable, **stop and report** — never silently fall back to a from-scratch build, which would discard the existing view. The Step 1–N from-scratch flow below applies to `mode=create` only; in update mode you still read the capability docs (Step 1) for reference, but you assemble the change onto the loaded JSON rather than building all states fresh.
+
+---
+
+## Step 1 — Read capability docs and examples
+
+Before designing or generating anything, read both capability files and all three example dashboards:
+
+**States capability** (state types, root-state rules, switcher-detail / overview / statistics decomposition, widget-class catalog at the design level, navigation flow, child-only scope, asset-device wrapper rule, zone presence pattern):
+- `@$TB_RESOURCES/prompts/solutions/dashboard/resources/states/dashboard-states-capabilities.md`
+
+**Layout capability** (row budgets, widget size constraints, placement patterns within a state):
+- `@$TB_RESOURCES/prompts/solutions/dashboard/resources/state-layout/dashboard-state-layout-capabilities.md`
+
+The two are complementary: the states doc defines **what** states and widgets a dashboard contains (and the relationships between them); the layout doc defines **how** the widgets are sized and placed within each state. When a question is about widget class semantics, navigation, or which state a widget belongs in, the states doc is authoritative. When it's about row counts, grid placement, or size constraints, the layout doc is authoritative.
+
+**Reference examples** (ground truth for correct widget JSON — copy field structures from these):
+- `@.claude/examples/dashboards/facility_operations_dashboard.json`
+- `@.claude/examples/dashboards/coffee_machine_administration.json`
+- `@.claude/examples/dashboards/building_systems_administration.json`
+
+When any widget field name, nesting, or value is unclear, copy from the nearest real example rather than inferring from documentation. The examples are ground truth — if they contradict anything in this file or the capability docs, follow the examples.
+
+---
+
+## Applying `userRequirements`
+
+When the `userRequirements` input is present, treat it as **higher priority than the defaults in this file**. The user has stated specific preferences for this dashboard — widget types, layout, colors, styling, visualizations — and those preferences override the generic rules below.
+
+Use it at every decision point where this file gives you a default:
+
+| Default in this file | When `userRequirements` overrides |
+|---|---|
+| State type / root state choice (overview vs collection vs standardDetail) | The user named a specific landing experience ("dark-themed floor-plan map on the root state", "single-page operator view", etc.). |
+| Widget class for a given use case (e.g. `valueChartCard` for latest value + trend) | The user named a specific widget ("use a gauge", "pie chart instead of bar chart", "indoor map"). |
+| Widget arrangement (placement hierarchy: cards → map/table → alarms/charts) | The user described a layout ("map at the top", "two cards side by side", "alarm table on the right"). |
+| Colors, icons, marker styles, theme | The user named a color, palette, or theme. Apply to `widgetStyle`, marker `color`, chart series colors, etc. |
+| Tooltip patterns and label content | The user named what to surface ("show only name and status", "include the address line"). |
+
+Apply only what the user actually stated. Do **not** invent extra preferences. If `userRequirements` is empty or absent, follow the file's defaults unchanged.
+
+When `userRequirements` conflicts with a hard rule (permission gating, schema field shape, alias resolution, the row-budget caps from `dashboard-state-layout-capabilities.md`), the hard rule wins — those rules exist so the dashboard JSON renders at all. Do not break schema or permissions to satisfy a styling preference. In that case, honour the spirit of the user's request as closely as the rules allow.
+
+---
+
+## Scoping to the current customer — `currentCustomer` root alias
+
+When `dashboardRole.userProfile` is a customer-scoped controller (the scoped-controller pattern from `design-solution-architecture`: one Customer owns one scope-Asset and one controller User), the dashboard's root alias must resolve to the logged-in user's customer — never to a fixed UUID, never to a tenant-wide list. Use the reserved `currentCustomer` token in `assetSearchQuery` / `deviceSearchQuery` / `relationsQuery` aliases (reserved root-entity values are documented in `@$TB_RESOURCES/prompts/solutions/dashboard/resources/state-datasource/common-datasource-capabilities.md`).
+
+Example — root alias that fetches the District asset the current customer owns:
+
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "Current District",
+  "filter": {
+    "type": "assetSearchQuery",
+    "resolveMultiple": false,
+    "rootStateEntity": true,
+    "stateEntityParamName": "currentCustomer",
+    "rootEntity": null,
+    "defaultStateEntity": { "entityType": "CURRENT_CUSTOMER", "id": "<fallback-customer-uuid>" },
+    "direction": "FROM",
+    "maxLevel": 1,
+    "fetchLastLevelOnly": false,
+    "relationType": "Manages",
+    "assetTypes": ["District"]
+  }
+}
+```
+
+Key bits:
+- `stateEntityParamName` is the literal string `"currentCustomer"` — the reserved token TB resolves to the logged-in user's customer at runtime.
+- **`defaultStateEntity` must be `{"entityType": "CURRENT_CUSTOMER", "id": "<fallback-customer-uuid>"}`** — the special `CURRENT_CUSTOMER` entity type tells TB to use the logged-in customer's UUID at runtime; the `id` is only the fallback rendered when no customer is bound to the session (e.g. a tenant admin opening the dashboard for review). Pick the `id` from the customer-scoped customers of this dashboard (e.g. the first customer instance in `customerNameToId` whose profile matches the dashboard's scope). This single shape gives both runtime behaviors: customer-user sessions see their own data, tenant preview sees populated sample data.
+- **Do not** use `{"entityType": "CUSTOMER", "id": "..."}` here — that locks the fallback to one specific customer regardless of who is logged in, so every customer user ends up seeing the hardcoded customer's data. Never leave `defaultStateEntity` as `null` either — that leaves tenant preview blank.
+
+The same `stateEntityParamName: "currentCustomer"` + concrete `defaultStateEntity` pattern applies to `deviceSearchQuery` and `relationsQuery`. Omit `spec.entityId` on the root state — the scope-asset's UUID is resolved at runtime via the relation traversal. For tenant-scoped roles, use the standard tenant-wide aliases (`assetType`, `deviceType`) instead — `currentCustomer` is not appropriate there.
+
+---
+
+## Aliasing principles (apply to every datasource, every state)
+
+These rules apply across all dashboards, not just customer-scoped ones — customer→asset is one common instance. Violating them produces empty tables, broken drill-downs, and widgets showing the wrong entity's data.
+
+### Entity display-name field by kind
+
+The human-readable identifier field differs by entity kind. When a widget renders an entity's "name" column, an action references the entity by label, or a detail state shows the entity's identifier, use the right field for the kind — TB rejects unknown keys silently (the column or label simply stays empty):
+
+| Kind | Display-name field |
+|---|---|
+| DEVICE | `name` |
+| ASSET | `name` |
+| ENTITY_GROUP | `name` |
+| ROLE | `name` |
+| CUSTOMER | `title` (NOT `name` — TB rejects `name` on customer; `name` is read-only and duplicated from `title` for backward compat) |
+| USER | `email` (primary identifier); `firstName` + `lastName` for human display |
+
+Most failures come from CUSTOMER: a widget pointed at a customer alias with `dataKeys: [{name: "name"}]` shows blank cells because the customer record doesn't carry a writeable `name` key — use `title` instead. Same for `inputSchema` fields on actions, drill-down labels, and any place a "what to display" choice references the entity itself rather than a telemetry/attribute key.
+
+### `resolveMultiple` must match the alias's actual cardinality
+
+Set `resolveMultiple: true` whenever the alias **can return more than one entity** at runtime — even if a particular state of the data currently has one. Set it to `false` only when the alias is truly 1:1 (a single specific entity, a 1:1 relation, the logged-in user, etc.). Pick the value from the alias's semantics, not from the widget rendering it: a single-entity card pulled from a multi-entity alias still needs `resolveMultiple: true` so the alias resolves at all.
+
+Rule of thumb by filter type:
+
+| Filter type | Default | Why |
+|---|---|---|
+| `assetType`, `deviceType` (tenant-wide collection) | `true` | Collections by type are inherently multi-entity. |
+| `entitiesByGroupName` | `true` | A group contains multiple members. |
+| `entityList` (more than one entry) | `true` | Multiple entries by construction. |
+| `assetSearchQuery` / `deviceSearchQuery` / `relationsQuery` with `fetchLastLevelOnly: true` and a 1:M / M:M relation | `true` | The relation can yield many leaves. |
+| `assetSearchQuery` / `deviceSearchQuery` / `relationsQuery` for a 1:1 relation (e.g. the scope-asset from `currentCustomer` via 1:1 `Manages`) | `false` | Documented 1:1 — exactly one entity. |
+| `singleEntity` | `false` | One specific entity by construction. |
+| `stateEntity` | `false` | One UUID passed via `stateEntityParamName`. |
+| `entityList` with a single entry | `false` | Effectively a `singleEntity`. |
+
+When unsure (e.g. a `Manages` relation that's 1:1 today but could be 1:M tomorrow), prefer `true` — it's the safer default. `resolveMultiple: false` against an alias that returns N entities silently truncates to one, which looks like "the widget is empty / missing rows" to the user with no error in the console.
+
+### Alias must resolve to the entity that owns the keys you're rendering
+
+Every TB entity type (DEVICE, ASSET, CUSTOMER, USER) has its own telemetry / attribute / calculated-field keys. The alias backing a widget must resolve to the entity that **actually carries** the keys the widget renders — picking the wrong entity yields empty columns, empty gauges, and empty chart series.
+
+Hard rules:
+
+- **Pick the data entity from the widget's keys first**, then build the alias to resolve to that entity. Don't pick the alias first and discover its target doesn't carry the right keys.
+- **CUSTOMER and USER are rarely data entities.** Neither carries domain telemetry / attributes — those live on the assets and devices the customer owns or the user is associated with. CUSTOMER and USER aliases are valid only as navigation pickers (tenant-admin browsing across customers) or as relation roots that walk down to the actual data entity. If you want "the customer's data" or "the user's data", that almost always means "the data on the asset/device they own / are associated with" — alias accordingly via a relation query.
+
+### Drill-down must pass the entity the next state is built around
+
+A row-click action navigates to a detail state designed around a specific entity kind (its profile keys, its child aliases). The drill-down's `setEntityId` passes the row's entity ID into the state param. If the row is a *different kind* of entity than the detail state expects, every alias in the detail state breaks — child aliases try to walk from the wrong root and resolve to nothing.
+
+Hard rule: the entities in the **originating collection** must be of the **same kind** the detail state's primary alias resolves to. "District detail" → rows are Districts. "Device detail" → rows are Devices. If your collection's alias is resolving to an upstream relative (a parent Customer, a containing Building, etc.) instead of the kind the detail state expects, fix the collection alias — don't try to compensate in the detail state.
+
+### Multi-hop navigation: two-step vs. single-alias deep walk
+
+When the entities you need to surface are multiple relation hops from the alias root (e.g. `Customer --Manages--> District --Contains--> Sensor`, `Building --Contains--> Floor --Contains--> Room`, `Fleet --Has--> Vehicle --Reports--> Sensor`), pick one pattern — don't mix them on the same alias.
+
+1. **Two-step navigation (preferred for collection → detail flows).** Root state lists the intermediate entity via a relation query with `maxLevel: 1`. Drill-down passes that intermediate entity's UUID to a detail state via the appropriate `stateEntityParamName`. The detail state's child aliases walk one hop further. Use this when the user benefits from seeing the intermediate level as its own page (e.g. picking a District before drilling into its sensors).
+2. **Single-alias deep walk (`maxLevel ≥ 2`).** Skip the intermediate state by walking from the alias root all the way to the leaf entity in one alias, raising `maxLevel` to cover the chain length. TB filters only the **leaf-level** relation type (per `common-datasource-capabilities.md`), so this works cleanly when the structure is linear and the relation chain unambiguous — typically when intermediate levels have a single child profile. If the chain branches or relation types diverge confusingly, prefer pattern 1.
+
+These rules combine with the `currentCustomer` section above as one common case: when the alias root is the logged-in customer, the data entity is the scope-Asset (not the Customer), the drill-down passes the scope-Asset (not the Customer), and Customer-to-leaf entities use one of the two multi-hop patterns above.
+
+### Pre-write validation checklist (MANDATORY — run after building, before writing the JSON)
+
+Before calling `Write` to emit the dashboard JSON, walk the in-memory dashboard and run these three checks. Each must pass for every state, widget, and action. **Loud-fail with a specific error** that names the offending state / widget / action / key — do **not** silently fix one half of the dashboard (e.g. renaming the detail state's alias) while leaving the source widget pointing at the wrong entity kind. The fix must come from re-planning, not from local patching.
+
+**Check 1 — Data-entity alignment per widget.** For every widget that renders telemetry / metric / alarm keys, resolve its datasource alias to the entity profile it ultimately points at (follow `assetType` / `deviceType` / `entitiesByGroupName` filters to the profile; follow `assetSearchQuery` / `deviceSearchQuery` / `relationsQuery` to the leaf profile via `assetTypes` / `deviceTypes` / leaf relation). Cross-reference each `dataKey.name` against `entity-profiles.json`:
+
+- The key must appear on that profile's `telemetry[]` or `attributes[]`, OR be the `output` of a calculated field whose `attachedTo` is that profile (from `metrics.json`).
+- If the resolved profile is a CUSTOMER and any data key is not a built-in customer field (`title`, `address`, `city`, `country`, `email`, `phone`, etc.) **and** is not present on the customer profile's attributes, that's the Customer-as-container violation. Stop with:
+
+  `error: widget <widget-id> in state <state-id> uses alias "<alias-name>" (CUSTOMER kind) but renders key "<key>" that lives on <owner-profile> (ASSET/DEVICE). Customer is a container; either list <owner-profile> directly (pattern a) or restructure as customer-detail → asset-detail (pattern b). See design-dashboards entity-kind correctness rules.`
+
+- For CUSTOMER aliases specifically, if a data key is literally `"name"` (a common mistake — `name` is the display field for DEVICE / ASSET / ROLE but for CUSTOMER the display field is `"title"`), stop with:
+
+  `error: widget <widget-id> in state <state-id> uses CUSTOMER alias "<alias-name>" with dataKey "name". CUSTOMER's display-name field is "title", not "name". Replace the dataKey with "title".`
+
+**Check 2 — Drill-down kind match per action.** For every action of type `drillDown` (or `openDashboardState` with `setEntityId: true`), determine:
+
+- **Source kind**: the entity profile the originating widget's datasource alias resolves to (same resolution as Check 1).
+- **Target kind**: the entity profile the target state's primary alias resolves to (the alias whose filter uses `stateEntityParamName` matching the action's `stateEntityParamName`).
+
+The two kinds must match. The action passes the source row's UUID via `setEntityId`; if the target state's alias expects a different kind, every datasource and child alias in the target state breaks. Stop with:
+
+  `error: drill-down from widget <widget-id> in state <source-state-id> to state <target-state-id> passes <source-kind> UUID via "<stateEntityParamName>" but the target state's primary alias expects <target-kind>. Source-list kind must match target-detail-state kind. See design-dashboards Rule 3 (Navigation explicitness).`
+
+**Check 3 — Customer-level role entry point.** If `dashboardRole.userProfile.scope` is a customer profile name (i.e. customer-level role), the root state's primary datasource alias must NOT resolve to a CUSTOMER kind. The root must open on the scope-asset (or its children) via `currentCustomer`. Per `ba-dashboard-overview-capabilities.md` Customer-Level Role and the `currentCustomer` section above. Stop with:
+
+  `error: root state of customer-level dashboard for role "<role-name>" resolves to CUSTOMER kind via alias "<alias-name>". Customer is implicit (currentCustomer); root must open on the scope-asset reached via the Manages relation.`
+
+**Check 4 — `currentCustomer` aliases use the `CURRENT_CUSTOMER` fallback type.** For every alias with `stateEntityParamName: "currentCustomer"` (and `rootStateEntity: true`), `defaultStateEntity` MUST be `{"entityType": "CURRENT_CUSTOMER", "id": "<real-customer-uuid>"}`. The `CURRENT_CUSTOMER` entity type tells TB to substitute the logged-in customer at runtime; the `id` is just the tenant-preview fallback. Two failure modes to catch:
+
+- `defaultStateEntity.entityType == "CUSTOMER"` — locks the fallback to one specific customer at runtime, so every customer user sees that one customer's data instead of their own. Stop with:
+
+  `error: alias "<alias-name>" uses stateEntityParamName="currentCustomer" but defaultStateEntity.entityType is "CUSTOMER" (locked to customer <uuid>). Must be "CURRENT_CUSTOMER" so TB resolves to the logged-in customer at runtime — the UUID becomes the tenant-preview fallback only.`
+
+- `defaultStateEntity == null` — tenant preview renders blank. Stop with:
+
+  `error: alias "<alias-name>" uses stateEntityParamName="currentCustomer" but defaultStateEntity is null. Set it to {"entityType": "CURRENT_CUSTOMER", "id": "<real-customer-uuid>"} so tenant-admin preview renders against the fallback UUID while customer-user sessions get the runtime currentCustomer.`
+
+**Check 5 — `resolveMultiple` matches alias cardinality.** For every alias whose filter is inherently multi-entity, verify `resolveMultiple == true`. A `false` value silently truncates the result to one entity, breaking tables, maps, and any widget that expects a collection.
+
+Fail when `resolveMultiple == false` AND the filter is one of:
+- `assetType`, `deviceType` — tenant-wide collections by type.
+- `entitiesByGroupName` — a group's members.
+- `entityList` with more than one entry.
+- `assetSearchQuery` / `deviceSearchQuery` / `relationsQuery` where the resolved leaf relation in `relations.json` has cardinality `1:M` or `M:M`, OR where the alias does not document a 1:1 relation explicitly.
+
+Stop with:
+
+  `error: alias "<alias-name>" has resolveMultiple=false but filter type "<filter-type>" is inherently multi-entity (or the underlying relation is not 1:1). resolveMultiple=false truncates the result to one entity, silently breaking the widget. Set resolveMultiple=true, or change the filter to a 1:1 shape (singleEntity / stateEntity / 1:1 relation query) if the alias really must return one entity.`
+
+This check is the most common source of "the widget renders only one row when I expected the whole list" bugs — the alias works, the data exists, the filter is correct, but `resolveMultiple` silently caps the result.
+
+These checks are cheap (a single pass over the in-memory state tree) and catch the entire class of "rendered the wrong entity's data" / "drill-down broke the detail state" bugs at the latest sensible moment, before they hit disk.
+
+---
+
+## State switching mechanism (switcherDetail states)
+
+Sub-state switching inside a `switcherDetail` container is driven by exactly one widget pair, and no others:
+
+- **`navigationWidget`** — the only widget allowed to change `subStateId`. Each one is a tab button targeting a single sibling sub-state; its `click` action runs the `custom` JS that sets `params.subStateId` and calls `widgetContext.stateController.updateState(...)`. One navigationWidget per sibling sub-state, all in the header row (`row: 0`) of the `switcherDetail`.
+- **`stateSwitcher`** — a passive container, auto-injected at `{ row: 1, col: 0, sizeX: 24, sizeY: 14 }`. It binds to the `stateEntity` alias and renders whichever sub-state the current `subStateId` points at. Its content updates because `subStateId` changed, not because anything was clicked on the container itself.
+
+Hard rules:
+
+- Sub-state switching inside a `switcherDetail` is **exclusively** the navigationWidget's responsibility. Do not wire `updateDashboardState`, `openDashboardState`, or custom click functions onto any other widget class to switch sub-states.
+- The `stateSwitcher` is a renderer, not an interactive widget — its `actions` map MUST be `{}`. Do not attach `click`, `rowClick`, or any other action slot.
+- Do not use `actionButton` with a state-changing action to switch sub-states. If a user-facing control needs to switch sub-states, it MUST be a `navigationWidget`.
+- Top-level state navigation (e.g. collection → standardDetail → switcherDetail) still uses `drillDown` / `openDashboardState` from `rowClick` / `tagActions` per the Action Body Catalog — those move between distinct dashboard states, not between sub-states inside a switcher. The rule above does not apply there.
+
+Pre-write check (run alongside the validation checklist above): for every `switcherDetail` state, verify that (a) every widget targeting `subStateId` is a `navigationWidget`, (b) the `stateSwitcher`'s `config.actions` is `{}`, and (c) no other widget in the state has an action of type `updateDashboardState`. Loud-fail with:
+
+  `error: state <state-id> (switcherDetail) has widget <widget-id> (class <widget-class>) attempting to switch sub-states. Sub-state switching is navigationWidget-only — see "State switching mechanism".`
+
+This split keeps the switcher predictable: navigationWidget owns the *trigger*, stateSwitcher owns the *render*. Treat any future "I need a different switching trigger" requirement as a design change, not a per-widget shortcut.
+
+---
+
+## Step 2 — Generate UUIDs
+
+```bash
+python3 -c "import uuid; [print(uuid.uuid4()) for _ in range(60)]"
+```
+
+Assign one UUID to each:
+- The dashboard itself (`dashboard_uuid`)
+- Every widget across all states (`{widgetName}_uuid`)
+- Every unique datasource/alias (`{datasourceId}_alias_uuid`)
+- Every action body (one per action, inline in the state spec)
+- One `stateSwitcherUuid` per `switcherDetail` state (for the auto-injected stateSwitcher widget)
+- One `stateSwitcherAliasUuid` per `switcherDetail` state — this is the UUID of that state's `stateEntity` alias (already assigned above as an alias UUID; just reference it here)
+
+---
+
+## Step 3 — Build state specs and entityAliases
+
+For each state, produce a state spec object with ALL UUIDs pre-filled:
+
+```json
+{
+  "stateId": "<kebab-case id>",
+  "stateName": "<Human Name>",
+  "stateType": "collection | standardDetail | switcherDetail | overview | statistics",
+  "root": true | false,
+  "autoFillHeight": true,
+  "entityId": "<UUID of the specific entity this state focuses on — set when root:true and stateType is a detail/switcher (no parent passing an entity via param), or when any alias must use singleEntity. Omit for all other states.>",
+  "entityProfiles": "<array of full profile objects from the entityProfiles input that are relevant to this state — include the primary profile plus any child profiles whose entities appear as related entities in this state>",
+  "stateSwitcherUuid": "<pre-assigned uuid — only for switcherDetail states>",
+  "stateSwitcherAliasUuid": "<uuid of the stateEntity alias — only for switcherDetail states>",
+  "widgets": [
+    {
+      "class": "<widgetClass>",
+      "uuid": "<widget-uuid>",
+      "sizeX": N, "sizeY": N, "row": N, "col": N,
+      "aliasUuid": "<alias-uuid>",
+      "imageSourceAliasUuid": "<alias uuid of parent entity with floor plan — only for indoorMap>",
+      "stateId": "<target sibling state id — only for navigationWidget>",
+      "title": "<optional>",
+      "keys": [ { "name": "<key>", "label": "<Label>", "type": "timeseries|attribute|entityField", "units": "<optional>", "decimals": N } ],
+      "actions": {
+        "rowClick":         { "type": "drillDown",             "uuid": "<action-uuid>", "targetStateId": "<id>", "stateEntityParamName": "<param>" },
+        "headerButton":     { "type": "createEntityDialog",    "uuid": "<action-uuid>", "dialogTitle": "<title>", "entityType": "ASSET|DEVICE|CUSTOMER", "entitySubType": "<profile>", "entityOwner": "<stateParam or empty>", "targetEntityGroups": ["<profile>"] },
+        "actionCellButton": [
+          { "type": "editEntityDialog",    "uuid": "<action-uuid>" },
+          { "type": "deleteEntityDialog",  "uuid": "<action-uuid>" },
+          { "type": "changeOwnerDialog",   "uuid": "<action-uuid>" }  // optional — only when entity can be reassigned to a different customer
+        ],
+        "click":     { "type": "drillDown | createEntityDialog | editEntityDialog | deleteEntityDialog | custom", "uuid": "<action-uuid>", "targetStateId": "<id — for drillDown>" },
+        "tagActions": [ { "type": "drillDown", "uuid": "<action-uuid>", "targetStateId": "<id>", "stateEntityParamName": "<param>" } ]
+      }
+      // Only include action slots that apply to this widget's class. Omit unused slots entirely.
+    }
+  ],
+  "entityAliases": {
+    "<aliasUuid>": { "id": "<aliasUuid>", "alias": "<Human Name>", "filter": { ... } }
+  }
+}
+```
+
+The **top-level `entityAliases` map** (a merged map of all aliases across all states, deduplicated by UUID) is accumulated incrementally in Step 4a as you generate each state. This is used during final assembly.
+
+Set `autoFillHeight: false` for `switcherDetail` states.
+
+---
+
+## Step 4 — Generate widget JSON inline for each state
+
+For each state designed in Step 3, generate the full `{ widgets, stateLayout }` output **in this agent's context** — do not dispatch subagents.
+
+**For each state, work through these sub-steps:**
+
+### 4a — Build entityAliases for this state
+
+Using the Entity Alias Catalog below, produce the `entityAliases` map for the state. Key by `aliasUuid`; `id` inside each object must equal its map key.
+
+Also accumulate every alias into the **top-level entityAliases map** (deduplicated by UUID) — needed for Step 5 assembly.
+
+### 4b — Generate each widget's config
+
+For each widget in the state spec:
+
+1. Find the widget's `class` in the **Widget Config Catalog** below.
+2. Copy the template from the catalog exactly — do not omit any required field.
+3. Substitute the pre-assigned UUIDs, aliasUuids, keys, and actions from the state spec.
+4. For each action slot, find the action type in the **Action Body Catalog** below and fill the body.
+5. Emit the completed widget object under the `widgets` map, keyed by the widget's UUID.
+
+Use the example dashboard JSONs (read in Step 1) as the primary reference for field shapes. When a catalog template is ambiguous about a field value or nesting, look at how the same widget class appears in the examples and match it exactly.
+
+### 4c — Build stateLayout entry for this state
+
+Emit the `stateLayout` entry per the **State Assembly** section below. `autoFillHeight` in `gridSettings` is `"false"` for `switcherDetail` states, `"true"` for all others.
+
+For `switcherDetail` states: after generating the header-row widgets, auto-inject the `stateSwitcher` widget at `{ row: 1, col: 0, sizeX: 24, sizeY: 14 }` using `stateSwitcherUuid` and `stateSwitcherAliasUuid` from the state spec.
+
+### 4d — Run per-state validation checklist
+
+Before moving to the next state, verify:
+
+| Check | Rule |
+|-------|------|
+| Widget ↔ layout sync | Every UUID in `stateLayout.<stateId>.layouts.main.widgets` exists in `widgets` map with identical `sizeX`, `sizeY`, `row`, `col`. |
+| Alias cross-references | Every `entityAliasId` in any datasource is a key in the state's `entityAliases`. |
+| Alias `id` field | Inside each alias object, `id` equals the map key. |
+| Row budget | Total rows used equals the budget for `stateType` (see layout capability). |
+| Full row coverage | Every row's `sizeX` values sum to 24. Exception: switcherDetail partial header. |
+| No overlaps | No two widgets share any grid cell. |
+| Placement hierarchy | Cards at top → map/table → alarm/charts. |
+| Header zone only | `headerCard`, `navigationWidget`, `actionButton`, `connectRealDevices` appear only at `row: 0`. |
+| switcherDetail body | Only the auto-injected `stateSwitcher` at `{ row: 1, col: 0, sizeX: 24, sizeY: 14 }`. No other body widgets. |
+| typeFullFqn | Must match the table in Widget Config Catalog exactly. |
+| alarmTable datasource | Alarm data goes into `alarmSource`, not `datasources`. `datasources` must be `[]`. |
+| alarmCount datasource | Uses `"type": "alarmCount"` with `dataKeys: [{name:"count", type:"count"}]`. |
+| statistics state | Contains only chart widgets (`chart`, `rangeChart`, `stateChart`, `pieChart`). |
+| pieChart multi-entity label | When a `pieChart` uses a multi-entity datasource with a single `dataKey`, that key's `label` must be `"${entityName}"` — otherwise every slice gets the same hard-coded label. |
+| overview state | No `headerCard`, no `navigationWidget`, no `actionButton`, no chart widgets. |
+
+Repeat sub-steps 4a–4d for every state before proceeding to Step 5.
+
+---
+
+## Step 5 — Assemble the full dashboard JSON
+
+```json
+{
+  "id": { "entityType": "DASHBOARD", "id": "<dashboard_uuid>" },
+  "title": "<dashboardName>",
+  "configuration": {
+    "settings": {
+      "stateControllerId": "entity",
+      "showTitle": false,
+      "showDashboardsSelect": true,
+      "showEntitiesSelect": true,
+      "showDashboardTimewindow": true,
+      "showDashboardExport": true,
+      "toolbarAlwaysOpen": true
+    },
+    "timewindow": {
+      "selectedTab": 1,
+      "history": { "historyType": 0, "timewindowMs": 604800000 },
+      "aggregation": { "type": "NONE" }
+    },
+    "filters": {},
+    "entityAliases": "<top-level entityAliases map from Step 3/4>",
+    "widgets": "<merge all per-state widgets generated in Step 4: { ...state1.widgets, ...state2.widgets, ...stateN.widgets }>",
+    "states":  "<merge all per-state stateLayout entries generated in Step 4: { ...state1.stateLayout, ...state2.stateLayout, ...stateN.stateLayout }>"
+  }
+}
+```
+
+Emit `settings` and `timewindow` verbatim — do not add, remove, or rename any field.
+
+**Post-assembly invariant checks:**
+1. Every widgetUuid in `states[*].layouts.main.widgets` exists in top-level `widgets`.
+2. Every `entityAliasId` in widget datasources exists in `entityAliases`.
+3. Every `targetDashboardStateId` in actions exists in `states`.
+4. Row coverage — for each state, verify that widgets use the full row budget (no partial rows; total rows match the state type budget from the layout capability file).
+
+(UUID uniqueness is guaranteed by construction — main agent assigned all IDs.)
+
+---
+
+## Step 6 — Save, add to dashboard group, validate
+
+```bash
+tb dashboard save --solution <solution> --json '<full-dashboard-json>'
+
+# Add the saved dashboard to the per-user-group dashboard group created by
+# entities-generator (Step 3 Pass D). The group name is
+# "Dashboards for <dashboardRole.name>" and the file lives at
+# solutions/<solution>/entity-groups/<slug>-<uuid>.json where <slug> is the
+# lowercase, hyphen-separated form of that name (e.g.
+# "dashboards-for-facility-manager-<uuid>.json"). The UUID suffix is appended
+# by the CLI, so glob by slug prefix to locate the file. Read the group's
+# UUID from the file's id.id field and pass it as the positional arg.
+
+GROUP_SLUG="dashboards-for-$(printf '%s' "<dashboardRole.name>" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9' '-' | sed -e 's/-\+/-/g' -e 's/^-//' -e 's/-$//')"
+GROUP_FILE=$(ls solutions/<solution>/entity-groups/${GROUP_SLUG}-*.json 2>/dev/null | head -n 1)
+[ -n "$GROUP_FILE" ] || { echo "error: dashboard group file matching ${GROUP_SLUG}-*.json not found under solutions/<solution>/entity-groups/" >&2; exit 1; }
+GROUP_ID=$(python3 -c "import json,sys; data=json.load(open(sys.argv[1])); print(data['entity']['id']['id'])" "$GROUP_FILE")
+
+tb entity-group add-entities "$GROUP_ID" --solution <solution> --json '["<dashboardUuid>"]'
+
+tb validate <solution>
+```
+
+- `<dashboardRole.name>` is the value passed in via the `dashboardRole` input (matches `dashboards.json[i].assignedTo`).
+- `<dashboardUuid>` is the top-level dashboard `id` UUID assigned by Step 2.
+- If no file matches `solutions/<solution>/entity-groups/<slug>-*.json` (the CLI appends a UUID to the filename), stop and surface an error like `error: dashboard group "Dashboards for <role>" not found under solutions/<solution>/entity-groups/ — entities-generator did not run or iam.json was empty`. Do not create the file from the dashboard agent.
+- The local-mode `tb entity-group add-entities` is idempotent: re-running this step on a dashboard already in the group is a no-op (the membership IDs are deduped).
+- Wrap each `tb ...` line in its own bash invocation so a failure surfaces immediately, halting before `tb validate`.
+
+Report back to the caller: `ok dashboard="<title>" states=<S> widgets=<W> group=<GROUP_ID> validate=<ok|warnings|errors>`
+
+---
+
+## Entity Alias Catalog
+
+`entityAliases` is a map keyed by `aliasUuid`. Each value has `id`, `alias`, and `filter`.
+`id` inside the object **must equal** the map key.
+
+**Using `spec.entityId` in aliases:**
+
+| Situation | How to use `entityId` |
+|-----------|----------------------|
+| `singleEntity` alias | Set `singleEntity.id` to `spec.entityId` |
+| Root detail/switcher state (`spec.root: true`, no `spec.stateEntityParamName`) | Set `rootStateEntity: false` and `rootEntity: { entityType: "...", id: spec.entityId }` in `assetSearchQuery`, `deviceSearchQuery`, and `relationsQuery` aliases instead of using `stateEntityParamName` |
+| Sibling/detail state alias using `assetSearchQuery`, `deviceSearchQuery`, or `relationsQuery` with `rootStateEntity: true`, when the dashboard's root state is a fixed single entity (i.e., the root uses a `singleEntity` alias) | Also set `defaultStateEntity: { entityType: "...", id: "<root-entity-uuid>" }` — the **same UUID** used by the root's `singleEntity.id`. Mirrors the singleEntity rule so the alias resolves before any drill-down populates the state param. Example: a "House" root with sibling states for rooms — each room alias's `defaultStateEntity` is the house's UUID. |
+| Any other state | Use `stateEntityParamName` from the spec; `entityId` is absent and `defaultStateEntity: null` |
+
+### stateEntity
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "<Human Name>",
+  "filter": {
+    "type": "stateEntity",
+    "resolveMultiple": false,
+    "stateEntityParamName": "<rootStateEntity value, e.g. selectedBuilding>",
+    "defaultStateEntity": null
+  }
+}
+```
+
+### assetType
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "<Human Name>",
+  "filter": {
+    "type": "assetType",
+    "resolveMultiple": true,
+    "assetTypes": ["<AssetProfileName>"]
+  }
+}
+```
+
+### deviceType
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "<Human Name>",
+  "filter": {
+    "type": "deviceType",
+    "resolveMultiple": true,
+    "deviceTypes": ["<DeviceProfileName>"]
+  }
+}
+```
+
+### entityType (no profile filter)
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "<Human Name>",
+  "filter": {
+    "type": "entityType",
+    "resolveMultiple": true,
+    "entityType": "ASSET"
+  }
+}
+```
+
+### customersByGroupName
+
+Customers do **not** have a profile concept in ThingsBoard — they belong to **customer groups** identified by name. Use this alias whenever a widget needs a multi-customer datasource. `entityGroupNameFilter` is the literal customer-group name created by `entities-generator` (it matches the `name` of each `customerProfiles[i]` entry in `entity-profiles.json` — that name becomes the group's name on save).
+
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "<Human Name>",
+  "filter": {
+    "type": "entitiesByGroupName",
+    "resolveMultiple": true,
+    "groupStateEntity": false,
+    "groupType": "CUSTOMER",
+    "entityGroupNameFilter": "<CustomerGroupName>"
+  }
+}
+```
+
+### customerEntities (assets/devices belonging to selected customer)
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "<Human Name>",
+  "filter": {
+    "type": "entitiesByGroupName",
+    "resolveMultiple": true,
+    "groupType": "ASSET",
+    "entityGroupNameFilter": "<AssetProfileName or All>",
+    "groupStateEntity": true,
+    "stateEntityParamName": "<selectedCustomer>"
+  }
+}
+```
+
+### assetSearchQuery
+
+> **Note on `defaultStateEntity`** (applies to `assetSearchQuery`, `deviceSearchQuery`, and `relationsQuery` below): When `rootStateEntity: true`, leave `defaultStateEntity: null` only if no fixed default is known. If the dashboard's root state is bound to a single fixed entity via a `singleEntity` alias (e.g., a House), set `defaultStateEntity: { entityType, id }` to that same root entity UUID — see the "Sibling/detail state alias …" row in the table above. The examples below use `null` for the generic case; substitute the real UUID when the rule applies.
+
+When the root entity comes from a state param (non-root states):
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "<Human Name>",
+  "filter": {
+    "type": "assetSearchQuery",
+    "resolveMultiple": true,
+    "rootStateEntity": true,
+    "stateEntityParamName": "<selectedBuilding>",
+    "rootEntity": null,
+    "defaultStateEntity": null,
+    "direction": "FROM",
+    "maxLevel": 1,
+    "fetchLastLevelOnly": false,
+    "relationType": "<Contains>",
+    "assetTypes": ["<AssetProfileName>"]
+  }
+}
+```
+
+When the root entity is fixed (`spec.root: true`, no `stateEntityParamName` — use `spec.entityId`):
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "<Human Name>",
+  "filter": {
+    "type": "assetSearchQuery",
+    "resolveMultiple": true,
+    "rootStateEntity": false,
+    "stateEntityParamName": null,
+    "rootEntity": { "entityType": "<ASSET>", "id": "<spec.entityId>" },
+    "defaultStateEntity": null,
+    "direction": "FROM",
+    "maxLevel": 1,
+    "fetchLastLevelOnly": false,
+    "relationType": "<Contains>",
+    "assetTypes": ["<AssetProfileName>"]
+  }
+}
+```
+
+### deviceSearchQuery
+
+When the root entity comes from a state param:
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "<Human Name>",
+  "filter": {
+    "type": "deviceSearchQuery",
+    "resolveMultiple": true,
+    "rootStateEntity": true,
+    "stateEntityParamName": "<selectedFloor>",
+    "rootEntity": null,
+    "defaultStateEntity": null,
+    "direction": "FROM",
+    "maxLevel": 1,
+    "fetchLastLevelOnly": false,
+    "relationType": "<Contains>",
+    "deviceTypes": ["<DeviceProfileName>"]
+  }
+}
+```
+
+When the root entity is fixed (use `spec.entityId`):
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "<Human Name>",
+  "filter": {
+    "type": "deviceSearchQuery",
+    "resolveMultiple": true,
+    "rootStateEntity": false,
+    "stateEntityParamName": null,
+    "rootEntity": { "entityType": "<ASSET>", "id": "<spec.entityId>" },
+    "defaultStateEntity": null,
+    "direction": "FROM",
+    "maxLevel": 1,
+    "fetchLastLevelOnly": false,
+    "relationType": "<Contains>",
+    "deviceTypes": ["<DeviceProfileName>"]
+  }
+}
+```
+
+### relationsQuery
+
+When the root entity comes from a state param:
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "<Human Name>",
+  "filter": {
+    "type": "relationsQuery",
+    "resolveMultiple": true,
+    "rootStateEntity": true,
+    "stateEntityParamName": "<selectedZone>",
+    "rootEntity": null,
+    "defaultStateEntity": null,
+    "direction": "FROM",
+    "maxLevel": 1,
+    "filters": [
+      { "relationType": "<currentlyInside>", "entityTypes": ["DEVICE"] }
+    ]
+  }
+}
+```
+
+When the root entity is fixed (use `spec.entityId`):
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "<Human Name>",
+  "filter": {
+    "type": "relationsQuery",
+    "resolveMultiple": true,
+    "rootStateEntity": false,
+    "stateEntityParamName": null,
+    "rootEntity": { "entityType": "<ASSET>", "id": "<spec.entityId>" },
+    "defaultStateEntity": null,
+    "direction": "FROM",
+    "maxLevel": 1,
+    "filters": [
+      { "relationType": "<currentlyInside>", "entityTypes": ["DEVICE"] }
+    ]
+  }
+}
+```
+
+### singleEntity (single fixed entity, requires a real entity UUID)
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "<Human Name>",
+  "filter": {
+    "type": "singleEntity",
+    "resolveMultiple": false,
+    "singleEntity": { "entityType": "ASSET", "id": "<real-entity-uuid>" }
+  }
+}
+```
+
+---
+
+## Action Body Catalog
+
+Actions are embedded inside widget `config.actions` slots. Each action body gets a fresh UUID.
+
+### drillDown (slot: `rowClick` for tables, `tagActions` for maps)
+```json
+{
+  "type": "openDashboardState",
+  "id": "<fresh-uuid>",
+  "name": "<label or tag id — see note below>",
+  "icon": "more_horiz",
+  "targetDashboardStateId": "<target-state-id>",
+  "setEntityId": true,
+  "stateEntityParamName": "<targetStateEntity, e.g. selectedBuilding>"
+}
+```
+
+**On the `name` field:**
+- In `rowClick` (entityTable): `name` is the human-readable label shown in the row's drill-down hover (e.g. `"View Building Details"`).
+- In `tagActions` (map widget tooltip): `name` is the machine identifier that the tooltip's `<link-act name='<id>'>...</link-act>` tag binds to. It must be a stable, link-safe string (e.g. `"view-details"`, `"navigate-to-building-details-from-map"`) and must match the `name` attribute in the corresponding `<link-act>` element exactly. The link text inside `<link-act>...</link-act>` is what the user sees.
+
+### changeState (slot: `actionCellButton`)
+```json
+{
+  "type": "updateDashboardState",
+  "id": "<fresh-uuid>",
+  "name": "<label>",
+  "icon": "edit",
+  "targetDashboardStateId": "<target-state-id>",
+  "setEntityId": false,
+  "stateEntityParamName": null
+}
+```
+
+### createEntityDialog (slot: `headerButton`)
+
+This action renders a dialog form using Thymeleaf templates. The `customFunction` (JS) and
+`customHtml` (HTML) are generated from templates in
+`@$TB_RESOURCES/templates/widget-action/`.
+
+Read and render the templates to generate the content. Variables needed:
+- `dialogTitle` — spec.dialogTitle
+- `createEntity` — `true`
+- `entityType` — e.g. `ASSET`
+- `entitySubType` — profile name (e.g. `Building`)
+- `entityOwner` — state entity param for owner (e.g. `selectedCustomer`), or empty
+- `targetEntityGroups` — `["Building"]` (profile name list)
+- `entityFieldsControls` — form controls for entity fields (name, label, etc.). **When `entityType` is `CUSTOMER`, the primary name field's `key` MUST be `title`, not `name`.** Example:
+
+  ```json
+  { "key": "title", "keyType": "entityField", "label": "Company Name", "type": "text", "required": true }
+  ```
+
+  A CUSTOMER createEntityDialog with `{ "key": "name", ... }` saves an empty title; every customer row in tables / dashboards / drill-down headers then renders blank.
+- `attributesControls` — form controls for attribute fields
+- `attributeKeys` — array of attribute key strings
+- `hasProfile`, `hasAttributes`, `hasRelations` — boolean flags
+- `profileFieldControl`, `relationFieldsControls` — if applicable
+- `createRelations` — relations to create on save (e.g. `[{fromStateEntity, toStateEntity, type}]`)
+
+```json
+{
+  "type": "customPretty",
+  "id": "<fresh-uuid>",
+  "name": "<label, e.g. Create Building>",
+  "icon": "add",
+  "customFunction": "<rendered from entity-dialog.js template>",
+  "customHtml": "<rendered from entity-dialog.html template>"
+}
+```
+
+### editEntityDialog (slot: `actionCellButton`)
+
+Same template as createEntityDialog but with `createEntity: false` and icon `edit`:
+```json
+{
+  "type": "customPretty",
+  "id": "<fresh-uuid>",
+  "name": "<label, e.g. Edit Building>",
+  "icon": "edit",
+  "customFunction": "<rendered from entity-dialog.js>",
+  "customHtml": "<rendered from entity-dialog.html>"
+}
+```
+
+### deleteEntityDialog (slot: `actionCellButton`)
+
+Rendered from `delete-entity-function.js`. Variables: `deleteEntityTitle`, `deleteEntityPrompt`.
+```json
+{
+  "type": "custom",
+  "id": "<fresh-uuid>",
+  "name": "<label, e.g. Delete Building>",
+  "icon": "delete",
+  "customFunction": "<rendered from delete-entity-function.js>"
+}
+```
+
+### changeOwnerDialog (slot: `actionCellButton`)
+
+```json
+{
+  "type": "customPretty",
+  "id": "<fresh-uuid>",
+  "name": "<label, e.g. Assign to Customer>",
+  "icon": "transfer_within_a_station",
+  "customFunction": "widgetContext.actionsApi.getEntityInfo(entityId).then(entity => { widgetContext.actionsApi.openChangeOwnerDialog(entityId, entity.entityType, entity.name); });"
+}
+```
+
+### createMapEntityDialog (slot: `headerButton` on map)
+```json
+{
+  "type": "placeMapItem",
+  "id": "<fresh-uuid>",
+  "name": "<label>",
+  "icon": "add",
+  "mapItemType": "marker",
+  "mapItemTooltips": {},
+  "customFunction": "<rendered from entity-dialog.js with map_placement=true>",
+  "customHtml": "<rendered from entity-dialog.html>"
+}
+```
+
+**To render CRUD dialog templates**, read:
+- `@$TB_RESOURCES/templates/widget-action/entity-dialog.js`
+- `@$TB_RESOURCES/templates/widget-action/delete-entity-function.js`
+- `@$TB_RESOURCES/templates/widget-action/entity-dialog.html`
+
+Substitute the template variables (Thymeleaf syntax) with the values from the action spec.
+
+---
+
+## Icons
+
+All widget icon names must come from `@$TB_RESOURCES/prompts/solutions/dashboard/resources/icons.json`. Read the file once and pick the most semantically appropriate icon from the category that matches the widget's domain (e.g. "HVAC Control" for temperature, "Water Metering" for water sensors). Never invent icon names.
+
+---
+
+## Using `spec.entityProfiles` for widget keys
+
+Before configuring any widget's `dataKeys`, look up the key definition in `spec.entityProfiles`. Use the profile metadata to set the following fields correctly — never invent or guess values for keys that are defined in the profiles:
+
+| Profile field | Widget field | Notes |
+|---|---|---|
+| `telemetryType: "TIMESERIES"` | `type: "timeseries"` | |
+| `telemetryType: "ATTRIBUTE"` | `type: "attribute"` | |
+| `units` | `units` on dataKey and on config | Omit both when absent in profile |
+| `dataType: "double"` | `decimals: 1` | Default for floating-point |
+| `dataType: "integer"` | `decimals: 0` | |
+| `dataType: "enum"` | widget type: `stateChart` | Use `enumValues` to build the `states` array in settings |
+| `minValue` / `maxValue` | `minValue` / `maxValue` in gauge/progressBar settings | Omit when absent in profile |
+| `classifier: "indoorLocationX"` | `xKey` on indoorMap marker layer | Key name for horizontal position |
+| `classifier: "indoorLocationY"` | `yKey` on indoorMap marker layer | Key name for vertical position |
+| `classifier: "image"` | `imageSource.entityKey` on indoorMap | Key name for the floor plan attribute |
+
+Only include keys from `spec.entityProfiles` in datasources — do not add keys that are absent from the profiles.
+
+---
+
+## Permissions gating — when to emit CRUD actions and `allowRepositioning`
+
+The assigned user's permission level is `dashboardRole.permissions`: one of `CRUD`, `RU`, or `R`. Use it to gate which action slots a widget emits, and whether map markers/polygons/circles can be repositioned. **A viewer role must not see create/edit/delete buttons or be able to drag markers.**
+
+Create/edit/delete entity actions live on `entityTable` and map widgets only — do not wire `createEntityDialog` / `editEntityDialog` / `deleteEntityDialog` onto generic `actionButton` widgets or any other widget class. Each of `entityTable` and the map widgets independently gets its own CRUD actions when the role allows; one does not require the other on the same state. When both happen to share a state, each gets its full action set targeting the same entity type/profile.
+
+| Permission | `entityTable` action slots | Map widget marker actions | Map widget layer edit | Map widget `mapActionButtons` |
+|---|---|---|---|---|
+| `CRUD` | `rowClick` (drillDown), `headerButton` (createEntityDialog), `actionCellButton` (editEntityDialog + deleteEntityDialog) | `tagActions` drillDown in tooltip, plus marker tooltip actions for edit/delete where applicable | `allowRepositioning: true` with `edit.enabledActions: ["add", "move", "remove"]` on every marker/polygon/circle layer | `mapActionButtons: [<placeMapItem action body>]` |
+| `RU` | `rowClick` (drillDown), `actionCellButton` (editEntityDialog only — no create, no delete) | `tagActions` drillDown; no create/delete | `allowRepositioning: true` with `edit.enabledActions: ["add", "move", "remove"]` | omit |
+| `R` | `rowClick` (drillDown) only — omit `headerButton` and `actionCellButton` entirely | `tagActions` drillDown only — no edit/delete actions in marker tooltips | `allowRepositioning: false` (the field defaults to omitted/false) | omit |
+
+Apply this gate **per widget**, every time you generate one of these widget classes. If the rule says "omit," do not emit the slot at all — empty action arrays are also not allowed for slots the user can't access.
+
+`fitMapBounds` stays `true` for `R`; for `RU` and `CRUD` it follows the existing rule (`true` unless any layer has `allowRepositioning: true`).
+
+---
+
+## Widget Config Catalog
+
+**All fields shown in each widget config template are required.** Do not omit any field that appears in the template. The only exceptions are fields explicitly annotated as optional (e.g. `units`, `decimals`, `minValue`, `maxValue` — omit these only when the entity profile does not define them for the key).
+
+Every widget body follows this outer shape:
+
+```json
+{
+  "id": "<widgetUuid>",
+  "type": "<see table>",
+  "typeFullFqn": "<see table>",
+  "sizeX": N, "sizeY": N, "row": N, "col": N,
+  "config": { ... }
+}
+```
+
+| widgetClass | type | typeFullFqn |
+|---|---|---|
+| `actionButton` | `latest` | `system.action_button` |
+| `connectRealDevices` | `latest` | `system.action_button` |
+| `navigationWidget` | `latest` | `system.action_button` |
+| `headerCard` | `latest` | `system.cards.markdown_card` |
+| `infoCard` | `latest` | `system.cards.markdown_card` |
+| `stateSwitcher` | `latest` | `system.cards.markdown_card` |
+| `batteryLevel` | `latest` | `system.battery_level` |
+| `signalStrength` | `latest` | `system.signal_strength` |
+| `horizontalValueCard` | `latest` | `system.cards.horizontal_value_card` |
+| `simpleGauge` | `latest` | `system.digital_gauges.simple_gauge_justgage` |
+| `progressBar` | `latest` | `system.progress_bar` |
+| `pieChart` | `latest` | `system.horizontal_doughnut` |
+| `barChart` | `latest` | `system.bars` |
+| `entityTable` | `latest` | `system.cards.entities_table` |
+| `alarmTable` | `alarm` | `system.alarm_widgets.alarms_table` |
+| `alarmCount` | `latest` | `system.alarm_count` |
+| `indoorMap` | `latest` | `system.image_map` |
+| `outdoorMap` | `latest` | `system.map` |
+| `chart` | `timeseries` | `system.time_series_chart` |
+| `valueChartCard` | `timeseries` | `system.simple_value_and_chart_card` |
+| `rangeChart` | `timeseries` | `system.range_chart` |
+| `stateChart` | `timeseries` | `system.state_chart` |
+
+---
+
+### `connectRealDevices`
+
+No datasource. `url` defaults to `https://thingsboard.io/docs/user-guide/connectivity-guide/`
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "Connect Devices",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": {},
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": false,
+  "padding": "0px",
+  "backgroundColor": "#FFFFFF00",
+  "datasources": [],
+  "settings": {
+    "appearance": {
+      "type": "filled",
+      "showLabel": true,
+      "label": "How to connect real devices?",
+      "showIcon": true,
+      "icon": "help_outline",
+      "mainColor": "var(--tb-primary-500)",
+      "backgroundColor": "#FFFFFF",
+      "customStyle": {}
+    },
+    "activatedState": { "action": "DO_NOTHING", "defaultValue": false },
+    "disabledState":  { "action": "DO_NOTHING", "defaultValue": false }
+  },
+  "actions": {
+    "click": [{
+      "type": "openURL",
+      "id": "<fresh-uuid>",
+      "name": "Open Docs",
+      "icon": "help_outline",
+      "url": "<connectDevicesUrl>",
+      "openNewBrowserTab": true
+    }]
+  }
+}
+```
+
+---
+
+### `headerCard`
+
+Shows the selected entity's name (and optionally address) as a page title banner.
+`pattern` is a markdown string using `${entityName}` and optionally `${address}`.
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": {},
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": false,
+  "padding": "0px",
+  "backgroundColor": "#FFFFFF00",
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid of the stateEntity datasource>",
+    "dataKeys": [
+      { "name": "name", "label": "Name", "type": "entityField", "color": "var(--tb-primary-500)", "settings": {} }
+    ]
+  }],
+  "settings": {
+    "useMarkdownTextFunction": false,
+    "markdownTextPattern": "**${Name}**",
+    "applyDefaultMarkdownStyle": true,
+    "markdownCss": ".tb-markdown-view p { display: flex; margin: 0; align-items: center; height: 100%; font-size: 28px; font-weight: 500; color: #212121; padding: 0; }"
+  },
+  "actions": {}
+}
+```
+
+---
+
+### `infoCard`
+
+Multi-key labeled summary panel. `dataKeys` lists every key referenced in the rendered content (4–5 max).
+
+`infoCard` content has two mutually exclusive modes — `useMarkdownTextFunction` picks between them. Pick **pattern** by default; use **function** only when you need conditional formatting that pure substitution can't express.
+
+**Mode A — Markdown/HTML pattern** (`useMarkdownTextFunction: false`)
+
+`markdownTextPattern` is a string of markdown or HTML with `${...}` substitutions. Each placeholder resolves at render time:
+
+- `${entityName}` → the datasource entity's name (always available, no `dataKeys` entry needed).
+- `${<KeyLabel>}` or `${<keyName>}` → the latest value of a key listed in `dataKeys`. Match the `label` (or the `name` when label is omitted) exactly — placeholders that don't match a declared key render empty.
+- Use `\n\n` to separate paragraphs in markdown; use `<br/>` inside a paragraph.
+
+Example pattern: `"**Location**: ${location}\n\n**Model**: ${model}"`.
+
+**Mode B — Markdown/HTML value function** (`useMarkdownTextFunction: true`)
+
+`markdownTextFunction` is the **body** of a JS function with signature `(data, ctx) => string`. It must `return` a markdown or HTML string.
+
+- `data: FormattedData[]` — one entry per resolved datasource entity. Each entry exposes basic entity properties (`entityId`, `entityName`) plus every key declared in `dataKeys` (by both its `name` and its `label`, e.g. `data[0]['First name']` and `data[0].firstName` both work).
+- `ctx: WidgetContext` — the widget context, with access to dashboard state, timewindow, services, etc.
+
+Example function body: `"return '# Some title\\n - Entity name: ' + data[0]['entityName'];"`.
+
+Use a function over a pattern when you need branching (e.g. show a different label depending on a status value, or fall back to a second key when the first is empty).
+
+**Settings fields** (all four can appear in the same `settings` object; the inactive mode's field is ignored but doesn't have to be removed):
+
+```json
+"settings": {
+  "useMarkdownTextFunction": false,
+  "markdownTextPattern": "**Location**: ${location}\n\n**Model**: ${model}",
+  "markdownTextFunction": "return '# Some title\\n - Entity name: ' + data[0]['entityName'];",
+  "applyDefaultMarkdownStyle": true,
+  "markdownCss": ".m { color: red; }"
+}
+```
+
+- `applyDefaultMarkdownStyle: true` — applies the built-in markdown stylesheet (paragraph spacing, font sizes). Keep `true` unless `markdownCss` fully styles the content.
+- `markdownCss` — extra CSS rules layered on top. Selectors are scoped to the widget's markdown container. Omit (or empty string) when no custom styling is needed.
+
+Full widget body:
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": false,
+  "padding": "10px",
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid>",
+    "dataKeys": [
+      { "name": "<key>", "label": "<Label>", "type": "<entityField|attribute|timeseries>", "color": "#4caf50", "settings": {} }
+    ]
+  }],
+  "settings": {
+    "useMarkdownTextFunction": false,
+    "markdownTextPattern": "**<Label>**: ${<key>}\n\n**<Label2>**: ${<key2>}",
+    "applyDefaultMarkdownStyle": true
+  },
+  "actions": {}
+}
+```
+
+---
+
+### `navigationWidget`
+
+Tab button that switches the `subStateId` param. One per sibling state in a `switcherDetail`.
+`stateId` is the target sibling state id (e.g. `"sensor-overview"`).
+
+**The only widget allowed to switch sub-states inside a `switcherDetail`** — see the **State switching mechanism** section above. Sub-state changes from any other widget class are a hard error.
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "<Tab label, e.g. Overview>",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": {},
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": false,
+  "padding": "0px",
+  "backgroundColor": "#FFFFFF00",
+  "datasources": [],
+  "settings": {
+    "appearance": {
+      "type": "outlined",
+      "showLabel": true,
+      "label": "<Tab label>",
+      "showIcon": false,
+      "icon": "",
+      "mainColor": "var(--tb-primary-500)",
+      "backgroundColor": "#FFFFFF00",
+      "customStyle": {}
+    },
+    "activatedState": {
+      "action": "GET_DASHBOARD_STATE_OBJECT",
+      "defaultValue": false,
+      "dataToValue": {
+        "type": "FUNCTION",
+        "compareToValue": true,
+        "dataToValueFunction": "return data.params.subStateId === \"<stateId>\";"
+      }
+    },
+    "disabledState": { "action": "DO_NOTHING" }
+  },
+  "actions": {
+    "click": [{
+      "type": "custom",
+      "id": "<fresh-uuid>",
+      "name": "Navigate",
+      "icon": "edit",
+      "customFunction": "let params = widgetContext.stateController.getStateParams();\n\nparams.subStateId = \"<stateId>\";\n\nwidgetContext.stateController.updateState(widgetContext.stateController.getStateId(), params);\nwidgetContext.updateAliases();"
+    }]
+  }
+}
+```
+
+---
+
+### `stateSwitcher`
+
+Auto-injected in every `switcherDetail` state. Binds to the `stateEntity` alias and renders
+the currently active sub-state. `defaultSubStateId` is the `stateId` of the first `navigationWidget`.
+Position: `{ "row": 1, "col": 0, "sizeX": 24, "sizeY": 14 }`.
+
+**Passive container — it never carries state-switching actions.** Its content updates because `subStateId` changed (driven by a sibling `navigationWidget`), not because anything was clicked on the container itself. `config.actions` MUST be `{}`. See the **State switching mechanism** section above.
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": {},
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": false,
+  "padding": "0px",
+  "backgroundColor": "#FFFFFF00",
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid of stateEntity>",
+    "dataKeys": [
+      { "name": "name", "label": "Name", "type": "entityField", "color": "var(--tb-primary-500)", "settings": {} }
+    ]
+  }],
+  "settings": {
+    "useMarkdownTextFunction": true,
+    "markdownTextFunction": "let subState = ctx.stateController.getStateParams().subStateId || \"<defaultSubStateId>\";\n\nreturn `<div tb-toast toastTarget=\"layout\" class=\"block\">\n            <tb-dashboard-state class=\"state\" [ctx]=\"ctx\" stateId=\"${subState}\" [syncParentStateParams]=\"true\"></tb-dashboard-state>\n        </div>`;",
+    "applyDefaultMarkdownStyle": true,
+    "markdownCss": ".block {\n    flex-grow: 1;\n    width: 100%;\n    height: 100%;\n    display: flex;\n    padding: 0;\n}\n\n.state {\n    flex-grow: 1;\n    padding: 0;\n    width: 100%;\n    height: 100%;\n}"
+  },
+  "actions": {}
+}
+```
+
+---
+
+### `actionButton`
+
+Trigger button for CRUD dialogs. All actions go to the `click` slot.
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "<label>",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": {},
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": false,
+  "padding": "0px",
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid>",
+    "dataKeys": [{ "name": "name", "label": "Name", "type": "entityField", "color": "var(--tb-primary-500)", "settings": {}}]
+  }],
+  "settings": {
+    "appearance": {
+      "type": "filled",
+      "showLabel": false,
+      "label": "<label>",
+      "showIcon": true,
+      "icon": "settings",
+      "mainColor": "var(--tb-primary-500)",
+      "backgroundColor": "#FFFFFF",
+      "customStyle": {}
+    },
+    "activatedState": { "action": "DO_NOTHING", "defaultValue": false },
+    "disabledState":  { "action": "DO_NOTHING", "defaultValue": false }
+  },
+  "actions": {
+    "click": [ <action body> ]
+  }
+}
+```
+
+---
+
+### `horizontalValueCard`
+
+Latest value strip card. `keyType` is `"timeseries"`, `"attribute"`, or `"entityField"`.
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "<metric label>",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": false,
+  "padding": "0px",
+  "margin": "0px",
+  "units": "<°C>",
+  "decimals": 1,
+  "widgetCss": "tb-icon { display: inline-flex; justify-content: center; align-items: center; border-radius: 50%; width: 40px!important; height: 40px!important; background-color: var(--tb-primary-50); }\n.tb-value-card-icon-row { width: 50%; justify-content: space-between; }",
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid>",
+    "dataKeys": [{
+      "name": "<key>",
+      "label": "<metric label>",
+      "type": "<timeseries|attribute|entityField>",
+      "color": "var(--tb-primary-500)",
+      "units": "<°C>",
+      "decimals": 1,
+      "settings": {}
+    }]
+  }],
+  "settings": {
+    "layout": "horizontal",
+    "showLabel": true,
+    "labelColor": { "type": "constant", "color": "#000000DE" },
+    "showIcon": true,
+    "icon": "<material-icon-name, e.g. thermostat>",
+    "iconColor": { "type": "constant", "color": "var(--tb-primary-500)" },
+    "iconSize": 24,
+    "iconSizeUnit": "px",
+    "valueColor": { "type": "constant", "color": "#000000DE" },
+    "valueFont": { "size": 30 },
+    "labelFont": { "size": 20 },
+    "showDate": false,
+    "autoScale": true
+  },
+  "actions": {}
+}
+```
+
+Omit `units` and `decimals` from config and dataKey when they are not applicable.
+
+---
+
+### `batteryLevel`
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "Battery",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "titleFont": { "size": 21, "sizeUnit": "px", "weight": "500", "lineHeight": "22px" },
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": false,
+  "units": "%",
+  "decimals": 0,
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid>",
+    "dataKeys": [{
+      "name": "<batteryLevel>",
+      "label": "<Battery Level>",
+      "type": "timeseries",
+      "color": "var(--tb-primary-500)",
+      "settings": {}
+    }]
+  }],
+  "settings": {
+    "layout": "horizontal_solid",
+    "batteryLevelColor": {
+      "type": "range",
+      "color": "rgb(224, 224, 224)",
+      "rangeList": {
+        "advancedMode": false,
+        "range": [
+          { "from": null, "to": 25,   "color": "rgba(227, 71, 71, 1)" },
+          { "from": 25,   "to": 50,   "color": "rgba(246, 206, 67, 1)" },
+          { "from": 50,   "to": null, "color": "rgba(92, 223, 144, 1)" }
+        ]
+      }
+    },
+    "batteryShapeColor": {
+      "type": "range",
+      "color": "rgba(224, 224, 224, 0.32)",
+      "rangeList": {
+        "advancedMode": false,
+        "range": [
+          { "from": null, "to": 25,   "color": "rgba(227, 71, 71, 0.32)" },
+          { "from": 25,   "to": 50,   "color": "rgba(246, 206, 67, 0.32)" },
+          { "from": 50,   "to": null, "color": "rgba(92, 223, 144, 0.32)" }
+        ]
+      }
+    }
+  },
+  "actions": {}
+}
+```
+
+---
+
+### `signalStrength`
+
+`layout` is `"wifi"` for WiFi/Bluetooth or `"cellular"` for mobile.
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "<Signal Strength>",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "titleFont": { "size": 21, "sizeUnit": "px", "weight": "500", "lineHeight": "22px" },
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": true,
+  "units": "dBm",
+  "decimals": 0,
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid>",
+    "dataKeys": [{
+      "name": "<rssi>",
+      "label": "<RSSI>",
+      "type": "timeseries",
+      "color": "var(--tb-primary-500)",
+      "settings": {}
+    }]
+  }],
+  "settings": { "layout": "wifi" },
+  "actions": {}
+}
+```
+
+---
+
+### `simpleGauge`
+
+`gaugeType` is `"donut"`, `"arc"`, `"horizontalBar"`, or `"verticalBar"`.
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "<metric label>",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "titleFont": { "size": 21, "sizeUnit": "px", "weight": "500", "lineHeight": "22px" },
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": false,
+  "units": "<°C>",
+  "decimals": 1,
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid>",
+    "dataKeys": [{
+      "name": "<temperature>",
+      "label": "<Temperature>",
+      "type": "timeseries",
+      "color": "#000000DE",
+      "settings": {}
+    }]
+  }],
+  "settings": {
+    "minValue": 0,
+    "maxValue": 100,
+    "gaugeType": "donut",
+    "showTitle": true,
+    "title": "<metric label>",
+    "titleFont": { "color": "#000000DE" },
+    "labelFont": {},
+    "valueFont": {},
+    "minMaxFont": {},
+    "showMinMax": false,
+    "showValue": true
+  },
+  "actions": {}
+}
+```
+
+Omit `minValue`/`maxValue` from settings when the metric has no fixed bounds.
+
+---
+
+### `progressBar`
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "<metric label>",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "titleFont": { "size": 21, "sizeUnit": "px", "weight": "500", "lineHeight": "22px" },
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": true,
+  "titleColor": "#000000DE",
+  "units": "%",
+  "decimals": 0,
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid>",
+    "dataKeys": [{
+      "name": "<fillLevel>",
+      "label": "<Fill Level>",
+      "type": "timeseries",
+      "color": "var(--tb-primary-500)",
+      "settings": {}
+    }]
+  }],
+  "settings": {
+    "layout": "simplified",
+    "tickMin": 0,
+    "tickMax": 100,
+    "autoScale": true,
+    "showTicks": false
+  },
+  "actions": {}
+}
+```
+
+---
+
+### `valueChartCard`
+
+Latest value + sparkline trend. Datasource has both `dataKeys` and `latestDataKeys` pointing to the same key.
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "<metric label>",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "titleFont": { "size": 21, "sizeUnit": "px", "weight": "500", "lineHeight": "22px" },
+  "useDashboardTimewindow": true,
+  "timewindow": {
+    "selectedTab": 1,
+    "history": { "historyType": 0, "timewindowMs": 604800000 },
+    "aggregation": { "type": "NONE" }
+  },
+  "showTitle": true,
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "units": "<°C>",
+  "decimals": 1,
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid>",
+    "dataKeys": [{
+      "name": "<temperature>",
+      "label": "<Temperature>",
+      "type": "timeseries",
+      "color": "var(--tb-primary-500)",
+      "settings": {}
+    }],
+    "latestDataKeys": [{
+      "name": "<temperature>",
+      "label": "<Temperature>",
+      "type": "timeseries",
+      "color": "var(--tb-primary-500)",
+      "settings": {}
+    }]
+  }],
+  "settings": {},
+  "actions": {}
+}
+```
+
+---
+
+### `chart` (time-series line chart)
+
+Each series entry has `name` (key), `label`, `type: "timeseries"`, `color`, `settings: {"yAxis": "default"}`.
+`yAxes` has one entry per axis; the default axis id is `"default"`.
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "<chart title>",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "titleFont": { "size": 21, "sizeUnit": "px", "weight": "500", "lineHeight": "22px" },
+  "useDashboardTimewindow": true,
+  "timewindow": {
+    "selectedTab": 1,
+    "history": { "historyType": 0, "timewindowMs": 604800000 },
+    "aggregation": { "type": "NONE" }
+  },
+  "showTitle": true,
+  "enableFullscreen": true,
+  "enableDataExport": true,
+  "padding": "0px",
+  "margin": "0px",
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid>",
+    "dataKeys": [
+      { "name": "<temperature>", "label": "<Temperature>", "type": "timeseries", "color": "var(--tb-primary-500)", "settings": { "yAxis": "default" }, "units": "°C", "decimals": 1 },
+      { "name": "<humidity>",    "label": "<Humidity>",    "type": "timeseries", "color": "#4CAF50",              "settings": { "yAxis": "default" }, "units": "%",  "decimals": 0 }
+    ]
+  }],
+  "settings": {
+    "dataZoom": false,
+    "showLegend": false,
+    "legendConfig": { "position": "top", "sortDataKeys": false, "showMin": false, "showMax": false, "showAvg": true, "showTotal": false, "showLatest": false },
+    "xAxis": { "show": true, "position": "bottom" },
+    "yAxis": { "show": true, "position": "left" },
+    "yAxes": {
+      "default": { "id": "default", "label": "<Temperature>", "position": "left", "units": "°C", "decimals": 1, "order": 0 }
+    }
+  }
+}
+```
+
+---
+
+### `rangeChart` (time-series with color bands)
+
+Same structure as `chart` but adds `rangeColors` in settings. Each range entry: `{ "from": N|null, "to": N|null, "color": "<hex>" }`.
+
+```json
+"config": {
+  ...same as chart up to settings...,
+  "settings": {
+    "dataZoom": false,
+    "showLegend": false,
+    "legendConfig": { "position": "top", "sortDataKeys": false, "showMin": false, "showMax": false, "showAvg": true, "showTotal": false, "showLatest": false },
+    "xAxis": { "show": true, "position": "bottom" },
+    "yAxis": { "show": true, "position": "left" },
+    "yAxes": {
+      "default": { "id": "default", "label": "<Temperature>", "position": "left", "units": "°C", "decimals": 1, "order": 0 }
+    },
+    "rangeColors": [
+      { "from": null, "to": 18,  "color": "#2196F3" },
+      { "from": 18,   "to": 26,  "color": "#4CAF50" },
+      { "from": 26,   "to": null,"color": "#F44336" }
+    ]
+  }
+}
+```
+
+---
+
+### `stateChart` (discrete state bands)
+
+`states` array maps values to colored labels. Use `constValue` for the raw key value (boolean, string, or number).
+
+```json
+"config": {
+  ...same outer config as chart (useDashboardTimewindow, timewindow, enableFullscreen)...,
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid>",
+    "dataKeys": [
+      { "name": "<active>", "label": "<Status>", "type": "timeseries", "color": "var(--tb-primary-500)", "settings": { "yAxis": "default" } }
+    ]
+  }],
+  "settings": {
+    "dataZoom": false,
+    "showLegend": false,
+    "legendConfig": { "position": "top", "sortDataKeys": false, "showMin": false, "showMax": false, "showAvg": true, "showTotal": false, "showLatest": false },
+    "xAxis": { "show": true, "position": "bottom" },
+    "yAxis": { "show": true, "position": "left" },
+    "yAxes": {
+      "default": { "id": "default", "label": "<Status>", "position": "left", "units": "", "decimals": 1, "order": 0 }
+    },
+    "states": [
+      { "value": true,  "label": "Online",  "color": "rgba(92, 223, 144, 1)" },
+      { "value": false, "label": "Offline", "color": "rgba(227, 71, 71, 1)" }
+    ]
+  }
+}
+```
+
+---
+
+### `barChart` (latest values, multiple entities, one key)
+
+`dataKeys` has exactly one entry with `type: "timeseries"`.
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "<chart title>",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "titleFont": { "size": 21, "sizeUnit": "px", "weight": "500", "lineHeight": "22px" },
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": true,
+  "padding": "0px",
+  "margin": "0px",
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid — must be multi-entity alias (assetType, deviceType, etc.)>",
+    "dataKeys": [{
+      "name": "<revenue>",
+      "label": "${entityName}",
+      "type": "timeseries",
+      "color": "var(--tb-primary-500)",
+      "settings": {}
+    }]
+  }],
+  "settings": {
+    "dataZoom": false,
+    "showLegend": false,
+    "xAxis": { "show": true, "position": "bottom" },
+    "yAxis": { "show": true, "position": "left" },
+    "yAxes": {},
+    "layout": "with_total"
+  },
+  "actions": {}
+}
+```
+
+---
+
+### `pieChart` (proportional distribution)
+
+Two patterns — never mix them:
+- **Single entity, multiple keys**: one datasource, multiple entries in `dataKeys`. Each slice = one key on the same entity. The key's `label` is the slice label.
+- **Multiple entities, one key**: one multi-entity datasource (`assetType`, `deviceType`, `assetSearchQuery`, `deviceSearchQuery`, etc.), one entry in `dataKeys`. Each slice = one entity contributing its value for that key. The dataKey's `label` **must be `"${entityName}"`** — the placeholder is resolved per-entity at render time, so each slice is labeled with that entity's name. Hard-coding a single string here would give every slice the same label.
+
+`dataKeys` entries have `type: "timeseries"` and `settings: {"yAxis": "<axisId>"}`.
+
+**Pattern 1 — Single entity, multiple keys** (e.g. one coffee machine's daily brew breakdown):
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "<chart title>",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "titleFont": { "size": 21, "sizeUnit": "px", "weight": "500", "lineHeight": "22px" },
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": true,
+  "padding": "0px",
+  "margin": "0px",
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid>",
+    "dataKeys": [
+      { "name": "<countOfAmericano>", "label": "<Americano>", "type": "timeseries", "color": "var(--tb-primary-500)", "settings": { "yAxis": "default" } },
+      { "name": "<countOfEspresso>",  "label": "<Espresso>",  "type": "timeseries", "color": "#4CAF50",              "settings": { "yAxis": "default" } }
+    ]
+  }],
+  "settings": {
+    "dataZoom": false,
+    "showLegend": true,
+    "legendConfig": { "position": "top", "sortDataKeys": false, "showMin": false, "showMax": false, "showAvg": true, "showTotal": false, "showLatest": false },
+    "xAxis": { "show": true, "position": "bottom" },
+    "yAxis": { "show": true, "position": "left" },
+    "yAxes": {
+      "default": { "id": "default", "label": "<Count>", "position": "left", "units": "", "decimals": 0, "order": 0 }
+    },
+    "layout": "with_total"
+  },
+  "actions": {}
+}
+```
+
+**Pattern 2 — Multiple entities, one key** (e.g. share of total daily revenue per shop). Use `${entityName}` as the `label` so each slice is labeled with the contributing entity's name:
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "<chart title, e.g. Revenue Share by Shop>",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "titleFont": { "size": 21, "sizeUnit": "px", "weight": "500", "lineHeight": "22px" },
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": true,
+  "padding": "0px",
+  "margin": "0px",
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid — must be a multi-entity alias (assetType, deviceType, assetSearchQuery, …)>",
+    "dataKeys": [
+      { "name": "<dailyRevenue>", "label": "${entityName}", "type": "timeseries", "color": "var(--tb-primary-500)", "settings": { "yAxis": "default" }, "units": "$", "decimals": 0 }
+    ]
+  }],
+  "settings": {
+    "dataZoom": false,
+    "showLegend": true,
+    "legendConfig": { "position": "top", "sortDataKeys": false, "showMin": false, "showMax": false, "showAvg": true, "showTotal": false, "showLatest": false },
+    "xAxis": { "show": true, "position": "bottom" },
+    "yAxis": { "show": true, "position": "left" },
+    "yAxes": {
+      "default": { "id": "default", "label": "<Revenue>", "position": "left", "units": "$", "decimals": 0, "order": 0 }
+    },
+    "layout": "with_total"
+  },
+  "actions": {}
+}
+```
+
+---
+
+### `entityTable`
+
+`dataKeys` columns: `type` is `"entityField"`, `"attribute"`, or `"timeseries"`.
+`config.actions` slots: `rowClick` for `drillDown`, `headerButton` for create, `actionCellButton` for edit/delete.
+
+**Customer rows — `name` is `title`, not `"name"`:**
+
+```json
+{ "label": "Customer", "name": "title", "type": "entityField" }
+```
+
+A CUSTOMER row column with `"name": "name"` renders blank — `title` is the customer's display field.
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "<table title>",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "titleFont": { "size": 21, "sizeUnit": "px", "weight": "500", "lineHeight": "22px" },
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": true,
+  "padding": "4px",
+  "datasources": [{
+    "type": "entity",
+    "entityAliasId": "<aliasUuid>",
+    "dataKeys": [
+      { "name": "name",        "label": "Name",        "type": "entityField", "color": "var(--tb-primary-500)", "settings": {} },
+      { "name": "<address>",   "label": "Address",     "type": "attribute",   "color": "var(--tb-primary-500)", "settings": {} },
+      { "name": "<occupancy>", "label": "Occupancy",   "type": "timeseries",  "color": "var(--tb-primary-500)", "settings": {}, "units": "%", "decimals": 0 }
+    ]
+  }],
+  "settings": {
+    "entitiesTitle": "<table title>",
+    "displayEntityName": false,
+    "displayEntityType": false
+  },
+  "actions": {
+    "rowClick":         [ <drillDown action body> ],
+    "headerButton":     [ <createEntityDialog action body> ],
+    "actionCellButton": [ <editEntityDialog body>, <deleteEntityDialog body> ]
+  }
+}
+```
+
+Only include slots that have actions. Empty slot arrays can be omitted.
+
+**Customer datasources — display-name column.** When the datasource alias resolves to `CUSTOMER` entities (e.g. `customersByGroupName`), the entity-display column **must** use `{ "name": "title", "label": "Name", "type": "entityField" }` — customers store their display name in `title`, not `name`. Emitting `"name": "name"` produces an empty column. The same rule applies to any widget that surfaces a customer's display name through an `entityField` key — `headerCard`, `infoCard`, `actionButton`, `stateSwitcher`, etc.
+
+Column `settings` for styled cells (e.g. status badge):
+```json
+"settings": {
+  "useCellContentFunction": true,
+  "useCellContentFunctionOnExport": true,
+  "cellContentFunction": "let color = '#757575'; let backColor = '#F5F5F5'; let text = 'Inactive'; if (value == 'true') { text = 'Active'; color = '#E8EAF6'; backColor = '#303F9F'; } return `<span style=\"font-size:14px;color:${color};background:${backColor};padding:8px;border-radius:6px;\">${text}</span>`;"
+}
+```
+
+---
+
+### `alarmTable`
+
+Fixed 5-column alarm data structure. Alarm source uses `alarmSource` (not `datasources`).
+`config.actions` same slots as entityTable.
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "Alarms",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "titleFont": { "size": 21, "sizeUnit": "px", "weight": "500", "lineHeight": "22px" },
+  "useDashboardTimewindow": true,
+  "timewindow": {
+    "selectedTab": 1,
+    "history": { "historyType": 0, "timewindowMs": 604800000 },
+    "aggregation": { "type": "NONE" }
+  },
+  "enableFullscreen": true,
+  "enableDataExport": true,
+  "showTitle": true,
+  "padding": "4px",
+  "datasources": [],
+  "alarmSource": {
+    "type": "entity",
+    "name": "alarms",
+    "entityAliasId": "<aliasUuid>",
+    "dataKeys": [
+      { "name": "createdTime",   "label": "Created Time", "type": "alarm", "color": "var(--tb-primary-500)", "settings": {} },
+      { "name": "originator",    "label": "Originator",   "type": "alarm", "color": "var(--tb-primary-500)", "settings": {} },
+      { "name": "type",     "label": "Type",         "type": "alarm", "color": "var(--tb-primary-500)", "settings": {} },
+      { "name": "severity", "label": "Severity",     "type": "alarm", "color": "var(--tb-primary-500)", "settings": {} },
+      { "name": "status",   "label": "Status",       "type": "alarm", "color": "var(--tb-primary-500)", "settings": {} }
+    ]
+  },
+  "alarmFilterConfig": {
+    "statusList": ["ACTIVE"],
+    "severityList": ["CRITICAL", "MAJOR", "MINOR", "WARNING", "INDETERMINATE"],
+    "typeList": [],
+    "searchPropagatedAlarms": true
+  },
+  "settings": {
+    "alarmsTitle": "Alarms",
+    "enableSelection": true,
+    "enableSearch": true
+  },
+  "actions": {}
+}
+```
+
+---
+
+### `alarmCount`
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "<Total Alarms>",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "titleFont": { "size": 21, "sizeUnit": "px", "weight": "500", "lineHeight": "22px" },
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": false,
+  "datasources": [{
+    "type": "alarmCount",
+    "entityAliasId": "<aliasUuid>",
+    "dataKeys": [{ "name": "count", "label": "count", "type": "count", "settings": {} }],
+    "alarmFilterConfig": {
+      "statusList": ["ACTIVE"],
+      "severityList": ["CRITICAL", "MAJOR", "MINOR", "WARNING", "INDETERMINATE"],
+      "typeList": [],
+      "searchPropagatedAlarms": true
+    }
+  }],
+  "settings": {
+    "label": "<Total Alarms>",
+    "showLabel": true,
+    "layout": "column",
+    "showIcon": true,
+    "icon": "warning",
+    "iconSize": 20,
+    "iconSizeUnit": "px",
+    "showIconBackground": true,
+    "iconBackgroundSize": 36,
+    "iconBackgroundSizeUnit": "px",
+    "iconBackgroundColor": {
+      "type": "range",
+      "color": "rgba(0, 105, 92, 1)",
+      "rangeList": {
+        "advancedMode": false,
+        "range": [
+          { "from": 0, "to": 1, "color": "rgba(0, 105, 92, 1)" },
+          { "from": 1, "to": null, "color": "rgba(209, 39, 48, 1)" }
+        ]
+      }
+    }
+  }
+}
+```
+
+---
+
+### `outdoorMap`
+
+Each layer in `markers`, `polygons`, `circles` is built per the rules below.
+`fitMapBounds` is `true` unless any layer has `allowRepositioning: true`.
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "titleFont": { "size": 21, "sizeUnit": "px", "weight": "500", "lineHeight": "22px" },
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": false,
+  "padding": "0px",
+  "margin": "0px",
+  "datasources": [],
+  "settings": {
+    "mapType": "geoMap",
+    "layers": [
+      { "label": "{i18n:widgets.maps.layer.roadmap}",  "provider": "openstreet", "layerType": "Esri.WorldStreetMap", "referenceLayer": null },
+      { "label": "{i18n:widgets.maps.layer.satellite}", "provider": "openstreet", "layerType": "Esri.WorldImagery" },
+      { "label": "{i18n:widgets.maps.layer.hybrid}",   "provider": "openstreet", "layerType": "Esri.WorldImagery", "referenceLayer": "openstreetmap_hybrid" }
+    ],
+    "markers": [ <marker layer> ],
+    "polygons": [ <polygon layer> ],
+    "circles":  [],
+    "fitMapBounds": true,
+    "mapActionButtons": [<placeMapItem action body>]
+  },
+  "actions": {}
+}
+```
+
+**Marker layer** (outdoor, `latitude`/`longitude` keys):
+```json
+{
+  "dsType": "entity",
+  "dsEntityAliasId": "<aliasUuid>",
+  "xKey": { "name": "latitude",  "label": "Latitude",  "type": "attribute", "color": "var(--tb-primary-500)", "settings": {} },
+  "yKey": { "name": "longitude", "label": "Longitude", "type": "attribute", "color": "var(--tb-primary-500)", "settings": {} },
+  "additionalDataKeys": [
+    { "name": "<name>", "label": "Name", "type": "entityField", "color": "var(--tb-primary-500)", "settings": {} }
+  ],
+  "markerType": "icon",
+  "markerIcon": { "icon": "location_on", "color": { "type": "constant", "color": "#2196F3" } },
+  "tooltip": {
+    "show": true,
+    "trigger": "click",
+    "type": "pattern",
+    "pattern": "<b>${entityName}</b><br/><b>Status:</b> ${Status}<br/><link-act name='view-details'>View details</link-act>",
+    "tagActions": [ <drillDown action body with name='view-details'> ]
+  },
+  "label": { "show": true, "type": "pattern", "pattern": "${entityName}" }
+}
+```
+
+**Tooltip pattern — never wire drill-down to the marker click itself.** Open a tooltip on click, then let the user follow a `<link-act>` link inside it to navigate. This lets the user read the entity's key values before deciding to drill down.
+
+- `trigger: "click"` and `type: "pattern"` are always set as above.
+- `pattern` is HTML (`<b>`, `<br/>` — not `\n`). Include the entity name and 1–3 of the most relevant keys (status, latest reading, occupancy, etc.) using `${KeyLabel}` substitutions. Every `${...}` placeholder must reference a key declared in `xKey`, `yKey`, or `additionalDataKeys` on the **same layer** — otherwise it renders empty. Pick the keys from `spec.entityProfiles` and add them to `additionalDataKeys` if not already there.
+- End with one `<link-act name='<actionName>'>Label</link-act>` link. The `name` attribute **must match** the `name` field on the corresponding `tagActions` entry — that's how the click is routed.
+- `tagActions` holds one drillDown action body per link in the pattern; set its `name` to the same string used inside `<link-act name='...'>`.
+
+When `allowRepositioning` is true, add:
+```json
+"edit": { "enabledActions": ["add", "move", "remove"] }
+```
+
+**Marker icon** (`markerIcon` on any marker layer — shared by `outdoorMap` and `indoorMap`):
+
+`icon` is a material-icon name from `icons.json`. `color` has two valid shapes — pick based on whether the marker color depends on live data:
+
+1. **`constant`** — every marker on the layer uses the same color. Use this when there is no status/state key to drive coloring (e.g. a generic "device" pin).
+
+   ```json
+   "markerIcon": {
+     "icon": "bolt",
+     "color": { "type": "constant", "color": "#2196F3" }
+   }
+   ```
+
+2. **`function`** — per-entity color computed at render time from that marker's live data. Use this when the entity has a status/state key whose value should change the pin color (open/closed, online/offline, severity tier, etc.).
+
+   - `colorFunction` is a JS expression that **must return a hex color string**.
+   - Reference live keys via `data.<KeyName>` (the key must be one of `xKey`, `yKey`, or an `additionalDataKeys` entry on the same layer — otherwise the value is undefined at evaluation time).
+   - Always end with a default `return` so a marker with a missing/unexpected value still gets a fallback color.
+
+   ```json
+   "markerIcon": {
+     "icon": "electric_meter",
+     "color": {
+       "type": "function",
+       "colorFunction": "if (data.Status === 'closed') { return '#4CAF50'; } else if (data.Status === 'tripped') { return '#F44336'; } else if (data.Status === 'open') { return '#FF9800'; } return '#757575';"
+     }
+   }
+   ```
+
+Never mix the two shapes — `constant` has `color: "<hex>"`, `function` has `colorFunction: "<js>"`. Picking the wrong shape silently disables the other field.
+
+**Polygon layer** (perimeter attribute):
+```json
+{
+  "dsType": "entity",
+  "dsEntityAliasId": "<aliasUuid>",
+  "polygonKey": { "name": "perimeter", "label": "Perimeter", "type": "attribute", "color": "var(--tb-primary-500)", "settings": {} },
+  "additionalDataKeys": [
+    { "name": "<name>", "label": "Name", "type": "entityField", "color": "var(--tb-primary-500)", "settings": {} }
+  ],
+  "fillType": "color",
+  "strokeWeight": 3,
+  "tooltip": {
+    "show": true,
+    "trigger": "click",
+    "type": "pattern",
+    "pattern": "<b>${entityName}</b><br/><link-act name='view-details'>View details</link-act>",
+    "tagActions": [ <drillDown action body with name='view-details'> ]
+  }
+}
+```
+
+The same tooltip pattern rule from the marker layer applies — open the tooltip on click, embed a `<link-act>` link, and put the drillDown action body in `tagActions` with a matching `name`. The same convention applies to circle layers (when present).
+
+---
+
+### `indoorMap`
+
+`aliasUuid` is the child entity alias (used for markers). `imageSourceAliasUuid` is the parent entity alias (used for the floor plan image source). Both must be present in the state spec for indoorMap widgets.
+
+**Floor plan image source:** Check `spec.entityProfiles` for a key with `classifier: "image"` on the parent entity profile. If found, use that key name in `imageSource.entityKey`. If no such classifier exists in any profile but positioning keys (`classifier: "indoorLocationX"` / `classifier: "indoorLocationY"`) are present, read `@$TB_RESOURCES/prompts/solutions/dashboard/resources/images.json` and pick the entry whose `type` best matches the solution domain. Use `fileName` as the static image reference in `imageSource`.
+
+Same structure as `outdoorMap` but uses `xKey`/`yKey` from `xPos`/`yPos` attributes, and `settings.mapType: "image"` with an `imageSource`.
+
+```json
+"config": {
+  "configMode": "basic",
+  "title": "",
+  "dropShadow": false,
+  "borderRadius": "8px",
+  "widgetStyle": { "box-shadow": "0px 2px 4px 0px #00000024;" },
+  "titleFont": { "size": 21, "sizeUnit": "px", "weight": "500", "lineHeight": "22px" },
+  "enableFullscreen": false,
+  "enableDataExport": false,
+  "showTitle": false,
+  "padding": "0px",
+  "margin": "0px",
+  "datasources": [],
+  "settings": {
+    "imageSource": {
+      "entityAliasId": "<aliasUuid of parent entity that has the floor plan image attribute>",
+      "sourceType": "entityKey",
+      "entityKey": { "name": "<floorPlan>", "label": "Floor Plan", "type": "attribute", "color": "var(--tb-primary-500)", "settings": {} }
+    },
+    "mapType": "image",
+    "markers": [{
+      "dsType": "entity",
+      "dsEntityAliasId": "<aliasUuid of child entities>",
+      "xKey": { "name": "xPos", "label": "X", "type": "attribute", "color": "var(--tb-primary-500)", "settings": {} },
+      "yKey": { "name": "yPos", "label": "Y", "type": "attribute", "color": "var(--tb-primary-500)", "settings": {} },
+      "markerType": "icon",
+      "markerIcon": { "icon": "sensors", "color": { "type": "constant", "color": "#2196F3" } },
+      "tooltip": {
+        "show": true,
+        "trigger": "click",
+        "type": "pattern",
+        "pattern": "<b>${entityName}</b><br/><b>Status:</b> ${Status}<br/><link-act name='view-details'>View details</link-act>",
+        "tagActions": [ <drillDown action body with name='view-details'> ]
+      }
+    }],
+    "polygons": [],
+    "circles": [],
+    "fitMapBounds": true,
+    "mapActionButtons": [<placeMapItem action body>]
+  },
+  "actions": {}
+}
+```
+
+If no parent-entity floor plan exists, omit `imageSource` entirely (the map renders as blank until a static image is configured in the UI).
+
+---
+
+## State Assembly
+
+### State body
+
+```json
+"<stateId>": {
+  "id": "<stateId>",
+  "name": "<Human State Name>",
+  "root": <true for the state with id "root", false for all others>,
+  "layouts": {
+    "main": {
+      "widgets": {
+        "<widgetUuid>": { "sizeX": N, "sizeY": N, "row": N, "col": N }
+      },
+      "gridSettings": {
+        "layoutType": "default",
+        "backgroundColor": "#EEEEEE",
+        "columns": "24",
+        "margin": 10,
+        "outerMargin": true,
+        "backgroundSizeMode": "100%",
+        "marginBetweenWidgets": "10",
+        "applyMarginToSides": "true",
+        "autoFillHeight": "true",
+        "mobileAutoFillHeight": "false",
+        "mobileRowHeight": "70"
+      }
+    }
+  }
+}
+```
+
+**`switcherDetail` states only:** set `autoFillHeight: "false"` and include only the header-row widgets
+(headerCard, navigationWidget, connectRealDevices, actionButton) plus the auto-generated `stateSwitcher`
+widget at `{ row: 1, col: 0, sizeX: 24, sizeY: 14 }`.
+
+**Position invariant:** every widget UUID in `states[sid].layouts.main.widgets` must appear
+in the top-level `widgets` map. The `sizeX`, `sizeY`, `row`, `col` values must be **identical**
+in both places.
+
+---
+
+## Critical invariants — verify before returning
+
+These invariants apply per-state and can be verified from the assembled state output:
+
+1. **Widget ↔ state sync** — every UUID in `stateLayout.<stateId>.layouts.main.widgets` is in the top-level `widgets` map.
+2. **Alias cross-references** — every `entityAliasId` inside widget datasources is a key in the state's `entityAliases` map.
+3. **switcherDetail** — contains only: `headerCard`, `navigationWidget`, `connectRealDevices`, ≤1 `actionButton`, and the auto-injected `stateSwitcher`.
+4. **statistics** — contains only chart widgets (`chart`, `rangeChart`, `stateChart`, `valueChartCard`, `pieChart`).
+5. **overview** — no `headerCard`, no `navigationWidget`, no `actionButton`, no chart widgets (`chart`, `rangeChart`, `stateChart`, `pieChart`).
+6. **typeFullFqn** — must match the table in the Widget Config Catalog exactly; never invent values.
+7. **alarmTable datasource** — alarm data goes into `alarmSource`, not `datasources`. `datasources` must be `[]`.
+8. **alarmCount datasource** — uses `"type": "alarmCount"` (not `"entity"`) with `dataKeys: [{name:"count", type:"count"}]`.
+
+UUID uniqueness, action target state existence, and row coverage are verified by the post-assembly checks in Step 5.