thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/resources/prompts/solutions/dashboard/resources/states/dashboard-states-capabilities.md

@@ -0,0 +1,702 @@
+# Dashboard States Knowledge Base
+
+This document describes ThingsBoard dashboard states and widget patterns used when decomposing dashboard use cases into concrete states and widgets.
+
+## Dashboard Structure
+
+A dashboard is composed of one or more **states**. Each state represents a distinct view the user can navigate to. Each state contains one or more **widgets** that display data and enable interactions.
+
+**CRITICAL: Exactly one state MUST have `id: "root"` and it MUST be the first element in the `states` array — this is the entry point displayed when the dashboard first opens.** Root is not a state type; it is a designation. Its purpose is determined by `demoRequirements` and the use cases together.
+
+**Use `demoRequirements` to determine the root state:**
+
+`demoRequirements` is a natural language string describing how many entities exist in this deployment (e.g., `"For demo: 1 CoffeeMachine"` or `"For demo: 3 ParkingCompanies, each with 5 ParkingLots"`). Use it as the primary signal:
+
+- **Customer entities** — always use a collection state as the root, regardless of quantity. Even `"1 ParkingCompany"` requires a collection state because customers represent independent accounts that can grow over time.
+- **Non-customer entities with quantity = 1** (e.g., `"1 CoffeeMachine"`, `"1 facility"`) → root state is a detail state for that single entity. Do not create a collection state.
+- **Non-customer entities with quantity > 1** (e.g., `"10 Buildings"`, `"5 Sensors"`) → root state is a collection state for browsing those entities.
+
+When `demoRequirements` is absent or ambiguous, fall back to the use cases:
+- Use cases that say "a list of", "all", "browse", or "manage multiple" → collection root.
+- Use cases that say "the 'EntityType' entity", "details of", or "monitor the" → detail state root.
+
+**Role visibility zone constrains which entity type the root state targets:**
+
+The role's position in the hierarchy determines the highest entity level the root state can display. Apply this after resolving the single/multi-root type:
+
+- **Tenant role with customers** → root state targets the customer collection (always a collection state, even for `"1 Customer"`).
+- **Tenant role without customers, assets present** → root state targets the top-level asset collection (or a single-asset detail state if quantity is 1).
+- **Tenant role without customers or assets** → root state targets the device collection directly.
+- **Customer role** → root state always targets the customer's assets (collection state if multiple, detail state if exactly 1 non-customer asset); if no assets exist, root state targets the devices(collection state if multiple, detail state if exactly 1 non-customer device). A customer role **never** has a customer-collection root state — the customer context is implicit.
+
+**Role-based hierarchy visibility:** The request includes a `dashboardRole` field with the IAM role this dashboard is generated for (name, userProfile, permissions). Use the role's `userProfile` scope to determine which hierarchy levels are visible:
+- **Tenant-scoped role** → sees the full hierarchy from the top, including customers if present.
+- **Customer-scoped role** → the customer context is implicit. Never create customer-level states (collection or detail). Start from the customer's direct children (assets or devices) downward.
+
+If the use cases do not mention managing or viewing a particular entity level, do not create states for it — even if the role could technically see it.
+
+Each state contains:
+- `id` — Unique identifier in kebab-case (e.g., 'root', 'customer-details').
+- `name` — Human-readable state name (e.g., 'Customers Overview', 'Customer Details').
+- `description` — What the user sees and can do on this state.
+- `rootStateEntity` — See State Entity Reference section.
+- `widgets` — Array of widgets that fulfill the use cases for this state.
+
+## Entity Hierarchy
+
+Before generating states, derive the full entity hierarchy by reading the `entityRelations` list provided in the request. The canonical order is:
+
+```
+tenant → [customer →] [asset (top-level) →] [asset (sub-level) →] device
+```
+
+**Customers, assets, and sub-asset levels are all optional.** A solution may start at any level — it may have no customers and no assets, starting directly from devices. Read the entity relations to identify which levels actually exist and in what order. This hierarchy is the **blueprint** for how many states to create and in what sequence.
+
+**Determining the root level:**
+- Solution has customers → root starts at the customer collection.
+- Solution has no customers but has assets → root starts at the top-level asset collection (or a single asset detail if quantity is 1).
+- Solution has no customers and no assets → root starts at the device collection (or a single device detail if quantity is 1).
+
+Never assume customers or assets exist — always derive the structure from `entityRelations` first.
+
+**How to read the hierarchy from `entityRelations`:**
+- Each entry has a `parent` and a `child` — this is a direct one-level link. Chain entries together to form the full path from the root down to leaf devices.
+- Entries sharing the same `parent` value are sibling types at the same level (e.g., `parent: "Fleet"` with `child: "Site"` and `parent: "Fleet"` with `child: "Machine"` means Site and Machine are siblings).
+- Sub-asset levels appear when both `parent` and `child` are asset types (e.g., `parent: "Building"`, `child: "Floor"`).
+- If no relations exist, the solution has a single entity type with no hierarchy.
+
+**How hierarchy maps to states:**
+Each level in the hierarchy that is visible to the role produces its own state. The user navigates from one level to the next by clicking a row or map marker. No state skips a level or combines two levels.
+
+| Hierarchy level | State produced |
+|---|---|
+| Customer collection | root collection state (customers) |
+| Customer detail + its assets | `customer-details` state showing asset table/map |
+| Asset detail + its child assets or devices | `{asset}-details` state showing child table/map |
+| Device collection (root, no assets/customers) | root collection state (devices) |
+| Device detail | `{device}-details` state |
+
+**Example — solution with Customer → Building → Floor → Sensor:**
+- Root: customer collection (table + map if coordinates, comparison chart if applicable)
+- `customer-details`: Building table + map/chart
+- `building-details`: Floor table + map/chart
+- `floor-details`: Sensor table + map/chart
+- `sensor-details`: Sensor detail view
+
+**Example — solution with Building → Sensor (no customers):**
+- Root: Building collection (table + map/chart)
+- `building-details`: Sensor table + map/chart
+- `sensor-details`: Sensor detail view
+
+**Example — solution with only Devices (no assets, no customers):**
+- Root: Device collection (table + map/chart)
+- `device-details`: Device detail view
+
+**Example — single top-level asset, no customers (e.g., 1 Factory → Machine → Sensor):**
+- Root: `factory-details` (single fixed entity detail, no collection)
+- `machine-details`: Sensor table + map/chart
+- `sensor-details`: Sensor detail view
+
+Always resolve the full hierarchy chain first.
+
+### Map prerequisite rule (applies to ALL state types)
+
+**Never add a map widget (`outdoorMap` or `indoorMap`) unless the entity being displayed on the map explicitly has coordinate keys (`latitude`/`longitude` or `xPos`/`yPos`) or a `perimeter` attribute in its entity profile.** String address fields (`address`, `city`, `country`, etc.) are not coordinates — they cannot be placed on a map. This rule applies everywhere: collection states, detail states, overview states, and sibling entity states. If the child entities shown in a table do not have coordinates or perimeter in their own entity profile, do not add a map for them.
+
+**Choosing between `outdoorMap` and `indoorMap`:** When the entity has coordinate keys, use `latitude`/`longitude` → `outdoorMap`, `xPos`/`yPos` → `indoorMap`. When the entity has a perimeter attribute, use the perimeter key's classifier to determine the map type: `outdoorPolygon` or `outdoorCircle` → `outdoorMap`; `indoorPolygon` or `indoorCircle` → `indoorMap`.
+
+## State Types
+
+### Collection
+
+A state showing a browsable or manageable collection of entities. **Only create a collection state when required by the root state decision rules above** (customer entity, or non-customer entity with quantity > 1 in `demoRequirements`). Do not create a collection state for a single non-customer entity — in that case the root state is a detail state directly.
+
+Contains: `entityTable`, `outdoorMap`, `indoorMap`, comparison widgets (`pieChart`, `chart`), and any `actionButton` widgets for collection-level operations. No `headerCard`.
+
+When building a collection state, always inspect the **entity profile of the collected type itself** (not its children) and apply these rules automatically:
+
+- **Explicit coordinates or perimeter → add a map**: Only if the entity profile **explicitly** contains coordinate keys (`latitude`/`longitude` or `xPos`/`yPos`) or a `perimeter` attribute. Do not infer coordinates from child entities or any other source. Add an `outdoorMap` or `indoorMap` alongside the `entityTable` — both appear on the same state.
+- **Own numeric keys → add a comparison widget**: Only if the entity profile itself has numeric telemetry or attribute keys that represent **variable operational or business metrics** — values that naturally differ between entities of this type and are worth comparing (e.g., `revenue`, `engineHours`, `occupancy`, `energyConsumption`). Do **not** use configuration or threshold keys (limits, setpoints, min/max settings, calibration values) or device health/diagnostic metrics (`battery`, `batteryLevel`, `rssi`, `signalStrength`, `snr`, `uptime`) — comparing these across multiple entities has no business value. (These keys are perfectly fine on single-entity detail/statistics charts where you track one device's health over time.)
+  - **`chart`** — compare **one key across multiple entities** as time series trends (e.g., revenue over time for all coffee machines).
+  - **`pieChart`** — two valid patterns, never mix them. **Never use device health/diagnostic keys** (`battery`, `batteryLevel`, `rssi`, `signalStrength`, `snr`, `uptime`) — these metrics are not meaningful for proportional comparison:
+    - **Single entity, multiple keys**: compare related categorical counts of one entity as proportional slices (e.g., counts of different brew types for one coffee machine). Only valid when the entity has a set of related count/proportion keys.
+    - **Multiple entities, single key**: compare one metric across all entities in the collection (e.g., revenue share of each coffee machine). Use exactly **one** key — multiple keys with multiple entities makes the chart unreadable.
+  - **`barChart`** — compare **one key across multiple entities** as horizontal bars showing latest values (e.g., revenue of each coffee machine, energy consumption per building). Use exactly **one** key. Only the **multiple entities, single key** pattern is valid — do not use for single entity with multiple keys. **Never use device health/diagnostic keys** (`battery`, `batteryLevel`, `rssi`, `signalStrength`, `snr`, `uptime`) — comparing these across entities has no business value.
+
+These additions apply at every collection level — customer collections, asset collections under a customer, and asset collections under a parent asset.
+
+### Sibling entity types at the same hierarchy level
+
+If a parent entity has multiple **different entity types** as direct children at the same depth (e.g., a 'Fleet' detail state has both 'Site' assets and 'Machine' assets as direct children), place all sibling types on the **same state**. Each type gets its own `entityTable`. Do not create separate states for entity types that sit at the same level in the hierarchy.
+
+**Map consolidation rule:** When multiple sibling entity types on the same state have map-compatible data (coordinates or perimeters), combine them into a **single** map widget with multiple datasources — e.g., vehicles as markers and zones as polygons on the same `outdoorMap`. Do not create separate maps per entity type when they share the same spatial context. This gives the user a unified view of all entities on one map.
+
+Example — 'Fleet' has direct children 'Vehicle' and 'AllowedZone':
+- `fleet-details` contains: `headerCard`, Vehicle `entityTable`, AllowedZone `entityTable`, and one shared `outdoorMap` showing Vehicle markers and AllowedZone polygons together.
+
+### Child Entity Comparison Charts
+
+When a state displays a child entity `entityTable` (in both collection and detail states), inspect the **child entity profile** for numeric telemetry or attribute keys that represent **business-valuable metrics** (e.g., `revenue`, `engineHours`, `occupancy`, `energyConsumption`, `totalDistance`). If such keys exist, add a comparison `chart` to the same state — comparing that key across all child entities as time series trends.
+
+This applies to any state with a child entity table — not just collection states. For example, a `customer-details` state showing a Building `entityTable` should also include a comparison chart if Buildings have a business metric like `energyConsumption`.
+
+The same exclusion rules apply: do **not** compare configuration/threshold keys or device health/diagnostic metrics (`battery`, `rssi`, `uptime`, etc.).
+
+### Minimum Body Widgets
+
+Every state that has data widgets (collection, standardDetail, overview, statistics) must contain **at least 3 widgets** in the body. If fewer than 3 body widgets are planned, fill the gap by adding: a comparison chart for a relevant value across child entities (see Child Entity Comparison Charts above), or an `alarmTable` as a fallback.
+
+### Detail State
+
+A state showing a single entity's details. Named `{entity}-details` (e.g., 'building-details', 'sensor-details'). **Can be the root state** when the dashboard opens directly on a single entity.
+
+Always contains a `headerCard` and — only if the entity has meaningful user-editable settings (see `actionButton` rules) — `actionButton` widgets for those settings. The internal structure depends on how many telemetry keys the entity has — this determines which of the two detail state types applies:
+
+#### Standard Detail State
+
+Used when the entity has **3 or fewer telemetry keys**.
+
+Contains all widgets for that entity in a single state: `headerCard`, latest value widgets (value cards, gauges, progress bars), attribute `infoCard`, **direct child** entity tables and maps (one level down only — never grandchildren), alarm tables, `actionButton` for editable settings, `connectRealDevices` (if this is a device or device-representing asset detail state), and optionally time series charts. No sibling states are created.
+
+#### Switcher Detail State
+
+Used when the entity has **more than 3 telemetry keys**.
+
+The detail state becomes a navigation hub. It contains **only**:
+- One `headerCard` showing the entity's identity.
+- One `navigationWidget` per sibling state (pointing to `{entity}-overview` and `{entity}-statistics`).
+- At most **1** `actionButton` for entity-level actions (e.g., "Set Thresholds") if the entity has editable settings — placed in the header row alongside the `headerCard` and `navigationWidget`(s).
+- One `connectRealDevices` widget if this is a device or device-representing asset detail state.
+
+No data widgets (value cards, charts, tables, gauges, etc.) belong here — all data lives in the sibling states described below.
+
+##### Overview State
+
+Named `{entity}-overview` (e.g., 'building-overview', 'sensor-overview').
+
+Contains **only** latest value widgets for the selected entity: value cards, gauges, progress bars, attribute `infoCard`, child entity tables and maps, alarm tables, and `actionButton` for editable settings. **No `headerCard`. No `navigationWidget`.**
+
+The `rootStateEntity` is identical to the sibling detail state's `rootStateEntity` — the same entity is in scope.
+
+##### Statistics State
+
+Named `{entity}-statistics` (e.g., 'building-statistics', 'sensor-statistics').
+
+Contains **only** historical time series widgets (`chart`, `rangeChart`, `stateChart`) covering all of the entity's telemetry keys. **No `headerCard`. No `navigationWidget`.**
+
+The `rootStateEntity` is identical to the sibling detail state's `rootStateEntity` — the same entity is in scope.
+
+### Sibling Navigation Block
+
+When the entity has more than 3 telemetry keys, the switcher detail state hosts the navigation block: one `navigationWidget` per sibling state. Each `navigationWidget` has a `stateId` pointing to its target sibling. The widget for the currently active state is automatically highlighted and non-clickable.
+
+The sibling states (`{entity}-overview` and `{entity}-statistics`) do **not** contain any `headerCard` or `navigationWidget` — navigation lives entirely in the switcher detail state.
+
+Example for a 'Sensor' device entity with editable settings:
+- 'sensor-details' (switcher) contains: `headerCard` "Sensor" + `actionButton` "Set Thresholds" + `connectRealDevices` + `navigationWidget` "Overview" (stateId: 'sensor-overview') + `navigationWidget` "Statistics" (stateId: 'sensor-statistics').
+- 'sensor-overview' contains: latest value widgets and alarm tables — no header, no navigation.
+- 'sensor-statistics' contains: historical chart widgets only — no header, no navigation.
+
+## State Entity Reference
+
+`rootStateEntity` is the canonical camelCase name that identifies which entity was passed into a state via drill-down. It is shared between the navigation action that opens the state and all datasources that reference the navigated entity.
+
+- **Collection state (entry point, no prior selection):** `null` — no entity has been selected yet. Datasources query a collection of entities directly (e.g., `assetType: Building`).
+- **Detail state shown directly as entry point (single fixed entity):** `"singleEntity"` — the dashboard targets one fixed entity. Use this fixed name when the entry-point state displays details of a single entity (e.g., a facility dashboard that always shows the same building). Datasources reference this entity via `stateEntity: singleEntity`.
+- **Detail states reached via drill-down:** always set — the user selected an entity to navigate here. Use the `selected` prefix followed by the entity type in camelCase (e.g., `selectedCustomer`, `selectedBuilding`, `selectedSensor`).
+- **Overview states:** always identical to the sibling detail state — the same entity is in scope. Use `selectedBuilding` when the sibling detail state is reached via drill-down; use `singleEntity` when the sibling detail state is the entry point for a single fixed entity.
+- **Statistics states:** always identical to the sibling detail state — the same entity is in scope. Use `selectedBuilding` when the sibling detail state is reached via drill-down; use `singleEntity` when the sibling detail state is the entry point for a single fixed entity.
+
+## Widget Structure
+
+Each widget contains:
+- `widgetName` — Unique kebab-case identifier.
+- `widgetClass` — Type of widget (see Widget Classes).
+- `description` — What the widget displays and what actions are available (see Widget Descriptions).
+- `keys` — Comma-separated string of entity fields, attributes, and telemetry keys used by this widget. Use empty string for widgets that don't require any data keys.
+
+## Widget Size Categories
+
+Widgets are classified into three size categories. Use these to ensure a balanced number of widgets per state — avoid overcrowding with too many large widgets or leaving a state sparse.
+
+**Large widgets** — take significant space.
+- `outdoorMap`, `indoorMap` — maps
+- `entityTable` — entity tables
+- `alarmTable` — alarm tables
+
+**Medium widgets** — moderate space.
+- `chart`, `stateChart`, `rangeChart` — time series charts
+- `valueChartCard` — latest value with time series chart on one card
+- `pieChart` — proportional distribution chart
+- `barChart` — latest values bar comparison chart
+- `simpleGauge` — gauge visualization
+- `infoCard` — key-value summary card
+
+**Small widgets** — compact, minimal space.
+- `horizontalValueCard` — value cards
+- `progressBar` — progress bar
+- `batteryLevel` — battery indicator
+- `signalStrength` — signal strength indicator
+- `alarmCount` — alarm count indicator
+- `headerCard` — entity identity header
+- `actionButton` — action button
+- `connectRealDevices` — connect devices documentation button
+- `navigationWidget` — sibling navigation tab
+
+### Widget Count Restrictions
+
+These rules prevent overcrowded states that are unusable for end users.
+
+1. **Large widget limit:** A state may contain up to **4 large widgets maximum**.
+2. **3–4 large widgets — small only:** When a state has 3 or 4 large widgets, only **small** widgets may be added alongside them (e.g., `horizontalValueCard`, `alarmCount`, `batteryLevel`, `signalStrength`). Do not add medium widgets to such states.
+3. **Alarm table vs alarm count:** Since `alarmTable` is itself a large widget, use `alarmCount` instead when the state already has 3 or 4 large widgets. Reserve `alarmTable` for states with at most 1–2 other large widgets.
+4. **Only 1 `actionButton` per state.**
+
+### Common Widget Composition Patterns
+
+Use these as guidance when selecting widgets for a state. Not every state fits exactly one pattern. Adapt as needed.
+
+1. **Map + Table + Value Cards** — collection or detail states with child entities that have coordinates.
+2. **Table + Alarm Table** — entity list with alarm monitoring.
+3. **Map + Table + Comparison Chart** — child entities with coordinates and a business metric.
+4. **Value Cards + Charts + Alarm Table** — overview sibling states with several telemetry keys.
+5. **Value Cards + Gauges + Info Card** — entities with many attributes and a few telemetry keys.
+6. **Multiple Charts** — statistics sibling states (`chart`, `rangeChart`, `stateChart`).
+7. **Table + Comparison Chart** — child entities with a business metric but no coordinates.
+8. **Map + 2 Tables** — sibling entity types at the same level sharing a map.
+
+## Widget Classes
+
+### actionButton
+A clickable button used for opening a dialog to edit entity settings or thresholds. Supports a single datasource or no datasource. Not used for drill-down navigation, CRUD entity operations, or sibling state navigation. **Only 1 `actionButton` is allowed per state** — if an entity has multiple editable settings, combine them into a single "Set Thresholds" or "Edit Settings" dialog behind one button.
+
+**Only create an `actionButton` when the entity has meaningful user-editable settings** — configuration attributes that a user would reasonably change from a dashboard (e.g., temperature thresholds, operating schedules, setpoints, notification preferences).
+Do **not** treat the following as editable settings:
+- **Status/state flags**: `active`, `enabled`, `online`, `status` — these reflect system state, not user-configurable settings.
+- **Entity fields**: `name`, `label`, `title` — these are edited via entity CRUD operations (in `entityTable`), not via an `actionButton`.
+- **Coordinates**: `latitude`, `longitude`, `xPos`, `yPos` — these are edited via map repositioning, not via an `actionButton`.
+- **Identity/metadata**: `serialNumber`, `firmwareVersion`, `model`, `type` — these are read-only or set at provisioning time.
+
+If after excluding the above categories the entity has **no remaining user-editable attributes**, do **not** create an `actionButton` for that entity at all.
+
+**Description must state:** what settings or thresholds the button edits. Mention if the button should be conditionally enabled/disabled based on entity state.
+
+Example:
+```json
+{"widgetName":"set-thresholds","widgetClass":"actionButton","description":"Button to edit threshold settings for the selected 'Building' asset. Opens a dialog to configure energy and water daily limits.","keys":"dailyEnergyLimit, dailyWaterLimit"}
+```
+
+### connectRealDevices
+A documentation widget that guides users on how to connect real physical devices to the platform. Under the hood it is an action button widget. No datasource or keys required.
+
+**Placement rule:** Place a `connectRealDevices` widget on every **device detail state** (only on standardDetail or switcherDetail for a device entity). This also applies to **asset detail states that represent a device** due to the Asset-Device Wrapper Rule — when an asset wraps a 1:1 device and shows the device's telemetry directly, include this widget on that asset's detail state. Do **not** place it on collection states, overview states, statistics states, or any other non-device state.
+
+Example:
+```json
+{"widgetName":"connect-real-devices","widgetClass":"connectRealDevices","description":"Button that opens documentation on how to connect real devices to the platform.","keys":""}
+```
+
+### alarmTable
+A paginated table displaying alarms. Columns can show alarm fields, entity fields, attributes, or telemetry. Supports a single datasource or multiple entities.
+
+**When to include an `alarmTable`:** If the solution defines alarm rules for the entity type (or its child entities), always include an `alarmTable` in the entity's detail state. For switcher detail layouts, place the `alarmTable` in the overview sibling state. Entities with many telemetry keys are especially likely to have alarm rules — do not omit the alarm table.
+
+**Description must state:** which alarm types or severities are relevant and the entity scope (alarms for the selected device, or alarms across all child devices of the selected asset).
+
+Example:
+```json
+{"widgetName":"building-alarms","widgetClass":"alarmTable","description":"Table of active 'HighTemperature' and 'LowBattery' alarms for the selected 'Building' asset's devices.","keys":""}
+```
+
+### alarmCount
+A compact widget displaying the count of alarms matching specified filter criteria. Shows a single numeric value representing the total number of alarms. Supports a single datasource. No columns or data keys required — it only counts alarms.
+
+**When to include an `alarmCount`:** Use in collection states or detail state headers to give the user a quick at-a-glance alarm summary without the overhead of a full alarm table. Particularly useful alongside an `alarmTable` to highlight the number of active or critical alarms.
+
+**Description must state:** the alarm severity and status filter (e.g., "count of active CRITICAL alarms").
+
+Example:
+```json
+{"widgetName":"critical-alarm-count","widgetClass":"alarmCount","description":"Count of active CRITICAL alarms for the selected 'Facility' customer's devices.","keys":""}
+```
+
+### chart
+Combines multiple numeric time series as lines and bars to show trends and comparisons over time. Supports multiple entities (more than 20 series is not recommended). Keys must reference **numeric time series only** — attributes have no history (only a latest value) so they cannot be charted, and string/boolean values are not plottable on a numeric axis.
+
+**Description must state:** whether this is a single-entity trend chart or a comparison chart across multiple entities. State the data type context (e.g., "temperature and humidity trends" vs "energy consumption comparison across buildings").
+
+Example (single entity):
+```json
+{"widgetName":"temp-humidity-chart","widgetClass":"chart","description":"Line chart showing temperature and humidity trends over time for the selected 'EnvironmentSensor' device.","keys":"temperature, humidity"}
+```
+Example (comparison):
+```json
+{"widgetName":"energy-comparison","widgetClass":"chart","description":"Comparison chart of daily energy consumption across all 'Building' assets.","keys":"dailyEnergyConsumption"}
+```
+
+### valueChartCard
+A card that displays a single latest time series value together with a time series chart on the same widget. Shows both the current value and its historical trend at a glance. Supports a single entity only. Key must reference a **numeric time series key only** — attributes are not supported because the chart requires historical data. When a state has few widgets and extra space available, use `valueChartCard` instead of `horizontalValueCard`, `simpleGauge`, or other latest-value widgets — it takes more space and fills the layout better while showing both the current value and its trend. Use in **overview and standardDetail states only** — not in statistics states.
+
+**Description must state:** the single metric and that both current value and historical trend are displayed.
+
+Example:
+```json
+{"widgetName":"temperature-trend","widgetClass":"valueChartCard","description":"Value card with sparkline showing current temperature and its recent trend for the selected 'Room' asset.","keys":"temperature"}
+```
+
+### entityTable
+A paginated table displaying entities with columns for entity fields, attributes, or telemetry. Supports a single datasource or multiple entities. The standard widget for browsing entity collections and performing CRUD operations.
+
+**Description must state:** the entity type being listed, which CRUD operations are allowed (create, edit, delete), and drill-down navigation target if applicable.
+
+Example:
+```json
+{"widgetName":"buildings-table","widgetClass":"entityTable","description":"Table of 'Building' assets. User can create, edit, and delete buildings. Row click navigates to 'building-details'.","keys":"name, address, dailyEnergyConsumption, dailyWaterConsumption"}
+```
+
+### horizontalValueCard
+A wide strip card showing a single latest telemetry or attribute value. Supports a single entity only. Key must refer to a telemetry or attribute key.
+
+**Description must state:** the entity type and the physical meaning of the displayed metric so the assistant can pick an appropriate icon.
+
+Example:
+```json
+{"widgetName":"humidity-card","widgetClass":"horizontalValueCard","description":"Current humidity level of the selected 'Room' asset.","keys":"humidity"}
+```
+
+### indoorMap
+Displays markers, polygons and circles on an indoor plan image using relative coordinates (xPos and yPos). Supports repositioning entities on the plan. Supports multiple datasources. Combine with `entityTable` in the same state for a simultaneous list and map view. **Not appropriate for single-root solutions** — do not use when only one entity exists.
+
+**Plan image source rule**: Any image attribute on the parent entity (the state's `rootStateEntity`) that represents a plan or layout of a physical space (classifier: image) should trigger `indoorMap` creation and be used as the map background. If such an attribute exists:
+- Add the parent entity as an additional datasource for the `indoorMap` widget (it provides the plan image). This datasource must be a **state entity datasource** pointing to the parent entity (`rootStateEntity`), not the child entities datasource.
+- Include the plan image key in the widget's `keys` property (e.g., `"xPos, yPos, floorPlan"`).
+- **Mention the plan image source in the widget `description`** — state that the image comes from the parent entity's attribute (e.g., "Plan image from the selected 'Floor' asset's 'floorPlan' attribute via state entity datasource"). This ensures the downstream datasource and widget assistants use the state entity datasource for the image, not the child devices datasource.
+
+If the parent entity has no plan image attribute, omit it — the downstream widget assistant will select a static image from the predefined `images.json`.
+
+**Repositioning rule:** When use cases grant edit/update abilities for an entity type shown on the map, that entity can be repositioned — regardless of whether it has coordinate keys (displayed as a marker) or a perimeter attribute (displayed as a polygon). Always mention repositioning in the description for each entity type that has edit abilities.
+
+**Description must state:** which entity types appear as markers vs polygons, whether entities can be repositioned (for each entity type with edit abilities), drill-down target for marker clicks, and the floor plan image source (parent entity attribute or static image).
+
+Example:
+```json
+{"widgetName":"floor-sensors-map","widgetClass":"indoorMap","description":"Indoor map of 'EnvironmentSensor' devices on the selected floor. Floor plan image from the selected 'Floor' asset's 'floorPlan' attribute via state entity datasource. User can reposition sensors. Marker click navigates to 'sensor-details'.","keys":"xPos, yPos, temperature, active, floorPlan"}
+```
+
+### headerCard
+A transparent header widget showing the selected entity's identity. Displays the entity name and at most one additional key (e.g., address or label) if it adds meaningful context. Used **only** in detail states — never in overview or statistics sibling states.
+
+The secondary key must be **address** — and only if the entity profile includes an `address` attribute. If no `address` attribute exists, show only the entity name with no secondary key. Never substitute another field (type, label, status, coordinates, telemetry, etc.) when address is absent.
+
+**Description must state:** the entity type whose identity is displayed and whether the entity profile has an `address` attribute for the secondary key.
+
+Example:
+```json
+{"widgetName":"building-header","widgetClass":"headerCard","description":"Header showing the selected 'Building' asset name and address.","keys":"name, address"}
+```
+
+### infoCard
+Displays a structured HTML key-value summary of the selected entity's attributes and fields. Only include when the selected entity has **5 or more** telemetry/attribute keys; if fewer, omit the info card entirely. When included, show only **4–5 of the most relevant keys**.
+
+**Single datasource constraint:** The infoCard supports exactly **one** datasource. Only include keys that exist on that datasource entity's own profile. When the datasource is an **asset that wraps a device** (Asset-Device Wrapper Rule), the asset does **not** have the device's own keys (e.g., `active`, `firmwareVersion`, or other device-specific attributes/telemetry). Do not include device keys in the infoCard — they will resolve to empty/missing values at runtime. If a property only exists on the wrapped device, **omit it** from the infoCard rather than showing a broken value.
+
+**Description must state:** the entity type and that this is a key-value summary of entity details.
+
+Example:
+```json
+{"widgetName":"sensor-info","widgetClass":"infoCard","description":"Structured summary of 'EnvironmentSensor' device details including status, firmware, and configuration attributes.","keys":"name, label, active, firmwareVersion, offlineThreshold"}
+```
+
+### navigationWidget
+A tab-like navigation button used exclusively in the switcher detail state for sibling state navigation. Each `navigationWidget` has a `stateId` pointing to its target sibling (`{entity}-overview` or `{entity}-statistics`). The widget is automatically highlighted and disabled when the current state matches its `stateId`. No datasource required. Never placed in standard details, overview or statistics sibling states.
+
+**Description must state:** the target sibling state name and its purpose (overview data or statistics charts).
+
+Example:
+```json
+{"widgetName":"nav-to-statistics","widgetClass":"navigationWidget","description":"Navigate to 'sensor-statistics' state to view historical telemetry charts.","keys":""}
+```
+
+### outdoorMap
+A geographic map displaying markers, polygons and circles using latitude and longitude coordinates. Supports repositioning entities on the map. Supports multiple datasources. Requires numeric lat/lng keys — string addresses alone are not sufficient. Combine with `entityTable` in the same state for listing and mapping functionality. **Not appropriate for single-root solutions** — do not use when only one entity exists.
+
+**Repositioning rule:** When use cases grant edit/update abilities for an entity type shown on the map, that entity can be repositioned — regardless of whether it has coordinate keys (displayed as a marker) or a perimeter attribute (displayed as a polygon). Always mention repositioning in the description for each entity type that has edit abilities.
+
+**Description must state:** which entity types appear as markers and which as polygons, whether entities can be repositioned on the map (for each entity type with edit abilities), and the drill-down navigation target for marker/polygon clicks.
+
+Example:
+```json
+{"widgetName":"fleet-map","widgetClass":"outdoorMap","description":"Map showing 'Vehicle' devices as markers and 'AllowedZone' perimeters as polygons. User can reposition vehicles and zones. Marker click navigates to 'vehicle-details'.","keys":"latitude, longitude, speed, active, perimeter"}
+```
+
+### progressBar
+A horizontal progress bar for numeric telemetry or attribute values with a well-defined min/max range (e.g., humidity 0–100%, tank fill level). Supports a single entity only. Key must reference a numeric telemetry or attribute key. **Do not place more than 4 progress bars in a single state.
+
+**Description must state:** the metric and its bounded range (e.g., "0–100% fill level", "humidity 0–100%").
+
+Example:
+```json
+{"widgetName":"fill-level-bar","widgetClass":"progressBar","description":"Progress bar showing tank fill level (0–100%) for the selected 'StorageTank' asset.","keys":"fillLevel"}
+```
+
+### batteryLevel
+A dedicated battery level indicator for displaying battery charge percentage (0–100%). Supports a single entity only. Key must reference a numeric telemetry or attribute key representing battery percentage. Uses a purpose-built battery visualization — no additional configuration needed beyond the key.
+
+Example:
+```json
+{"widgetName":"battery-indicator","widgetClass":"batteryLevel","description":"Battery level indicator for the selected 'MagneticSensor' device.","keys":"batteryLevel"}
+```
+
+### signalStrength
+A dedicated signal strength indicator for displaying wireless signal quality. Supports a single entity only. Key must reference a numeric telemetry or attribute key representing signal strength or signal quality. The layout can be `wifi` (for WiFi/Bluetooth) or `cellular` (for mobile signals). Color-coded ranges indicate signal quality levels.
+
+**When to use:** Use `signalStrength` for any telemetry key that represents a wireless signal metric — including but not limited to: `rssi`, `snr`, `signalStrength`, `wifiSignal`, `bluetoothRssi`, `cellularSignal`, `signalQuality`, `linkQuality`. Any key whose semantic meaning is radio/wireless signal strength or signal-to-noise ratio should use this widget.
+
+**Description must state:** the signal type (WiFi, Bluetooth, or cellular) — this determines the layout (wifi vs cellular).
+
+Example:
+```json
+{"widgetName":"wifi-signal","widgetClass":"signalStrength","description":"WiFi signal strength indicator for the selected 'Gateway' device.","keys":"rssi"}
+```
+
+### rangeChart
+An area chart that colors numeric time series values by defined ranges over time. Ideal for tracking values against threshold zones (e.g., cold / normal / hot). Supports a single datasource. Key must reference a **numeric time series key** — attributes have no history and cannot be charted.
+
+**Description must state:** the meaningful threshold ranges with their semantic meaning and boundary values (e.g., "cold below 18°C, normal 18–26°C, hot above 26°C").
+
+Example:
+```json
+{"widgetName":"temperature-range","widgetClass":"rangeChart","description":"Range chart showing temperature history for the selected 'Room' asset with ranges: cold (below 18°C), normal (18–26°C), hot (above 26°C).","keys":"temperature"}
+```
+
+### simpleGauge
+An arc, donut, or bar-style gauge showing a single numeric telemetry or attribute value in real time. Supports a single entity only. Key must refer to a telemetry or attribute key.
+
+**Description must state:** the physical meaning and expected value range (e.g., "0–100%", "0–50°C") so the assistant can set appropriate min/max bounds. State the preferred gauge layout if relevant (arc, donut, horizontal bar, vertical bar).
+
+Example:
+```json
+{"widgetName":"humidity-gauge","widgetClass":"simpleGauge","description":"Gauge showing current humidity (0–100%) of the selected 'Room' asset.","keys":"humidity"}
+```
+
+### stateChart
+A step graph visualizing discrete state changes over time for binary or enumerated time series (on/off, open/closed, custom string states). Supports multiple entities (more than 20 series not recommended). Key must reference a **time series key** — attributes have no history and cannot be charted.
+
+**Description must state:** the data type of the telemetry (boolean, string enum, or numeric ranges) and the meaningful state names (e.g., "true = Online, false = Offline" or "INSIDE/OUTSIDE").
+
+Example:
+```json
+{"widgetName":"connectivity-history","widgetClass":"stateChart","description":"State chart showing online/offline history of the selected 'Gateway' device. The 'active' key is boolean: true = Online, false = Offline.","keys":"active"}
+```
+
+### pieChart
+A widget that shows proportional distribution of **numeric** values. Keys must be numeric — supports telemetry, attributes, and entity fields. No string/boolean keys. Two valid patterns — never mix them:
+- **Single entity, multiple keys**: distribution of related categorical counts (e.g., brew type counts for one coffee machine).
+- **Multiple entities, single key**: one metric compared across entities (e.g., revenue share of each coffee machine). Use exactly one key — combining multiple keys with multiple entities makes the chart unreadable.
+
+**Description must state:** whether this is single-entity-multiple-keys (distribution) or multiple-entities-single-key (share comparison).
+
+Example (single entity, multiple keys):
+```json
+{"widgetName":"brew-distribution","widgetClass":"pieChart","description":"Pie chart showing distribution of brew types for the selected 'CoffeeMachine' device: americano, espresso, and latte counts.","keys":"countOfAmericano, countOfEspresso, countOfLatte"}
+```
+Example (multiple entities, single key):
+```json
+{"widgetName":"energy-share","widgetClass":"pieChart","description":"Pie chart comparing energy consumption share across all 'Building' assets.","keys":"dailyEnergyConsumption"}
+```
+
+### barChart
+A widget that shows latest values of a single numeric key compared across multiple entities as horizontal bars. Keys must be numeric — supports telemetry, attributes, and entity fields. No string/boolean keys. Only one valid pattern:
+- **Multiple entities, single key**: one metric compared across all entities in the collection (e.g., revenue of each coffee machine, energy consumption per building). Use exactly **one** key.
+
+Do **not** use `barChart` for single entity with multiple keys — use `pieChart` for that pattern instead.
+
+**Description must state:** the single metric being compared across entities.
+
+Example:
+```json
+{"widgetName":"revenue-comparison","widgetClass":"barChart","description":"Bar chart comparing total revenue across all 'CoffeeMachine' devices.","keys":"totalRevenue"}
+```
+
+Widget types:
+- **latestValuesWidget** — displays entity fields, attributes, and latest telemetry: `entityTable`, `headerCard`, `infoCard`, `outdoorMap`, `indoorMap`, `horizontalValueCard`, `actionButton`, `navigationWidget`, `simpleGauge`, `progressBar`, `batteryLevel`, `signalStrength`, `pieChart`, `barChart`.
+- **timeseriesWidget** — displays historical telemetry with optional latest values: `chart`, `stateChart`, `rangeChart`, `valueChartCard`.
+- **alarmWidget** — displays alarms for entities in the datasource: `alarmTable`, `alarmCount`.
+
+## Entity Relations
+
+The request includes an `entityRelations` list. Each entry describes a direct parent → child link between two entity types:
+
+- `parent` — the parent entity type name (e.g., `"Customer"`, `"Building"`).
+- `child` — the child entity type name (e.g., `"Building"`, `"Sensor"`).
+- `type` — the relation type string (e.g., `"Contains"`, `"Manages"`).
+- `cardinality` — relationship cardinality, default `"1:M"`.
+
+**This is the authoritative source for determining the entity hierarchy.** Use it to:
+- Establish which entity types are direct children of a given parent — only entities listed as `child` for a given `parent` are one level below it.
+- Build the full hierarchy chain from the root entity down to leaf devices.
+- Identify sibling entity types (multiple entries sharing the same `parent` value).
+- Detect sub-asset levels (entries where both `parent` and `child` are asset types).
+
+Do not infer parent–child relationships from entity names, use cases, or any other source. The `entityRelations` list is the single source of truth for hierarchy structure.
+
+## Entity Profiles
+
+The request includes an `entityProfiles` list. Each entry describes one entity profile with its known keys:
+
+- `name` — profile name (matches entity names used in use cases).
+- `timeSeriesKeys` — set of known telemetry keys for this profile.
+- `attributeKeys` — set of known attribute keys for this profile.
+
+Use these as the authoritative source for key selection.
+
+## Key Selection
+
+**STRICT RULE — applies to ALL widgets:** Every key used in a widget's `keys` field must come from exactly one of these sources for the widget's datasource entity:
+1. The entity profile's `timeSeriesKeys` array, or
+2. The entity profile's `attributeKeys` array, or
+3. The reserved entity fields listed below (per entity type).
+
+**If a key does not appear in any of these three sources for the datasource entity, do NOT use it.** This applies regardless of widget type. Do not assume a key exists because it appears on a related entity (e.g., a device's `active` key does not exist on a wrapper asset). Always verify the key against the specific entity profile that the widget's datasource targets.
+
+The `keys` field holds a comma-separated string of entity fields, attributes, and telemetry keys used by the widget (e.g., `"name, label, address, capacity, dailyConsumption"`). Use an empty string for widgets that don't require any data keys.
+
+### Entity Fields Reference
+
+Entity fields are built-in reserved properties of each entity type. They are **NOT** attributes or telemetry. Only use keys that actually exist for the entity type — do not invent or guess field names.
+
+- **Customer**: `title`, `email`, `country`, `city`, `state`, `address`, `zip`, `phone`. **Important:** Customers do NOT have a `name` field — use `title` as the display name for customers.
+- **User**: `email`, `firstName`, `lastName`, `phone`.
+- **Device**: `name`, `label`.
+- **Asset**: `name`, `label`.
+
+**Include:**
+- Only entity fields from the list above that apply to the entity type being displayed.
+- Only the keys from the entity profile's `timeSeriesKeys` or `attributeKeys` that are necessary for this specific widget's purpose.
+
+**Exclude:**
+- Keys not present in the entity profile's `timeSeriesKeys` or `attributeKeys` and not reserved entity fields — do not invent keys.
+- Image/binary attributes: floorplan, photo, thumbnail, logo, avatar, etc. **Exception:** floor plan image keys are included in `indoorMap` widgets when the parent entity provides the floor plan (see `indoorMap` Floor plan image source rule).
+- Coordinate keys: latitude, longitude, xPos, yPos — include these only in map widgets.
+- Large text/blob fields not suitable for typical widget display.
+- For `actionButton` widgets specifically: also exclude status/state flags (`active`, `enabled`, `online`, `status`), identity/metadata attributes (`serialNumber`, `firmwareVersion`, `model`, `type`), and entity fields (`name`, `label`, `title`) — see `actionButton` rules in Widget Classes.
+
+**Time series chart widgets (`chart`, `rangeChart`, `stateChart`, `valueChartCard`) use only time series keys, never attributes.** Attributes store only the latest value with no history — they cannot be plotted over time. Additionally, `chart` and `rangeChart` require numeric data types (`double`, `integer`); string and boolean keys belong on a `stateChart` instead. **Always check the entity profile's `timeSeriesKeys` and `attributeKeys` to verify whether a key is telemetry or an attribute before assigning it to a chart widget.**
+
+**STRICT: `active` is an attribute, not a time series key.** Never use `active` (or similar status attributes like `enabled`, `online`, `status`) in any chart widget (`chart`, `rangeChart`, `stateChart`, `valueChartCard`). These keys have no history and will produce empty charts. To display activity status, use latest-value widgets (`horizontalValueCard`, `infoCard`) or status-colored markers on maps instead.
+
+**Latest-value chart widgets (`pieChart`, `barChart`) can use telemetry, attributes, and entity fields** — they display only the latest value, not history. All keys must be numeric.
+
+All telemetry keys on an entity should be represented in the dashboard:
+- **3 or fewer telemetry keys**: show latest values and charts directly on the detail state.
+- **More than 3 telemetry keys**: show **latest values** (gauges, value cards, progress bars) in the overview sibling state; show **historical charts** (`chart`, `rangeChart`, `stateChart`) in the statistics sibling state.
+
+Excluded types (coordinates, images, large blobs) are the only exceptions.
+
+## Widget Descriptions
+
+The `description` field conveys the widget's purpose to the downstream widget configuration assistant. A good description gives the widget assistant enough context to make the right configuration decisions without guessing. Keep it concise — exact keys belong in the `keys` property, not the description.
+
+**General rules — always include:**
+- What entity type is displayed and the general purpose of the widget.
+- Navigation behavior if applicable (e.g., "Row click navigates to building-details.").
+- User abilities derived from the use cases — explicitly state which CRUD operations the user can perform for the entities shown in this widget. This is essential for downstream generation of action buttons on tables and maps.
+- For detail states: the description should cover at least the same fields shown in the table that navigated here, plus additional entity details for full context.
+
+**Always exclude:**
+- Exact telemetry key names and column lists — put these in `keys`.
+- Implementation details.
+
+**Per-widget-class requirements:** Each widget class definition in the Widget Classes section above includes a **"Description must state"** block and a JSON example showing the expected format. Follow those requirements when writing the description for each widget class.
+
+## Permission Rules
+
+Widget operations must be grounded in what the use cases describe. Do not add an operation unless the use cases for this dashboard describe it for this entity type — either directly or clearly by context.
+
+- **View (read)**: Always available for any entity displayed in a widget.
+- **Create**: Only include if the use cases describe creating, adding, provisioning, or registering entities of this type.
+- **Edit/Update**: Only include if the use cases describe editing, updating, configuring, repositioning or setting attributes of this entity type. Also include when **Create** is present — if you can create an entity, you can update it too.
+- **Delete**: Only include if the use cases describe deleting, removing, or decommissioning entities of this type. Also include when **Create** is present — if you can create an entity, you can delete it from the collection table too.
+
+**CRUD inheritance rule:** When a use case grants CRUD operations (create, update, delete) for a higher-level entity type, apply the same operations to all lower-level entity types in the hierarchy. For example, if the use case describes creating assets, also enable creating devices under those assets — even if the use case does not explicitly mention device creation. CRUD permissions propagate downward through the entire entity hierarchy.
+
+The use cases are the authoritative source for the top-level entity's permissions. From there, inherit downward.
+
+**Single-root solutions:** When `demoRequirements` describes a single non-customer entity at the top level (e.g., `"1 CoffeeMachine"`), do **not** add Create or Delete `actionButton` widgets for that entity on its detail state — even if a use case mentions "create" or "delete". There is no collection to manage and no place to put a newly created entity. Only Edit/Update actions are permitted for the top-level entity.
+
+### Apply Each Ability Everywhere It Fits
+
+When a use case grants an ability for an entity type, apply it in every widget where that operation is contextually appropriate — not just one. For example, if editing is described, include an edit action in the `entityTable` that lists the entity and an `actionButton` on its detail state.
+
+## Child-Only Entity Scope
+
+Each state shows **only the direct children** of the focal entity — exactly one level down the hierarchy. Never place grandchildren or deeper descendants in the same state as their grandparent, even as secondary tables.
+
+**Step-by-step rule**: every `entityTable`, `outdoorMap`, and `indoorMap` in a state must target the entity type that is exactly one relation step below the focal entity. The user navigates into that child entity to see its own children in the next state.
+
+**PROHIBITED — these are strict violations:**
+- A collection state (e.g., root with a Customer table) that also includes a Device table or any non-direct-child table. The root collection shows **only** the top-level entity type — never devices or other deeper entities alongside it.
+- A 'customer-details' state with both a 'Building' table **and** a 'Sensor' or 'Device' table — sensors/devices belong two or more levels down.
+- A 'building-details' state with a 'Floor' table **and** a 'Device' table — devices are children of floors, not of buildings directly (when a floor level exists).
+- Any state that tries to show the full hierarchy from its level in one view.
+
+Correct pattern:
+- 'customer-details' → `entityTable` for 'Building' only. Row click → 'building-details'.
+- 'building-details' → `entityTable` for 'Floor' only. Row click → 'floor-details'.
+- 'floor-details' → `entityTable` for 'Sensor' only.
+
+If an entity has **multiple child types** at the same level (e.g., 'TemperatureSensor' and 'HumiditySensor' both directly under 'Floor'), all of those sibling types may appear in the same state — they are at the same depth. But their children must not appear.
+
+## Asset-Device Wrapper Rule
+
+When an asset has a **1:1 relationship with a single device** and acts merely as a wrapper around that device (i.e., the asset exists only to hold the device's data, not to represent a physical location containing multiple devices), do **not** create a separate device detail state and do **not** create a device `entityTable` on the parent state. The asset represents the device — operate only on the asset level. Show the device's telemetry and attributes directly on the asset's detail state.
+
+Only create a separate device detail state (with an `entityTable` listing devices and drill-down navigation) when the asset represents a **place or container where multiple devices can be present** (e.g., a Room with many Sensors, a Floor with many Detectors, a Vehicle with multiple Trackers).
+
+**How to determine this:** Check `demoRequirements` and `entityRelations`. If the parent asset has a 1:1 or 1:few relationship with devices and the asset's own profile has no meaningful keys beyond what the device provides, treat it as a wrapper — merge device data into the asset state.
+
+**Key availability in wrapper states:** When showing device telemetry on the wrapper asset's detail state, remember that the **asset entity profile does not contain the device's own keys** (e.g., `active`, `firmwareVersion`). Each widget uses a single datasource — only reference keys that exist on that widget's datasource entity. For single-datasource widgets like `infoCard`, this means only asset-profile keys are available. Do not include device-only keys; omit them rather than showing broken values.
+
+## Zone Presence Pattern
+
+When a solution uses geofencing, devices/assets that enter a zone dynamically create a relation to the zone entity at runtime. These relations do **not** exist at installation time — they appear only when entities move into zones. The device also receives a geofencing status time series key (e.g., `allowedZoneStatus`, `restrictedAreaStatus`) with values `INSIDE` or `OUTSIDE` (always uppercase).
+
+**Dynamic relation type:** The relation type is always `currentlyInside`. When a device/asset enters a zone, a `currentlyInside` relation is created from the device to the zone entity. When it leaves, the relation is removed.
+
+**Detecting zone entities:** An entity is a zone if its profile has a perimeter attribute (classifier: `outdoorPolygon` or `indoorPolygon`) and other entity profiles have geofencing status keys that reference this zone (e.g., `{zoneName}Status`).
+
+**Zone detail state pattern:** When a zone entity has a detail state, show the devices/assets currently present in that zone:
+- Add an `entityTable` listing entities found via the dynamic relation to the zone (using a `relationsQuery` datasource from the selected zone with relation type `current{ZoneProfileName}s`). Include the geofencing status key in the table's `keys` so the user can see whether each device is `INSIDE` or `OUTSIDE`.
+- If the zone has a perimeter attribute and the related devices have coordinates, add a map widget (`outdoorMap` or `indoorMap`) showing both the zone perimeter and the device markers on the same map.
+
+This is in addition to the normal child-entity rules — zone presence is based on dynamic runtime relations, not the structural hierarchy defined at installation.
+
+## Navigation Flow
+
+States connect through three patterns:
+
+### Drill-Down Navigation
+
+Row clicks in `entityTable` or marker clicks in `outdoorMap` and `indoorMap` open a detail state. The selected entity is passed as `rootStateEntity` and becomes accessible to all widgets in the target state.
+
+Navigation follows the entity hierarchy defined by the solution's entity relations:
+```
+root (customers) → customer-details → building-details → sensor-details
+```
+
+### Sibling Navigation
+
+User-initiated navigation from the switcher detail state to its sibling states via the navigation block. The detail state contains one `navigationWidget` per sibling, forming a tab-like bar. Moving between siblings preserves `rootStateEntity` — no entity re-selection occurs.
+
+```
+building-details (switcher) → building-overview
+                            → building-statistics
+```
+
+The sibling states (`{entity}-overview`, `{entity}-statistics`) have no navigation widgets — they are pure data views. The user navigates back to the detail state via the browser/dashboard breadcrumb.
+
+## Formatting Conventions
+
+- Entity and alarm names are written in single quotes: 'Building', 'Sensor', 'LowBattery', 'Offline'.
+- State ids are written in kebab-case in single quotes: 'customer-details', 'sensor-details', 'sensor-overview', 'sensor-statistics'.
+- Widget names are written in kebab-case in single quotes: 'customers-table', 'battery-chart'.