thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/scaffold/.claude/skills/generate-alarms/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: generate-alarms
+description: "Expands attachedTo fanout, then dispatches one alarm-generator Haiku subagent per (alarm, profile) pair in parallel. Each agent renders its alarm rule and saves it via `tb alarm-rule save`. The tb CLI applies a file-level lock during the read-modify-write on the parent profile's file, so concurrent saves from siblings targeting the same profile serialize at the lock — no race, no corruption. The skill only dispatches and aggregates."
+user-invocable: false
+---
+
+# Generate Alarms
+
+Thin orchestrator. Expands `attachedTo` fanout (string or array) into individual (alarm, profile) pairs, then dispatches one `alarm-generator` subagent **per pair** in parallel — every alarm-profile combination renders and saves concurrently in its own Haiku instance. The file-level lock inside `tb` makes concurrent writes to the same parent profile safe, so no separate save phase is needed.
+
+## Inputs from the orchestrator
+
+- `solution` — solution slug.
+- `workdir` — absolute path to the solution directory, created and verified by `/create-solution` Step 1c. Treat as **opaque** — do not re-derive from `solution`, do not re-verify. Must contain `design/alarms.json` and `design/entity-profiles.json`.
+
+## EXTREMELY IMPORTANT — anti-shortcut rules
+
+- Dispatch exactly `sum(len(attachedTo) for each alarm)` agents (treating a string `attachedTo` as length 1). No "representative subset," no skipping.
+- If any agent returns an error, surface every agent's output verbatim and stop. Do not advance to validation.
+
+## Step 1 — Load + expand fanout
+
+1. `Read` `$workdir/design/alarms.json`.
+2. If `alarms` is missing or empty, return `alarms: 0 rules across 0 profiles (validate=skipped)` and stop.
+3. **Expand fanout.** For each alarm entry whose `attachedTo` is an array, emit one logical (alarm, profile) pair per array element. For string `attachedTo`, emit one pair. The same `name`/`severity`/`createRules`/`clearCondition`/`propagate` repeats across the pairs — only the resolved profile differs.
+
+Expected save count: the total number of expanded (alarm, profile) pairs.
+
+## Step 2 — Dispatch one alarm-generator per pair in parallel
+
+In **one assistant message**, emit one `Agent` tool call per expanded pair. Subagent type: `alarm-generator`, `description="generate alarm rule"`. Each brief:
+
+- `solution`: the slug
+- `profile`: the single target profile name (string)
+- `alarm`: the single alarm design entry (inline JSON)
+- `entityProfilesJsonPath`: `$workdir/design/entity-profiles.json`
+
+For very large solutions (say, more than ~40 pairs), split the dispatch across successive messages — but **do not** group pairs into the same brief. The whole point is one generator per pair for maximum parallelism within each message.
+
+Wait for every agent to return. Each returns one of:
+
+- `alarm "<alarmName>" attached to "<profile>": saved` — success.
+- `error: alarm "<alarmName>" attached to "<profile>": <message>` — render or save failure.
+
+## Step 3 — Aggregate
+
+If any agent returned an error, surface every agent's output verbatim and stop. Do not advance to Step 4.
+
+If all succeeded, count the saves and check against the expected save count from Step 1. If short, stop with `error: expected <X> alarm saves, completed <Y>`.
+
+## Step 4 — Validate
+
+`tb validate <solution>`. Surface any errors verbatim.
+
+## Return value
+
+```
+alarms: <N> rules across <P> profiles (validate=<ok|errors>)
+```
+
+Where `<N>` is the total count of successful `alarm-generator` saves and `<P>` is the number of distinct profiles touched.
+
+## Skip-by-filesystem rule
+
+For each alarm rule entry in `alarms.json.alarms`, look up the parent profile/instance file under `<workdir>/`. If that file already has an alarm rule with the same `name` in its `calculatedFields` array (alarm rules embed as `type: ALARM` calculatedFields), **skip silently** — do not overwrite. Generate only alarm rules that are net-new on the target profile/instance.
+
+**Return contract.** Final summary line:
+
+```
+GENERATED added=<JSON: {alarms: [alarm-name-1, alarm-name-2, …]}>
+```

