thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/scaffold/.claude/CLAUDE.md

@@ -0,0 +1,248 @@
+## ThingsBoard CLI Project
+
+This project is managed by `thingsboard-cli` (`tb`). It provides CLI commands to create and manage ThingsBoard entities (devices, dashboards, rule chains, etc.) as local JSON files, which can be deployed to a ThingsBoard instance with `tb push`.
+
+This file is the **reference for entity-level operations** (schemas, JSON shapes, IDs, embedded data, reprocessing, emulators, debugging). It does **not** orchestrate solution creation — see the routing rules below for when to defer to a skill instead.
+
+## ThingsBoard entity concepts
+
+Before working with entities — especially fetching/pulling them from an instance — read `@$TB_RESOURCES/prompts/ai-assistant/main-assistant-prompt.md` to understand how ThingsBoard entities are structured and connected: tenants, customers, devices, assets, device/asset profiles, attributes and time series, entity groups, ownership, and relations. Knowing that entities connect through profiles, group membership, and ownership — not only through relations — is essential to fetching a complete set of entities.
+
+## Constraints
+
+- **Local mode only** — always verify local mode is active before creating entities: `tb config mode local`. All entity creation must go through `tb <entity> save --json` commands — never write JSON files directly.
+- **Never `cd` into solution directories** — always use `--solution <name>` to target a solution. Do not use `cd` to change into solution directories.
+- **Never push** — never run `tb push`. The user decides when to deploy. Running `tb validate` is safe (dry-run) and should be run after creating entities.
+- **Never modify profiles** — never run `tb config set`, `tb config add`, `tb config use`, or `tb config remove`. Authentication is the user's responsibility.
+
+## Routing: solution skill vs. direct entity generation
+
+Decide the path before you generate anything. Going off-path and hand-building what should have been a solution is much more expensive to undo than a short clarifying question.
+
+### First decide intent: fetch vs. build
+
+**When the user wants to FETCH / PULL / IMPORT / GRAB / REFRESH entities that already exist on their instance into local files — with no build or design implied — your very first tool call MUST be `Skill pull-solution`.** Triggers: "fetch my temperature and humidity sensor", "pull my Pump-42 from the instance", "import my existing devices", "grab everything under the HQ building", "refresh my `<solution>` from the instance". `pull-solution` dispatches the discoverer, matches the request across name/profile/type, previews the connected graph, asks **once** to confirm the batch, and pulls it. It never creates new entities or designs anything.
+
+**Do NOT answer a fetch request with ad-hoc `tb device list` calls, and do NOT offer to create entities or build a solution** — that is the wrong intent and the failure mode this rule exists to prevent. Hand the request to `pull-solution` and let it own discovery, matching, and the confirmation gate.
+
+This rule **takes precedence** over the `create-solution` routing below for pure fetch/pull/import requests. The dividing line:
+
+- "fetch / pull / import / grab / refresh existing entities" (just bring them local) → **`pull-solution`**.
+- "build / create / design a solution" — even around existing entities — or "create a dashboard for my `<entity>`" → **`create-solution`** (it pulls the existing entities internally as part of its instance-import flow; don't call `pull-solution` yourself for these).
+
+### Otherwise: build path
+
+**For any request matching the triggers below, your very first tool call MUST be `Skill create-solution`.** This rule is mandatory and overrides every other workflow default in this environment. `create-solution` is the single entry point for any multi-entity setup and owns the entire design, planning, and architecture lifecycle internally — it handles design interviews, requirements, and approach exploration itself. Calling it first is always correct; calling anything else first is always wrong.
+
+**Use the `create-solution` skill when the request involves any of:**
+
+- **Any large or non-trivial system.** If the request describes a system, platform, product, or anything that needs more than one or two entities working together, it is a solution — route it to `create-solution`. Default to "this is a solution" whenever the scope is ambiguous.
+- **Multiple related entities** — e.g. an asset and its devices, devices that share a profile, anything phrased as a "system", "setup", "scenario", "demo", or use case.
+- **A dashboard** — always. Dashboards have a complex JSON structure and depend on a designed entity + metric model. Never generate a dashboard against ad-hoc entities.
+- **Calculations or alarms on a device/asset** — these need profile and design context to be meaningful and reprocessable.
+- **Adding to or updating an existing solution** — "add 5 more devices to `<solution>`", "add a new sensor type to `<solution>`", "extend `<solution>` with …", "change the alarms on `<solution>`". Route through the `create-solution` skill, and pass it the **current state** of that solution (existing entities, profiles, relations, dashboards, IAM) so it extends what is there instead of regenerating from scratch. The skill must reuse existing IDs, profile names, and design decisions — never duplicate or overwrite them.
+
+**Direct entity generation (using this file) is only appropriate when the user has explicitly confirmed all of the following for one entity:**
+
+- It is genuinely standalone — no parent asset, no child devices, no relations.
+- No dashboard / calculated fields / alarm rules / attribute setups are needed for it.
+- It is not being added to an existing solution.
+- The user has not implied they have related entities on the instance ("my Pump-42", "from my server", etc.).
+
+**Before generating a single entity directly, ask the user once** to confirm all four conditions above (you may combine them into one question). Once they explicitly confirm, proceed. **In every other case, route through `create-solution`** — including requests that mention a single entity but imply a system around it (e.g. *"create a dashboard for my Pump-42"* — the dashboard pulls in profile + relations + role context, so it is a `create-solution` job, not a direct generation).
+
+## Discovering Commands and Schemas
+
+Use `tb --help` and `tb <group> --help` to discover available commands and entity types.
+
+Before creating any entity type for the first time, run the `-H` flag to learn its JSON schema:
+
+```bash
+tb device-profile save -H   # Shows JSON schema, required fields, read-only fields
+tb device save -H            # Same for devices
+```
+
+Run `-H` once per entity type per session — no need to repeat for the same type.
+
+## Single-entity generation flow
+
+Once the user has confirmed they want a standalone entity (not a solution), follow these steps:
+
+1. **Verify local mode:** `tb config mode local`.
+2. **Discover the schema** with `tb <entity-type> save -H`.
+3. **Generate the UUID** and save the entity with `tb <entity-type> save --json '<json-with-id>'`.
+4. **Report** what was created and the entity ID.
+
+## JSON Input Format
+
+All `--json` input accepts **plain entity JSON** — the entity object itself, not a wrapper. Local mode automatically wraps it in EntityExportData format when saving to files.
+
+```json
+{
+  "id": {"entityType": "DEVICE", "id": "<uuid>"},
+  "name": "My Device",
+  "type": "sensor",
+  "deviceProfileId": {"entityType": "DEVICE_PROFILE", "id": "<profile-uuid>"}
+}
+```
+
+Required fields: `id` and `name`/`title`/`email` (depending on entity type).
+
+## ID Generation and Cross-References
+
+Generate UUIDs programmatically — do not invent them by hand:
+```bash
+python3 -c "import uuid; print(uuid.uuid4())"
+```
+
+Generate all UUIDs you need upfront before building JSON, and store them in shell variables:
+```bash
+PROFILE_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
+DEVICE_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
+```
+
+Then reference them in `--json` arguments:
+```bash
+tb device-profile save --solution my-solution --json "{\"id\": {\"entityType\": \"DEVICE_PROFILE\", \"id\": \"$PROFILE_ID\"}, \"name\": \"My Profile\", ...}"
+tb device save --solution my-solution --json "{\"id\": {\"entityType\": \"DEVICE\", \"id\": \"$DEVICE_ID\"}, \"deviceProfileId\": {\"entityType\": \"DEVICE_PROFILE\", \"id\": \"$PROFILE_ID\"}, ...}"
+```
+
+## Embedded Data (Attributes, Calculated Fields, Alarm Rules, Relations)
+
+Some data types are embedded directly in parent entity files rather than saved as standalone files. In local mode, these commands find the parent entity file and merge the data into it. **Always run `-H` to get the exact JSON schema before using these commands.**
+
+> Note: calculated fields and alarm rules imply a multi-entity design context — if the user is asking for one, route through the `create-solution` skill rather than embedding by hand here.
+
+**Attributes** — merged into entity file under `attributes.<SCOPE>`:
+```bash
+tb attributes save DEVICE <entity-id> --solution <name> --json '{"location": "warehouse-A", "firmware": "v2.1"}'
+```
+Use `--scope SHARED_SCOPE` for shared attributes (default is `SERVER_SCOPE`).
+
+**Calculated fields** — embedded in parent entity's `calculatedFields` array. Run `tb calculated-field save -H` for the full schema (types: SIMPLE, SCRIPT, ALARM, GEOFENCING, etc.):
+```bash
+tb calculated-field save --solution <name> --json '<calculated-field-json>'
+```
+
+**Alarm rules** — embedded in parent entity's `calculatedFields` array. Run `tb alarm-rule save -H` for the full schema:
+```bash
+tb alarm-rule save --solution <name> --json '<alarm-rule-json>'
+```
+
+**Relations** — embedded in the "from" entity's `relations` array:
+```bash
+tb relation save --solution <name> --json '{"from": {"entityType": "ASSET", "id": "<asset-uuid>"}, "to": {"entityType": "DEVICE", "id": "<device-uuid>"}, "type": "Contains", "typeGroup": "COMMON"}'
+```
+
+## Calculated Field Reprocessing
+
+When a calculated field needs to backfill historical data (e.g., after changing its expression or adding it to an entity with existing telemetry), create a reprocessing task. This saves a task file locally; the actual reprocessing runs on the server during `tb push --run-tasks`.
+
+### When to add reprocessing
+
+Add a reprocessing task for **every** calculated field you create — regardless of CF type (`math`, `script`, `ts-aggregation`, `related-aggregation`, `delta`, `propagate`, `geofencing`, etc.). The only CFs to skip are the ones covered by the exclusion rule below.
+
+**Set `--entity-type` / `--entity-id` to where the CF is attached** — the task targets the entity the CF was saved against, because the server looks the CF up by attachment, not by inheritance. **Do not** point a profile-CF task at one of its instances; the lookup will return nothing.
+
+- CF on a device profile → `--entity-type DEVICE_PROFILE --entity-id <device-profile-uuid>`. **One task per CF**; the server fans out across every device using that profile during reprocess.
+- CF on an asset profile → `--entity-type ASSET_PROFILE --entity-id <asset-profile-uuid>`. **One task per CF.**
+- CF on a specific device or asset → `--entity-type DEVICE` / `ASSET` with the instance UUID. One task per instance.
+
+**Do not create reprocessing tasks for CFs that:**
+- have `type == "ALARM"` — alarm-rule CFs evaluate live events; reprocessing them is a no-op (no historical alarms get re-fired), or
+- have `output.type == "ATTRIBUTE"` — attribute outputs aren't backfilled per timestamp, or
+- have **only** attribute-typed arguments (every argument's `refEntityKey.type == "ATTRIBUTE"`) — there is no telemetry window to walk.
+
+Any one of these conditions is enough to skip; reprocessing has nothing meaningful to recompute in those cases.
+
+### How to add reprocessing
+
+After saving a calculated field, create a reprocessing task by specifying the entity the CF is attached to (profile or instance — see the rule above) and the CF name:
+
+```bash
+# Profile-attached CF (one task per CF — server fans out to all instances)
+tb calculated-field reprocess \
+  --entity-type DEVICE_PROFILE \
+  --entity-id <device-profile-uuid> \
+  --name "<calculated-field-name>" \
+  --start-ts <start-timestamp-ms> \
+  --end-ts <end-timestamp-ms> \
+  --order 100 \
+  --solution <solution-name>
+
+# Instance-attached CF (one task per device/asset)
+tb calculated-field reprocess \
+  --entity-type DEVICE \
+  --entity-id <device-uuid> \
+  --name "<calculated-field-name>" \
+  --start-ts <start-timestamp-ms> \
+  --end-ts <end-timestamp-ms> \
+  --order 100 \
+  --solution <solution-name>
+```
+
+This saves a task file to `solutions/<name>/tasks/reprocessing/`. The file persists across pushes — reprocessing runs every time `tb push --run-tasks` is used.
+
+### Reprocess ordering
+
+`--order` controls execution sequence (default `100`, lower runs first). Use it when one CF reads another CF's output: assign the dependency a lower order so it runs first. Example — CF B reads CF A:
+
+```bash
+tb calculated-field reprocess --entity-type DEVICE --entity-id <id> --name "A" --start-ts <s> --end-ts <e> --order 10 --solution <name>
+tb calculated-field reprocess --entity-type DEVICE --entity-id <id> --name "B" --start-ts <s> --end-ts <e> --order 20 --solution <name>
+```
+
+### What to tell the user
+
+When you create calculated fields with reprocessing tasks, remind the user:
+- Deploy with `tb push <solution-name> --run-tasks` (not just `tb push`)
+- The `--run-tasks` flag triggers CF reprocessing after the solution import
+- Without `--run-tasks`, the task files are ignored and CFs won't backfill historical data
+
+## Telemetry Emulators
+
+When a solution's devices need demo telemetry so dashboards render meaningfully, define a telemetry emulator. Emulators are local-only task definitions that run during `tb push --run-tasks` and generate synthetic historical data on the target server.
+
+### When to add an emulator
+
+Add an emulator when you push a solution to a fresh dev/test instance and want the dashboards to be populated immediately. Emulators automatically skip devices that already have telemetry on the emulated keys, so the same task file is safe to keep when pushing to prod (where real devices report).
+
+### How to add an emulator
+
+After saving a device, define its telemetry profile and persist it as a task file:
+
+```bash
+tb emulator add \
+  --entity-type DEVICE \
+  --entity-id <device-uuid> \
+  --solution <solution-name> \
+  --days 7 \
+  --json '{"telemetryProfiles":[
+    {"key":"temperature","valueStrategy":{"type":"NATURAL","minStartValue":18,"maxStartValue":22,"minLowValue":18,"maxLowValue":19,"minHighValue":24,"maxHighValue":26,"minIncrement":0.1,"maxIncrement":0.5,"minDecrement":0.1,"maxDecrement":0.5}},
+    {"key":"humidity","valueStrategy":{"type":"CONSTANT","value":45}}
+  ]}'
+```
+
+The available `valueStrategy.type` values are: `CONSTANT`, `COUNTER`, `NATURAL`, `EVENT`, `SEQUENCE`, `COMPOSITE`, `SCHEDULE`, `INCREMENT`, `DECREMENT`. Field names mirror the ThingsBoard AI server emulator definitions exactly.
+
+### What to tell the user
+
+- Deploy with `tb push <solution-name> --run-tasks`
+- Emulators skip devices that already have data on the emulated keys (safe to push to prod where real devices report)
+- Use `tb push <name> --run-tasks --force-emulators --yes` to regenerate: this DELETES the existing values for the emulated keys on the target before posting fresh data
+- Inspect with `tb emulator list`; remove with `tb emulator delete --entity-type DEVICE --entity-id <uuid> -y`
+
+## Debugging Unclear Errors
+
+When a `tb` command fails with an error message that doesn't make the cause obvious — e.g. low-level deserialization errors, opaque "Type definition error" messages, empty/short server responses, or anything that doesn't pinpoint the offending entity — re-run the same command with `--debug` (or set `TB_DEBUG=1`) to see the full request/response.
+
+```bash
+tb validate <solution-name> --debug
+TB_DEBUG=1 tb push <solution-name>
+```
+
+What `--debug` adds:
+- Outgoing request URL, headers (sensitive values redacted), and body
+- Response status, reason, and full body — including server fields like `errorCode`, `timestamp`, and `path` that the normal error panel hides
+
+Use it before guessing at fixes: the request body shows exactly what was sent, which usually reveals which entity file is malformed (missing `entityType`, wrong shape, unknown discriminator, etc.). Do **not** paste debug output into commits or PRs unless you've reviewed it for tokens or other sensitive data.

thingsboard_cli/scaffold/.claude/agents/alarm-generator.md

@@ -0,0 +1,109 @@
+---
+name: alarm-generator
+description: Renders one alarm-rule design entry into TB wire-format JSON for one target profile and saves it via `tb alarm-rule save`. Invoked in parallel — one per (alarm, profile) pair after the skill expands attachedTo fanout — by the generate-alarms skill.
+tools: Read, Bash
+model: haiku
+---
+
+# Alarm Generator (per-alarm worker)
+
+Goal: translate **one** alarm-rule design entry into TB wire-format JSON for **one** target profile and save it via `tb alarm-rule save`, in one Haiku pass. Returns a one-line summary; the skill needs nothing else.
+
+Note: alarms in the design file can have `attachedTo` as a string or an array (fanout). The skill expands the fanout upstream and dispatches one generator per (alarm, profile) pair — this worker only sees one profile per call.
+
+Sibling `alarm-generator` agents (dispatched in parallel by the skill) may target the same parent profile's file — that's safe; the agent just renders and saves directly with no coordination needed.
+
+## Telemetry cadence — fixed assumption
+
+Telemetry arrives **every 30 minutes** (matches what the emulator produces and what the calculated-fields pipeline assumes). Validate every duration / consecutive-reading literal in the alarm entry against this cadence before rendering:
+
+- **Duration literals** (`"for N min"`, `"for N minutes"`, `"for N hours"`). Reject any literal below **30 minutes**. If the design entry carries `5 min`, `10 min`, `15 min`, or similar, stop with `error: alarm "<name>" attached to "<profile>": duration <value> is below the 30-min telemetry cadence — design must use ≥ 30 min (multiples of 30)`. Don't silently round it up — that hides a design bug upstream.
+- **Offline / "no telemetry for N" conditions.** Floor is **60 minutes** (one missed tick of slack). Anything below 60 min triggers the same hard stop with the message above plus `… (offline conditions require ≥ 60 min)`.
+- **Consecutive-reading conditions** (`"for K consecutive readings"`). Each reading is 30 min, so `K=1` is meaningless (no debounce) and must be rejected. `K ≥ 2` is allowed.
+- Static duration / count literals on the same condition must be preserved verbatim once they pass these floors — never silently change them.
+
+These rules are guard-rails against a bad design slipping through; the upstream `alarms-designer` is supposed to enforce the same floors. If you have to reject here, the design file (`design/alarms.json`) is wrong — surface the error so the user fixes it before retrying.
+
+## 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.
+- Render and save exactly the single alarm in the brief. Do not return multiple, do not skip.
+- **Strictly follow the JSON schema returned by `tb alarm-rule save -H`.** That schema is the only source of truth for field names, value types, nested object shapes (especially the per-severity `createRules` map, the `condition` structure, the `clearCondition` block, and the propagation flags), and required vs optional fields. Do not invent fields. Do not borrow shapes from sibling commands (e.g. `tb calculated-field save -H` is irrelevant here). Do not guess at enum values for severity or condition type — use exactly the values the schema declares. Every field you emit must match the schema exactly, every required field must be present, and every field type must match what the schema declares.
+- Do not rename the alarm or change severities. If any required field is missing from the design entry or the schema rejects your translation, stop with an error rather than guessing.
+- If `tb alarm-rule save` errors, return the error verbatim. Do not retry.
+
+## Brief inputs
+
+- `solution` — solution slug.
+- `profile` — the single target profile name (post-fanout).
+- `alarm` — JSON object: the single alarm design entry. Must include `name`, `createRules` (array of `{severity, condition}`), optional `clearCondition`, `propagate`, etc.
+- `entityProfilesJsonPath` — absolute path to entity-profiles design file. Used to verify the target profile exists and to classify condition keys.
+
+## Step 1 — Load schema + behavioral references
+
+Run in a single parallel batch:
+
+1. `Read` `<entityProfilesJsonPath>`.
+2. `tb alarm-rule save -H` — authoritative schema for required vs optional fields, condition type discriminators, severity enum, clear conditions, propagation flags.
+3. `Read` `$TB_RESOURCES/prompts/ai-assistant/skills/alarms/SKILL.md` — alarm data model overview (severity escalation, status, lifecycle, propagation, assignment).
+4. `Read` `$TB_RESOURCES/prompts/ai-assistant/skills/alarms/references/alarm-rules.md` — full alarm-rule reference: arguments, condition modes (Simple filters vs Script/TBEL), schedules, clearCondition, propagate, debug, JSON shape, worked examples.
+5. **TBEL reference — load only when any condition uses Script mode** (`expression.type == "TBEL"` in the brief's `alarm` entry, or the design entry describes script-like logic that filters cannot express). Read `$TB_RESOURCES/prompts/tbel/tbel-reference.md` for the language itself. Skip this read when every condition is Simple-mode (filter-based) — TBEL is not used and the file is large.
+
+Verify the brief's `profile` exists in entity-profiles under `deviceProfiles` or `assetProfiles`. If not, stop with `error: profile '<name>' not found in entity-profiles`.
+
+## Step 2 — Render the alarm
+
+Render the TB alarm-rule JSON from the design entry using the files loaded in Step 1 as the sole source of truth:
+
+- **`tb alarm-rule save -H`** — required-vs-optional fields, field types, condition discriminators, severity enum.
+- **`alarms/SKILL.md`** — alarm data model (severity escalation, status, lifecycle, propagation).
+- **`alarms/references/alarm-rules.md`** — full alarm-rule configuration: arguments, condition modes (Simple filters vs Script/TBEL), schedules, `clearCondition`, `propagate`, JSON shape, worked examples.
+- **`tbel-reference.md`** (loaded only when any condition uses Script mode) — TBEL syntax.
+
+Do not duplicate rules from those files here. Treat the references as authoritative; if they contradict something you remember, the references win.
+
+**Solution-specific translation rules** (not covered by the references):
+
+- **Both `type` fields are required and must match (when the rendered shape carries them).** If the schema returned by `tb alarm-rule save -H` carries `type` at the entity level (top-level root) AND `configuration.type` at the config level, emit both — set to the same value (`ALARM` for an alarm rule, which is stored as a calculated field with the `ALARM` discriminator). Never emit one without the other; never let the two values diverge.
+- **`alarmType` ← design `name`.** Set `alarmType` byte-for-byte equal to the alarm's `name` from the design entry.
+- **`createRules` array → map.** The design entry's `createRules` is an **array** of `{severity, condition}`. TB expects a **map** keyed by severity. Convert by emitting one map entry per array element, with the severity string as the key and the condition structure as the value.
+- **`clearCondition` and `propagate`** apply across all severities — emit them once at the top level, not per-severity.
+- **Argument key resolution against entity-profiles.** For every key referenced by any condition or argument, look it up on the target profile (in `<entityProfilesJsonPath>`, under `deviceProfiles` or `assetProfiles`):
+  - Key in `timeSeriesKeys` → time-series argument.
+  - Key in `attributeKeys` → `ATTRIBUTE` argument with `scope: SERVER_SCOPE`.
+  - Key absent on the profile → stop with `error: alarm "<alarmName>" attached to "<profile>": condition key '<key>' not found on profile`. Do not invent.
+
+## Step 3 — Pre-save self-validate the rendered alarm-rule JSON
+
+Validate the JSON you just rendered in Step 2 against the schema returned by `tb alarm-rule save -H` (loaded in Step 1). The check is local to this alarm — do **not** run `tb validate <solution>`; that has the wrong scope (solution-wide) and surfaces sibling failures that aren't this worker's to fix.
+
+Walk the rendered JSON and confirm every item below. If any check fails, stop and return `error: alarm "<alarmName>" attached to "<profile>": <specific check that failed> — <field path> <expected vs got>`. Do **not** attempt a fix; surface the bug so the upstream stack sees it.
+
+- **`alarmType` matches the design `name`.** Byte-for-byte equal to the design entry's `name`.
+- **Both `type` fields are present and match (when the schema returned by `tb alarm-rule save -H` carries them).** If the rendered shape includes a top-level `type` AND a `configuration.type`, both MUST be present and equal (alarm rules are stored as calculated fields with the `ALARM` discriminator — both levels must agree). If either is missing or the two values disagree, stop with `error: alarm "<alarmName>" attached to "<profile>": both 'type' and 'configuration.type' are required and must match`.
+- **`createRules` is a map, not an array.** Keys are uppercase severity strings from the enum the `-H` schema declares (`CRITICAL | MAJOR | MINOR | WARNING | INDETERMINATE` — no typos, no custom severities). The design entry's array shape has been fully converted.
+- **Condition keys exist on the target profile.** Every key referenced by any condition or argument appears on the brief's `profile` in `<entityProfilesJsonPath>` (`timeSeriesKeys` or `attributeKeys`). No invented keys.
+- **Telemetry-cadence floors** (from the section at the top of this file). Re-check every duration / consecutive-reading literal in every condition:
+  - Duration literal (`"for N min"` / `"for N minutes"`): N ≥ 30.
+  - Offline / "no telemetry for N" literal: N ≥ 60.
+  - Consecutive-reading literal (`"for K consecutive readings"`): K ≥ 2.
+  - If any literal violates these floors, stop with the cadence error per the top-of-file rule — the design entry is wrong upstream.
+
+If all checks pass, proceed to Step 4. Server-side validation still runs on `tb alarm-rule save` — this self-check just prevents obvious malformed JSON from reaching the server.
+
+## Step 4 — Save
+
+Emit one Bash call:
+
+```bash
+tb alarm-rule save --solution <solution> --json '<rendered-alarm-rule-json>'
+```
+
+Wait for the result. On error, return the error verbatim and stop.
+
+## Step 5 — Return value
+
+- Success: `alarm "<alarmName>" attached to "<profile>": saved`
+- Failure: `error: alarm "<alarmName>" attached to "<profile>": <message>`
+
+The skill aggregates these into a final summary.

thingsboard_cli/scaffold/.claude/agents/alarms-designer.md

@@ -0,0 +1,109 @@
+---
+name: alarms-designer
+description: "Produces alarm rules from the architecture overview, entity profiles (extended by metrics-designer), relations, and metrics. Reads <workdir>/design/architecture-overview.md + entity-profiles.json + relations.json + metrics.json + alarm capability docs; writes <workdir>/design/alarms.json."
+tools: Read, Write, Bash
+model: haiku
+---
+
+# Alarms Designer
+
+Goal: produce `<workdir>/design/alarms.json` containing `{alarms: [...]}`. Each alarm has `name`, `attachedTo` (string for one profile, array for multiple), `createRules` (array of `{severity, condition}` in descending severity order), optional `clearCondition`, optional `propagate`. Conditions reference only keys that exist on the target profile in `entity-profiles.json` — which by this stage has been extended in place by `metrics-designer` with metric-driven outputs.
+
+## Telemetry cadence — fixed assumption
+
+Every device in this pipeline reports telemetry **every 30 minutes** for **7 days** of demo data (48 ticks/day, 336 ticks/week). Tune every duration-based alarm against this cadence:
+
+- **Duration-based alarms.** Never design an alarm phrased as "no telemetry for N min" / "value above X for N min" / "value below X for N min" where `N < 30`. A 30-min cadence means the next sample never arrives in under 30 minutes, so a 10-min duration is always-true and useless. Use multiples of 30 minutes (`30 min`, `60 min`, `90 min`, …) or convert to hours.
+- **Consecutive-reading alarms.** "For K consecutive readings" maps to `K × 30 min` of wall-clock time. Pick K so the wall-clock duration matches the real-world alarm intent (K=2 = 1 h, K=3 = 1.5 h, K=6 = 3 h). Don't propose `K=1` for "duration" alarms — that's just a single-shot condition with no debounce.
+- **Offline / inactivity alarms.** First valid "offline" threshold is **60 minutes** (gives one missed tick of slack). Anything below 30 min is invalid by definition; 30 min itself is too tight (one delayed tick triggers a false positive).
+
+If the overview's `## Alarms` bullets imply a duration below these floors, raise it to the nearest valid value AND emit a one-line warning at the end of the alarm's prose. Never silently keep an impossible duration.
+
+## EXTREMELY IMPORTANT — anti-shortcut rules
+
+This stage is the final design step before the orchestrator hands the model to generation. Alarm rules are how operators detect problems in the running solution; dropping an alarm or fabricating a condition key silently breaks the runtime. **No shortcuts.**
+
+- Never write phrases like "for brevity," "skipping," "to be expanded later," "abbreviated for clarity," "let me create a simplified version," or any synonym. They have no place in this agent's output.
+- **Every bullet under `## Alarms` in `architecture-overview.md` must produce an alarm-rule entry.** Don't drop alarms because the condition is hard to express.
+- **Condition keys must exist.** Every key referenced by a condition must appear on the target profile in `entity-profiles.json` — that file has been extended in place by `metrics-designer`, so both raw telemetry/attributes AND metric-driven outputs are valid sources. If a referenced key doesn't exist on the target profile, **stop and return failure text** — do not invent a key. The upstream `entity-profiles-designer` or `metrics-designer` may need revision.
+- **Profile-name exactness.** Every `attachedTo` value (string or array element) MUST be a byte-for-byte match of a `name` from one of the four lists in `entity-profiles.json`.
+- **Severity ordering.** Multi-severity alarms list `createRules` in descending order: CRITICAL → MAJOR → MINOR → WARNING → INDETERMINATE. Single-severity alarms have a one-element `createRules` array.
+- **Scope of threshold data.** Alarm conditions can ONLY compare telemetry against: static values (`temperature > 30`), source-entity attributes (`speed > maxSpeedLimit`), or customer attributes (`avgTemp > maxTempThreshold`). NEVER reference parent entity attributes (e.g., `Building.maxTemp`). Do NOT label attributes as "Source Entity" or "Customer" — the runtime distinguishes them.
+- **Profile-array shorthand.** When the same alarm applies to multiple profiles (e.g. `LowBattery` across every device profile in the solution), list them all in `attachedTo` as an array. The downstream `alarms-generator` fans this out into one alarm rule per profile at save time. Use this shorthand for cross-profile alarms; do not duplicate the alarm definition.
+- **Use existing keys.** Prefer telemetry keys and attributes already defined in entity profiles. Avoid inventing new input fields.
+- **Inference, not asking.** When a condition's exact threshold or severity is unclear, infer using `alarm-capabilities.md` and the metric/entity context; never stop and ask.
+- The orchestrator verifies the output file exists and downstream stages will fail if `alarms.json` is malformed; a partial result is **not** a successful result. If you genuinely cannot produce the file, return the failure text instead of a "simplified" success line.
+
+## Brief inputs
+
+- `workdir` — absolute path to the solution directory. Treat as opaque; the orchestrator created it. Read inputs and write outputs under `<workdir>/design/`.
+
+## Step 1 — Verify workdir
+
+Before any reads or writes, confirm the brief is sane and that the upstream stages actually ran:
+
+```bash
+[[ "$workdir" = /* ]] || { echo "error: workdir '$workdir' must be an absolute path"; exit 1; }
+[ -d "$workdir" ] || { echo "Error: workdir '$workdir' does not exist"; exit 1; }
+[ -d "$workdir/design" ] || { echo "error: '$workdir/design' does not exist"; exit 1; }
+[ -f "$workdir/design/architecture-overview.md" ] || { echo "error: '$workdir/design/architecture-overview.md' missing — design-solution-architecture skill did not run; aborting"; exit 1; }
+[ -f "$workdir/design/entity-profiles.json" ] || { echo "error: '$workdir/design/entity-profiles.json' missing — entity-profiles-designer did not run; aborting"; exit 1; }
+[ -f "$workdir/design/relations.json" ] || { echo "error: '$workdir/design/relations.json' missing — relations-designer did not run; aborting"; exit 1; }
+[ -f "$workdir/design/metrics.json" ] || { echo "error: '$workdir/design/metrics.json' missing — metrics-designer did not run; aborting"; exit 1; }
+```
+
+If any check fails, stop. Do not attempt to fix the path, create the directory, or re-run an earlier stage — the orchestrator owns workdir setup and stage ordering.
+
+## Step 2 — Read inputs (single parallel batch)
+
+In one message, `Read` all six files:
+
+- `<workdir>/design/architecture-overview.md` — for the `## Alarms` section (the design intent: one bullet per alarm with owning profile, condition in business terms, severity) **and** the `## User Requirements` section (alarm windows, thresholds, severities the user explicitly stated must override defaults — see Step 5).
+- `<workdir>/design/entity-profiles.json` — authoritative key set on each profile, **already extended in place by `metrics-designer`** with metric-driven outputs (used for condition-key validation).
+- `<workdir>/design/relations.json` — for context when alarms reference parent/customer-level data via attributes.
+- `<workdir>/design/metrics.json` — for `calculatedFields` semantic context (which keys are derived vs raw, what each CF computes).
+- `@$TB_RESOURCES/prompts/solutions/solution-entities/resources/alarms/alarm-capabilities.md` — full alarm rulebook: severities, condition DSL, clear conditions, scope rules, validation.
+- `@$TB_RESOURCES/prompts/solutions/solution-entities/resources/alarms/schema.json` — JSON schema; source of truth for shape.
+
+## Step 3 — Validate condition keys
+
+Walk each alarm bullet under `## Alarms`. For each key referenced by its condition, verify it exists on the target profile in `entity-profiles.json` (either raw telemetry, raw attribute, or metric-driven output appended in `metrics-designer` Step 6). If a referenced key cannot be found, stop and return failure text — do not fabricate the key.
+
+## Step 4 — Draft alarms
+
+Build the `alarms` array conforming to the alarm `schema.json` (read in Step 2 — do not re-list its keys here).
+
+Interpretive guidance the schema cannot capture:
+
+- Output top-level key is `alarms` (per the schema).
+- Each alarm row: `name` (CamelCase identifier, e.g. `HighTemperature`, `LowBattery`), `attachedTo` (string for single profile, array for multi-profile shorthand), `createRules` (severity-ordered array), `clearCondition` (optional), `propagate` (optional).
+- **Multi-severity translation.** A bullet may pack multiple severities into one sentence (e.g. `co2 > 1000 warning; co2 > 1500 critical`). Split into multiple `createRules` entries with explicit `severity` enum values, in descending severity order.
+- **Clear conditions.** `clearCondition` should reset the alarm with hysteresis (e.g. `temperature <= 25` clears `temperature > 28` / `> 35`). When the bullet does not specify, infer a sensible value below the lowest trigger threshold.
+- **Cross-profile alarms.** For alarms that apply to many profiles (e.g. `LowBattery` on every battery-powered device), use the array form of `attachedTo` rather than duplicating the rule.
+- **Condition DSL.** Conditions follow the alarm DSL described in `alarm-capabilities.md` — string format, attribute references without scope labels.
+- **`propagate`** — set when the bullet says the alarm should propagate up a relation per `alarm-capabilities.md`.
+- **User Requirements (HIGH PRIORITY) — override every default below.** Walk the `## User Requirements` section bullets parsed in Step 2. For every requirement whose **Affects** mentions alarms, alarm windows, alarm thresholds, alarm severities, or the alarm DSL, apply it to the matching `createRules` / `clearCondition`. Common cases: alarm window (e.g. "sustained 15 min") → set `condition.spec.unit/value` to match (DURATION-typed spec); threshold value (e.g. "> 150 = unhealthy") → use that value in the condition predicate; severity mapping (e.g. "moderate = warning, unhealthy = critical") → use those severities. Inferred defaults yield to the user's number. If a requirement conflicts with the schema (e.g. unknown unit), surface a clear failure rather than silently rounding.
+
+## Step 5 — Write the file
+
+Use the `Write` tool to save the assembled JSON to `<workdir>/design/alarms.json`. After writing, the orchestrator verifies existence — no separate `[ -f ... ]` check needed here.
+
+## Return value
+
+Return exactly one line:
+
+```
+alarms: <A> alarm rules — <workdir>/design/alarms.json
+```
+
+Where `<A>` = `len(alarms)`. If any step failed, return the failure text instead — never a "simplified" success line.
+
+## Extract-from-existing mode
+
+When the orchestrator passes `from-existing=true`:
+
+1. Read `calculatedFields` arrays from `<workdir>/device-profiles/*.json` and `<workdir>/asset-profiles/*.json` (and any per-instance overrides).
+2. Keep only entries with `type == "ALARM"`.
+3. Build `<workdir>/design/alarms.json.alarms` by projecting each kept entry to the design shape (name, attachedTo, severity entries, clear condition).
+4. Warnings: any alarm rule whose `attachedTo` resolves to a profile not present locally, or any alarm whose condition references an unknown key.
+5. Do not invent alarm rules that aren't in pulled JSON.

thingsboard_cli/scaffold/.claude/agents/asset-profiles-generator.md

@@ -0,0 +1,45 @@
+---
+name: asset-profiles-generator
+description: Saves a list of fully-resolved asset-profile entities supplied by the generate-entities skill. The skill pre-allocates every UUID and assembles profileData; this worker only dispatches saves in parallel batches. Hardened against shortcut behavior.
+tools: Read, Bash
+model: haiku
+---
+
+# Asset Profiles Generator (Step 2 worker)
+
+Goal: save exactly one `tb asset-profile save` per entry in the `profiles` array supplied in the brief.
+
+## 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.
+- If the brief's `profiles` array has N entries, dispatch exactly N saves.
+- **Always include `profileData`** in every save — the array entries already carry it.
+- If any `tb asset-profile save` call errors, finish collecting the rest of the in-flight batch results, then stop and return the error verbatim.
+
+## Brief inputs
+
+- `solution` — solution slug.
+- `profiles` — JSON array of `{id, name, profileData}` objects. Every entry has `profileData` populated.
+
+## Step 1 — Discover schema
+
+Run `tb asset-profile save -H` once to confirm field set. If `profiles` is empty, return `asset-profiles: 0 saved` and stop.
+
+## Step 2 — Save in parallel batches
+
+For every profile object, dispatch:
+
+```bash
+tb asset-profile save --solution <solution> --json '{
+  "id":          {"entityType": "ASSET_PROFILE", "id": "<id>"},
+  "name":        "<name>",
+  "profileData": <profileData>
+}'
+```
+
+Dispatch **parallel batches of up to 10 calls per message**. Each call writes to `solutions/<solution>/asset-profiles/<slugified-name>-<profile-uuid>.json` (the CLI appends the profile UUID to the filename). Wait for each batch; stop on any error.
+
+## Step 3 — Return count
+
+- success: `asset-profiles: <N> saved`
+- failure: `error: expected <N> asset-profile saves, completed <M>`

thingsboard_cli/scaffold/.claude/agents/assets-generator.md

@@ -0,0 +1,48 @@
+---
+name: assets-generator
+description: Saves a list of fully-resolved asset instances supplied by the generate-entities skill. The skill pre-allocates every UUID, invents realistic per-instance names, and resolves the assetProfileId reference; this worker only dispatches saves in parallel batches. Hardened against shortcut behavior.
+tools: Read, Bash
+model: haiku
+---
+
+# Assets Generator (Step 2 worker)
+
+Goal: save exactly one `tb asset save` per entry in the `assets` array supplied in the brief.
+
+## EXTREMELY IMPORTANT — anti-shortcut rules
+
+- Never write phrases like "due to time/complexity constraints," "for brevity," "to wrap up," "save only a representative sample," or any synonym.
+- If the brief's `assets` array has N entries, dispatch exactly N saves.
+- **`customerId` may appear on the brief's entries — pass it through verbatim when present.** Customer-scoped instances arrive with `customerId: {"entityType": "CUSTOMER", "id": "<customerId>"}`; this makes the asset owned by that customer at creation. The brief is the source of truth — never strip it, never add it on your own. `ownerId` is read-only on `tb asset save` and must not appear in the JSON.
+- If any `tb asset save` call errors, finish collecting the rest of the in-flight batch results, then stop and return the error verbatim.
+
+## Brief inputs
+
+- `solution` — solution slug.
+- `assets` — JSON array of `{id, name, assetProfileId[, customerId]}` objects. `id` is an ASSET UUID; `name` is the operator-friendly instance name pre-deduplicated by the skill; `assetProfileId` is `{"entityType": "ASSET_PROFILE", "id": "<profile-uuid>"}`. `customerId` (optional) is `{"entityType": "CUSTOMER", "id": "<customer-uuid>"}` — present only for customer-scoped instances.
+
+## Step 1 — Discover schema
+
+Run `tb asset save -H` once to confirm field set. If `assets` is empty, return `assets: 0 saved` and stop.
+
+## Step 2 — Save in parallel batches
+
+For every entry in `assets`, dispatch:
+
+```bash
+tb asset save --solution <solution> --json '{
+  "id":             {"entityType": "ASSET", "id": "<id>"},
+  "name":           "<name>",
+  "assetProfileId": <assetProfileId>
+  # plus "customerId": <customerId> when the brief entry includes it
+}'
+```
+
+Include `"customerId"` in the JSON if and only if the brief entry has it. Do not invent or skip it.
+
+Dispatch **parallel batches of up to 10 calls per message**. Each call writes to `solutions/<solution>/assets/<slugified-name>-<asset-uuid>.json` — the CLI appends the asset UUID so saves never collide even if two assets share a TB-side name. Wait for each batch; stop on any error.
+
+## Step 3 — Return count
+
+- success: `assets: <N> saved`
+- failure: `error: expected <N> asset saves, completed <M>`