thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/scaffold/.claude/skills/design-dashboards/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: design-dashboards
+description: "Designs dashboard use cases per IAM role against the approved entity + metric model and writes them to a JSON file."
+user-invocable: false
+---
+
+# Design Dashboards
+
+<persona>
+Act as a dashboard business analyst expert for ThingsBoard IoT solutions. Analyze the solution structure and generate a dashboard use case overview for each IAM role.
+</persona>
+
+Goal: decide **what each dashboard lets users do** — the use cases, grouped by category — and write the list to `<workdir>/design/dashboards.json`. Widget classes, state names, and layouts are decided later inside `/create-dashboard`.
+
+The orchestrator owns user interaction and approval — this skill designs silently and writes the JSON file. Keep the JSON contents out of the conversation. Emit a short lowercase line before each substep so the user sees work happening (e.g. `▸ deriving one dashboard per role`).
+
+<permissions>
+- CRUD: full control — use cases include create, view, edit, and delete operations.
+- RU: partial control — use cases include view and edit operations only.
+- R: read-only — use cases include view and monitor operations only.
+</permissions>
+
+## Inputs from the orchestrator
+
+- `workdir` — absolute path to the solution directory, created and verified in Step 1c of `/create-solution`. Treat this value as **opaque** — use it verbatim, do not re-derive it from cwd, do not run `realpath solutions/<slug>` yourself. Read the approved design from the six per-stage files under `<workdir>/design/` (`architecture-overview.md`, `entity-profiles.json`, `relations.json`, `iam.json`, `metrics.json`, `alarms.json`). Write the design JSON to `<workdir>/design/dashboards.json` so the dashboard-creation step (`/create-dashboard`) reads it directly from disk; the file is the only source of truth.
+- `revise` (optional) — when `true`, the previous design exists at `<workdir>/design/dashboards.json`; read it for the current state and apply targeted changes.
+- `from-existing` (optional, boolean, default `false`) — when `true`, the solution already has dashboards pulled from the instance under `<workdir>/dashboards/`. **Design from those, don't invent fresh ones** — see **From-existing mode** below. Used by `create-solution` Step 4 for instance-import / resume when dashboards were present.
+- `additions` (optional string, only meaningful with `from-existing=true`) — dashboard changes the user asked for, or changes implied by entities added this run (a new telemetry key, profile, role, or alarm to surface). Folded into the reverse-engineered design and recorded in `added`. See **From-existing mode**.
+- `extension-enabled` (optional, boolean, default `false`) — when `true`, also read `<workdir>/design/extension-design.json` and `<project_root>/extension/README.md`, and propose `widgetActions` on dashboards whose role permissions warrant POSTing to extension endpoints.
+- `extension-only` (optional, boolean, default `false`) — when `true`, DO NOT regenerate the full design. Read the existing `<workdir>/design/dashboards.json`, OVERLAY `widgetActions` for new extension endpoints onto the dashboards whose roles warrant them, and write the file back. Every other field is preserved verbatim.
+
+### workdir verification (before any read or write)
+
+Before touching disk, verify the orchestrator-supplied `workdir`:
+
+```bash
+[[ "$workdir" = /* ]] || { echo "Error: workdir '$workdir' must be an absolute path (received from /create-solution Step 1c)"; exit 1; }
+[ -f "$workdir/design/architecture-overview.md" ]                || { echo "Error: '$workdir/design/architecture-overview.md' missing — design-solution-architecture did not write it; aborting"; exit 1; }
+[ -f "$workdir/design/entity-profiles.json" ] || { echo "Error: '$workdir/design/entity-profiles.json' missing — Phase 1 stage 2b did not write it; aborting"; exit 1; }
+[ -f "$workdir/design/relations.json" ]       || { echo "Error: '$workdir/design/relations.json' missing — Phase 1 stage 2c did not write it; aborting"; exit 1; }
+[ -f "$workdir/design/iam.json" ]             || { echo "Error: '$workdir/design/iam.json' missing — Phase 1 stage 2c did not write it; aborting"; exit 1; }
+[ -f "$workdir/design/metrics.json" ]         || { echo "Error: '$workdir/design/metrics.json' missing — Phase 1 stage 2d did not write it; aborting"; exit 1; }
+[ -f "$workdir/design/alarms.json" ]          || { echo "Error: '$workdir/design/alarms.json' missing — Phase 1 stage 2e did not write it; aborting"; exit 1; }
+if [ "$extension_enabled" = "true" ]; then
+  [ -f "$workdir/design/extension-design.json" ] || { echo "Error: '$workdir/design/extension-design.json' missing — extension-enabled=true but the extension-design stage did not write it; aborting"; exit 1; }
+fi
+```
+
+If any check fails, stop the skill — do **not** create directories yourself, do **not** fall back to deriving a path from a slug. A failed check is an upstream bug to surface, not to paper over.
+
+## Step 1 — Set dashboard scope
+
+Default: one dashboard per IAM role. This is a recommendation, not a hard rule — produce more dashboards for a role when the user explicitly asks for it, or when the role's responsibilities cover distinct workflows that a single dashboard would crowd (e.g. an operator role overseeing both fleet ops and maintenance may warrant separate dashboards).
+
+Write `{"dashboards": []}` to `<workdir>/design/dashboards.json` and return immediately when the original solution request explicitly says `no dashboards`, `skip dashboards`, `without dashboards`, or equivalent.
+
+## Step 1b — Extension-only overlay branch (only when `extension-only=true`)
+
+If `extension-only=true`, do **NOT** regenerate the design. The existing `<workdir>/design/dashboards.json` is the authoritative source of `name`, `assignedTo`, `overview`, `useCases`, and `userRequirements` for every dashboard — those fields are preserved verbatim. Load the existing file into memory, then **skip Steps 2.5, 3, and 4 in their fresh-generation form** and jump straight to **Step 3b** (the dedicated overlay step) which walks each existing dashboard and overlays `widgetActions` from `extension-design.json` based on role permissions and entity dependencies. After Step 3b writes the file back, return immediately — Step 4 is skipped because Step 3b already owns the write.
+
+If the existing `<workdir>/design/dashboards.json` is missing when `extension-only=true`, stop with a clear error — overlay cannot run without a prior approved design.
+
+When `extension-only=false` (default), ignore this step and proceed top-to-bottom from Step 2.
+
+## Step 1c — From-existing mode (only when `from-existing=true`)
+
+The user already has dashboards on the instance, pulled under `<workdir>/dashboards/`. **Design from those — follow the existing dashboards; do not invent one per role and do not recreate them.** This mirrors how `design-solution-architecture` reverse-engineers existing entities.
+
+1. **Discover** the pulled dashboards: scan `<workdir>/dashboards/*.json`. If there are none, `from-existing` has nothing to reverse-engineer — fall through to the fresh flow (Steps 2–4, one dashboard per role).
+2. **Reverse-engineer one design entry per existing dashboard.** For each pulled dashboard file, read it and derive its design entry faithfully — do not redesign it:
+   - `name` ← the dashboard's title (verbatim).
+   - `assignedTo` ← the role it serves (from its assignment / owning customer in the JSON; if not resolvable, the closest `iam.json` role, else leave the existing assignment).
+   - `overview` ← a 1–2 sentence summary of what the dashboard already does.
+   - `useCases` ← derived from the dashboard's actual states and widgets, grouped into the five categories — describe what the dashboard *already lets users do*, not an idealized redesign.
+   - Mark these as imported (they are **not** listed in `added`).
+3. **Apply `additions`** (when non-empty) onto this reverse-engineered set — never by starting over:
+   - A change to an existing dashboard (surface a new key/alarm, adjust a use case) → fold it into that dashboard's entry; record the dashboard name and the changed/added use case(s) in the top-level `added: [string]` array.
+   - A **new** dashboard → add one **only when the user explicitly asked for a new dashboard**. Otherwise prefer extending an existing dashboard. Any genuinely new dashboard's name goes in `added`.
+   - Entity-driven changes (a profile/role/key added this run) → surface them on the dashboard(s) whose role already covers that area, as a change to the existing entry — not a new dashboard.
+4. **Do not add a dashboard for a role that doesn't already have one** unless `additions` explicitly calls for it. Following the existing set is the point.
+5. Write the merged set to `<workdir>/design/dashboards.json` (Step 4 format), then return. Skip the fresh per-role derivation in Step 3.
+
+`create-solution`'s Step 2 reads the `added` array to label each dashboard `[imported]` (reverse-engineered) or `[new]` (added/changed this run), exactly as it does for entities.
+
+## Step 2 — Read the overview capability doc
+
+Single file read:
+
+- `@$TB_RESOURCES/prompts/solutions/dashboard/resources/ba-overview/ba-dashboard-overview-capabilities.md` — use-case categories (Entity Overview, Entity Management, Monitoring & Statistics, Alarm Handling, Navigation) and the shape of a dashboard overview.
+
+## Step 2.5 — Read the extension surface (only when `extension-enabled=true`)
+
+Skip this step when `extension-enabled=false`.
+
+Otherwise:
+
+1. Resolve the project root: `project_root="$(dirname "$(dirname "$workdir")")"`.
+2. Read `<workdir>/design/extension-design.json` for the full endpoint contract (request/response shapes, custom roles, dashboards referenced by name).
+3. Read `<project_root>/extension/README.md` if it exists. The README is the authoritative surface of what the built extension actually exposes; parse its `## Features` section to enumerate endpoints by feature, method, path, auth, and return summary. Use the deterministic helper at `src/thingsboard_cli/core/extension_manifest.py::parse_file`:
+
+   ```bash
+   PROJECT_ROOT="$project_root" python3 -c "import os, json; from pathlib import Path; from thingsboard_cli.core.extension_manifest import parse_file; m = parse_file(Path(os.environ['PROJECT_ROOT']) / 'extension' / 'README.md'); print(json.dumps([{'slug': f.slug, 'endpoints': [{'method': e.method, 'path': e.path, 'auth': e.auth, 'returns': e.returns} for e in f.endpoints]} for f in m.features]))"
+   ```
+
+   (Pass `$project_root` through an env var to avoid shell quoting bugs when the path contains spaces.) If the README does not exist yet (the extension hasn't been built — e.g. design ran before Step 3.5), rely on `extension-design.json` alone.
+
+4. When proposing use cases for a role, include `widgetActions` in that dashboard's entry — but only for roles whose permissions warrant the action (e.g. a viewer role without CRUD on the target resource does not get a "create profile" button). Each action references a single extension endpoint by its path.
+
+## Step 3 — Derive one dashboard per role
+
+**Skip this step entirely when `from-existing=true` and Step 1c found existing dashboards** — that mode already wrote `dashboards.json` from the pulled dashboards plus any additions. This fresh per-role derivation runs only for fresh designs (or when `from-existing=true` but no dashboards were on disk).
+
+For each role in `iam.json.roles`, build a `dashboardOverview`:
+
+- `name` — dashboard title
+- `assignedTo` — role name
+- `overview` — 1–2 sentences on what this dashboard is for
+- `useCases` — grouped by the five categories above
+- `userRequirements` (optional) — concise natural-language summary of any dashboard preferences the user stated in the original solution request or in conversation messages (widget types, layout, styling, colors, specific visualizations). HIGH PRIORITY — overrides default generation decisions. Omit the field when no preferences apply to this dashboard.
+
+At the start of this step, `Read` all six per-stage design files in a single batch: `<workdir>/design/architecture-overview.md`, `<workdir>/design/entity-profiles.json`, `<workdir>/design/relations.json`, `<workdir>/design/iam.json`, `<workdir>/design/metrics.json`, `<workdir>/design/alarms.json`. Use them as follows:
+
+- `architecture-overview.md` — free-form markdown overview. The H1 title and the Summary section provide the solution title and summary for dashboard naming and overview prose.
+- `entity-profiles.json.deviceProfiles` / `entity-profiles.json.assetProfiles` — telemetry/attribute keys that monitoring and overview use cases may reference.
+- `entity-profiles.json.customerProfiles` / `entity-profiles.json.userProfiles` — customer/user context (drives multi-tenant nuances).
+- `relations.json.entityRelations` — parent/child structure for navigation use cases.
+- `iam.json.roles` — the role list this skill iterates over and each role's permissions (drives management-action gating).
+- `metrics.json.calculatedFields` — calculated-field definitions (semantic context: which metric produces which output, expression summary, attachedTo profile). The keys themselves (both raw inputs and calculated-field outputs) all live in `entity-profiles.json` after `metrics-designer` extends it in place — there is no separate `addedProfileKeys` list.
+- `alarms.json.alarms` — alarm rules available for alarm-handling use cases.
+
+Customer mode is derived locally: `customerMode = (entity-profiles.json.customerProfiles.length > 0) ? "customer-hierarchy" : "tenant-only"`.
+
+Ground every use case in what actually exists in those files: monitoring only for telemetry keys that exist in `entity-profiles.json` (raw or metric-derived — both are in the same `telemetry[]` list after `metrics-designer` runs), alarm handling only for alarms that exist, management actions only for operations the role's permissions allow (CRUD/RU/R).
+
+**RU permission scope.** RU's "edit" covers updates to both **configuration attributes** (thresholds, names, static settings) and **operational shared/server attributes** (setpoints, toggles, commanded state — e.g. `plugState`, `targetTemperature`). It does **not** cover RPC commands or writes to telemetry keys — those require write permission on the device.
+
+**Floor plan per navigation state.** When a state has indoor positioning, it uses the **focal entity's** floor plan — never the parent's or a deeper descendant's. Direct children render as markers on it. At each navigation level, the floor plan switches to that level's entity: Home state shows Home's floor plan with Room markers; Room state shows Room's floor plan with device markers.
+
+**Use-case depth test — the mental replacement check.** A right-sized use case names the entity and the data/action, never the widget class, state name, size, or layout. Test it: mentally strip words like *table*, *card*, *chart*, *map*, *sizeX=12*, *column*, *row*. If the use case still reads, it's at the right level. If it falls apart without them, you've smuggled widget decisions in — rewrite with plain-English data and user action instead.
+
+### Entity-kind correctness rules (HARD RULES — applied to every use case)
+
+These three rules prevent a class of bug where a use case names entity X but the keys it shows live on entity Y. When the dashboard generator renders such a use case, it produces a widget whose datasource resolves to X but whose data keys belong to Y — empty columns at best, broken drill-downs at worst. Phrase every use case so X and Y are the same entity, or the relation between them is explicit in the use case.
+
+#### Rule 1 — Customer-as-container
+
+A **customer profile** in a customer-scoped solution is typically a **container**, not a data entity. The customer record carries no domain telemetry/metric/alarm keys — those live on the customer's scope-asset(s) (reached via the `Manages` relation from `relations.json`, 1:1 or 1:M). Apply this rule per role:
+
+- **Customer-level role** (role's userProfile has `scope = <customerProfileName>`): the dashboard entry point is the **scope-asset**, not the customer collection. The customer is implicit (`currentCustomer`); do not generate "list customers", "view customer details", or any use case whose primary entity is a customer. Per the `Customer-Level Role` rule in `ba-dashboard-overview-capabilities.md`.
+
+- **Tenant-level role** that legitimately needs cross-customer browsing: pick **one** of two patterns, never mix them. Pattern choice is driven by the role's permissions, not by how much info the customer carries:
+  - **Pattern (b) — customer-list → customer-detail → asset-detail.** **Default for CRUD and RU roles** (admins / managers who need to manage entities across the hierarchy). The root state lists customers with customer-owned keys only (title, address, contract, etc. — never telemetry that lives on the scope-asset). Row-click drills to a customer-detail state that shows:
+    - The customer's own attributes (always — even if sparse, the customer-detail state exists to anchor the hierarchy).
+    - A list of the scope-asset(s) owned by that customer (filtered by the customer-as-state-entity).
+    - For CRUD roles: a "Create asset under this customer" action button on the asset list (uses `addEntity` dialog with the customer pre-selected as owner).
+    - For CRUD roles on customer keys: edit / delete actions on the customer's own attributes.
+    Row-click on a scope-asset drills further to the asset-detail state, passing the asset UUID. Two-step navigation: customer-list → customer-detail → asset-detail. This pattern reflects how an admin actually works — they need a place to *create* assets under a specific customer and to *manage* the customer record itself; the customer-detail state is that anchor even when its own data is sparse.
+  - **Pattern (a) — list scope-assets with an owner column.** **For R (read-only) tenant-level roles** that need a flat operational view across customers without management actions. List the scope-asset directly at root, add a column derived from the asset → owning customer relation showing the customer's name, and (when the role has RU or CRUD on the asset's ownership) an optional row action to reassign the owner. Drill-down passes the scope-asset's UUID to the asset-detail state. Skips the customer-detail intermediate — fine for view-only flows because there's nothing to manage on the customer side.
+
+  Picking the pattern: start from the role's permissions. CRUD/RU → pattern (b). R → pattern (a). When uncertain, default to pattern (b) — admins skipping the customer layer feels broken because they lose the natural place to create / edit / delete entities under a customer.
+
+#### Rule 2 — Use-case entity check (every bullet, before finalizing)
+
+For each use case bullet:
+
+1. Identify every entity profile name mentioned.
+2. Identify every telemetry / metric / alarm key mentioned (cross-reference `entity-profiles.json.{deviceProfiles,assetProfiles}[].telemetry/attributes` and `metrics.json.calculatedFields[].attachedTo` + `alarms.json.alarms[].attachedTo`).
+3. For each key, confirm the use case names an entity that **owns** that key. If the named entity is a parent/customer and the key lives on a child/scope-asset, the bullet is wrong — rewrite to either:
+   - Replace the entity with the one that owns the key (e.g. "Display Districts (one per District Operator customer) with current AQI" instead of "Display District Operators with current AQI"), or
+   - Make the relation traversal explicit ("For each District Operator, show the AQI of the District it manages" — but only when you really want a customer row and the AQI is a related column, which then forces pattern (b) from Rule 1).
+
+**Canonical anti-example (from a real failing dashboard):** a "District Operators" widget in the tenant-admin City AQI dashboard, datasource alias resolving to CUSTOMER entities (the District Operator customer group), `dataKeys = ["title", "avgDistrictAqi", "districtAqiCategory"]` — but `avgDistrictAqi` and `districtAqiCategory` live on the District ASSET, not on the customer. The rendered widget showed customer names with empty AQI columns, and the row-click passed a customer UUID into a `district-detail` state that expected an asset UUID — every alias in the detail state broke. The fix: switch the alias to `"All Districts"` (asset), add a column derived from the District→Customer owner relation, and let the row-click pass the District UUID (pattern (a) above).
+
+#### Rule 3 — Navigation explicitness
+
+Every navigation / drill-down use case must:
+- Name the **source entity kind** (what the user clicks on) — e.g. "from the Districts list" or "from a Customer row".
+- Name the **target entity kind** the detail state is built around — e.g. "drill into a District to see its sensors".
+- The source kind and target kind must match. The drill-down's `setEntityId` will pass the source row's UUID; the target state's primary alias must accept that kind.
+
+If the user benefit calls for navigating across kinds (e.g. customer → asset), express it as two hops: customer-list → customer-detail (kind-matched) → asset-detail (kind-matched). Never write a single use case like "drill from customer X to asset Y details" — that's a kind mismatch by construction.
+
+## Step 3b — Overlay widgetActions on existing dashboards (only when `extension-only=true`)
+
+This step runs **instead of** Steps 2.5, 3, and 4 when `extension-only=true` (see Step 1b). It is the only path that mutates `<workdir>/design/dashboards.json` in overlay mode.
+
+1. Resolve the project root: `project_root="$(dirname "$(dirname "$workdir")")"`.
+2. Read `<workdir>/design/extension-design.json` (required — stop with a clear error if missing) for the endpoint contract, custom roles, and dashboards-referenced-by-name. Also read `<project_root>/extension/README.md` if it exists (parse via `src/thingsboard_cli/core/extension_manifest.py::parse_file` as shown in Step 2.5) to confirm which endpoints are actually exposed by the built extension.
+3. Read `<workdir>/design/iam.json` to resolve each existing dashboard's `assignedTo` role to its permission set.
+4. Read the existing `<workdir>/design/dashboards.json` into memory. Iterate each dashboard:
+   - Determine the candidate endpoints from `extension-design.json` whose purpose maps to actions the dashboard's role permissions warrant (CRUD/RU/R — same gating rule as Step 3). A viewer role without CRUD on the target resource does **not** get a "create" button.
+   - For each warranted endpoint, build a `widgetActions` entry `{endpoint, label, inputSchema}` and add (or merge with) the dashboard's existing `widgetActions` array. Do **not** duplicate an entry that already references the same endpoint.
+   - Leave dashboards with no warranted action unchanged (do not introduce an empty `widgetActions` array — omit the field entirely).
+5. **Preserve every other field verbatim** on every dashboard: `name`, `assignedTo`, `overview`, `useCases`, `userRequirements`. Only `widgetActions` may be added or extended.
+6. Write the updated object back to `<workdir>/design/dashboards.json` using the `Write` tool.
+7. Print one confirmation line:
+
+   ```
+   dashboards design updated at <workdir>/design/dashboards.json: widgetActions overlaid on <N> dashboards
+   ```
+
+Return immediately after this step — Step 4 is owned by the fresh-generation flow and must not run again.
+
+## Step 4 — Write the `dashboards` JSON file
+
+Build the JSON object with the structure shown below and write it to `<workdir>/design/dashboards.json` using the `Write` tool. On revision, this overwrites the existing file. The on-disk file is the only authoritative artifact — keep the JSON contents out of the conversation.
+
+````markdown
+```json
+{
+  "dashboards": [
+    {
+      "name": "Facility Operations",
+      "assignedTo": "FacilityManager",
+      "overview": "Monitor all rooms in the building, track temperature and humidity, and handle environmental alarms.",
+      "useCases": {
+        "entityOverview": ["View all rooms in the building with current temperature and humidity"],
+        "entityManagement": [],
+        "monitoringStatistics": ["Compare average temperature across rooms over the last 24 hours"],
+        "alarmHandling": ["View and acknowledge HighTemperature alarms"],
+        "navigation": ["Drill into a room to see its sensor detail"]
+      },
+      "userRequirements": "Use a dark theme with a building floor-plan map on the root state.",
+      "widgetActions": [
+        {
+          "endpoint": "/api/extension/user-profiles",
+          "label": "Create profile",
+          "inputSchema": {
+            "name": "string",
+            "defaultDashboardName": "string",
+            "roleNames": "string[]"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+````
+
+`widgetActions` is optional. Include it only when `extension-enabled=true` AND the role's permissions warrant the action. Omit the field entirely when the array would be empty.
+
+Then print one line confirming the file was written, in this format:
+
+```
+dashboards design written to <workdir>/design/dashboards.json: <N> dashboards
+```
+
+(Or `0 dashboards` if Step 1 skipped.)
+
+<instructions>
+- Output: One dashboard definition per IAM role, each with `name`, `assignedTo`, `overview`, `useCases`, and optionally `userRequirements`. Written to `<workdir>/design/dashboards.json`; do not print the JSON to the conversation.
+- User Requirements: Consolidate dashboard preferences from the user's original solution request and any subsequent conversation messages (widget types, layout, styling, colors, specific visualizations) into a concise natural-language summary on the relevant dashboard's `userRequirements` field. User requirements have HIGH PRIORITY — they override default generation decisions. If no preferences apply, omit the field.
+- Permission application: Map each role's permission level to use-case verbs per `<permissions>` above (CRUD → create/view/edit/delete; RU → view/edit; R → view/monitor only).
+</instructions>
+
+<rules>
+- Default to one dashboard per IAM role; use the exact role name for `assignedTo`. Generate additional dashboards for a role only when the user explicitly asks, or when the role's distinct workflows cannot fit a single dashboard — in either case, give each dashboard a distinct, descriptive name and reuse the same `assignedTo` role.
+- Analyze entity attribute keys and telemetry keys to determine which visualizations and use cases are applicable for each entity.
+- Use `entity-profiles.json.customerProfiles.length` to identify the solution type (multi-root vs single-root) — it drives `customerMode`.
+- Use cases describe WHAT the user can do, not HOW it is implemented (apply the mental replacement check above).
+- Each dashboard targets ~10 use cases as a default — this is a recommendation, not a hard cap. Go above when the user explicitly asks for more or when the role's responsibilities genuinely require more use cases to cover the workflow. Stay below when there's nothing meaningful left to add.
+- Follow the solution types, navigation hierarchy, use case structure, visualization support, and ability description patterns defined in `ba-dashboard-overview-capabilities.md`.
+- IMPORTANT: In JSON string values, use real newline characters for line breaks, never the literal escape sequence `\n` doubled (`\\n`).
+- `widgetActions.inputSchema`: when a field carries a TB entity reference (dashboard, customer, role, device, asset), use the entity NAME (or stable slug) as the value type — never a UUID. The extension resolves names to UUIDs at request time. UUIDs would break across `tb push` targets (dev/test/prod each have their own).
+- `extension-only=true`: do NOT regenerate `useCases`, `overview`, `name`, `assignedTo`, or `userRequirements` on existing dashboards. Read the existing `dashboards.json`, set or extend each dashboard's `widgetActions` array as needed, and write the file back. Dashboards whose role doesn't warrant any new action are written back unchanged.
+</rules>
+
+<resources>
+The resources that you must use:
+- `ba-dashboard-overview-capabilities.md` — Solution types, navigation hierarchy, use case categories, visualization support, and ability description patterns (read once in Step 2).
+- `<workdir>/design/architecture-overview.md` plus `<workdir>/design/{entity-profiles,relations,iam,metrics,alarms}.json` — Six per-stage design files read in Step 3 as the authoritative source for entities, profiles, telemetry, relations, roles, computed metrics, and alarms.
+</resources>
+
+## Partial regeneration (`regen-targets=[<names>]`)
+
+When the orchestrator passes `regen-targets=[<dashboard-name>, …]` along with `revise=true`, regenerate only the listed dashboards in `dashboards.json`. Leave every other entry untouched. Used by `create-solution` Step 3.7 when only a subset of dashboards is affected by an added key.

thingsboard_cli/scaffold/.claude/skills/design-solution-architecture/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: design-solution-architecture
+description: "Designs the solution end-to-end. Drafts the architecture overview using the live interview context, then dispatches subagents for entity profiles, relations + IAM (parallel), metrics, alarms. Each stage writes a per-stage file under <workdir>/design/."
+user-invocable: false
+---
+
+# Design Solution Architecture
+
+Orchestrator for the full design phase. Step 1 uses the live interview context to draft the architecture overview; Steps 2–5 dispatch specialist subagents that read inputs from disk.
+
+## User and design needs override defaults
+
+The defaults, counts, structural patterns, and limits in this skill (and the subagents it dispatches) are **recommendations**, not hard gates. Override them when either:
+
+- The user explicitly asks for something that exceeds or contradicts the default (more demo entities per profile, more customers per customer profile, more dashboards per role, more use cases per dashboard, a different structural pattern), **or**
+- The solution's own pattern coherently needs more — e.g. a fleet-tracking demo needs ~20 vehicles for a meaningful map; a multi-floor building needs one asset per floor; a parent–child hierarchy needs enough children to demonstrate aggregation; a multi-tenant SaaS demo needs several customer instances per customer profile; a complex operator role may warrant multiple dashboards. Pick counts that let the dashboards, metrics, and relations actually demonstrate the pattern, not a token sample.
+
+In both cases, scale the design up (or down) to fit. No silent capping, no pushback.
+
+Exceptions: anything called out as a "hard rule" in a dispatched subagent, and safety-critical invariants the downstream generators depend on (byte-for-byte name matching, schema correctness, customer-pairing alignment). Defaults still apply when the user is silent and the pattern doesn't demand more.
+
+## ThingsBoard concepts
+
+Before starting, `Read` `src/thingsboard_cli/resources/prompts/ai-assistant/main-assistant-prompt.md` for the canonical reference on core ThingsBoard concepts (tenants, customers, devices, assets, profiles, attributes, telemetry, relations). These definitions govern how the design phase models entities, ownership, and relations — defer to them when phrasing the architecture overview and downstream stages.
+
+## Inputs from /create-solution
+
+- `slug` — used for narration; not written into any design file.
+- `workdir` — absolute path to solution dir, created in /create-solution Step 1c. Treat as opaque — do not re-derive from `slug` or cwd, do not run `realpath solutions/<slug>` yourself.
+- `revise` (optional) — `false` for fresh design. When `true`, see Revision Flow below.
+- `extension-enabled` (optional, boolean, default `false`) — when `true`, run the additional `extension-design` stage between relations and IAM. The stage's `entityDependencies.customRoles` then fold into IAM as first-class roles.
+- `from-existing` (bool, default `false`) — when `true`, skip the "draft architecture from interview context" pass entirely. Each stage subagent runs in *extract* mode (read pulled JSON in `<workdir>/` and synthesize its stage file from that data). The orchestrator writes `architecture-overview.md` last from the stage files. Used by `create-solution` Step 1f for instance-import and resume-with-missing-design cases.
+- `additions` (optional string, only meaningful with `from-existing=true`) — a brief describing net-new artifacts the user asked for *on top of* the imported entities (e.g. "add a VibrationSensor device profile with rms/peak telemetry", "add a HighTemp alarm on the Boiler profile"). When present, the orchestrator folds these into the design in the same pass — see **Additions in from-existing mode** below. When empty/absent, `from-existing` behaves as a pure extract.
+
+## Step 1 — Write the architecture overview
+
+Use the live interview context — the user's answers, clarifications, and side comments — directly. `solution-capabilities.md` is already in conversation context (loaded in /create-solution Step 1a — do not re-read).
+
+### Draft the markdown
+
+Write `<workdir>/design/architecture-overview.md` as a single markdown document following the structured template below. The section **headings** and **order** are fixed (downstream readers find sections by literal H1/H2 match); the **contents** inside each section follow the per-section format rules — prose for narrative sections, tables for structured ones.
+
+### Template
+
+```markdown
+# <Solution Name>
+
+## Summary
+
+<2–4 sentences describing what the solution does. May extend the user's stated scope with inferred context but must not contradict it.>
+
+## User Requirements
+
+<One bullet per cross-cutting parameter the user specified in the original request or conversation (timings, thresholds, intervals, severities, demo durations). Phrase each as: **scope** — **value** (user stated). **Affects:** which downstream stages must honor it. These requirements **override** defaults wherever they apply (emulator tick, alarm windows, CF aggregation windows, threshold values). When the user stated nothing cross-cutting, write `_(none — defaults apply)_` and end the section.>
+
+Examples:
+- **Telemetry interval — `AirQualitySensor.aqi`: 10 min** (user stated). **Affects:** emulator generation tick (override default 30 min); ts-aggregation CF windows on this key.
+- **Alarm window — `District` HighAvgAQI: 15 min sustained** (user stated). **Affects:** alarm rule `condition.spec.unit/value`; any ts-aggregation CF backing this alarm.
+- **Threshold — `AirQualitySensor.aqi > 150 = unhealthy`** (user stated). **Affects:** alarm condition; thresholded calculated fields.
+- **Demo data span — 30 days of history** (user stated). **Affects:** emulator `days` parameter.
+
+## Device & Asset Profiles
+
+### <Profile Name 1> (DEVICE | ASSET)
+
+<Prose listing every key the profile reports or holds. For each key: name, dataType, units, min/max, allowed values where known. Cover both telemetry-style and configuration-style keys.>
+
+### <Profile Name 2> (DEVICE | ASSET)
+
+<…>
+
+## Customers & Users
+
+<One short paragraph stating whether the solution is tenant-only or uses customer hierarchy, plus any context the tables below don't capture.>
+
+### Customer Profiles
+
+| Name | Parent | Description |
+|---|---|---|
+| <exact customer profile name> | Tenant \| <parent customer profile name> | <one-line role/purpose> |
+
+### User Profiles
+
+| Name | Scope | Description |
+|---|---|---|
+| <exact user profile name> | Tenant \| <customer profile name> | <one-line role/purpose> |
+
+## Relations
+
+<Prose covering every structural parent-child link with direction and cardinality (1:1, 1:M, M:M). Be explicit about which side is parent and which is child — `relations-designer` parses this into structured rows.>
+
+## Metrics
+
+- <One bullet per calculated field: owning profile, what it computes from which inputs, what it represents. Phrase well enough that the architect can pick a calculated-field type (`math`, `script`, `ts-aggregation`, `related-aggregation`, `propagate`, `geofencing`, `delta`).>
+
+## Alarms
+
+- <One bullet per alarm: owning profile, condition in business terms, severity (single or multi-level). Do not write in calculated-field syntax.>
+
+## Demo Entities
+
+| Profile | Count | Customer Profile |
+|---|---|---|
+| <exact profile name> | <N> | <customer profile name or —> |
+```
+
+### Per-section rules
+
+**Headings.** Keep every H1 / H2 / H3 heading exactly as shown (`## Summary`, `## User Requirements`, `## Device & Asset Profiles`, `### <Profile> (DEVICE | ASSET)`, `## Customers & Users`, `### Customer Profiles`, `### User Profiles`, `## Relations`, `## Metrics`, `## Alarms`, `## Demo Entities`). Order is fixed. Downstream consumers match these headings literally.
+
+**User Requirements.** Scan the original solution request and every conversation message for cross-cutting parameters the user explicitly stated — timings (telemetry frequency, alarm windows, demo span, schedule cadence), thresholds (alarm trigger values, expected ranges), severities, retention spans, units, and any other "do it this way" instructions that affect more than one downstream stage. Convert each to a one-line bullet using the format shown in the template, and list which downstream stages must honor it under **Affects:**. This section is the contract downstream stages (`metrics-designer`, `alarms-designer`, `device-emulator-generator`, `attribute-values-generator`, etc.) read and respect. Do **not** invent requirements the user did not state — if the user said nothing cross-cutting, write `_(none — defaults apply)_` and let downstream defaults run. User requirements override every documented default in this skill and in dispatched subagents (per the top-level "User and design needs override defaults" rule).
+
+**Device & Asset Profiles.** One `### <Profile Name> (DEVICE | ASSET)` subsection per profile. Apply the device-vs-asset rule from `solution-capabilities.md` to pick the suffix. Profile name in the H3 heading is the canonical spelling — every other reference (Demo Entities table, prose) must match it byte-for-byte.
+
+**Customers & Users.**
+- Always include both tables, even when empty.
+- The `## Customers & Users` paragraph states tenant-only vs customer-hierarchy in one sentence; mention sub-customer depth if the solution uses it.
+- For tenant-only solutions, the Customer Profiles table has a single row with `— | — | (none — tenant-only)`. For customer-hierarchy solutions, one row per customer profile.
+- The Customer Profiles `Parent` column is `Tenant` for top-level customer profiles, or the exact name of another customer profile from this same table for sub-customer profiles. Sub-customer chains of arbitrary depth are allowed; cycles are not.
+- The User Profiles table always has at least one tenant-level admin row (`Scope = Tenant`). For `CUSTOMER_USER`-style profiles, `Scope` is the exact customer profile name from the Customer Profiles table.
+
+**Demo Entities.**
+- The table is the single source of truth for instance counts across **all** profile kinds — DEVICE, ASSET, CUSTOMER, and USER profiles all appear here. `entities-planner` parses this table to know how many of each to create.
+- `Profile` matches a profile name byte-for-byte against one of:
+  - The `### <Profile Name> (DEVICE | ASSET)` H3 headings (for DEVICE / ASSET rows).
+  - The `### Customer Profiles` table's `Name` column (for CUSTOMER rows).
+  - The `### User Profiles` table's `Name` column (for USER rows).
+- `Count` defaults per profile kind:
+  - DEVICE / ASSET — defaults to **5 per profile** for a usable demo dataset.
+  - CUSTOMER — defaults to **1 per profile**.
+  - USER — defaults to **1 per profile**.
+  All three are recommendations, not hard caps. Override when (a) the user explicitly asks for a different number, or (b) the solution's pattern needs more to be meaningful — e.g. a fleet-tracking demo benefits from ~20 vehicles for a usable map; a multi-tenant SaaS demo needs several CUSTOMER instances; a multi-operator workflow needs several USER instances of the operator role; a parent–child hierarchy needs enough children to show aggregation. Pick counts that let dashboards, metrics, and relations actually demonstrate the pattern.
+- `Customer Profile` column rules per kind:
+  - DEVICE / ASSET rows: exact customer profile name when the solution uses customer hierarchy AND that customer profile exists; otherwise `—`.
+  - CUSTOMER rows: must match the customer profile's `Parent` column from `### Customer Profiles`. When `Parent = Tenant`, the cell is `—`. When `Parent` names another customer profile, the cell is that profile name (a sub-customer is owned by an instance of its parent customer profile).
+  - USER rows: must match the `Scope` value from the `### User Profiles` table — exact customer profile name for customer-scoped users, `—` for tenant-scoped users.
+  - For tenant-only solutions, every row's Customer Profile column is `—`.
+- Row presence:
+  - DEVICE / ASSET: one row per profile that should have demo instances (omit rows with Count=0).
+  - CUSTOMER: one row per entry in `### Customer Profiles` (skip in tenant-only solutions where that table holds only the placeholder row).
+  - USER: one row per entry in `### User Profiles`.
+- Customer-scoped fan-out semantics — Count is **per customer instance** for every customer-scoped row (DEVICE, ASSET, USER, sub-customer CUSTOMER). The same natural reading applies across all kinds, so the architect never has to multiply by customer-instance count manually.
+  - DEVICE / ASSET — if `District | 5 | DistrictCustomer` and DistrictCustomer has Count=3, the planner creates 5 Districts per customer for 15 total.
+  - USER — if `DistrictSupervisor | 1 | DistrictCustomer` and DistrictCustomer has Count=3, the planner creates 1 supervisor per customer for 3 total (one per district). Every customer instance gets at least Count users of the profile; no customer is left without a user of a customer-scoped profile.
+  - Sub-customer CUSTOMER — if `Branch | 2 | Region` and Region has Count=3, the planner creates 2 Branches per Region instance for 6 total. Sub-customer chains compose multiplicatively the same way.
+- **Tenant-scoped USER Count** (Customer Profile column is `—`) is the **literal total** number of users of that profile — e.g. `CityAQIAdministrator | 2 | —` creates 2 tenant admins total.
+
+Author the Demo Entities table early (decide profiles + counts + customer ownership) — it's the canonical source of demo dataset facts and the rest of the document should not contradict it.
+
+Emit narration: `▸ architecture overview done`.
+
+## Step 2 — Dispatch entity-profiles-designer
+
+`Agent` with `subagent_type=entity-profiles-designer`, `description="design entity profiles"`, and brief: just `workdir`. Wait for completion. Verify `<workdir>/design/entity-profiles.json` exists. Stop on failure.
+
+**When called with `from-existing=true`** — the subagent reads `<workdir>/device-profiles/*.json`, `<workdir>/asset-profiles/*.json`, `<workdir>/customers/*.json`, and `<workdir>/users/*.json` and synthesizes `<workdir>/design/entity-profiles.json` directly from these files (profile names, kinds, key schemas, customer/user profile metadata). No interview context is consulted. When a profile cannot be cleanly inferred from the pulled JSON (missing fields, ambiguous kind, unparseable schema), the subagent emits a one-line entry under the stage file's top-level `warnings: [...]` array.
+
+Emit narration: `▸ entity profiles done`.
+
+## Step 3 — Dispatch relations-designer + iam-designer
+
+### When `extension-enabled=false` (default) — parallel batch
+
+In ONE message with two `Agent` tool uses (single batch):
+
+- `subagent_type=relations-designer`, `description="design relations"`, brief: `{workdir}`
+- `subagent_type=iam-designer`, `description="design IAM"`, brief: `{workdir}`
+
+Wait for both. Verify `<workdir>/design/relations.json` AND `<workdir>/design/iam.json` exist. If either failed, surface the error and stop.
+
+**When called with `from-existing=true`** — both subagents run in extract mode (no interview context):
+
+- **relations-designer** scans `<workdir>/devices/*.json`, `<workdir>/assets/*.json`, and any other entity files for embedded `relations` arrays. It builds `<workdir>/design/relations.json` by collecting every unique `(fromType, toType, type)` triple. Any relation with a missing target (target entity not present locally) is added to the stage's `warnings: [...]` list.
+- **iam-designer** reads `<workdir>/customers/*.json`, `<workdir>/users/*.json`, `<workdir>/roles/*.json`, and `<workdir>/entity-groups/*.json`. It builds `<workdir>/design/iam.json`'s `roles` from role files (folding any `entityDependencies.customRoles` from `extension-design.json` when present) and derives `customerMode` from whether customers exist. Anything that cannot be cleanly inferred (orphan user with no role, role referenced from groups but missing on disk) is recorded under `warnings: [...]`.
+
+Emit narration: `▸ relations + iam done`.
+
+### When `extension-enabled=true` — serialise so extension custom roles fold into IAM
+
+The order becomes `relations` → `extension-design` → `iam` so IAM can close over `entityDependencies.customRoles` from the extension design.
+
+1. Dispatch `subagent_type=relations-designer`, `description="design relations"`, brief: `{workdir}`. Wait for completion. Verify `<workdir>/design/relations.json`. Stop on failure. Emit narration: `▸ relations done`.
+
+2. Run the **extension-design** stage inline (no separate subagent in v1 — the work is small and corrections happen at the orchestrator's approval gate):
+   - `Read` `<workdir>/design/architecture-overview.md` and `<workdir>/design/relations.json`.
+   - Using the live interview context plus the conversation history (specifically what the user said when they opted into extensions), build a JSON object with this shape:
+
+     ```json
+     {
+       "endpoints": [
+         {
+           "path": "/api/extension/<feature>",
+           "method": "POST",
+           "purpose": "<one sentence>",
+           "auth": "jwt",
+           "request": {"field": "type"},
+           "response": {"field": "type"},
+           "security": "TENANT_ADMIN"
+         }
+       ],
+       "scheduledTasks": [],
+       "entityDependencies": {
+         "customRoles": ["..."],
+         "dashboardsReferencedByName": ["..."]
+       }
+     }
+     ```
+
+     Reference TB entities **by name** (or stable slug), never by UUID — `tb push` is multi-target and UUIDs differ across dev/test/prod.
+
+   - Write the object to `<workdir>/design/extension-design.json` via the `Write` tool.
+   - Emit narration: `▸ extension design done`.
+
+3. Dispatch `subagent_type=iam-designer`, `description="design IAM"`, brief: `{workdir}`. The IAM designer reads `extension-design.json` if present and folds `entityDependencies.customRoles` into `iam.json.roles` as first-class roles. Wait. Verify `<workdir>/design/iam.json`. Stop on failure. Emit narration: `▸ iam done`.
+
+## Step 4 — Dispatch metrics-designer
+
+`Agent` with `subagent_type=metrics-designer`, `description="design metrics"`, and brief: just `workdir`. Wait. Verify `<workdir>/design/metrics.json`. Stop on failure.
+
+**When called with `from-existing=true`** — the subagent reads embedded `calculatedFields` arrays from `<workdir>/device-profiles/*.json` and `<workdir>/asset-profiles/*.json`, filters out entries with `type == "ALARM"`, and builds `<workdir>/design/metrics.json`'s `calculatedFields` list directly from what remains (owning profile, name, type, arguments, output, expression). No interview context is consulted. Any CF entry that cannot be cleanly inferred (malformed shape, unknown type, missing arguments) is added to the stage's `warnings: [...]` list.
+
+Emit narration: `▸ metrics done`.
+
+## Step 5 — Dispatch alarms-designer
+
+`Agent` with `subagent_type=alarms-designer`, `description="design alarms"`, and brief: just `workdir`. Wait. Verify `<workdir>/design/alarms.json`. Stop on failure.
+
+**When called with `from-existing=true`** — the subagent reads embedded `calculatedFields` arrays from `<workdir>/device-profiles/*.json` and `<workdir>/asset-profiles/*.json`, keeps only entries with `type == "ALARM"`, and builds `<workdir>/design/alarms.json`'s `alarms` list directly from what remains (owning profile, name, condition, severity, propagation). No interview context is consulted. Any alarm entry that cannot be cleanly inferred (malformed condition, missing severity, unparseable rule) is added to the stage's `warnings: [...]` list.
+
+Emit narration: `▸ alarms done`.
+
+## Step 6 — Return
+
+Print one summary line and return control to `/create-solution`:
+
+```
+design saved to <workdir>/design/: architecture-overview.md, entity-profiles.json, relations.json, iam.json, metrics.json, alarms.json[, extension-design.json]
+```
+
+Include `extension-design.json` in the summary list only when `extension-enabled=true`. The orchestrator (`/create-solution` Step 2) reads the files, renders a presentation, and owns the approval gate.
+
+## Revision flow
+
+When invoked with `revise=true, --stage <name>`:
+
+| Revised stage | Re-runs (in order) |
+|---|---|
+| `architecture-overview` | entity-profiles, relations, [extension-design when enabled], iam, metrics, alarms (every other stage) |
+| `entity-profiles` | relations, [extension-design when enabled], iam, metrics, alarms |
+| `relations` | when `extension-enabled=true`: extension-design → iam → metrics → alarms; when `extension-enabled=false`: iam, metrics, alarms |
+| `extension-design` | iam (custom roles may have changed); flag metrics + alarms for re-review if extension behavior they reference shifted |
+| `iam` | (none — no other design stage reads iam.json) |
+| `metrics` | alarms |
+| `alarms` | (none) |
+
+Re-dispatch follows the same Steps 1–5 ordering, skipping anything not in the cascade. After all required stages finish, return the same summary line as Step 6.
+
+## Additions in from-existing mode
+
+The extract/design pass **always runs** in `from-existing` mode — Steps 2–5 plus the overview write happen whether or not `additions` was passed. This section describes only the *extra* fold-in step that runs **additionally** when a non-empty `additions` brief is present. It lets `create-solution` produce a merged design — imported entities **plus** the user's net-new ask — in a single call, instead of extracting and then making a second revise pass. With no `additions`, skip this section entirely; the extract result is the final design.
+
+Sequence (only when `additions` is non-empty):
+
+1. **Extract first.** The Steps 2–5 extract pass has already run (it always does), so every stage file faithfully mirrors the pulled entities. Do not let the additions retroactively change those extracted entries — they must stay byte-accurate for idempotency with the instance.
+2. **Map the additions to stages.** Parse the `additions` brief into one or more entries and route each to the stage that owns it:
+
+   | Addition | Stage |
+   |---|---|
+   | new alarm rule | `alarms` |
+   | new calculated field / metric | `metrics` |
+   | new telemetry / attribute key, or new device/asset profile, or new entity instance | `entity-profiles` (a new instance also gets a `## Demo Entities` row in the overview) |
+   | new role / user profile | `iam` |
+
+3. **Append, then cascade.** For each affected stage, append the new entry to its stage file (and reflect it in `architecture-overview.md`'s matching section), then run the **Revision flow** cascade for that stage so downstream stages pick up the addition (e.g. a new profile cascades to relations → iam → metrics → alarms). Reuse the existing Revision-flow machinery — do not invent a parallel path.
+4. **Record what was added.** Every entry created while applying `additions` — the appended entry itself and anything the cascade derives for it — is recorded by name in its stage file's top-level `added: [string]` array. Extracted (imported) entries are never listed in `added`. This is the only signal `create-solution`'s Step 2 uses to label `[imported]` vs `[new]`, so it must be complete.
+
+## Warnings and additions aggregation (`from-existing=true`)
+
+Each stage subagent appends its warnings to its own stage file under a top-level `warnings: [string]` key, and (when `additions` ran) the names of entries it added under a top-level `added: [string]` key. The orchestrator's Step 2 gate reads the `warnings` arrays to render a "Warnings" section, and reads the `added` arrays to tag each design entry `[imported]` (extracted) or `[new]` (in `added`).