thingsboard-cli 4.4.0__tar.gz → 4.4.0.1__tar.gz

{thingsboard_cli-4.4.0 → thingsboard_cli-4.4.0.1}/CHANGELOG.md

@@ -2,6 +2,103 @@
 
 All notable changes to ThingsBoard CLI are documented in this file.
 
+## [4.4.0.1] — Unreleased
+
+First-run usability release.
+
+### Added
+
+- **`tb config --browser`.** Connect on a local web page instead of the
+  terminal, in two steps: select ThingsBoard Cloud (North America),
+  ThingsBoard Cloud (Europe), or your own server; then paste an API key.
+  For your own server, `https://` is optional: the CLI tries HTTPS first,
+  then HTTP, and warns when the key would travel over plain HTTP. AI agents run commands
+  without an interactive terminal, so they cannot type into the wizard. The
+  page runs on `127.0.0.1` with a one-time token, tests the connection, and
+  closes after 15 minutes. The key never appears in the terminal, the chat,
+  or the logs, and the browser does not offer to save it as a password.
+- **`tb init` connects the CLI and shows the next steps.** `tb init` checks
+  the ThingsBoard connection and prints `Connected to <url>`. If the CLI is
+  not connected, an interactive `tb init` offers to connect: it opens the API
+  keys page and tests the key. `--browser` uses the local web page instead
+  (for AI agents). At the end, `tb init` shows how to start the agent and an
+  example prompt. Non-interactive runs never wait for input; `--skip-config`
+  skips the connection step.
+- **`tb emulator run [SOLUTION]`.** Sends live demo data to ThingsBoard for a
+  limited time (`--duration`, default 10 minutes; `--interval`, default 5
+  seconds) from the solution's emulators, so the dashboard changes while you
+  watch it. Each device continues from its latest stored value. The command
+  shows the dashboard links at the start. Press Ctrl+C to stop.
+- **`tb init <folder>`.** Creates the project in a new or existing folder.
+- **`tb init --guided`.** Asks for the project folder and offers to start
+  Claude Code or Antigravity in it. The one-line installer uses this option.
+
+### Changed
+
+- **Clear connection errors.** A failed connection now says what to fix: an
+  invalid or expired API key, a user without permissions, a URL that is not a
+  ThingsBoard server, a host that was not found, a connection or TLS problem.
+  Before, the message was only `HTTP 401` or a raw network error.
+- **The `tb config` wizard lets you try again.** On a failed connection in an
+  interactive terminal, the wizard asks `Try again?` and does not save a
+  broken profile unless you confirm. Piped input keeps the previous behavior.
+  The wizard also shows the page where you create an API key.
+- **The agent deploys after you confirm.** At the end of a build, update, or
+  standalone change, the agent asks once: "Deploy to ThingsBoard and stream
+  live demo data for 5 minutes?" On approval it runs `tb push --run-tasks`,
+  starts `tb emulator run` in the background, and shows the dashboard links.
+  Progress notices in the middle of a build no longer tell you to push.
+- **Demo history follows the solution.** The design picks how many days of
+  history the emulators write (7 by default; 30 for monthly patterns such as
+  billing or consumption; up to 90 for seasonal trends). Generated dashboards
+  open on a realtime window of the same length, so charts show the whole
+  history and keep moving when live data arrives.
+- **README:** one-line installers, `tb init`, and the `TB_URL`, `TB_API_KEY`,
+  `TB_PROFILE`, `TB_CONFIG_HOME` and `TB_DEBUG` environment variables.
+- **Dashboards use HTML pages by default.** On ThingsBoard 4.4.0.1 and later
+  (and when the version is unknown), the agent builds every dashboard state as
+  an HTML page. Stock widgets appear only in embedded helper states: maps, and
+  the alarm table when users acknowledge or clear alarms. Pages open the stock
+  entity dialogs from their own buttons. On older servers the agent keeps
+  the previous behavior: stock widgets in a grid, custom content only on
+  request. Existing dashboards keep their layout; only new or rebuilt states
+  follow the new default.
+- **Quick builds for small requests.** "My sensor sends {…}. Show it on a
+  dashboard." now builds only the device, the alarm you asked for, demo
+  data and one dashboard — no interview, no approval stops, and no made-up
+  customers, roles or users. Say "full solution" for the full design flow.
+  Grow a quick build later with `update-solution`: when you add the first
+  customer, user group or role, the agent writes the full role design and
+  moves the existing dashboard to the new administrator role instead of
+  creating a second one.
+- **No empty folders in new projects.** `tb init` and `tb solution new` no
+  longer create every entity folder up front; the CLI creates a folder when
+  it saves the first file there. The empty root folders next to
+  `solutions/<name>/` looked like a second copy of the solution. `tb init`
+  also writes a short `README.md` that explains the project layout (an
+  existing README is kept). Existing projects are not changed.
+
+### Fixed
+
+- **Embedded charts no longer show "No data" for a selected device.** The
+  agent could name a state alias parameter `entityId` while the page
+  published the device as the default state entity, so the alias resolved to
+  nothing. The alias template, the composition rules and a new validation
+  check now keep the two in step.
+- **Standalone dashboards no longer look for a missing dashboard group.**
+  They are built for the built-in tenant administrator, who sees every tenant
+  dashboard, so the agent no longer needs a "Dashboards for Default" group.
+- **Feedback is asked only after the user sees a result.** `tb validate` no
+  longer flags a feedback ask. The agent runs `validate` in the middle of a
+  solution build, so the question appeared before the dashboards existed.
+  Only a successful `tb push` flags the ask now.
+  The agent asks at least 15 minutes after the push, so you can look at the
+  result first, and only at the end of its reply — it handles your request
+  first.
+- **`tb push --run-tasks` prints the dashboard links last.** The links came
+  before the emulators and the calculated field reprocessing ran, so a quick
+  click could show an empty dashboard.
+
 ## [Unreleased] — Pre-v1 Release Audit Fixes
 
 This release closes all 71 findings from the Pre-v1 release audit