thingsboard_cli/scaffold/.claude/skills/generate-attributes/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: generate-attributes
+description: "Saves realistic static ATTRIBUTE-type key values onto already-created devices and assets. Scans the solution's device/asset files, then dispatches one attribute-values-generator subagent per profile in parallel — each worker invents per-instance values and calls `tb attributes save`. Run after `generate-entities` completes."
+user-invocable: false
+---
+
+# Generate Attributes
+
+Thin dispatcher. The skill does the scanning + per-profile context extraction; one `attribute-values-generator` subagent per profile (in parallel) does the AI call for template values, per-instance variation, and the actual `tb attributes save` calls.
+
+## Inputs from the orchestrator
+
+- `solution` — solution slug.
+- `workdir` — absolute path to the solution directory. Treat as **opaque** — do not re-derive from `solution`. Must contain `design/entity-profiles.json`, `design/relations.json`, and `design/architecture-overview.md`.
+
+## Step 1 — Check for ATTRIBUTE keys
+
+Read `$workdir/design/entity-profiles.json`.
+
+For each `DEVICE` or `ASSET` profile, filter `telemetry` array items where `telemetryType == "ATTRIBUTE"` — these are the profile's ATTRIBUTE keys (the agent's `attributeKeys` brief input).
+
+If **no profile** has any ATTRIBUTE keys, skip the rest of the skill (print nothing, return to caller).
+
+## Step 2 — Build the entity list (one scan)
+
+In a single parallel batch, `Read` everything the dispatch needs:
+
+- All `solutions/<solution>/device-profiles/*.json` → map `profileId → profileName` from each file's `entity.id.id` and `entity.name`.
+- All `solutions/<solution>/asset-profiles/*.json` → same map for asset profiles.
+- All `solutions/<solution>/devices/*.json` → for each: `entity.id.id`, `entity.name`, `entity.deviceProfileId.id`, **and the full `entity.attributes.SERVER_SCOPE` object (defaulting to `{}` when absent)**; resolve `profileName` via the device-profile map; record `{entityType: "DEVICE", id, name, profileName, existingKeys}` where `existingKeys` is the set of keys already present in `SERVER_SCOPE`.
+- All `solutions/<solution>/assets/*.json` → same for assets, including `existingKeys`.
+- `$workdir/design/relations.json` — parent zone/asset names per entity profile (follow `entityRelations` where `child == <profile>`).
+- `$workdir/design/architecture-overview.md` — customer name + site context for the AI prompt anchoring. Read the **Customers & Users → Customer Profiles** table: `customerName` = the `Name` cell of the first data row (empty string if the table has no rows or only the `(none — tenant-only)` placeholder). Pull any geographic/site hint from the Summary section.
+
+If `solutions/<solution>/devices/` and `solutions/<solution>/assets/` are both empty or missing, stop and report: "No entities found in solution — generate-attributes cannot run."
+
+For each profile with ATTRIBUTE keys, group the discovered entities by `profileName` and assign each entity a 1-based `index` in discovery order. Extract `parentZoneName` (the parent in `entityRelations` for this profile, or empty string), `customerName`, and `siteName` from the loaded design files.
+
+## Step 2.5 — Filter to missing keys only
+
+This is what makes the skill safe to run after `pull-solution` (which embeds existing attributes server-side) and after a partial re-design that folds a new attribute key into an existing profile. The skill must never overwrite values already present on entities.
+
+For each profile with ATTRIBUTE keys:
+
+1. Let `profileKeys` = the set of attribute key names from the profile's `attributeKeys` definitions.
+2. For each entity grouped under this profile, compute `keysToSave = profileKeys - existingKeys` (set difference — keys defined on the profile that are NOT already populated on this entity's file).
+3. **Drop** every entity whose `keysToSave` is empty.
+4. After the per-entity filter, if **no entity remains** for this profile, drop the profile from the dispatch list entirely (log `profile <profile>: skipped — all entities already populated` once in the final summary).
+5. Otherwise, compute `attributeKeysFiltered` = the union of `keysToSave` across the surviving entities, intersected with the profile's `attributeKeys` definitions (preserves each key's `dataType`, `classifier`, `enumValues`, `units`, `minValue`, `maxValue`). This is what the agent receives — the AI template call only needs to invent values for keys that at least one entity is missing.
+
+If every profile is dropped at step 4, print the skipped-profile lines and the totals line (`attributes total: 0 entities, 0 total keys, 0 errors`), then return without dispatching any agents.
+
+## Step 3 — Dispatch one agent per profile in parallel
+
+In **one assistant message**, emit one `Agent` tool call per **surviving** profile from Step 2.5 (≥1 entity with ≥1 missing key). Subagent type: `attribute-values-generator`, `description="generate attribute values"`. Each brief contains:
+
+- `solution`: the slug
+- `profile`: profile name
+- `entityType`: `DEVICE` or `ASSET`
+- `attributeKeys`: `attributeKeysFiltered` from Step 2.5 (only keys at least one surviving entity is missing — inline JSON array of `{key, dataType, classifier, enumValues, units, minValue, maxValue}`)
+- `entities`: the surviving entity list with per-entity missing keys (inline JSON array — `{id, name, index, keysToSave}` where `keysToSave` is the entity's missing-key list from Step 2.5)
+- `parentZoneName`: string (or empty)
+- `customerName`: string (or empty)
+- `siteName`: string (or empty)
+
+The agent picks the floor plan filename itself (only if its `attributeKeys` includes an image/floorPlan key) — the skill does not.
+
+Wait for every agent to return. Each returns a block:
+
+```
+attributes: <entityType> <uuid> (<name>): <N> keys saved
+attributes: <entityType> <uuid> (<name>): ERROR — <message>
+profile <profile>: <D> entities, <K> total keys, <E> errors
+```
+
+## Step 4 — Aggregate
+
+Print every agent's block verbatim, then a global totals line:
+
+```
+attributes total: <E> entities, <K> total keys, <Err> errors
+```
+
+Where `<E>`, `<K>`, `<Err>` are sums across all profile blocks.
+
+If `<Err> > 0`, append: `attribute errors logged above.`
+
+## Skip-by-filesystem rule
+
+The skill enforces this in **Step 2.5**: per-entity `existingKeys` are read from the entity's `attributes.SERVER_SCOPE` object, and only the set difference (`profileKeys - existingKeys`) is dispatched as `keysToSave`. Entities with nothing to save are dropped before the agent is invoked; profiles with no surviving entities are skipped entirely. The agent only sees — and only saves — keys that are net-new on each target entity.
+
+**Return contract.** Final summary line:
+
+```
+GENERATED added=<JSON: {attrKeys: [{entity, scope, key}, …]}>
+```

thingsboard_cli/scaffold/.claude/skills/generate-calculated-fields/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: generate-calculated-fields
+description: "Dispatches one cf-generator Haiku subagent per calculated field in parallel. Each agent renders its CF and saves it via `tb calculated-field save`. The tb CLI applies a file-level lock during the read-modify-write on the parent profile's file, so concurrent saves from siblings targeting the same profile serialize at the lock — no race, no corruption. The skill only dispatches and aggregates."
+user-invocable: false
+---
+
+# Generate Calculated Fields
+
+Thin orchestrator. Dispatches one `cf-generator` subagent **per calculated field** in parallel — every CF renders and saves concurrently in its own Haiku instance. The file-level lock inside `tb` makes concurrent writes to the same parent profile safe, so no separate save phase is needed.
+
+## Inputs from the orchestrator
+
+- `solution` — solution slug.
+- `workdir` — absolute path to the solution directory, created and verified by `/create-solution` Step 1c. Treat as **opaque** — do not re-derive from `solution`, do not re-verify. Must contain `design/metrics.json` and `design/entity-profiles.json`.
+
+## EXTREMELY IMPORTANT — anti-shortcut rules
+
+- Dispatch exactly `len(calculatedFields)` agents. No "representative subset," no skipping.
+- If any agent returns an error, surface every agent's output verbatim and stop. Do not advance to validation.
+
+## Step 1 — Load metrics file
+
+1. `Read` `$workdir/design/metrics.json`.
+2. If `calculatedFields` is missing or empty, return `calculatedFields: 0 fields (validate=skipped)` and stop.
+
+## Step 2 — Dispatch one cf-generator per CF in parallel
+
+In **one assistant message**, emit one `Agent` tool call per entry in the `calculatedFields` array. Subagent type: `cf-generator`, `description="generate calculated field"`. Each brief:
+
+- `solution`: the slug
+- `cf`: the single CF entry (inline JSON)
+- `entityProfilesJsonPath`: `$workdir/design/entity-profiles.json`
+
+For very large solutions (say, more than ~40 CFs), split the dispatch across successive messages — but **do not** group CFs into the same brief. The whole point is one generator per CF for maximum parallelism within each message.
+
+Wait for every agent to return. Each returns one of:
+
+- `cf "<cfName>" attached to "<profile>": saved` — success.
+- `error: cf "<cfName>" attached to "<profile>": <message>` — render or save failure.
+
+## Step 3 — Aggregate
+
+If any agent returned an error, surface every agent's output verbatim and stop. Do not advance to Step 4.
+
+If all succeeded, count the saves and check against `len(calculatedFields)` from Step 1. If short, stop with `error: expected <X> CF saves, completed <Y>`.
+
+## Step 4 — Validate
+
+`tb validate <solution>`. Surface any errors verbatim.
+
+## Return value
+
+```
+calculatedFields: <N> fields across <P> profiles (validate=<ok|errors>)
+```
+
+Where `<N>` is the total count of successful `cf-generator` saves and `<P>` is the number of distinct profiles touched (count of unique `attached to "<profile>"` strings in the agent returns).
+
+## Skip-by-filesystem rule
+
+For each CF entry in `metrics.json.calculatedFields`, look up the parent profile/instance file under `<workdir>/`. If that file already has a CF with the same `name` in its `calculatedFields` array, **skip silently** — do not overwrite. Generate only CFs that are net-new on the target profile/instance.
+
+**Return contract.** Final summary line:
+
+```
+GENERATED added=<JSON: {cfs: [{name, outputKey}, …]}>
+```

thingsboard_cli/scaffold/.claude/skills/generate-dashboard-json/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: generate-dashboard-json
+description: "Generate a complete ThingsBoard dashboard JSON. Dispatches the dashboard-json-generator Sonnet agent. Takes solution context (entity profiles, relations, use cases, IAM role) and outputs ready-to-save TB JSON."
+user-invocable: true
+---
+
+# Generate Dashboard JSON
+
+Thin dispatcher. Delegates all work to the `dashboard-json-generator` agent (Sonnet).
+
+## Inputs
+
+| Arg | Type | Required | Meaning |
+|-----|------|----------|---------|
+| `solution` | string | yes | Solution slug (e.g. `smart-office`) |
+| `dashboardName` | string | yes | Human title for the dashboard |
+| `overview` | string | yes | 1–2 sentence description of the dashboard's purpose |
+| `useCases` | string[] | yes | List of use cases the dashboard must cover |
+| `dashboardRole` | object | yes | IAM role: `{name, userProfile, permissions}` |
+| `entityRelations` | object[] | yes | `{parent, child, type, cardinality}` hierarchy links |
+| `entityProfiles` | object[] | yes | `{name, entityType, timeSeriesKeys[], attributeKeys[]}` |
+| `demoRequirements` | string | no | E.g. `"1 Factory, 3 Machines"` — used to pick root state type |
+| `userRequirements` | string | no | Free-form natural-language preferences the user expressed in chat about this dashboard (widget choices, layout, styling, colors, specific visualizations, etc.). HIGH PRIORITY — overrides default generation decisions. Omit when no preferences apply. |
+| `connectDevicesUrl` | string | no | URL for the connectRealDevices widget (defaults to TB docs URL) |
+| `widgetActions` | object[] | no | Defaults to `[]`. Each entry `{endpoint, label, inputSchema}` wires a button on the dashboard to a custom extension endpoint. When non-empty, the generated dashboard must include those buttons and POST request bodies using entity **names** (never UUIDs). |
+| `mode` | string | no | `create` (default) or `update`. `update` when the dashboard already exists on disk (pulled from the instance **or** generated by a previous run) and the ask is a **change**, not a rebuild — see **Update mode** below. |
+| `existingDashboardPath` | string | conditional | **Required when `mode=update`.** Absolute path to the existing dashboard JSON under `<workdir>/dashboards/` to edit in place. |
+| `workdir` | string | conditional | Absolute path to the solution directory (the same `workdir` `create-dashboard` receives — originating from `/create-solution` Step 1c). Optional when `widgetActions` is empty; **required** when `widgetActions` is non-empty so Step 1 can resolve the project root and read the edition from `<project_root>/extension/pom.xml`. |
+
+## Action
+
+### Step 1 — Resolve the extension edition (only when `widgetActions` is non-empty)
+
+When `widgetActions` is empty, skip this step and pass `extensionEdition=""` into the agent brief.
+
+When `widgetActions` is non-empty, `workdir` is required (see Inputs). Derive the project root from it first, then read the edition from `<project_root>/extension/pom.xml`:
+
+```bash
+project_root="$(dirname "$(dirname "$workdir")")"
+PROJECT_ROOT="$project_root" python3 -c "import os; from pathlib import Path; from thingsboard_cli.core.extension_starter_unpacker import parse_pom_artifact_id, edition_from_artifact_id; print(edition_from_artifact_id(parse_pom_artifact_id(Path(os.environ['PROJECT_ROOT']) / 'extension' / 'pom.xml')) or '')"
+```
+
+(`workdir` is `<project-root>/solutions/<slug>`; two `dirname` walks back to the project root.)
+
+Map the resolved edition to the widget JS snippet to embed:
+
+- `PE` → `examples/widgets/on-premise-button.js`.
+- `PaaS` → `examples/widgets/cloud-button.js`.
+
+If the resolution returns an empty string (no `pom.xml` yet), stop and report — `widgetActions` cannot be wired without a built extension to point at.
+
+### Step 2 — Dispatch the agent
+
+Use the `Agent` tool with `subagent_type=dashboard-json-generator` and `description="generate dashboard JSON"`. Pass all inputs above as the agent brief, plus two derived fields:
+
+- `extensionEdition` — the value resolved in Step 1 (`PE` / `PaaS` or empty).
+- `widgetJsSnippetPath` — the snippet path resolved in Step 1 (or empty when no widgetActions).
+
+Instruct the agent (in the brief) to:
+
+- Embed `widgetJsSnippetPath`'s content for each entry in `widgetActions`, parameterised by the entry's `endpoint`, `label`, and `inputSchema`.
+- Build request payloads that reference TB entities by **name** (from `inputSchema`), never by UUID. The extension resolves names to UUIDs at request time, which is required for `tb push`'s multi-target portability.
+
+Print the agent's one-line return summary verbatim. On error, stop and report — the caller depends on the dashboard JSON.
+
+## Update mode (`mode=update`)
+
+Use when the dashboard already exists on disk — pulled from the instance **or** generated by a previous run — and the ask is a **change** to it, not a rebuild. The goal is to **keep the existing dashboard's view** and edit it surgically, the same way entity changes are folded into an existing design rather than regenerated from scratch.
+
+Pass `mode=update` and the required `existingDashboardPath` into the agent brief, and instruct it to:
+
+1. **Load the existing dashboard JSON** at `existingDashboardPath` as the starting point — its widgets, layouts, states, aliases, settings, and `entityAliases` are the baseline and are preserved.
+2. **Apply only the changes** implied by the use cases / additions for this dashboard — add or adjust the specific widget(s), state(s), or alias(es) needed, and nothing else. A use case that is already satisfied by an existing widget needs no change.
+3. **Preserve everything untouched** verbatim — do not renumber, restyle, relayout, or drop widgets/states the change doesn't concern. Keep the dashboard's existing `id`/title so the save updates the same dashboard rather than creating a new one.
+4. Write the edited JSON back so `create-dashboard` saves it over the existing dashboard.
+
+**Create new only when the user explicitly asked for a new dashboard.** Absent an explicit "new dashboard" request, an existing dashboard is updated in place, never duplicated. If `mode=update` but `existingDashboardPath` is missing or unreadable, stop and report — do not silently fall back to generating a fresh dashboard (that would discard the user's existing view).

thingsboard_cli/scaffold/.claude/skills/generate-emulators/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: generate-emulators
+description: "Orchestrates emulator-task generation. Groups devices by profile, dispatches one device-emulator-generator Haiku subagent per profile in parallel. Each worker handles its profile's strategy selection + full strategy JSON + parallel `tb emulator add` calls across its devices. The skill aggregates results."
+user-invocable: false
+---
+
+# Generate Emulators
+
+Inline orchestrator. Builds the per-profile device list, then dispatches one `device-emulator-generator` subagent per profile in parallel. Each worker does Stage 1 (strategy selection), Stage 2 (full strategy JSON per key, plus per-device SEQUENCE overrides), and Stage 3 (parallel `tb emulator add` across its devices). All emulator task files write to different paths (`solutions/<solution>/tasks/emulators/<device-uuid>.json`), so saves never race — within a worker or across workers.
+
+## Inputs
+
+- `solution` — solution slug
+- `workdir` — absolute path to solution directory (treat as opaque — do not re-derive)
+
+## Architecture-overview path setup
+
+The `architecture-overview.md` file is optional context (used for GPS anchoring). Compute the path to pass to workers in Step 2:
+
+```bash
+[ -f "$workdir/design/architecture-overview.md" ] && ARCH_OVERVIEW_MD="$workdir/design/architecture-overview.md" || ARCH_OVERVIEW_MD=""
+```
+
+`workdir` itself is created and verified by `/create-solution` Step 1c — do not re-verify. The same applies to the required design files (`entity-profiles.json`, `relations.json`, `alarms.json`) and the prerequisite that `entities-generator` ran first (so `devices/` and `device-profiles/` exist).
+
+## EXTREMELY IMPORTANT — anti-shortcut rules
+
+- Never write phrases like "due to time/complexity constraints," "for brevity," "to wrap up," "let me create a simplified version," or any synonym.
+- Dispatch one worker per **non-empty** profile group. Skip profiles with zero devices, but never skip a profile that has devices.
+- If any worker subagent returns an error, surface the error verbatim and stop — do not continue dispatching to other profiles or claim partial success.
+
+## Step 1 — Build device list grouped by profile
+
+Read the device-profile and device files that `entities-generator` materialized earlier in the pipeline:
+
+- `Read` every `<workdir>/device-profiles/*.json` → build a map `profileId → profileName` from each file's `entity.id.id` → `entity.name`.
+- `Read` every `<workdir>/devices/*.json` → for each, extract `entity.id.id`, `entity.name`, `entity.deviceProfileId.id`; resolve `profileName` via the map above; record as `{id, name, profileName}`.
+
+Group the device records by `profileName`. Drop profiles with zero devices.
+
+If the resulting map is empty, stop with: "No devices found in solution — generate-emulators cannot run before entities-generator has materialized devices." (Note: assets and customers are intentionally ignored — `tb emulator add` accepts `--entity-type DEVICE` only.)
+
+## Step 2 — Dispatch one worker per profile in parallel
+
+In **one assistant message**, emit one `Agent` tool call per profile group. Subagent type: `device-emulator-generator`, `description="generate device emulators"`. Each call's brief:
+
+- `solution`: the solution slug
+- `profile`: the profile name (string)
+- `devices`: the array of `{id, name}` records grouped to this profile (inline JSON)
+- `entityProfilesJsonPath`: `<workdir>/design/entity-profiles.json`
+- `relationsJsonPath`: `<workdir>/design/relations.json`
+- `alarmsJsonPath`: `<workdir>/design/alarms.json`
+- `metricsJsonPath`: `<workdir>/design/metrics.json` (used by the worker to exclude calculated-field outputs from emulation — the CF system computes those keys, so emitting an emulator entry for them double-writes and breaks the reprocess flow)
+- `architectureOverviewMdPath`: the value of `$ARCH_OVERVIEW_MD` (an absolute path, or empty string if the file isn't present)
+
+Wait for every worker to return. Each worker returns a block:
+
+```
+device <uuid> (<name>): <N> keys emulated  [profile: <profile-name>]
+device <uuid> (<name>): ERROR — <tb error message>
+profile <profile>: <D> devices, <K> total key assignments, <E> errors
+```
+
+(One `device:` line per device + one `profile:` totals line.)
+
+If any worker errored on dispatch (the Agent call itself failed) or returned a final-line error count > 0, surface every error verbatim and stop. Do not advance.
+
+## Step 3 — Aggregate worker results
+
+Print every worker's block verbatim, in order, then a global totals line:
+
+```
+total: <D> devices, <K> total key assignments, <E> errors
+```
+
+Where `<D>`, `<K>`, `<E>` are the sums across all profile blocks.
+
+If `<E> > 0`, append:
+
+```
+errors logged above; resolve before pushing with `tb push <solution> --run-tasks`.
+```
+
+If `<E> == 0`, append:
+
+```
+emulator task files queued; `tb push <solution> --run-tasks` deploys the solution and generates demo telemetry.
+emulator task files are idempotent — they skip devices that already have data on the emulated keys, so this push is safe in prod.
+```
+
+## Skip-by-filesystem rule
+
+For each device in the design that needs an emulator task:
+
+- If the device file already exists at `<workdir>/devices/<name>.json` AND `<workdir>/tasks/emulators/<device-name>.json` already exists, skip silently (the emulator task is already in place).
+- If the device existed in `<workdir>/devices/` before this run (i.e., it's an imported device from the instance-import path), generate an emulator ONLY when the orchestrator passed `import-emulator-opt-in=true`. Net-new devices (added by this run) always get emulators regardless.
+
+**Return contract.** Final summary line:
+
+```
+GENERATED added=<JSON: {emulators: [device-name-1, device-name-2, …]}>
+```

thingsboard_cli/scaffold/.claude/skills/generate-entities/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: generate-entities
+description: "Orchestrates entity materialization. Dispatches the entities-planner Haiku agent (does all the bookkeeping — UUIDs, names, slices, wiring plan), then dispatches 8 worker subagents in parallel to render and save customers / roles / entity-groups / profiles / devices / assets / users, then dispatches wiring-executor and relations-generator Haiku agents in parallel to own the wiring/relations bash loops."
+user-invocable: false
+---
+
+# Generate Entities
+
+Thin dispatcher: main Claude dispatches the `entities-planner` Haiku agent which does **all** the bookkeeping (load files, allocate UUIDs, invent names, build the 8 worker slices, build the wiring + relations plan). Main Claude then dispatches 8 worker subagents in parallel with their pre-computed slices, then dispatches `wiring-executor` and `relations-generator` Haiku agents in parallel — those two own all of the wiring/relations `tb` bash loops in their own contexts. Main does **no** UUID allocation, **no** slice building, **no** name generation, **no** bash iteration — that's all in Haiku.
+
+## Inputs from the orchestrator
+
+- `solution` — solution slug.
+- `workdir` — absolute path to the solution directory, created and verified by `/create-solution` Step 1c. Treat as **opaque** — do not re-derive from `solution`, do not re-verify. Must contain `design/architecture-overview.md`, `design/entity-profiles.json`, `design/relations.json`, and `design/iam.json`.
+
+## Step 1 — Dispatch the planner
+
+1. `tb config mode local` (idempotent).
+2. Use the `Agent` tool with `subagent_type=entities-planner` and `description="plan entities"`. Brief:
+   - `solution`: the slug
+   - `architectureOverviewPath`: `<workdir>/design/architecture-overview.md`
+   - `entityProfilesJsonPath`: `<workdir>/design/entity-profiles.json`
+   - `relationsJsonPath`: `<workdir>/design/relations.json`
+   - `iamJsonPath`: `<workdir>/design/iam.json`
+
+The planner returns one of:
+- Success: a single-line JSON blob `{"workers": {...}, "wiring": {...}, "expected_counts": {...}, "customerMode": "..."}`.
+- Failure: a single-line `error: <description>`.
+
+If the return value parses as JSON, treat it as the plan and continue. If parsing fails, surface the planner's text verbatim and stop.
+
+### Step 2 — Dispatch 8 worker subagents in parallel
+
+In **one assistant message**, emit one `Agent` tool call per non-empty worker slice. Skip workers whose slice is empty (e.g. no `users-generator` if `workers.users` is empty; no `customers-generator` if `customerMode == "tenant-only"`).
+
+Each Agent call must include a short `description` (3–5 words) such as `description="generate <type>"` (e.g. `"generate customers"`, `"generate roles"`, `"generate device profiles"`).
+
+| Slice key in plan       | Worker (`subagent_type`)      | Brief field name |
+|-------------------------|-------------------------------|------------------|
+| `workers.customers`     | `customers-generator`         | `customers`      |
+| `workers.roles`         | `roles-generator`             | `roles`          |
+| `workers.entity_groups` | `entity-groups-generator`     | `groups`         |
+| `workers.device_profiles`| `device-profiles-generator`  | `profiles`       |
+| `workers.asset_profiles`| `asset-profiles-generator`    | `profiles`       |
+| `workers.devices`       | `devices-generator`           | `devices`        |
+| `workers.assets`        | `assets-generator`            | `assets`         |
+| `workers.users`         | `users-generator`             | `users`          |
+
+Each Agent call brief contains:
+- `solution`: the slug
+- The slice array as inline JSON (under the named field above).
+
+Each worker returns `<type>: <N> saved` or `error: <message>`.
+
+**Wait for every dispatched worker to return.** If any worker errored, surface its output verbatim and stop. Cross-check each worker's `<N>` against the corresponding entry in `expected_counts` — short count = stop.
+
+### Step 3 — Dispatch wiring + relations in parallel
+
+In **one assistant message**, emit one `Agent` tool call per non-empty workload. Main Claude does **no** bash iteration here — both agents own their loops internally.
+
+**3a. `wiring-executor`** — owns dashboard perms, memberships, and role perms. Skip the dispatch if `wiring.dashboard_perms`, every sub-array of `wiring.memberships` (`user_groups`, `profile_groups`, `customer_groups`), and `wiring.role_perms` are all empty.
+
+Use the `Agent` tool with `subagent_type=wiring-executor` and `description="execute wiring"`. Brief:
+
+- `solution`: the slug
+- `dashboard_perms`: `wiring.dashboard_perms` (inline JSON array)
+- `memberships`: `wiring.memberships` (inline JSON object with `user_groups`, `profile_groups`, `customer_groups`)
+- `role_perms`: `wiring.role_perms` (inline JSON array)
+
+The agent runs the three sub-steps **in this order — dashboard perms, then memberships, then role perms** — because dashboard perms and role perms both merge into the same user-group file's `additionalInfo.permissions` array and would race if interleaved. Within each sub-step the agent dispatches its `tb entity-group …` calls in parallel batches of up to 10 per message.
+
+Returns one of:
+- Success: `wiring: dashboard_perms=<N1>, memberships=<N2>, role_perms=<N3>`
+- Failure: `error: <description>`
+
+**3b. `relations-generator`** — owns the `tb relation save` loop. Skip if `wiring.relations` is empty.
+
+Use the `Agent` tool with `subagent_type=relations-generator` and `description="generate relations"`. Brief:
+
+- `solution`: the slug
+- `relations`: `wiring.relations` (inline JSON array)
+
+Each entry is already shaped as the full `--json` body (`{from, to, type, typeGroup}`); the agent iterates and saves sequentially. Returns one of:
+
+- Success: `relations: <N> saved`
+- Failure: `error: relation <i>/<N> from <fromType>:<fromId> to <toType>:<toId>: <message>`
+
+**Wait for both dispatches to return.** If either errored, surface its output verbatim and stop. Parse the counts and fold them into the Step 5 check.
+
+### Step 4 — `tb validate <solution>`
+
+Run once. Surface any errors verbatim.
+
+### Step 5 — Verify counts
+
+Compare actual counts against `expected_counts` from the plan blob:
+- Step 2 worker return lines → `customers`, `roles`, `entity_groups`, `device_profiles`, `asset_profiles`, `devices`, `assets`, `users`
+- `wiring-executor` return → `dashboard_perms`, `memberships`, `role_perms`
+- `relations-generator` return → `relations`
+
+If any actual is less than expected, stop and return `error: expected <X> <type>, completed <Y>`.
+
+Print **one summary line** and return:
+
+```
+entities: <P> profiles, <D> devices, <A> assets, <C> customers, <U> users, <R> roles, <REL> relations (validate=<ok|errors>)
+```
+
+## Skip-by-filesystem rule
+
+Before writing any entity file, check whether the target path under `<workdir>/` already exists on disk. If it does, **skip silently** — do not overwrite. This single rule serves both the instance-import case (pulled entities already on disk) and the resume case (entities from a previous run).
+
+**Early-exit:** if every entry in every design file resolves to a target file that already exists, return immediately with `added: {}` and log one line `"No entity changes required."`.
+
+**Return contract.** When this skill returns, emit a final structured summary line:
+
+```
+GENERATED added=<JSON with keys: profiles, customers, users, roles, entity_groups, devices, assets — each a list of names>
+```
+
+The orchestrator parses this line to populate the `added` summary used by the dashboard impact classifier (spec § 5).