thingsboard-cli 4.3.1.2.post1__tar.gz → 4.3.1.2.post3__tar.gz

thingsboard_cli-4.3.1.2.post3/.gitignore

@@ -0,0 +1,17 @@
+.idea
+*.iml
+.planning
+docs
+docs/superpowers
+/.claude
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/

thingsboard_cli-4.3.1.2.post3/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: thingsboard-cli
+Version: 4.3.1.2.post3
+Summary: CLI tool for managing ThingsBoard resources
+Project-URL: Homepage, https://github.com/thingsboard/thingsboard-cli
+Project-URL: Source, https://github.com/thingsboard/thingsboard-cli
+Project-URL: Issues, https://github.com/thingsboard/thingsboard-cli/issues
+Requires-Python: <3.15,>=3.11
+Requires-Dist: click<9.0,>=8.1
+Requires-Dist: filelock<4.0,>=3.13
+Requires-Dist: httpx<1.0,>=0.28
+Requires-Dist: packaging>=24.0
+Requires-Dist: pydantic-settings<3.0,>=2.13
+Requires-Dist: pydantic<3.0,>=2.12
+Requires-Dist: questionary<3.0,>=2.0
+Requires-Dist: rich<15.0,>=14.0
+Requires-Dist: tb-pe-client==4.3.1.3.post2
+Requires-Dist: textual<2.0,>=0.83
+Requires-Dist: typer<1.0,>=0.24.1
+Requires-Dist: tzdata>=2024.1
+Description-Content-Type: text/markdown
+
+# ThingsBoard CLI
+
+CLI tool for managing ThingsBoard resources from the terminal.
+
+## Installation
+
+Install [uv](https://docs.astral.sh/uv/) if you don't have it:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Then install the CLI:
+
+```bash
+uv tool install thingsboard-cli
+```
+
+### Upgrading
+
+The CLI checks for updates automatically on launch and prompts to upgrade. You can also upgrade manually:
+
+```bash
+tb update
+```
+
+### Shell Completion
+
+```bash
+# Bash
+tb --install-completion bash
+
+# Zsh
+tb --install-completion zsh
+
+# Fish
+tb --install-completion fish
+```
+
+Restart your terminal after installing completion.
+
+## Usage
+
+```bash
+tb --help
+tb config set --url https://thingsboard.cloud --api-key YOUR_KEY
+tb device list
+```
+
+## Verbose Help
+
+Use `-H` or `--help-verbose` on any command to see detailed API documentation, JSON schemas, and field descriptions:
+
+```bash
+tb device create -H
+tb dashboard save -H
+```
+
+## Contributing
+
+For local development setup, editable installs, regenerating help text, and publishing, see [CONTRIBUTING.md](https://github.com/thingsboard/thingsboard-cli/blob/master/CONTRIBUTING.md).

thingsboard_cli-4.3.1.2.post3/pyproject.toml

@@ -0,0 +1,90 @@
+[project]
+name = "thingsboard-cli"
+version = "4.3.1.2.post3"
+description = "CLI tool for managing ThingsBoard resources"
+readme = "README.md"
+requires-python = ">=3.11,<3.15"
+dependencies = [
+    "typer>=0.24.1,<1.0",
+    "click>=8.1,<9.0",
+    "pydantic>=2.12,<3.0",
+    "pydantic-settings>=2.13,<3.0",
+    "rich>=14.0,<15.0",
+    "textual>=0.83,<2.0",
+    "questionary>=2.0,<3.0",
+    "httpx>=0.28,<1.0",
+    "tb-pe-client==4.3.1.3.post2",
+    "packaging>=24.0",
+    "filelock>=3.13,<4.0",
+    # IANA time-zone database for `zoneinfo`. Windows ships no system tz data,
+    # so emulator timeZone validation (ZoneInfo("UTC")) fails without this.
+    "tzdata>=2024.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/thingsboard/thingsboard-cli"
+Source = "https://github.com/thingsboard/thingsboard-cli"
+Issues = "https://github.com/thingsboard/thingsboard-cli/issues"
+
+[project.scripts]
+thingsboard = "thingsboard_cli.main:app"
+tb = "thingsboard_cli.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# Pin the core metadata version. hatchling >=1.32 defaults to Metadata-Version
+# 2.5, which twine 6.x rejects (it caps validation at 2.4), so uploads fail.
+# 2.4 is what the whole packaging ecosystem accepts today.
+[tool.hatch.build.targets.sdist]
+core-metadata-version = "2.4"
+
+[tool.hatch.build.targets.wheel]
+core-metadata-version = "2.4"
+packages = ["src/thingsboard_cli"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"scaffold" = "thingsboard_cli/scaffold"
+"extension-starter" = "thingsboard_cli/extension-starter"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+src = ["src", "tests"]
+exclude = ["src/thingsboard_cli/help/_generated"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "UP", "B", "SIM", "RUF", "I"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+plugins = ["pydantic.mypy"]
+exclude = ["src/thingsboard_cli/help/_generated"]
+disallow_any_generics = false
+warn_return_any = false
+
+[[tool.mypy.overrides]]
+module = "tb_pe_client.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "e2e: end-to-end tests requiring real ThingsBoard instance",
+    "requires_tb: e2e tests that require TB_URL/TB_API_KEY (auto-applied to most e2e files; test_extension.py opts out)",
+    "maven_e2e: e2e tests that require a working Maven wrapper + JDK 17+",
+    "docker_e2e: e2e tests that require a reachable Docker daemon",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.20.0",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=7.1.0",
+    "pytest-mock>=3.15.1",
+    "respx>=0.22.0",
+    "ruff>=0.15.8",
+]

thingsboard_cli-4.3.1.2.post3/scaffold/agent-kit/INSTRUCTIONS.md

@@ -0,0 +1,306 @@
+## 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 the `thingsboard-concepts` skill to understand how ThingsBoard entities are structured and connected: tenants, customers, devices, assets, device/asset profiles, attributes and time series, 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.
+- **`tb feedback` is allowed** — running `tb feedback` (to record user feedback, see below) is safe and expected; it is not a config or push command.
+
+## Feedback
+
+Two separate things — do both.
+
+### 1. Always end a completed generation with a feedback invitation
+
+Whenever you finish generating anything — a single entity, a standalone artifact (`standalone-*`), or a full solution (`create-solution` / `update-solution`) — the **last line of your final message MUST be**, verbatim:
+
+> Help us make the CLI better — share quick feedback anytime with `tb feedback`.
+
+This is a passive one-liner (not a question); print it in the same turn the generation finishes, after any deploy/`tb push` notice. Do not skip it, and do not print it when you did not generate anything.
+
+### 2. Follow the feedback hook
+
+A feedback hook (Claude Code `UserPromptSubmit` / Antigravity `PreInvocation`) runs `tb feedback --hook` automatically on **every** message. When a feedback ask is due (the user generated something, or skipped a real-terminal push prompt — and it's been ≥4h since the last ask), the hook injects a reminder telling you to ask. **You never track timing yourself; just obey the reminder when it appears.**
+
+When you see that reminder, **before** handling the request, ask **one** `AskUserQuestion` (`header: "Feedback"`, options **Yes** · **Partly** · **No** · **Skip**):
+
+> "Did you achieve the result you expected? Tell us what to improve in your own words — your feedback shapes what we build next."
+
+The user clicks an option, or picks the auto-provided **"Other"** field to write a comment (the only free-text path — capture whatever they write). Then **record it yourself** (never make the user run the command):
+
+- **Yes / Partly / No** → `tb feedback --outcome <yes|partly|no> [--message "<their comment>"] [--feature "<a feature idea>"] --source push-followup`
+- **Skip** (or no answer) → `tb feedback --dismiss`
+
+Then continue with the request. Ask at most once per reminder; do not ask when no reminder is present. Feedback is anonymous and honors the analytics opt-out (the hook stays silent when analytics is off).
+
+<!-- The question wording and the `tb feedback --outcome … --source push-followup` / `--dismiss`
+     command spec above mirror `_HOOK_REMINDER` in src/thingsboard_cli/core/feedback.py.
+     Keep the two in sync when either changes. -->
+
+## 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. targeted vs. build vs. update
+
+Route by **intent**, then by existence/completeness. Check the paths **in this order** — the first match wins:
+
+1. **Fetch / pull / import / grab / refresh** existing entities (no build or change implied) → `Skill pull-solution` (see rule below — unchanged).
+2. **Targeted ask** — the request names a **specific artifact or a small targeted set** to build, add, edit, fix, or **diagnose**: "add a calculated field to my Pump-42", "fix my EfficiencyIndex CF", "fix my OverheatAlarm", "2 devices for the water-pump profile", "a dashboard showing my Pump-42", "add a humidity gauge to the pump dashboard" — and equally diagnostic questions about a specific artifact: "I have a calculated field on my Ira device but it does not work — why?", "why does my OverheatAlarm never fire?". A diagnostic question IS a fix-intent ask: the standalone skill diagnoses first and applies the fix only after the user confirms. → Run the **standalone-vs-solution gate** below BEFORE calling any skill (diagnostic phrasing already decides — skip the gate, invoke the skill directly). Do NOT invoke `update-solution` or `create-solution` for a targeted ask until the gate (or unambiguous phrasing) has decided. This path matches even when the named entities already exist locally or on the instance — touching existing entities does not by itself make the ask solution-scoped.
+3. **Build / create / generate a NEW solution from scratch** → `Skill create-solution`.
+4. **Continue / finish / resume generation** of a solution whose prior build was interrupted → `Skill create-solution` (its local resume-to-continue detects which steps completed and runs only the remaining ones; it does not refresh from the instance).
+5. **Add to / extend / change / modify a solution** — the ask is phrased at solution scope ("add 5 more devices to `<solution>`", "add a new sensor type to `<solution>`", "extend `<solution>` with …", "change the alarms on `<solution>`") or implies redesigning multiple artifact kinds together → first tool call MUST be `Skill update-solution`. It locates the target (local, then instance), refreshes only with consent, and applies the change surgically; if nothing exists to update, it hands back to `create-solution`.
+
+The create/update line is **intent + completeness**, not merely "does it exist": finishing an unfinished build is `create-solution`; surgically changing a finished solution is `update-solution`.
+
+### Targeted entity ask: the standalone-vs-solution gate
+
+This is path 2's decision point — for a targeted ask it runs **before any skill is invoked**. When the request names a **specific artifact or a small targeted set** to build, add, edit, or fix — one or a few calculated fields (including a CF chain), alarm rules, devices/assets/customers/users/profiles/entity groups (e.g. "2 devices for the water-pump profile"), a standalone dashboard to create over existing entities, or a dashboard tweak — on known or named targets, with **no solution design implied** (no new profile + relations + IAM + dashboard set to design together), ask once via `AskUserQuestion` before routing:
+
+- `question`: `"Just these item(s), or full solution treatment (design context, related entities kept in one place)?"`
+- `header`: `"Scope"`
+- `options`: `Just these items` · `Full solution treatment`
+
+Route the answer:
+
+- **Just these items** → the matching standalone-* skill: `standalone-calculated-fields`, `standalone-alarm-rules`, `standalone-dashboard`, or `standalone-entities` (devices, assets, customers, users, profiles, entity groups).
+- **Full solution treatment** → `update-solution` (existing target) or `create-solution` (new system), per the rules above.
+
+**Skip the question when the phrasing already decides:** "just the CFs, nothing else" / "only these two alarms" / "fix my OverheatAlarm" → standalone path directly; "and design alarms + a dashboard around it" or anything implying a system → solution path directly. Asks that need design work (new profiles with relations/IAM, role-based dashboard sets, anything phrased as a system/setup/scenario) never see the gate — they route per the rules above. The fetch/pull rule still takes precedence over this gate for pure fetch requests.
+
+**The gate applies whenever the work begins — including mid-conversation.** When an ad-hoc investigation or Q&A turns into create/edit/fix work ("yes, fix it"), invoke the matching standalone-* skill at that moment. Never hand-roll `tb … save` calls, mode switches, or scratch solutions inline — the skill owns the resolver, key discovery, foundations rendering, validation, and commit flow.
+
+**A follow-up change to a dashboard you generated or pushed earlier in this same conversation is still an edit — route it.** Immediately after the `dashboard-generator` agent runs and the dashboard is saved/pushed, the JSON is fresh in your context and it is tempting to "just tweak it" inline. Don't: a follow-up dashboard change ("make that gauge a chart", "add a humidity widget", "fix the alias") routes through `standalone-dashboard` (or `update-solution` for a solution dashboard) → `dashboard-generator` in **update mode**, exactly as a cold-start edit would. Having just built the dashboard, or holding its JSON in context, is **not** a license to hand-edit the dashboard JSON — alias-owns-keys, `typeFullFqn`, widget templates, and the validation walk only get applied through the agent, and hand-edits silently reintroduce the inaccuracies the agent exists to prevent.
+
+---
+
+**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` and `update-solution` routing below for pure fetch/pull/import requests.
+
+### Otherwise: build or update path
+
+**Use the `create-solution` skill when the request involves any of:**
+
+- **Any large or non-trivial NEW system.** If the request describes building a new system, platform, product, or anything that needs more than one or two entities working together from scratch, route it to `create-solution`. Default to "this is a solution" whenever the scope is ambiguous and no existing solution is named.
+- **Multiple related entities** — e.g. a new asset and its devices, devices that share a new profile, anything phrased as a "system", "setup", "scenario", "demo", or new use case.
+- **A dashboard on a NEW solution** — Dashboards have a complex JSON structure and depend on an entity + metric model; never hand-build dashboard JSON outside a skill. (A dashboard *change* on an existing solution routes to `update-solution`; a small standalone dashboard over **existing** entities — "a dashboard showing my Pump-42 temperature" — routes through the gate to `standalone-dashboard`, which resolves the entities, recovers their live keys, and builds its design context ad-hoc.)
+- **Calculations or alarms on a NEW device/asset** — these need profile and design context to be meaningful and reprocessable.
+- **Continuing / finishing an interrupted build** — if a prior create run was interrupted and the solution is only partially built, route here; `create-solution` resumes from where it left off using only local state.
+
+**Use the `update-solution` skill when the request involves any of:**
+
+- **Adding to or modifying an existing solution** — "add 5 more devices to `<solution>`", "add a new sensor type to `<solution>`", "extend `<solution>` with …", "change the alarms on `<solution>`". `update-solution` locates the solution (local, then instance), reuses existing IDs, profile names, and design decisions, and applies the change surgically. It never regenerates untouched artifacts.
+- **Changing a dashboard on an existing solution** — adding a widget, changing a chart, adjusting layout. Routing here (not `create-solution`) preserves the existing dashboard content.
+- **Instance-import** — building a solution around entities that already live on the instance (the import, reverse-engineering, and fold-in work lives in `update-solution`).
+- **Any request that touches entities already present** locally or on the instance.
+
+**Direct entity generation (using this file's command reference inline) is superseded by the standalone-* skills.** A targeted ask that passes the gate above as "Just these items" routes to `standalone-entities` / `standalone-calculated-fields` / `standalone-alarm-rules` / `standalone-dashboard` — those skills own the standalone flow (resolver, scratch solution, schema discipline). The "Single-entity generation flow" and command sections below remain as the reference those skills follow.
+
+## 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 route through a skill, never by hand here — `standalone-calculated-fields` / `standalone-alarm-rules` when the gate chose the standalone path, `create-solution` for a new solution, `update-solution` for solution-level changes.
+
+**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-4.3.1.2.post3/scaffold/agent-kit/agents/alarm-generator.md

@@ -0,0 +1,96 @@
+---
+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
+skills:
+  - alarm-rule-foundations
+---
+
+# 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.
+
+`alarm-rule-foundations` is already in your context (preloaded). It defines the reference reading map, the schema discipline, the rendering rules (both `type` fields with the `ALARM` discriminator, severity-keyed `createRules` map, top-level `clearCondition`/`propagate`), the pre-save self-validation walk, and the save command. Do NOT re-read it from disk. This file adds only the solution-pipeline layer: the brief contract, the design-entry translation rules, the telemetry cadence, entity-profiles key resolution, and the already-exists backstop.
+
+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 design pass (`design-solution-architecture`) is supposed to enforce the same floors. If you have to reject here, the `## Alarms` bullet in `architecture-overview.md` 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.
+- Follow the foundations **schema discipline** exactly. 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.
+
+## 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.
+- `architectureOverviewPath` — absolute path to `architecture-overview.md`, the single design artifact. Used to verify the target profile exists and to classify condition keys.
+- `overwrite` (optional bool, default `false`) — `true` when this alarm's definition changed this run: skip the Step 4 already-exists backstop and re-save over the existing entry.
+
+## Step 1 — Load schema + behavioral references
+
+Run the foundations **required-reading batch** (the `-H` schema, the alarm data-model overview, the full alarm-rule reference, the TBEL reference only when a condition uses Script mode), plus `Read` `<architectureOverviewPath>` — all in a single parallel batch.
+
+Verify the brief's `profile` exists in the overview as a `### <Profile> (DEVICE|ASSET)` subsection. If not, stop with `error: profile '<name>' not found in architecture-overview.md`.
+
+## Step 2 — Render the alarm
+
+Render the TB alarm-rule JSON from the design entry per the foundations **schema discipline** and **rendering rules**, with the Step 1 files as the sole source of truth. Do not duplicate rules from those files here; treat the references as authoritative.
+
+**Solution-specific translation rules** (how the design entry maps onto the TB shape):
+
+- **`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 the severity-keyed **map** described in foundations. Convert by emitting one map entry per array element, with the severity string as the key and the condition structure as the value.
+- **Argument key resolution against the overview.** For every key referenced by any condition or argument, look it up under the target profile's `### <Profile>` subsection in `architecture-overview.md`:
+  - Key under `Telemetry:` → time-series argument (a derived key annotated `(derived: …)` is still a time-series key).
+  - Key under `Attributes:` → `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
+
+Run the foundations **self-validation walk** on the rendered JSON. Append these solution-specific checks to the walk:
+
+- **`alarmType` matches the design `name`.** Byte-for-byte equal to the design entry's `name`.
+- **Condition keys exist on the target profile.** Every key referenced by any condition or argument appears under the brief's `profile` in the overview (`Telemetry:` or `Attributes:`). 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.
+
+Per the foundations walk, any failure stops with an error naming the check, the field path, and expected vs got — do **not** attempt a fix; surface the bug so the upstream stack sees it.
+
+## Step 4 — Save (with already-exists backstop)
+
+The dispatching skill already filtered out (alarm, profile) pairs that exist on disk; as a backstop against races, re-check just before saving — **unless the brief carries `overwrite=true`** (the alarm's definition changed this run; save unconditionally, replacing the same-name entry): locate the parent profile file under `solutions/<solution>/device-profiles/` or `solutions/<solution>/asset-profiles/` (the file whose entity `name` equals the brief's `profile`) and check its embedded `calculatedFields` array for an `ALARM`-type entry with the same alarm name. If present, **do not save** — return `alarm "<alarmName>" attached to "<profile>": skipped (already exists)`.
+
+Otherwise 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`
+- Backstop skip: `alarm "<alarmName>" attached to "<profile>": skipped (already exists)`
+- Failure: `error: alarm "<alarmName>" attached to "<profile>": <message>`
+
+The skill aggregates these into a final summary.