{thingsboard_cli-4.4.0 → thingsboard_cli-4.4.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thingsboard-cli
-Version: 4.4.0
+Version: 4.4.0.1
 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
@@ -26,13 +26,19 @@ CLI tool for managing ThingsBoard resources from the terminal.
 
 ## Installation
 
-Install [uv](https://docs.astral.sh/uv/) if you don't have it:
+Run one command. It installs [uv](https://docs.astral.sh/uv/) if it is missing, installs the CLI, and starts the guided setup:
 
 ```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
+# macOS and Linux
+curl -LsSf https://thingsboard.io/cli/install.sh | sh
 ```
 
-Then install the CLI:
+```powershell
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://thingsboard.io/cli/install.ps1 | iex"
+```
+
+Or install with uv yourself:
 
 ```bash
 uv tool install thingsboard-cli
@@ -64,9 +70,26 @@ Restart your terminal after installing completion.
 ## Usage
 
 ```bash
-tb --help
-tb config set --url https://thingsboard.cloud --api-key YOUR_KEY
+tb init my-project      # create a project, connect to ThingsBoard, and see the next steps
+tb config               # connect to ThingsBoard (add --browser when an AI agent runs it)
 tb device list
+tb --help
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|---|---|
+| `TB_URL` | ThingsBoard URL. Overrides the URL of the active profile. |
+| `TB_API_KEY` | API key. Overrides the credentials of the active profile. Use it with `TB_URL` in CI. |
+| `TB_PROFILE` | Name of the profile to use, the same as `--profile`. |
+| `TB_CONFIG_HOME` | Folder for profiles and settings. Default: `~/.thingsboard`. |
+| `TB_DEBUG` | Set to `1` to print every HTTP request and response, the same as `--debug`. |
+
+Example for CI:
+
+```bash
+TB_URL=https://thingsboard.cloud TB_API_KEY=$TB_API_KEY tb push my-solution
 ```
 
 ## Verbose Help

thingsboard_cli-4.4.0.1/README.md

@@ -0,0 +1,84 @@
+# ThingsBoard CLI
+
+CLI tool for managing ThingsBoard resources from the terminal.
+
+## Installation
+
+Run one command. It installs [uv](https://docs.astral.sh/uv/) if it is missing, installs the CLI, and starts the guided setup:
+
+```bash
+# macOS and Linux
+curl -LsSf https://thingsboard.io/cli/install.sh | sh
+```
+
+```powershell
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://thingsboard.io/cli/install.ps1 | iex"
+```
+
+Or install with uv yourself:
+
+```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 init my-project      # create a project, connect to ThingsBoard, and see the next steps
+tb config               # connect to ThingsBoard (add --browser when an AI agent runs it)
+tb device list
+tb --help
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|---|---|
+| `TB_URL` | ThingsBoard URL. Overrides the URL of the active profile. |
+| `TB_API_KEY` | API key. Overrides the credentials of the active profile. Use it with `TB_URL` in CI. |
+| `TB_PROFILE` | Name of the profile to use, the same as `--profile`. |
+| `TB_CONFIG_HOME` | Folder for profiles and settings. Default: `~/.thingsboard`. |
+| `TB_DEBUG` | Set to `1` to print every HTTP request and response, the same as `--debug`. |
+
+Example for CI:
+
+```bash
+TB_URL=https://thingsboard.cloud TB_API_KEY=$TB_API_KEY tb push my-solution
+```
+
+## 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.4.0 → thingsboard_cli-4.4.0.1}/extension-starter/extension/target/thingsboard-extension-1.0.0-SNAPSHOT.jar

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
-name: thingsboard_cli-4.4.0/extension-starter/extension/target/thingsboard-extension-1.0.0-SNAPSHOT.jar
+name: thingsboard_cli-4.4.0.1/extension-starter/extension/target/thingsboard-extension-1.0.0-SNAPSHOT.jar
 size: 39342529 bytes
 sha256: b2a093f7037d1d4fcc9b196d9bd5412a02920a181b39e2d02cf54939630a6d7d

{thingsboard_cli-4.4.0 → thingsboard_cli-4.4.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "thingsboard-cli"
-version = "4.4.0"
+version = "4.4.0.1"
 description = "CLI tool for managing ThingsBoard resources"
 readme = "README.md"
 requires-python = ">=3.11,<3.15"

thingsboard_cli-4.4.0.1/roadmap/connectivity.md

@@ -0,0 +1,111 @@
+# ThingsBoard CLI: device connectivity roadmap
+
+## Goal
+
+The user connects a real device to a solution that the agent built. The user sees live data on the dashboard.
+Later, the agent does most of this work for the user.
+
+## When
+
+This work starts after the release `4.4.0.1`. That release adds the configuration fixes, the live emulator (`tb emulator run`) and the new docs at `/docs/cli/`.
+
+## Current state (CLI 4.4.0)
+
+- `tb device credentials <device-id>` accepts only a device UUID. It shows only the access token.
+- No command shows how to send data from a device.
+- The emulator creates history only: 7 days, with one value each 30 minutes. It runs one time, during `tb push --run-tasks`. After that, the dashboard data does not change.
+- No agent skill helps with device connection.
+- The CLI has no commands for rule chain transformations, integrations, converters or IoT Gateway configuration.
+
+## Milestones
+
+Each milestone is a CLI release, together with its docs. Do the milestones in this order.
+
+### M1 — Connect one device by HTTP or MQTT
+
+**User result:** "I have a device. The CLI tells me exactly how to send data. I see the data on my dashboard."
+
+| # | Change | Details |
+|---|---|---|
+| M1.1 | `tb device connect <name-or-id>` | Find the device by name or UUID. Get its credentials. Show commands that are ready to run: `curl` for HTTP and `mosquitto_pub` for MQTT. Use the host from the active profile. Add `--transport http\|mqtt` and `--format json` (for agents). |
+| M1.2 | Example payload | Make the example payload from the device's emulator definition. If there is none, use the telemetry keys of the device profile. If there are no keys, use `{"temperature": 25}`. |
+| M1.3 | Credential types | Support `ACCESS_TOKEN` and `MQTT_BASIC` fully. For `X509_CERTIFICATE`, show the required files and link to the docs. Do not show secrets unless the user adds `--show-secrets`. |
+| M1.4 | Host and port | HTTP: use the profile URL. MQTT: use the host of the profile URL with port 1883, or port 8883 with `--tls`. Add `--host` and `--port` for self-hosted instances with a different setup. **Verify the MQTT hosts for Cloud NA and Cloud EU before release.** |
+| M1.5 | `tb device connect --wait` | After the commands are shown, wait for the first telemetry from the device (default timeout: 5 minutes). Then show "Data received: temperature=22.5 …" and the dashboard link. This gives the user a clear success message. |
+| M1.6 | `tb device credentials` accepts a name | A small change. It makes the command the same as `tb device get`. |
+| M1.7 | Agent skill `connect-real-device` | The user asks "How do I connect my sensor?" The agent runs `tb device connect --format json`. Then it explains the steps and runs `--wait` while the user sends data. |
+| M1.8 | Skills show the next step | After `tb push`, the standalone skills and the solution skills tell the user: "To send real data, run `tb device connect <name>`." |
+
+**Docs:** the guide "Connect your real device". Add a "Next step" link from the Quickstart.
+
+**Done when:** a new user sends one value with `curl` and sees it on the dashboard in 3 minutes or less.
+
+### M2 — Live emulator as a real device
+
+The first release (`4.4.0.1`) adds `tb emulator run`. That command sends data through the tenant REST API. This milestone changes it to send data the same way a real device does.
+
+**User result:** "The emulator tests my device credentials and my device profile before I connect real hardware."
+
+| # | Change | Details |
+|---|---|---|
+| M2.1 | Send through the device API | Use the device credentials and the host logic from M1.4. Keep the tenant REST API as a fallback with `--via rest`. |
+| M2.2 | Choose the transport | Add `--transport http\|mqtt`. Use the same transport as the device profile by default. |
+| M2.3 | Show errors per device | If a device cannot send, show the device name and the reason, for example "invalid token". Continue with the other devices. |
+
+**Docs:** add the transport options to the emulator section of the Commands reference.
+
+### M3 — Data from devices that does not match the model
+
+**User result:** "My device sends nested JSON or other units. The agent adapts the data, so the dashboard shows the correct values."
+
+| # | Change | Details |
+|---|---|---|
+| M3.1 | Rule chain skill | Add an agent skill that creates and changes rule chains with TBEL transformation nodes. The `tb rule-chain` command exists, but no skill uses it. |
+| M3.2 | Payload analysis | The user gives an example payload. The agent compares it with the device profile. Then the agent suggests one of these: a calculated field, a TBEL transformation, or a change to the model. |
+| M3.3 | Test the transformation locally | Run a TBEL script on an example payload before the push. Check that `tb system test-script` (or a similar command) does this. |
+
+**Docs:** the guide "Adapt your device payload".
+
+### M4 — Many devices
+
+**User result:** "I connect 50 devices without manual work for each device."
+
+| # | Change | Details |
+|---|---|---|
+| M4.1 | Device provisioning | Enable provisioning on a device profile. Show the provision key and the provision secret. Show the device-side request. |
+| M4.2 | Export credentials | `tb device credentials --solution <slug> --format csv`, for factory and installer workflows. |
+| M4.3 | Agent skill | "Prepare my fleet of 50 sensors for connection." The agent selects bulk creation or provisioning. |
+
+**Docs:** the guide "Connect many devices".
+
+### M5 — Gateways and integrations
+
+**User result:** "My devices use Modbus, OPC-UA, LoRaWAN or a vendor cloud. The agent configures the connection."
+
+| # | Change | Details |
+|---|---|---|
+| M5.1 | Integrations and converters | Add CLI commands and a skill for integrations and uplink/downlink converters. Start with HTTP, The Things Stack (TTN) and ChirpStack. This is a large task. Discuss it with the platform team first. |
+| M5.2 | IoT Gateway configuration | The agent creates an IoT Gateway connector configuration (Modbus, OPC-UA, BACnet) from a short description. |
+
+**Docs:** the guides "Connect LoRaWAN devices" and "Connect devices through IoT Gateway".
+
+### M6 — The agent connects the device
+
+**User result:** "I describe my device. The agent connects it."
+
+| # | Change | Details |
+|---|---|---|
+| M6.1 | Firmware and script examples | The agent creates device-side code for common platforms: Arduino/ESP32, Python, Node-RED. It uses the ThingsBoard SDK docs. |
+| M6.2 | Check the full path | The agent runs `tb device connect --wait` and checks the dashboard values. |
+| M6.3 | Research | Find out if the agent can find devices on the local network, or set up a device that the user connected to the computer. |
+
+## Out of scope
+
+- Browser login. It is a separate configuration task.
+- Notifications (email, Slack, Teams). This is a separate roadmap item.
+
+## Open questions
+
+1. What are the MQTT hosts and ports for Cloud NA and Cloud EU? Is TLS required?
+2. Who in the platform team owns the integration APIs for M5?
+3. Do we show device secrets in the terminal by default? Current plan: no.

{thingsboard_cli-4.4.0 → thingsboard_cli-4.4.0.1}/scaffold/agent-kit/INSTRUCTIONS.md

@@ -12,10 +12,39 @@ Before working with entities — especially fetching/pulling them from an instan
 
 - **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.
+- **Push only after the user confirms** — follow *Deploy after confirmation* below. Subagents never push. 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.
 
+## Built-in tenant administrator (quick builds, standalone dashboards)
+
+A quick build (`create-solution` quick mode) and a standalone dashboard have no designed roles. They use the **built-in tenant administrator** — the user running the agent. Every skill and agent recognizes it from the files, not from a flag:
+
+- **Overview marker:** the `### User Groups and Roles` table holds only the placeholder row `| — | — | — | (none — the tenant administrator uses the solution) |`. It is never combined with real rows.
+- **Dashboard marker:** `dashboards.json` entry with `assignedTo: "Tenant Administrator"`. The name `Tenant Administrator` is **reserved** — never name a designed user group or role that.
+- **Role object** for such a dashboard, in every brief (create, update, standalone): `{name: "Tenant Administrator", userGroup: "Tenant", permissions: "CRUD", builtIn: true}`. No "Dashboards for …" group exists or is created for it — tenant administrators see every tenant dashboard.
+- **Growing it into a full solution** (the first customer group, user group or role is added): replace the placeholder row with the real rows — including the one tenant-level administrator row the overview contract requires — and **promote** the existing dashboard to that tenant-level administrator role instead of designing a second admin dashboard: change its `assignedTo` to the role name and update it in place, so it joins that role's "Dashboards for <role>" group. Its states and use cases stay as they are. Other new roles get their own dashboards.
+
+## Deploy after confirmation
+
+When a generation flow is complete — a full solution, an update, or a standalone change — and `tb validate` passes, offer to deploy **once, as the last step of the flow**. Never ask in the middle of a flow.
+
+Ask one `AskUserQuestion` (`header: "Deploy"`): "Deploy to ThingsBoard and stream live demo data for 5 minutes?" Options:
+
+- **Deploy and stream live data** — only when the solution has emulator tasks (`tasks/emulators/`); mark it recommended.
+- **Deploy only**
+- **Not now**
+
+Then:
+
+- **Deploy:** run `tb push <slug> --run-tasks`. Show the user the `Dashboards:` links that the command prints.
+- **Stream:** right after the push, start `tb emulator run <slug> --duration 5m` as a **background** command and do not wait for it. If you cannot run a background command, do not start it — give the user the command instead.
+- **Not now:** print `To deploy later, run: tb push <slug> --run-tasks`.
+- If the request already asks to deploy or to see the result in ThingsBoard ("…and deploy it", "show it on a dashboard"), skip the question: deploy, and start the live stream when emulator tasks exist. Always use the active profile.
+- If `tb push` fails, show the error verbatim and stop.
+
+**Reply after a deployment — short.** One sentence on what is live, the dashboard link(s), and one line on the live stream ("Demo data streams for 5 minutes."). Write every dashboard as a Markdown link with its title — `[Office Air Quality](https://thingsboard.cloud/dashboards/all/<id>)` — never as a bare URL or a title followed by a URL in parentheses. The same applies to any other ThingsBoard page you link (device, profile, alarm list). Add a next action only when the user must act, with its exact command. Do not list what was created, do not repeat design details, and do not mention internal tooling limits. Details belong in the solution README.
+
 ## Feedback
 
 Two separate things — do both.
@@ -30,9 +59,9 @@ This is a passive one-liner (not a question); print it in the same turn the gene
 
 ### 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.**
+A feedback hook (Claude Code `UserPromptSubmit` / Antigravity `PreInvocation`) runs `tb feedback --hook` automatically on **every** message. When a feedback ask is due (the user pushed a result to ThingsBoard at least 15 minutes ago, 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**):
+When you see that reminder, **first handle the user's request completely**. Then, at the end of your reply, 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."
 
@@ -41,7 +70,7 @@ The user clicks an option, or picks the auto-provided **"Other"** field to write
 - **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).
+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.

{thingsboard_cli-4.4.0 → thingsboard_cli-4.4.0.1}/scaffold/agent-kit/agents/dashboard-generator.md

@@ -41,9 +41,10 @@ There is no fallback between modes: in Update mode a missing or unreadable `exis
 | `dashboardName` | string | yes | Human title for the dashboard |
 | `overview` | string | yes | 1–2 sentence description of the dashboard's purpose |
 | `useCases` | string[] | yes | List of use cases the dashboard must cover (in Update mode: context only — see Mode: Update) |
-| `dashboardRole` | object | yes | IAM role: `{name, userGroup, permissions}` |
+| `dashboardRole` | object | yes | IAM role: `{name, userGroup, permissions, builtIn?}`. `builtIn: true` = the built-in tenant administrator (quick mode, standalone dashboards): no dashboard group exists for it — skip the group-membership step after saving; tenant administrators see every tenant dashboard. |
 | `entityRelations` | object[] | yes | `{parent, child, type, cardinality}` hierarchy links |
 | `entityProfiles` | object[] | yes | `{name, entityType, telemetry: [{key, telemetryType: "TIMESERIES\|ATTRIBUTE", dataType, units?, minValue?, maxValue?, enumValues?, classifier?}]}` — projected by the caller from each `### <Profile>` subsection's `Telemetry:`/`Attributes:` sub-lists in architecture-overview.md |
+| `historyDays` | integer | no | Demo data span in days (default `7`) — the length of the dashboard's default time window. The caller reads it from the `Demo data span` line of architecture-overview.md. |
 | `demoRequirements` | string | no | E.g. `"1 Factory, 3 Machines"` — used to pick root state type |
 | `userRequirements` | string | no | Free-form natural-language preferences the user expressed in chat about this dashboard (widget choices, layout, styling, colors, specific visualizations, etc.). HIGH PRIORITY — overrides default generation decisions. Omit when no preferences apply. |
 | `connectDevicesUrl` | string | no | URL for the connectRealDevices widget (defaults to TB docs URL) |
@@ -58,7 +59,7 @@ There is no fallback between modes: in Update mode a missing or unreadable `exis
 
 ## Step 1 — Knowledge (every mode)
 
-`dashboard-foundations` is already in your context (preloaded) — its **core**: the dashboard structure (envelope, grid and HTML page states, global entityAliases), userRequirements handling, UUID conventions, how to fill a widget from a plan, and the Custom HTML path summary. Do NOT re-read SKILL.md from disk. The topic rules live in its `references/` directory and are read **on demand** per the index in the core: aliasing, navigation, validation checklists, widget timewindows, theme/dark mode, permissions gating, and the full Custom HTML path. Read each topic file at most once per run, only when the task touches that topic, and **at the step that needs it** — a file read early stays in context for every later call (in Create mode the index marks which are always needed). Follow this even when the brief asks you to read skills or references "in full" or up front: loading on demand is how those instructions are satisfied, so do not pre-read the topic files.
+`dashboard-foundations` is already in your context (preloaded) — its **core**: the dashboard structure (envelope, grid and HTML page states, global entityAliases), userRequirements handling, UUID conventions, how to fill a widget from a plan, and the layout policy (HTML pages first). Do NOT re-read SKILL.md from disk. The topic rules live in its `references/` directory and are read **on demand** per the index in the core: aliasing, navigation, validation checklists, widget timewindows, theme/dark mode, permissions gating, and the full Custom HTML path. Read each topic file at most once per run, only when the task touches that topic, and **at the step that needs it** — a file read early stays in context for every later call (in Create mode the index marks which are always needed). Follow this even when the brief asks you to read skills or references "in full" or up front: loading on demand is how those instructions are satisfied, so do not pre-read the topic files.
 
 **Capability docs — Create mode: read them in C1, before planning; Update mode: read nothing from them unless the change adds a new state or a widget class the dashboard does not have yet, and then only the sections for that.** Every line you read stays in context for all later calls, so read the states doc **by section** (it is ~60 KB; a dashboard needs about half):
 
@@ -112,7 +113,7 @@ The available names are listed in dashboard-foundations. Pull each needed templa
 ### C1 — Build structure and the validated plan
 
 1. Using dashboard-foundations, decide the states/navigation and build the global `entityAliases` map (allocate UUIDs per the UUID conventions).
-2. Produce a COMPACT render-plan, per state: each widget as `{widgetType, title, aliasRef, dataKeys, layout {x,y,w,h}, actions}`. No widget JSON yet. When a Custom HTML path trigger fires (see the Custom HTML path summary in dashboard-foundations — explicit custom-HTML/composite ask, visual-upgrade ask, or a use case no stock widget expresses), pick the host per "Pick the host" in that section: when the custom content fills the whole state, plan the **state** as an HTML page — `{stateId, host: "page", contentSpec}`, no widgets; only when it is one region of a grid that also holds stock widgets, plan that widget as `{widgetType: "htmlContainer", title, contentSpec, layout}`. Never plan a grid state whose only widget is a full-state htmlContainer — except on a server older than ThingsBoard 4.4.0.1 (`tb system info` → `htmlPageLayout: false`), where it is the required fallback. **Check the server first:** before choosing any host, apply the server version gate from the dashboard-foundations core ("Server version gate" — `tb system info --format json`, once per run); when it selects the fallback, plan every whole-state custom view as the full-state htmlContainer fallback. `contentSpec` per the shape in that section. Stock widgets remain the default for every other use case.
+2. Produce a COMPACT render-plan. **First apply the server version gate** from the dashboard-foundations core ("Layout policy" — `tb system info --format json`, once per run) and plan in the mode it selects. **HTML page mode (ThingsBoard 4.4.0.1+, or version unknown — the default):** plan every state a user navigates to as an HTML page — `{stateId, host: "page", contentSpec}`, no widgets — with `contentSpec` per the shape in `references/custom-html-path.md`. Plan a grid state only as an **embedded helper** that a page hosts via `<tb-dashboard-state>`: stock maps (`outdoor-map`, `indoor-map`, `trip-map`) and the stock alarm table when users acknowledge or clear alarms — `{stateId, host: "helper", widgets: [...]}`, never a navigation target. Stock entity dialogs (create/edit/delete) are page actions, not helper states: list them in the page's `contentSpec` as JavaScript-source actions in `htmlPageConfig.actions`, opened from page buttons. **Grid mode (`htmlPageLayout: false`, server older than 4.4.0.1):** plan per state each widget as `{widgetType, title, aliasRef, dataKeys, layout {x,y,w,h}, actions}`; stock widgets are the default; when a grid-mode trigger fires (explicit custom-HTML/composite ask, visual-upgrade ask, a use case no stock widget expresses, a grid-bound limitation), use an htmlContainer region `{widgetType: "htmlContainer", title, contentSpec, layout}`, and for a whole-state custom view the full-state htmlContainer fallback. No widget JSON yet.
 3. VALIDATE the plan before pulling any template or emitting any JSON (this is where correctness is won):
    - Every widget's `aliasRef` resolves to an alias in the map that OWNS the keys in `dataKeys` (Rule: alias-owns-keys).
    - Every drill-down/navigation action's source kind matches the target state's primary alias kind (Rule: drill-down kind-match).
@@ -152,7 +153,7 @@ Read only the `dashboard-foundations` reference files the change touches (e.g. `
 
 For each entry in `changedUseCases`, add or adjust the specific widget(s), state(s), or alias(es) required to satisfy that one use case, and nothing more. If an entry is already covered by an existing widget, leave it alone. Plan the change with the same validation rules as C1 (alias-owns-keys, drill-down kind-match, customer-as-container), scoped to the pieces you touch; pull catalog templates on-demand only for widget/alias/action types the change introduces.
 
-If the change rebuilds a **whole state** as custom content ("redesign the device list page", "make this view fully custom"), apply the server version gate first (dashboard-foundations core, "Server version gate" — `tb system info --format json`); unless it selects the full-state htmlContainer fallback (then use the fallback and never convert to an HTML page), make that state an HTML page: replace its `layouts.main` with the HTML page state body and drop the widgets it no longer shows from the top-level `widgets` map (only those no other state references). Leave an existing single-full-width-htmlContainer state as it is unless `changedUseCases` touches it; when it does, convert it to an HTML page by moving the container's `config.settings`/`config.actions` into `htmlPageConfig` (content unchanged). A change to one region of a grid state stays an htmlContainer in that grid.
+A **new state** added in Update mode follows the layout policy like a fresh build: an HTML page in HTML page mode. Existing states keep their layout unless the change touches them. If the change rebuilds a **whole state** as custom content ("redesign the device list page", "make this view fully custom"), apply the server version gate first (dashboard-foundations core, "Server version gate" — `tb system info --format json`); unless it selects the full-state htmlContainer fallback (then use the fallback and never convert to an HTML page), make that state an HTML page: replace its `layouts.main` with the HTML page state body and drop the widgets it no longer shows from the top-level `widgets` map (only those no other state references). Leave an existing single-full-width-htmlContainer state as it is unless `changedUseCases` touches it; when it does, convert it to an HTML page by moving the container's `config.settings`/`config.actions` into `htmlPageConfig` (content unchanged). A change to one region of a grid state stays an htmlContainer in that grid.
 
 If the change is "make the dashboard dark" (or similar), it is a settings-level edit, not a widget rebuild: pull `dashboard-dark-mode`, add/update `settings.dashboardCss` (and the toggle widget if a toggle was asked for), and leave every existing widget, state, and alias untouched.
 
@@ -194,6 +195,7 @@ tb validate <solution>
 - **Save from a file, never inline.** `--json` takes a file path (absolute path or a name ending in `.json`), `-` for stdin, or inline JSON — always use the file path for a dashboard. A dashboard with HTML pages is easily over 100 KB, and the OS caps a single command-line argument at ~128 KB: `--json '<json>'` or `--json "$(cat file)"` fails with `Argument list too long` and costs a wasted retry. The file you assembled the JSON in is the one to pass.
 - `<dashboardRole.name>` is the value passed in via the `dashboardRole` input (matches `dashboards.json[i].assignedTo`).
 - `<dashboardUuid>` is the top-level dashboard `id` UUID — freshly allocated in Create mode, the preserved existing `id` in Update mode.
+- When `dashboardRole.builtIn` is `true`, skip the `GROUP_SLUG` / `GROUP_FILE` / `add-entities` lines entirely and go straight to `tb validate`.
 - If no file matches `solutions/<solution>/entity-groups/<slug>-*.json` (the CLI appends a UUID to the filename), stop and surface an error like `error: dashboard group "Dashboards for <role>" not found under solutions/<solution>/entity-groups/ — entities-generator did not run or no roles were defined`. Do not create the file from the dashboard agent.
 - The local-mode `tb entity-group add-entities` is idempotent: re-running this step on a dashboard already in the group is a no-op (the membership IDs are deduped).
 - Wrap each `tb ...` line in its own bash invocation so a failure surfaces immediately, halting before `tb validate`.

{thingsboard_cli-4.4.0 → thingsboard_cli-4.4.0.1}/scaffold/agent-kit/agents/device-emulator-generator.md

@@ -15,8 +15,8 @@ The save step (`tb emulator add`) writes one task file per device under `solutio
 
 Every emulator generated by this worker produces telemetry on the **same fixed schedule**:
 
-- **Window: 7 days** — always pass `--days 7` to `tb emulator add`. Do not shorten and do not extend.
-- **Tick interval: 30 minutes** — the emulator emits one sample per key per 30-minute tick. That is **48 ticks/day**, **336 ticks/week**.
+- **Window: the Demo data span** — read the `Demo data span: <N> days` line under the `## Demo Entities` table of the architecture overview and pass `--days <N>` to `tb emulator add`. When the line is missing, use `--days 7`. A User Requirements "demo data span" bullet wins. The dashboards' default time window uses the same span, so do not choose a different one.
+- **Tick interval: 30 minutes** — the emulator emits one sample per key per 30-minute tick. That is **48 ticks/day** (336 per week).
 - All `anomalyChance` / `minIncrement` / `minDecrement` / `INCREMENT` / `DECREMENT` / `COUNTER` rate values must be sized to this cadence (per-tick = per-30-min). If the briefing materials quote real-world frequencies (e.g. "twice a day"), convert with `anomalyChance = 48 ÷ fires_per_day`.
 - This cadence is shared with the calculated-fields pipeline — see `cf-generator.md` "Telemetry cadence" for the matching CF assumptions (45-min `timeWindow` on `TS_ROLLING`, `HOUR`/`DAY` aggregation intervals, etc.).
 
@@ -186,7 +186,7 @@ tb emulator add \
   --entity-type DEVICE \
   --entity-id <device-uuid> \
   --solution <solution> \
-  --days 7 \
+  --days <N> \
   --json '{"telemetryProfiles": [<assembled-array>]}'
 ```
 

{thingsboard_cli-4.4.0 → thingsboard_cli-4.4.0.1}/scaffold/agent-kit/agents/entities-planner.md

@@ -42,7 +42,7 @@ The brief's path is guaranteed absolute and existing by the dispatching skill
 1. **`Read` `architecture-overview.md`** and parse it into these in-memory structures (the rest of this agent refers to them by these logical names):
    - `deviceProfiles` / `assetProfiles` — one entry per `### <Profile> (DEVICE|ASSET)` subsection (name = heading minus suffix). Each carries its `Telemetry:` keys as `timeSeriesKeys` and `Attributes:` keys as `attributeKeys` (derived keys annotated `(derived: …)` are still keys of that profile).
    - `customerGroups` — one per `### Customer Groups` data row (skip the tenant-only placeholder row `— | — | (none — tenant-only)`). Each has `name`, `scope` (the `Parent` cell: `Tenant` or a parent customer group name).
-   - `userGroups` — one per `### User Groups and Roles` data row. Each has `name`, `scope` (the `Scope` cell: `Tenant` or a customer group name), `permissions` (the `Permissions` cell: `CRUD`/`RU`/`R`).
+   - `userGroups` — one per `### User Groups and Roles` data row (skip the quick-mode placeholder row `— | — | — | (none — …)`; then `userGroups` and `roles` are empty). Each has `name`, `scope` (the `Scope` cell: `Tenant` or a customer group name), `permissions` (the `Permissions` cell: `CRUD`/`RU`/`R`).
    - `roles` — the same `### User Groups and Roles` rows viewed as roles: `{name: <Name>, userGroup: <Name>, permissions: <Permissions>}`. There is one role per user group; the tenant admin (`Scope=Tenant`, `Permissions=CRUD`) is first. When the User Groups and Roles table is empty, `roles` is empty.
    - `entityRelations` — parse the `## Relations` prose into `{parent, child, type, cardinality}` rows (direction and cardinality are stated explicitly in the prose; default cardinality `1:M` when unstated).
    - **Profile `scope`** (device/asset profiles have no explicit scope field): derive it — if any `## Demo Entities` row whose `Profile` matches this profile names a customer group in its `Customer Group` column, `scope` = that customer group name; otherwise `scope = "Tenant"`. A profile maps to one scope; conflicting rows are a malformed overview → stop with an error.

thingsboard_cli-4.4.0.1/scaffold/agent-kit/skills/alias-state-entity/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: alias-state-entity
+description: "stateEntity entity alias — a renderable TB JSON template pulled on-demand by dashboard-generator that resolves a single entity from the current dashboard state parameter."
+user-invocable: false
+---
+
+### stateEntity
+```json
+{
+  "id": "<aliasUuid>",
+  "alias": "<Human Name>",
+  "filter": {
+    "type": "stateEntity",
+    "resolveMultiple": false,
+    "stateEntityParamName": "<\"\" or a named param, e.g. selectedBuilding — see below>",
+    "defaultStateEntity": null
+  }
+}
+```
+
+**`stateEntityParamName` must match how the entity is published — the two never mix:**
+
+| Publisher | Publishes | `stateEntityParamName` |
+|---|---|---|
+| HTML page / htmlContainer selecting an entity for an embedded state: `ctx.stateController.updateState(null, {entityId, entityName})` | the **default** state entity | `""` (empty) |
+| Drill-down action or `openState` that sets a **named** param: `{selectedBuilding: {entityId, entityName}}` | a named param | that name, e.g. `selectedBuilding` |
+
+ThingsBoard reads `params[<name>].entityId` when a name is set and `params.entityId` when it is empty. **Never use `entityId` or `entityName` as the name** — `params.entityId.entityId` does not exist, so the alias resolves to nothing and every widget on it shows "No data to display" although the data exists.

{thingsboard_cli-4.4.0 → thingsboard_cli-4.4.0.1}/scaffold/agent-kit/skills/commit-step/SKILL.md

@@ -18,7 +18,7 @@ Invoke from any solution-generation orchestrator after each logical step has fin
 - After dashboards are saved (Step 5 in `create-solution`)
 - After any revision that touches saved files
 
-Run **after** `tb validate <slug>` (when the orchestrator validates) — a broken solution should not be committed. Run **before** the push notice — the commit is part of "the step is done".
+Run **after** `tb validate <slug>` (when the orchestrator validates) — a broken solution should not be committed. Run **before** the progress notice — the commit is part of "the step is done".
 
 ## Inputs