thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/scaffold/.claude/agents/attribute-values-generator.md

@@ -0,0 +1,124 @@
+---
+name: attribute-values-generator
+description: Generates realistic static ATTRIBUTE values for one DEVICE or ASSET profile and saves them across all entities of that profile via parallel `tb attributes save` batches. One AI call per profile for the template; per-instance variation rules applied per entity; saves dispatched in batches of 10 (different files, race-free). Invoked in parallel — one per profile with ATTRIBUTE keys — by generate-entities Part 2.
+tools: Read, Bash
+model: haiku
+---
+
+# Attribute Values Generator (per-profile worker)
+
+Goal: for **one** profile that has ≥1 ATTRIBUTE-type key, generate realistic static values once (per profile), apply per-instance variation per entity, then `tb attributes save` for every entity of that profile in parallel batches.
+
+The save step writes one entity file at a time per call — different files per call, so the batch is race-free across this profile's entities. Across different profiles (other agents running in parallel): also race-free, because each agent writes to its own profile's entity files.
+
+## 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.
+- Process **every** entity in the brief's `entities` array — the skill has already filtered out entities that have no missing keys, so every entry here genuinely needs work. Do not drop entities to save tokens.
+- For each entity, save **only the keys listed in its `keysToSave` field**. The skill performs the missing-key filtering; your job is to honor it. Do not save keys outside `keysToSave` (those are already populated on the entity and must not be overwritten).
+- One AI call total for the template (Step 1). Do not re-call the AI per entity — per-entity variation is mechanical (Step 2).
+- If any `tb attributes save` call fails, log the failure and continue with the next entity — return the error count in the final summary. Do **not** stop the batch; failures are reported, not fatal.
+
+## Brief inputs
+
+- `solution` — solution slug.
+- `profile` — profile name.
+- `entityType` — `DEVICE` or `ASSET` (the `--entity-type` flag for `tb attributes save`).
+- `attributeKeys` — JSON array of key definitions for the ATTRIBUTE keys that **at least one entity in this brief is missing** (the skill has pre-filtered this to the union of `keysToSave` across the brief's entities). Each entry: `{key, dataType, classifier?, enumValues?, units?, minValue?, maxValue?}`.
+- `entities` — JSON array of `{id, name, index, keysToSave}` for every entity that has at least one missing key. `index` is 1-based, used by the variation rules in Step 2. `keysToSave` is the subset of `attributeKeys[*].key` that this specific entity does not yet have populated — save **only** these keys for this entity.
+- `parentZoneName` — name of the parent zone/asset from `relations.json`, or empty string if none.
+- `customerName` — customer name parsed from `architecture-overview.md` (the markdown's Customers & Users section), or empty string.
+- `siteName` — site name parsed from `architecture-overview.md` (Summary or Customers section), or empty string.
+
+## Step 0 — Pick the floor plan filename (if relevant)
+
+Decide locally whether this profile needs a floor plan filename. Inspect `attributeKeys`:
+
+- If **any** key has `classifier == "image"` OR `key` name (lowercased) contains `"floorplan"`, the profile needs a filename.
+- Otherwise, set `floorPlanFileName = ""` and skip the rest of Step 0.
+
+When needed:
+
+1. `Read` `@$TB_RESOURCES/prompts/solutions/dashboard/resources/images.json` — floor plan filenames grouped by `type`.
+2. Match the `solution` slug to a `type` field (e.g. `smart-office` → `"Smart office"`; `parking` → `"Smart parking"`; `retail` → `"Smart retail"`; `assisted-living` → `"Assisted living"`; `irrigation` → `"Smart irrigation"`; `oil-station-monitoring` → `"Oil station"`). Substring/keyword match is fine — pick the most specific type whose name appears in the solution slug.
+3. Pick the first `fileName` from the matching entries (e.g. `"smart-office-plan-1.png"`) and store as `floorPlanFileName`.
+4. If no type matches, use the first entry in the file and add `Note: no floor plan type matched solution domain — using default.` to your eventual return output.
+
+## Step 1 — Generate template values (one AI call)
+
+Make exactly **one** AI call with this context:
+
+- Profile name and `entityType`.
+- The full `attributeKeys` array.
+- `parentZoneName`, `customerName`, `siteName`, `solution` (slug), and `floorPlanFileName` from Step 0.
+
+Task for the AI:
+
+> "Generate realistic static attribute values for all ATTRIBUTE keys in this profile. Return a flat JSON object `{"key": value}` where each value is type-correct for the key's dataType. Rules:
+> - STRING keys: realistic text (model numbers, addresses, serial prefixes, phone numbers, emails)
+> - BOOLEAN keys: a sensible default (e.g. `active: true`, `enabled: true`)
+> - INTEGER/DOUBLE keys: a value within minValue–maxValue bounds if given
+> - enumValues keys: pick one value from the enumValues list
+> - classifier=image or floorPlan key name: use exactly the value `/api/images/system/<floorPlanFileName>` (always prefix the filename with `/api/images/system/`, e.g. `/api/images/system/assisted-living-plan-1.png`)
+> - classifier=outdoorPolygon (e.g. `perimeter`): emit a **JSON string** containing the serialized polygon array — e.g. `"[[37.77,-122.42],[37.78,-122.42],[37.78,-122.41],[37.77,-122.41]]"` (note the surrounding quotes, the value is a string, NOT a raw JSON array). Coordinates are `[lat, lng]` pairs anchored to the customer zone. 4–8 vertices, polygon closes implicitly (do not repeat the first vertex).
+> - classifier=indoorPolygon (e.g. `indoorZone`): emit a **JSON string** containing the serialized polygon array in normalized `[x, y]` coordinates within [0.0, 1.0] — e.g. `"[[0.1,0.1],[0.9,0.1],[0.9,0.9],[0.1,0.9]]"` (string, not raw array).
+> - classifier=latitude/longitude: coordinates inside the customer zone (anchor to city/region from the customerName/siteName context)
+> - classifier=indoorLocationX/indoorLocationY: a value in [0.0, 1.0]
+> - Classifier takes precedence over key name for strategy selection; key name is used as fallback when classifier is absent.
+> - classifier=phone: a realistic local phone number
+> - classifier=email: a realistic email address
+> - classifier=address: a realistic street address anchored to the customer region
+> Do NOT generate per-instance variation here — generate one representative value per key."
+
+Store the output as `templateValues` (flat JSON object keyed by key name).
+
+## Step 2 — Apply per-instance variation rules
+
+For each entity in `entities`, build its final attribute JSON by starting from `templateValues`, **restricting the object to the keys listed in this entity's `keysToSave`**, then replacing per-key values that need variation. Keys outside `keysToSave` must not appear in the saved JSON — they are already populated on the entity file and must not be overwritten. The variation rules:
+
+| Condition | Rule |
+|---|---|
+| classifier absent AND key name (lowercased) contains `"serial"` or equals `"deviceid"` | Append zero-padded 3-digit index suffix: `<base>-001`, `<base>-002`, … |
+| `classifier == indoorLocationX` | If `len(entities) == 1`: use `0.5`. Otherwise grid-space: `round(0.1 + (index-1) * 0.8 / (len(entities)-1), 2)` |
+| `classifier == indoorLocationY` | Even `index` → `0.3`; odd `index` → `0.7` |
+| `classifier == latitude` | Add small offset per device: `round(baseLat + (index-1) * 0.0002, 6)` |
+| `classifier == longitude` | Add small offset per device: `round(baseLon + (index-1) * 0.0002, 6)` |
+| All other keys | Same value as `templateValues[key]` |
+
+`baseLat` and `baseLon` are the values from `templateValues` for those keys.
+
+Hold the resolved per-entity JSON objects in working memory keyed by entity id.
+
+## Step 3 — Save attributes in parallel batches
+
+**Pre-save check — polygon-classifier values must be JSON strings.** For every entity's resolved JSON, walk the `attributeKeys` definitions and verify: every key whose `classifier` is `outdoorPolygon` or `indoorPolygon` (e.g. `perimeter`, `indoorZone`) has a **string** value that parses as a JSON array of `[lat,lng]` (outdoor) or `[x,y]` (indoor) coordinate pairs. If any such key is a raw JSON array, raw object, `null`, or an unparseable string, log `attributes: <entityType> <uuid> (<name>): ERROR — polygon key '<key>' must be a JSON string, got <type>` and skip the save for that entity (count it as failed, continue with the rest). The server stores attributes as strings; a raw array would either be coerced unpredictably or rejected by the geofencing CF that reads it.
+
+For every entity in `entities`, dispatch:
+
+```bash
+tb attributes save <entityType> <entity-id> --solution <solution> --json '<resolved-attribute-json>'
+```
+
+No `--scope` flag — default `SERVER_SCOPE` is correct.
+
+Dispatch in **parallel batches of up to 10 per message**. Each call writes to a different entity file, so the batch is race-free. Wait for each batch to return before sending the next.
+
+**On per-call failure:** log `attributes: <entityType> <uuid> (<name>): ERROR — <message>` for that entity, mark it failed in your counters, and continue with the rest of the batch — do NOT stop. Other entities should still be processed.
+
+## Step 4 — Return value
+
+Print one line per successful save, one line per failed save, then a profile totals line:
+
+```
+attributes: <entityType> <uuid> (<name>): <N> keys saved
+attributes: <entityType> <uuid> (<name>): ERROR — <message>
+profile <profile>: <D> entities, <K> total keys, <E> errors
+```
+
+Where:
+- `<N>` per successful save = `len(keysToSave)` for that entity (the saved JSON contains exactly that entity's missing keys — variation modifies values, never the key set).
+- `<K>` per profile total = sum of `<N>` across successful entities.
+- `<E>` per profile total = count of failed saves.
+- `<D>` per profile total = `len(entities)`.
+
+The skill aggregates one of these blocks per profile.

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

@@ -0,0 +1,179 @@
+---
+name: cf-generator
+description: Renders one calculated-field design entry into TB wire-format JSON and saves it via `tb calculated-field save`. Invoked in parallel — one per CF — by the generate-calculated-fields skill.
+tools: Read, Bash
+model: haiku
+---
+
+# CF Generator (per-CF worker)
+
+Goal: translate **one** calculated-field design entry into TB wire-format JSON and save it via `tb calculated-field save`, in one Haiku pass. Returns a one-line summary; the skill needs nothing else.
+
+Sibling `cf-generator` agents (one per CF, 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
+
+Every device in this pipeline reports telemetry **every 30 minutes**. This is the canonical reporting interval the emulator produces and the CF must be tuned against:
+
+- **Reporting interval** = 30 minutes = `1_800_000` ms.
+- **48 ticks/day, 336 ticks/week** — match the emulator's demo data window (7 days × 48).
+- For TB CF type `SCRIPT` (metric `delta` and any rolling-window `script`), the `TS_ROLLING` argument's `timeWindow` must be **~1.5× the reporting interval** → use **`2_700_000` ms** (45 minutes). This guarantees the rolling buffer always contains the previous tick (`limit: 2`) without dragging in stale samples.
+- For TB CF type `ENTITY_AGGREGATION` (metric `ts-aggregation`), pick `configuration.interval` so each window contains enough ticks to be meaningful (`HOUR` = 2 ticks, `DAY` = 48, `WEEK` = 336). Never pick a `CUSTOM` `durationSec` shorter than 1,800 seconds — the window would be empty most of the time.
+- For TB CF type `RELATED_ENTITIES_AGGREGATION`, set `configuration.deduplicationIntervalInSec` to at least `1800` (one tick); going lower wastes cycles since no new data arrives between ticks.
+
+If the design entry specifies a different interval explicitly, follow the entry — otherwise these defaults apply.
+
+## 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 CF in the brief. Do not return multiple, do not skip.
+- **Strictly follow the JSON schema returned by `tb calculated-field save -H`.** That schema is the only source of truth for field names, value types, nested object shapes, type discriminators, and required vs optional fields. Do not invent fields. Do not borrow field names from sibling CF subtypes that don't apply (`SIMPLE` shape ≠ `SCRIPT` shape ≠ `RELATED_ENTITIES_AGGREGATION` shape — never mix them). Do not guess at discriminator values. 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.
+- 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 calculated-field save` errors, return the error verbatim. Do not retry.
+
+## Brief inputs
+
+- `solution` — solution slug.
+- `cf` — JSON object: the single CF design entry from the metrics file. Always includes `name`, `attachedTo` (single profile name), `type`, `inputs`, `output`, and `calculation` (a short natural-language description of what the metric computes — the spec).
+- `entityProfilesJsonPath` — absolute path to entity-profiles design file. Needed to classify each argument's `refEntityKey.type` as `TS_LATEST` vs `ATTRIBUTE` (based on whether the key lives in `timeSeriesKeys` or `attributeKeys` of the relevant profile). Related-aggregation CFs also use this to find the related profile's keys.
+
+## Step 1 — Decide the TB CF subtype
+
+Before reading anything, translate the brief's design `cf.type` to the TB CF subtype and to the reference filename that documents it. This decision drives which files Step 2 reads — picking the right subtype up front avoids loading every per-type reference, keeps context tight, and prevents subtype bleed (the most common rendering failure).
+
+| Design `cf.type` (brief)     | TB subtype                     | Reference                 |
+|------------------------------|--------------------------------|---------------------------|
+| `math`                       | `SIMPLE`                       | `simple.md`               |
+| `script`, `delta`            | `SCRIPT`                       | `script.md`               |
+| `ts-aggregation`             | `ENTITY_AGGREGATION`           | `ts-aggregation.md`       |
+| `related-aggregation`        | `RELATED_ENTITIES_AGGREGATION` | `related-aggregation.md`  |
+| `geofencing`                 | `GEOFENCING`                   | `geofencing.md`           |
+| `propagate`                  | `PROPAGATION`                  | `propagation.md`          |
+
+If `cf.type` is not in this table, stop with `error: cf "<cfName>" attached to "<profile>": unknown design type '<cf.type>' — expected one of math/script/delta/ts-aggregation/related-aggregation/geofencing/propagate`.
+
+Also decide **up front** whether the resulting CF will embed TBEL. TBEL applies when:
+
+- TB subtype is `SCRIPT` (covers design `script` and `delta`); **or**
+- TB subtype is `RELATED_ENTITIES_AGGREGATION` and the design entry carries a `filter` or a function-typed metric `input` (`AggFunctionInput`); **or**
+- TB subtype is `PROPAGATION` and the design entry sets `applyExpressionToResolvedArguments: true`.
+
+TBEL does **not** apply for `SIMPLE`, `ENTITY_AGGREGATION`, `GEOFENCING`, or bare `PROPAGATION`. Carry the boolean `needsTbel` into Step 2.
+
+## Step 2 — Load schema + behavioral references
+
+Run in a single parallel batch, picking files based on the Step 1 decision:
+
+1. `Read` `<entityProfilesJsonPath>`.
+2. `tb calculated-field save -H` — authoritative schema (required vs optional fields, type discriminators, nested config shapes) for every CF sub-type.
+3. `Read` `$TB_RESOURCES/prompts/ai-assistant/skills/calculated-fields/SKILL.md` — top-level reference: argument JSON shape, output type/strategy, rounding rules, `defaultValue` rules, host-selection guidance.
+4. `Read` `$TB_RESOURCES/prompts/ai-assistant/skills/calculated-fields/references/<reference>` — the per-type reference chosen in Step 1. Read **only** this one — do not load other subtypes' references.
+5. If `needsTbel == true`: `Read` `$TB_RESOURCES/prompts/tbel/tbel-reference.md`. Otherwise omit this file entirely — TBEL is not used and the file is large.
+
+Verify the brief's `cf.attachedTo` profile exists in entity-profiles under `deviceProfiles` or `assetProfiles`. If not, stop with `error: profile '<name>' not found in entity-profiles`.
+
+## Step 3 — Render the CF
+
+Render the CF JSON from the design entry using the files loaded in Step 2 as the sole source of truth:
+
+- **`tb calculated-field save -H`** — required-vs-optional fields, field types, type discriminators.
+- **`calculated-fields/SKILL.md`** — top-level CF shape: argument source/type tables, output type/strategy, rounding, `defaultValue` conventions, host-selection guidance.
+- **The per-type reference** (`references/<subtype>.md`) — the chosen subtype's exact `configuration` shape, valid enum values, and per-subtype rules. **Never borrow fields between subtypes** — `SIMPLE` ≠ `SCRIPT` ≠ `ENTITY_AGGREGATION` ≠ `RELATED_ENTITIES_AGGREGATION` ≠ `GEOFENCING` ≠ `PROPAGATION`.
+- **`tbel-reference.md`** (loaded only when `needsTbel`) — TBEL syntax, helpers, gotchas.
+
+**TBEL standard library constraints — required for every TBEL script.** TBEL is based on MVEL, not JavaScript. The following rules MUST hold in every script emitted; a script that violates any of them throws at runtime on the server:
+
+- **`Math.max` / `Math.min` take exactly 2 arguments.** TBEL only binds the 2-argument forms. Calling them with 3+ arguments throws `unable to resolve method: java.lang.Math.max(Double, Double, Double) [arglength=3]`. Chain pairwise:
+  ```
+  var result = Math.max(Math.max(a, b), c);                       // 3 values
+  var result = Math.max(Math.max(Math.max(a, b), c), d);          // 4 values
+  ```
+  Same rule for `Math.min`. Every other `Math` method (`Math.round`, `Math.abs`, `Math.sqrt`, `Math.pow`, `Math.floor`, `Math.ceil`, `Math.log`, …) works normally.
+- **No ES6+ syntax.** Use `var` only — no `let`, no `const`. Use named functions or inline blocks — no arrow functions (`=>`). Use string concatenation with `+` — no template literals (backtick strings). Read members by name or index — no destructuring (`var {a, b} = obj`) or spread (`...`).
+- **One `var` per line.** `var a, b, c = 0;` is a syntax error. Declare each variable on its own line: `var a = 0; var b = 0; var c = 0;`.
+- **`null`, not `undefined`.** TBEL has no `undefined`. Absent values are `null`; check with `!= null` (or use the null-safe `?.` operator).
+
+**Both `type` fields are required and must match.** Emit `type` at the **entity level** (top-level CF root) AND `configuration.type` at the **config level** — both set to the same TB subtype string from the Step 1 mapping (`SIMPLE | SCRIPT | PROPAGATION | GEOFENCING | ENTITY_AGGREGATION | RELATED_ENTITIES_AGGREGATION`). Never emit one without the other; never let the two values diverge. The server rejects a CF missing either field, and downstream processing breaks silently when they disagree.
+
+**Argument key resolution against entity-profiles.** For every input key the design entry references, look it up on the parent profile (in `<entityProfilesJsonPath>`, under `deviceProfiles` or `assetProfiles`):
+
+- Key in `timeSeriesKeys` → time-series argument (`TS_LATEST` by default; `TS_ROLLING` when the subtype's reference says a window is needed).
+- Key in `attributeKeys` → `ATTRIBUTE` argument with `scope: SERVER_SCOPE`.
+- Key absent on the profile → stop with `error: cf "<cfName>" attached to "<profile>": input key '<key>' not found on profile`. Do not invent.
+
+**Parse `cf.calculation` into the implementation.** The design's `calculation` is the natural-language spec — translate it into the implementation (TBEL body for `SCRIPT`, `configuration` shape for the rest) using the per-type reference and `tbel-reference.md` (when `needsTbel`). For `math` only, `cf.expression` copies verbatim into `SIMPLE`'s `configuration.expression`.
+
+### Delta template — only for design `cf.type == "delta"`
+
+The skill emits design type `delta` as a synthetic `SCRIPT`-subtype CF tuned for the fixed 30-minute reporting cadence. The per-type reference (`references/script.md`) covers SCRIPT in general but **not** this specific shape — use the template below verbatim.
+
+- **Argument:** exactly one `TS_ROLLING` arg keyed on the input, `limit: 2`, `timeWindow: 2_700_000` (45 min = 1.5× the 30-min cadence — guarantees the buffer always contains the previous tick).
+- **Expression body** (substitute `<in>` = input arg name, `<out>` = output key):
+  - **Increase mode** — for counters, energy, engine-hours, anything monotonically rising:
+    ```
+    if (<in>.count() < 2) { return {"<out>": 0}; }
+    var delta = <in>.last() - <in>.first();
+    if (delta < 0) { return {"<out>": 0}; }
+    return { ts: ctx.latestTs, values: {"<out>": delta} };
+    ```
+  - **Decrease mode** — for consumption from a falling level: swap to `<in>.first() - <in>.last()` and gate with `if (delta <= 0)`.
+- **Mode selection.** Read `mode` from the design entry. If absent, infer from semantics — counter / monotonically rising → increase; consumption / falling level → decrease. If still ambiguous, stop with `error: cf "<cfName>": delta mode unclear — design must specify mode (increase or decrease)`.
+- **Cadence floor.** `timeWindow` must be ≥ `2_700_000`. Lower values mean the buffer can be empty between ticks — reject as a cadence violation.
+
+## Step 4 — Pre-save self-validate the rendered CF JSON
+
+Validate the JSON you just rendered in Step 3 against the schema returned by `tb calculated-field save -H` (loaded in Step 2). The check is local to this CF — 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, **capture** the specific failure(s) — which check tripped, the field path, expected vs got — and proceed to Step 4a (re-render). Do not proceed to Step 5 with a known-bad JSON. If every check passes on the first try, skip Step 4a and proceed directly to Step 5.
+
+This walk is **not** a re-statement of the schema — the server already enforces required fields, unknown fields, and missing extras. Focus only on the failure modes the retry in Step 4a can actually fix:
+
+- **Both `type` fields are present and match.** The rendered JSON MUST carry `type` at the **entity level** (top-level CF root, one of `SIMPLE | SCRIPT | PROPAGATION | GEOFENCING | ENTITY_AGGREGATION | RELATED_ENTITIES_AGGREGATION`) AND `configuration.type` at the **config level** (same enum, same value). Either field missing, or the two values disagreeing, is a hard validation failure — the server rejects the CF and downstream processing breaks silently when the values diverge.
+- **Type discriminator matches subtype shape.** `configuration.type` is one of `SIMPLE | SCRIPT | PROPAGATION | GEOFENCING | ENTITY_AGGREGATION | RELATED_ENTITIES_AGGREGATION`, and the rest of `configuration` matches that subtype — no fields from a different subtype leaked in. This is the #1 rendering failure; catching it locally lets the retry rebuild without burning a server roundtrip.
+- **Per-argument-type fields.** For each entry in `configuration.arguments`:
+  - `refEntityKey.type` is `TS_LATEST` / `TS_ROLLING` / `ATTRIBUTE`.
+  - `TS_ROLLING` arg: `limit` and `timeWindow` present; `defaultValue` absent.
+  - `TS_LATEST` / `ATTRIBUTE` arg: `limit` and `timeWindow` absent.
+  - `TS_ROLLING` only appears when `configuration.type == SCRIPT`.
+  - `ATTRIBUTE` arg on an asset-profile parent has `scope: "SERVER_SCOPE"`.
+- **Output shape gotchas.** For `SCRIPT`, `output.name` is absent (keys come from the script's return). For `ATTRIBUTE` output on an asset-profile parent, `output.scope == "SERVER_SCOPE"`.
+- **Telemetry-cadence floors** (from the section at the top of this file — these are solution-specific and the server does **not** enforce them). `TS_ROLLING.timeWindow == 2_700_000` (45 min), `ENTITY_AGGREGATION` `CUSTOM durationSec ≥ 1800` if used, `RELATED_ENTITIES_AGGREGATION.deduplicationIntervalInSec ≥ 1800`. If any value is below the floor, stop with an explicit cadence error — the design entry is wrong upstream.
+- **TBEL standard library constraints** (only when the rendered CF embeds a TBEL script — `SCRIPT` subtype, including the `delta` template). Re-read each script string and confirm: no `Math.max`/`Math.min` call has 3+ arguments; no `let`/`const`/arrow function/template literal/destructuring/spread appears; every `var` declares a single variable; no `undefined` token appears (use `null`). Any violation is a hard self-validation failure — re-render in Step 4a with the specific violation as a constraint.
+
+If all checks pass, proceed to Step 5. Server-side validation still runs on `tb calculated-field save` — this self-check just prevents obvious malformed JSON from reaching the server.
+
+## Step 4a — Re-render once on self-validation failure
+
+Only reached if Step 4 caught at least one failure. Re-do Step 3 using the captured failure(s) as explicit constraints on the new render:
+
+- **Missing entity-level `type` or `configuration.type`** → set the absent field to the subtype the design entry dictates (per the Step 1 mapping). Both fields are required.
+- **Entity-level `type` and `configuration.type` disagree** → reset both to the subtype the design entry dictates. They must match exactly.
+- **Extra / foreign field** (a field from a different subtype leaked in) → remove it.
+- **Wrong type-discriminator value** (e.g. `configuration.type`, `refEntityKey.type`, `output.type`) → correct it to the value the design entry dictates.
+- **Per-argument-type field violation** (e.g. `defaultValue` on `TS_ROLLING`, or `limit`/`timeWindow` on `TS_LATEST` / `ATTRIBUTE`) → rebuild the offending argument with **only** the legal fields for its `refEntityKey.type`.
+- **`TS_ROLLING` on a non-SCRIPT subtype** → either drop the rolling window (downgrading to `TS_LATEST`) when the design entry doesn't actually need rolling, or stop and error if the design entry genuinely requires a rolling arg on a non-SCRIPT subtype (that's an upstream bug).
+- **Cadence-floor violation** (`TS_ROLLING.timeWindow < 2_700_000`, `ENTITY_AGGREGATION CUSTOM durationSec < 1800`, `RELATED_ENTITIES_AGGREGATION.deduplicationIntervalInSec < 1800`) → set the value to the floor.
+
+After re-rendering, run **Step 4 again** on the new JSON.
+
+- If the re-rendered JSON passes self-validation, proceed to Step 5.
+- If the re-rendered JSON still fails, stop and return `error: cf "<cfName>" attached to "<profile>": self-validation failed twice — first: <first failure summary>; second: <second failure summary>`.
+
+**Exactly one** re-render attempt. If both renders fail, surface the error — do not loop further.
+
+## Step 5 — Save
+
+Emit one Bash call:
+
+```bash
+tb calculated-field save --solution <solution> --json '<rendered-cf-json>'
+```
+
+Wait for the result. On error, return the error verbatim and stop.
+
+## Step 6 — Return value
+
+- Success: `cf "<cfName>" attached to "<profile>": saved`
+- Failure: `error: cf "<cfName>" attached to "<profile>": <message>`
+
+The skill aggregates these into a final summary.

thingsboard_cli/scaffold/.claude/agents/cf-reprocess-generator.md

@@ -0,0 +1,132 @@
+---
+name: cf-reprocess-generator
+description: Discovers calculated fields in a solution, applies the eligibility filter, and queues `tb calculated-field reprocess` calls in parallel batches. Supports local mode (writes task files for later `tb push --run-tasks`) and remote mode (calls the server immediately). Invoked by the reprocess-calculated-fields skill. Reads inputs from disk; conversation context is not required.
+tools: Read, Bash
+model: haiku
+---
+
+# CF Reprocess Generator
+
+Goal: queue `tb calculated-field reprocess` tasks for every eligible calculated field in a deployed solution. Each task writes to its own file (`solutions/<slug>/tasks/reprocessing/<unique>.json` in local mode) or hits its own server endpoint (remote mode), so dispatches go in **parallel batches of up to 10 per message** — different destinations, no race.
+
+## 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 discovery step finds N eligible CFs, dispatch exactly N reprocess calls — no "representative subset."
+- If any `tb calculated-field reprocess` call errors, finish collecting the rest of the in-flight batch results, then stop and return the error verbatim.
+
+## Brief inputs
+
+- `solution` — solution slug. Required in local mode; in remote mode it can still be passed (used for context only — the remote call doesn't take `--solution`).
+- `mode` — `local` (default) or `remote`. In `local`, dispatches write task files under `solutions/<slug>/tasks/reprocessing/`. In `remote`, dispatches call the server directly via `--remote` and return a `Job`.
+- `startTs` / `endTs` — millisecond timestamps for the reprocess window. If omitted, default to **last 7 days** (`endTs = now`, `startTs = now − 7d`).
+- `nameFilter` — optional substring or exact CF name to narrow the scope. If set, only CFs whose `name` matches are reprocessed.
+- `entityTypeFilter` / `entityIdFilter` — optional. Restricts to CFs attached to a specific entity (e.g. `entityType=DEVICE_PROFILE`, `entityId=<uuid>`).
+
+## Step 1 — Discover calculated fields
+
+Build the list of CFs in the solution by scanning the solution directory:
+
+- `Read` every file under `solutions/<solution>/device-profiles/*.json`, `solutions/<solution>/asset-profiles/*.json`, `solutions/<solution>/devices/*.json`, `solutions/<solution>/assets/*.json`.
+- For each file, inspect the `entity.calculatedFields` array (CFs embed into the parent entity's file). For each CF entry, record:
+  - `name` (the CF name)
+  - `entityType` of the parent (`DEVICE_PROFILE`, `ASSET_PROFILE`, `DEVICE`, `ASSET`)
+  - `entityId` of the parent (from `entity.id.id`)
+  - `output.type` (`TIME_SERIES` or `ATTRIBUTE`) — needed for the eligibility filter
+  - `configuration.arguments[*].refEntityKey.type` — needed for the eligibility filter
+
+If `solutions/<solution>/` has none of these directories or every directory is empty, stop with `error: no entities found in solution '<solution>' — reprocess cannot run before entities have been materialized`.
+
+Apply `nameFilter` / `entityTypeFilter` / `entityIdFilter` (if any) to drop CFs that don't match.
+
+## Step 2 — Apply the eligibility filter
+
+Drop a CF from the list if any of these holds — its reprocess would have nothing meaningful to compute:
+
+- **`type == "ALARM"`** — alarm-rule calculated fields are evaluated against live events; reprocessing them does not produce or re-fire historical alarms, so the operation is a no-op.
+- **`output.type == "ATTRIBUTE"`** — attribute outputs aren't written per timestamp; there is no time-window backfill to perform.
+- **All arguments are attribute-typed** — every `refEntityKey.type == "ATTRIBUTE"`. There is no historical telemetry window to walk.
+
+All other CF types remain eligible — `math`, `script`, `ts-aggregation`, `related-aggregation`, `delta`, `propagate`, `geofencing`. **Do not** drop a CF just because it's `script`/`math`/`propagate`/`geofencing`; only the three rules above apply.
+
+If the resulting eligible list is empty, return `reprocess tasks queued: 0 (no eligible CFs)` and stop.
+
+## Step 3 — Compute reprocess order from CF dependencies
+
+One CF can read another CF's output as an input — e.g. an `aqi` CF on `Device` produces `aqi`; an `avgAqi` CF on `Asset` reads related-aggregated `aqi`. The dependent CF (`avgAqi`) must reprocess **after** its inputs (`aqi`), otherwise it backfills against stale data. `tb calculated-field reprocess` honours `--order` (lower runs first, default `100`), so each call needs a per-CF integer order that respects the dependency graph.
+
+Build the order map:
+
+1. `Read` `solutions/<solution>/design/metrics.json` if it exists. Skip the whole step (every eligible CF gets `--order 100`) if it's missing — that's the standalone-reprocess fallback.
+2. For each eligible CF `X` from Step 2, look up its entry in `metrics.json.calculatedFields` by `name`. Read `X.inputs` (the input key list) and `X.output.keys` (the output key list — `metrics.json` declares these explicitly, so don't try to parse SCRIPT bodies).
+3. `X.dependencies = { Y ∈ eligible CFs : any key in X.inputs is in Y.output.keys }`. Match by key name only — that catches same-profile chains, related-aggregation, and propagate without needing to model relations here. CFs filtered out in Step 2 are not dependencies (they don't run).
+4. Topologically assign integer orders:
+   - CFs with empty `dependencies` get `order = 1`.
+   - Otherwise `order(X) = 1 + max(order(Y) for Y in X.dependencies)`.
+5. If a cycle is detected (no CF makes progress in a pass), stop with `error: dependency cycle among calculated fields: <cf-names>`.
+
+CFs with the **same order run in parallel on the server**, so independent metrics (`avgAqi` vs `peopleCount`) naturally end up sharing an order — no manual grouping needed.
+
+## Step 4 — Dispatch reprocess calls in parallel batches
+
+Pick the time window once for the whole run:
+- If `startTs` and `endTs` were both provided, use them.
+- Otherwise: `endTs = $(date +%s%3N)`, `startTs = $((endTs - 7 * 24 * 60 * 60 * 1000))` (last 7 days in ms).
+
+Dispatch one call per eligible CF, in **parallel batches of up to 10 per message**. Each call has its own destination (different task file in local mode, different server job in remote mode), so the batch is race-free. Wait for each batch to return before dispatching the next; stop on any error. In **local mode**, pass `--order <N>` from the Step 3 map on every call — that's the field `tb push --run-tasks` uses to sequence task execution.
+
+### Local mode
+
+```bash
+tb calculated-field reprocess \
+  --entity-type <DEVICE|ASSET|DEVICE_PROFILE|ASSET_PROFILE> \
+  --entity-id <entity-uuid> \
+  --name "<cf-name>" \
+  --start-ts <startTs> \
+  --end-ts <endTs> \
+  --order <N> \
+  --solution <solution>
+```
+
+**Set `--entity-type` / `--entity-id` to where the CF is attached** — the server filters by attachment, not inheritance. For profile-attached CFs (`DEVICE_PROFILE` / `ASSET_PROFILE`), emit **one** task per CF — the server fans out across all instances at run time. Never create per-instance tasks for a profile-attached CF.
+
+### Remote mode
+
+The remote call uses the **positional CF UUID** and the `--remote` flag. The `--entity-type` / `--entity-id` / `--name` / `--solution` flags are LOCAL mode only and must NOT be passed in remote mode.
+
+CF UUIDs are discovered from the local files in Step 1 (the `id.id` field on each CF in the parent's `calculatedFields` array). If a CF's local file doesn't carry a UUID, fall back to a name lookup:
+
+```bash
+tb calculated-field list --entity-type <T> --entities <entity-uuid> --name "<cf-name>" --format json
+```
+
+Then dispatch:
+
+```bash
+tb calculated-field reprocess <calculated-field-uuid> \
+  --remote \
+  --start-ts <startTs> \
+  --end-ts <endTs>
+```
+
+The CLI returns a `Job` with status `QUEUED` / `PENDING` / `RUNNING` / `COMPLETED` / `FAILED` / `CANCELLED`. Treat anything other than `COMPLETED` (or a still-running status acceptable to the caller) as a failure to be surfaced.
+
+## Step 5 — Return value
+
+**Local mode:**
+
+```
+reprocess tasks queued: <N> (deploy with `tb push <solution> --run-tasks` to execute)
+```
+
+**Remote mode:**
+
+Print one line per call, then a totals line:
+
+```
+reprocess <cf-name> on <ENTITY_TYPE> <uuid>: <Job.status> (job-id: <id>)
+...
+reprocess total: <N> calls, <F> failed
+```
+
+If `<F> > 0`, append `errors logged above.`

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

@@ -0,0 +1,50 @@
+---
+name: customers-generator
+description: Saves a list of fully-resolved customer entities supplied by the generate-entities skill. The skill pre-allocates every UUID and renders the JSON-ready dicts; this worker only dispatches saves in parallel batches. Reads no design files. Hardened against shortcut behavior.
+tools: Read, Bash
+model: haiku
+---
+
+# Customers Generator (Step 2 worker)
+
+Goal: save exactly one `tb customer save` per entry in the `customers` 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 `customers` array has N entries, dispatch exactly N saves. No "representative subset," no skipping.
+- If any `tb customer save` call errors, finish collecting the rest of the in-flight batch results, then stop and return the error verbatim. Do not retry.
+
+## Brief inputs
+
+- `solution` — solution slug.
+- `customers` — JSON array of `{id, title[, parentCustomerId]}` objects. `id` is a CUSTOMER UUID; `title` is the unique customer instance name. `parentCustomerId` (optional) is `{"entityType": "CUSTOMER", "id": "<parent-uuid>"}` — present only for sub-customer instances (the parent customer must already exist on the server when this customer is created). The skill has already pre-allocated every UUID, deduplicated titles, and **topologically ordered the array by hierarchy depth** so every parent appears before its sub-customers.
+
+## Step 1 — Discover schema
+
+Run `tb customer save -H` once to confirm the field set required by the local CLI. If the brief's `customers` array is empty, return `customers: 0 saved` and stop without touching anything.
+
+## Step 2 — Save in parallel batches
+
+For every entry in `customers`, dispatch:
+
+```bash
+tb customer save --solution <solution> --json '{
+  "id":               {"entityType": "CUSTOMER", "id": "<id>"},
+  "title":            "<title>"
+  # plus "parentCustomerId": <parentCustomerId> when the brief entry includes it
+}'
+```
+
+Pass `parentCustomerId` through verbatim when present on the brief entry; omit otherwise. Never strip it, never invent it.
+
+Dispatch **parallel batches of up to 10 calls per message**. Each call writes to `solutions/<solution>/customers/<slugified-title>-<customer-uuid>.json` — the CLI appends the customer UUID so saves never collide even if two customers share a TB-side title. Wait for each batch to return before the next; stop on any error.
+
+**Hierarchy ordering.** The brief's `customers` array is pre-sorted by hierarchy depth (top-level customers first, then depth-2 sub-customers, etc.). Process the array in order — within a batch of 10, every parent referenced by a sub-customer in a *later* batch must already be saved. Because batches complete sequentially, this is automatic **as long as you do not reorder the array or interleave depths within a batch**. The planner has already laid out the array so that the natural sequential chunking respects dependencies; preserve that order.
+
+## Step 3 — Return count
+
+Count successful saves and compare to `len(customers)`. Return:
+
+- success: `customers: <N> saved`
+- failure: `error: expected <N> customer saves, completed <M>` (or the original `tb` error if a save failed)