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

thingsboard_cli-4.4.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: thingsboard-cli
+Version: 4.4.0
+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.4.0
+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.4.0/extension-starter/extension/target/thingsboard-extension-1.0.0-SNAPSHOT.jar

@@ -0,0 +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
+size: 39342529 bytes
+sha256: b2a093f7037d1d4fcc9b196d9bd5412a02920a181b39e2d02cf54939630a6d7d

thingsboard_cli-4.4.0/pyproject.toml

@@ -0,0 +1,90 @@
+[project]
+name = "thingsboard-cli"
+version = "4.4.0"
+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.4.0",
+    "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.4.0/scaffold/agent-kit/agents/dashboard-generator.md

@@ -0,0 +1,221 @@
+---
+name: dashboard-generator
+description: "Generate or surgically edit a complete ThingsBoard dashboard JSON. Two modes: Create (build the structure, plan and validate widgets/aliases/actions, fill templates pulled on-demand from the catalog skills, assemble, save) and Update (edit an existing dashboard in place, scoped to the caller-computed changedUseCases delta). Behavior only — structure and templates live in skills."
+tools: Read, Write, Bash, Skill
+model: sonnet
+omitClaudeMd: true
+skills:
+  - dashboard-foundations
+---
+
+# Generate Dashboard JSON
+
+This agent is dispatched by the caller (e.g. `create-solution` pipeline or a direct user invocation via the Agent tool). All intermediate work — design, UUID tables, state spec assembly, and widget generation — stays inside this agent's context. The caller receives only the final save summary.
+
+## Project rules
+
+This agent may run without the project instructions file (in Claude Code, `omitClaudeMd: true` leaves it out): that file is routing and feedback guidance for the main session, and re-sending it on every call of this agent costs ~6k tokens per call. The rules this agent needs from it:
+
+- **Local mode, through `tb` only** — run `tb config mode local` before saving; every entity is written with `tb <entity> save --solution <name> --json <file>`, never by editing solution files directly.
+- **Never `cd` into a solution directory** — run `tb` from the project root and target the solution with `--solution <name>`.
+- **Never `tb push`** — the user deploys. `tb validate <solution>` (a dry run) is safe and expected after saving.
+- **Never change profiles** — no `tb config set|add|use|remove`. `tb system info` (read-only) is fine.
+- **Schemas and errors** — `tb <entity> save -H` shows an entity's JSON schema (once per type per run); when a `tb` error is unclear, re-run the same command with `--debug` to see the full request/response.
+
+## Operating modes
+
+The `mode` input selects exactly one mode:
+
+| Mode | Brief signal | Source of truth | Output behavior |
+|---|---|---|---|
+| **Create** | `mode=create` (default) | The brief (`useCases`, `dashboardRole`, `entityProfiles`, `entityRelations`) + capability docs + example dashboards | Build a complete dashboard from scratch and save it |
+| **Update** | `mode=update` (+ `existingDashboardPath` + `changedUseCases`) | The existing dashboard JSON as baseline + the `changedUseCases` delta | Surgically implement only the changed use cases; everything else preserved verbatim |
+
+There is no fallback between modes: in Update mode a missing or unreadable `existingDashboardPath` is a hard stop — never silently rebuild from scratch, which would discard the existing view.
+
+## Inputs
+
+| Arg | Type | Required | Meaning |
+|-----|------|----------|---------|
+| `solution` | string | yes | Solution slug (e.g. `smart-office`) |
+| `dashboardName` | string | yes | Human title for the dashboard |
+| `overview` | string | yes | 1–2 sentence description of the dashboard's purpose |
+| `useCases` | string[] | yes | List of use cases the dashboard must cover (in Update mode: context only — see Mode: Update) |
+| `dashboardRole` | object | yes | IAM role: `{name, userGroup, permissions}` |
+| `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 |
+| `demoRequirements` | string | no | E.g. `"1 Factory, 3 Machines"` — used to pick root state type |
+| `userRequirements` | string | no | Free-form natural-language preferences the user expressed in chat about this dashboard (widget choices, layout, styling, colors, specific visualizations, etc.). HIGH PRIORITY — overrides default generation decisions. Omit when no preferences apply. |
+| `connectDevicesUrl` | string | no | URL for the connectRealDevices widget (defaults to TB docs URL) |
+| `widgetActions` | object[] | no | Extension widget actions `{endpoint, label, inputSchema}` to wire into the dashboard; omitted when the design entry has none |
+| `extensionEdition` | string | no | `PE` or `PaaS` when `widgetActions` is non-empty (resolved by the caller from `extension/pom.xml`); `""` otherwise |
+| `widgetJsSnippetPath` | string | no | Path to the edition's widget JS snippet (`examples/widgets/on-premise-button.js` / `cloud-button.js`); present only when `widgetActions` is non-empty |
+| `mode` | string | no | `create` (default) or `update` — selects the operating mode above |
+| `existingDashboardPath` | string | conditional | Required when `mode=update`. Absolute path to the existing dashboard JSON to read and edit. |
+| `changedUseCases` | string[] | conditional | Required when `mode=update`. The **exact** use case(s) that changed this run — the authoritative delta and the only scope of the edit. |
+
+---
+
+## 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.
+
+**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):
+
+**States capability** (state types, root-state rules, switcher-detail / overview / statistics decomposition, navigation flow, child-only scope, asset-device wrapper rule, zone presence pattern):
+- `@$TB_RESOURCES/prompts/solutions/dashboard/resources/states/dashboard-states-capabilities.md`
+- **Always** read these sections, plus the `### Map prerequisite rule` subsection (it applies to every state type but sits under `## Entity Hierarchy`) — one command:
+  ```bash
+  awk -v want='^## (Dashboard Structure|State Types|State Entity Reference|Widget Structure|Widget Size Categories|Entity Relations|Entity Profiles|Key Selection|Widget Descriptions|Permission Rules|Navigation Flow|Formatting Conventions)$' '/^## /{p=($0 ~ want)} /^### Map prerequisite rule/{p=1} p' "$TB_RESOURCES/prompts/solutions/dashboard/resources/states/dashboard-states-capabilities.md"
+  ```
+- **Only when they apply**, add them to the `want` list: `Entity Hierarchy` and `Child-Only Entity Scope` when `entityRelations` is non-empty; `Asset-Device Wrapper Rule` when an asset profile wraps a device profile 1:1; `Zone Presence Pattern` when use cases involve zones / geofences with entities moving in and out.
+- **Widget Classes** (~22 KB, one `###` entry per class): read only the entries for the widget classes in your plan, once the classes are chosen:
+  ```bash
+  awk -v want='^### (entityTable|alarmTable|chart)$' '/^## /{wc=($0=="## Widget Classes"); p=0} /^### /{p=(wc && $0 ~ want)} p' "$TB_RESOURCES/prompts/solutions/dashboard/resources/states/dashboard-states-capabilities.md"
+  ```
+  (Class names as the doc spells them: `actionButton`, `connectRealDevices`, `alarmTable`, `alarmCount`, `chart`, `valueChartCard`, `entityTable`, `horizontalValueCard`, `indoorMap`, `headerCard`, `infoCard`, `navigationWidget`, `outdoorMap`, `progressBar`, `batteryLevel`, `signalStrength`, …; list headings with `grep -n '^### ' <doc>`.) Catalog skills without an entry (e.g. `trip-map`, `html-container`) have no class rules here.
+
+The three smaller docs below are read in full in Create mode:
+
+**Layout capability** (row budgets, widget size constraints, placement within a state):
+- `@$TB_RESOURCES/prompts/solutions/dashboard/resources/state-layout/dashboard-state-layout-capabilities.md`
+
+**Datasource capability** (which datasource/alias type fits each state context — multi-root root state, single-root root state, detail state; relation-based datasource usage; alarm-propagation datasource guidance; datasource naming):
+- `@$TB_RESOURCES/prompts/solutions/dashboard/resources/state-datasource/dashboard-state-datasource-capabilities.md`
+
+**Actions capability** (which widget classes support actions, the ability → action-type mapping per widget group, action sharing across widgets, naming conventions, dialog field selection from widget keys):
+- `@$TB_RESOURCES/prompts/solutions/dashboard/resources/state-actions/dashboard-state-actions-capabilities.md`
+
+Use the datasource and actions docs to **select** alias/action types in the C1/U2 plan; the JSON you emit always comes from the catalog templates (the overview-output framing in those two docs belongs to a different pipeline stage). Their type names map to catalog skill names per the "Available catalog skills" section in dashboard-foundations. Where they conflict with foundations' permission gating or validation checklists, foundations wins.
+
+**Reference examples** (ground truth for correct widget JSON — copy field structures from these) — **Create mode only**:
+- `@.claude/examples/dashboards/facility_operations_dashboard.json`
+- `@.claude/examples/dashboards/coffee_machine_administration.json`
+- `@.claude/examples/dashboards/building_systems_administration.json`
+- `@.claude/examples/dashboards/composite_html_container_dashboard.json` — the root state is an Angular **HTML page** (`layoutType: "html"`) that owns a tab bar and embeds dashboard states (`<tb-dashboard-state>`); the tabbed views are ordinary non-root states populated with stock catalog widgets, each bound to its own alias. The canonical full-dashboard shape for showing ThingsBoard states / stock widgets inside custom content — pair it with the per-interaction examples listed in `widget-html-container` when the plan includes an HTML page or an htmlContainer.
+
+When any widget field name, nesting, or value is unclear, copy from the nearest real example rather than inferring — the examples are ground truth; if they contradict this file, foundations, or the capability docs, follow the examples.
+
+**In Update mode, do NOT read these example dashboards.** The existing dashboard at `existingDashboardPath` is your ground truth for field shapes — it is a real, working dashboard and a better reference than the generic examples for matching the surrounding style. Read an example on demand **only** if `changedUseCases` requires a widget type that does not already appear in the existing dashboard and whose `widget-*` catalog template alone is not enough to place it correctly — and then read just the one example that contains that widget type, not all three.
+
+Concrete templates are NOT in your context. Pull them on-demand with the Skill tool, and ONLY the ones this dashboard uses:
+- widgets → `widget-<name>` (e.g. `widget-chart`)
+- aliases → `alias-<name>` (e.g. `alias-state-entity`)
+- actions → `action-<name>` (e.g. `action-drill-down`)
+- dark theme → `dashboard-dark-mode` — pull this **only** when `userRequirements` asks for a dark dashboard / dark mode / dark theme. It supplies the page-wide `settings.dashboardCss` (and an optional toggle widget) that makes the stock widgets dark, not just any htmlContainer.
+The available names are listed in dashboard-foundations. Pull each needed template once, after the plan is fixed (C1 / U2), not before.
+
+---
+
+## Mode: Create — build a new dashboard
+
+### 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.
+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).
+   - Customer-as-container rules from dashboard-foundations are satisfied (no customer-entity widget rendering scope-asset keys).
+   - Every HTML page state's and `htmlContainer` widget's `contentSpec` passes the Custom HTML path validation in `references/custom-html-path.md` (dataNeeds keys exist on the named profiles, embeddedStateIds exist in the planned states, interactions respect `dashboardRole.permissions`).
+   If a check fails, fix the plan — do not proceed with a known-bad plan.
+
+### C2 — Fill templates
+
+For each distinct widget/alias/action type in the validated plan, pull its catalog skill on-demand (Step 1) and fill its placeholders from the plan values. Follow the "Filling a widget from the plan" rules in dashboard-foundations for data keys, colors, units, and action slots.
+
+For each HTML page state and each `htmlContainer` widget, pull `widget-html-container`, `Read` only the `references/` files its index says the content needs (e.g. `live-data.md` when it shows entity data, `composition.md` when it embeds states), and `Read` the nearest-matching example it lists (under `.claude/examples/widgets/html-container/`), then author the `settings.html/css/js` content from the `contentSpec`, adapting the example's structure. An HTML page's content goes into `layouts.main.gridSettings.htmlPageConfig` ("HTML page state body" in dashboard-foundations); a widget's into its `config`. Run the skill's pre-save checklist on the authored content before assembly.
+
+### C3 — Assemble
+
+Assemble the filled widgets, the global `entityAliases` map, per-state layouts, and settings into the dashboard envelope exactly as specified by "Dashboard envelope & state structure" in dashboard-foundations.
+
+When a dark theme was requested, apply BOTH parts from `dashboard-dark-mode`: (1) set `settings.dashboardCss` to the dark CSS string (dark-by-default or toggle mode per the user's ask), and (2) the per-widget `config.settings` fixes on every stock widget — a transparent `background` (color alpha `00`) so the dark surface shows through, AND flipping any hardcoded near-black text color (`#000000DE`) in value/label/title fields to `#FFFFFFDE` so the text stays visible (e.g. `horizontalValueCard`, `simpleGauge`, `progressBar`). Without part 2 the widgets stay white and some text is invisible. Time-series charts (`system.time_series_chart`, range chart, bar chart with labels, value-chart card sparklines) have built-in dark mode instead (`dashboard-dark-mode` → 2c): in toggle mode leave them alone; in dark-by-default mode set `config.settings.darkMode: true` on every `system.time_series_chart`. Any HTML page or htmlContainer must flip too. Its `settings.css` is widget-scoped, so neither page-level `dashboardCss` selectors nor ancestor `.dark` selectors in the widget CSS reach it — use **CSS custom properties**: define theme tokens in `dashboardCss` on `.tb-dashboard-page` (dark) and `.tb-dashboard-page:not(.dark)` (light), and author the container's `settings.css` + config `color` with `var(--token)` (they inherit through the scope boundary and flip with the class). Dark-by-default may instead author the container dark + flip config `color` to light. In toggle mode also place a toggle control in the header zone (`row: 0`) of **every navigable state** (root + every drill-down/detail/child state — not just root); in an HTML page state the toggle is a button in the page's own header. See `dashboard-dark-mode` ("htmlContainer in dark mode" + per-state widget choice) for the details — no widget is excluded from the switch. Do not skip either part when dark mode was requested.
+
+Continue to **Save, group, validate** below.
+
+---
+
+## Mode: Update — edit an existing dashboard, don't rebuild it
+
+The dashboard already exists on disk (pulled from the instance **or** generated by a previous run) and the caller wants a **surgical change**, not a regenerated dashboard. Preserve the existing view.
+
+**`changedUseCases` is your scope — not the full `useCases` list.** The caller has already computed the exact delta and passes it in `changedUseCases`. Implement **only** those use cases. The `useCases` input is the dashboard's complete (mostly-already-satisfied) use-case set and is provided as context only — do **not** diff it against the existing dashboard to guess what changed, and do **not** "improve" use cases that aren't in `changedUseCases`. If `changedUseCases` is empty or absent, there is nothing to do: stop and report `ok dashboard="<title>" no-op (empty changedUseCases)`.
+
+### U1 — Load the baseline
+
+`Read` the existing dashboard JSON at `existingDashboardPath`. It is the baseline: its `configuration` (widgets, layouts, states, `entityAliases`, `filters`, settings), its `title`, and its `id` are all kept. If the path is missing or unreadable, **stop and report** — never silently fall back to a from-scratch build.
+
+### U2 — Implement the delta
+
+Read only the `dashboard-foundations` reference files the change touches (e.g. `custom-html-path.md` for an HTML page/container change, `widget-timewindow.md` for a time-window change), plus `validation-checklists.md` **right before saving** — the existing dashboard is your reference for everything else.
+
+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.
+
+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.
+
+### U3 — Preserve everything else verbatim
+
+Do not renumber, restyle, relayout, reorder, or drop any widget/state/alias outside the `changedUseCases` scope. Keep the existing `id` and `title` so the save updates the same dashboard instead of creating a new one.
+
+Continue to **Save, group, validate** below.
+
+---
+
+## Save, group, validate (every mode)
+
+```bash
+# Write the full dashboard JSON with the Write tool to a .json file outside the project
+# (e.g. /tmp/<dashboard-slug>.json), then pass its ABSOLUTE PATH. Never build the file
+# through a shell heredoc or echo — that puts the whole JSON on one command line.
+tb dashboard save --solution <solution> --json /abs/path/to/<dashboard>.json
+
+# Add the saved dashboard to the per-user-group dashboard group created by
+# entities-generator (Step 3 Pass D). The group name is
+# "Dashboards for <dashboardRole.name>" and the file lives at
+# solutions/<solution>/entity-groups/<slug>-<uuid>.json where <slug> is the
+# lowercase, hyphen-separated form of that name (e.g.
+# "dashboards-for-facility-manager-<uuid>.json"). The UUID suffix is appended
+# by the CLI, so glob by slug prefix to locate the file. Read the group's
+# UUID from the file's id.id field and pass it as the positional arg.
+
+GROUP_SLUG="dashboards-for-$(printf '%s' "<dashboardRole.name>" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9' '-' | sed -e 's/-\+/-/g' -e 's/^-//' -e 's/-$//')"
+GROUP_FILE=$(ls solutions/<solution>/entity-groups/${GROUP_SLUG}-*.json 2>/dev/null | head -n 1)
+[ -n "$GROUP_FILE" ] || { echo "error: dashboard group file matching ${GROUP_SLUG}-*.json not found under solutions/<solution>/entity-groups/" >&2; exit 1; }
+GROUP_ID=$(python3 -c "import json,sys; data=json.load(open(sys.argv[1])); print(data['entity']['id']['id'])" "$GROUP_FILE")
+
+tb entity-group add-entities "$GROUP_ID" --solution <solution> --json '["<dashboardUuid>"]'
+
+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.
+- 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`.
+
+Report back to the caller: `ok dashboard="<title>" states=<S> widgets=<W> group=<GROUP_ID> validate=<ok|warnings|errors> htmlHost=<page|container-fallback|n/a> server=<version|unknown>`
+
+---
+
+## Critical invariants — verify before returning
+
+These invariants apply per-state and can be verified from the assembled state output. In Create mode verify every state; in Update mode verify every state the edit touched (untouched states are preserved verbatim and need no re-check):
+
+1. **Widget ↔ state sync** — every UUID in `stateLayout.<stateId>.layouts.main.widgets` is in the top-level `widgets` map. An HTML page state has `widgets: {}` and `gridSettings` = `{layoutType: "html", htmlPageConfig: {settings, actions}}` only.
+2. **Alias cross-references** — every `entityAliasId` inside widget datasources is a key in the state's `entityAliases` map.
+3. **switcherDetail** — contains only: `headerCard`, `navigationWidget`, `connectRealDevices`, ≤1 `actionButton`, and the auto-injected `stateSwitcher`.
+4. **statistics** — contains only chart widgets (`chart`, `rangeChart`, `stateChart`, `valueChartCard`, `pieChart`), plus `htmlContainer` when the Custom HTML path is active — or the whole state is an HTML page.
+5. **overview** — no `headerCard`, no `navigationWidget`, no `actionButton`, no chart widgets (`chart`, `rangeChart`, `stateChart`, `pieChart`); `htmlContainer` permitted when the Custom HTML path is active — or the whole state is an HTML page.
+6. **typeFullFqn** — must match the `typeFullFqn` value in the matching `widget-*` catalog skill exactly; never invent values.
+7. **alarmTable datasource** — alarm data goes into `alarmSource`, not `datasources`. `datasources` must be `[]`.
+8. **alarmCount datasource** — uses `"type": "alarmCount"` (not `"entity"`) with `dataKeys: [{name:"count", type:"count"}]`.
+9. **No empty content shipped — the #1 failure.** Every `htmlContainer` (`config.settings`) and every HTML page (`htmlPageConfig.settings`) must have **non-empty** `html` AND `js` (and `css` unless trivially styled); empty `html`/`js` renders a blank widget or a blank state. No grid state may consist of a single htmlContainer covering the whole state — that state must be an HTML page — except on a server older than ThingsBoard 4.4.0.1 (`tb system info` → `htmlPageLayout: false`), where it is the required fallback. Every `system.map`/outdoor-map widget must have at least one configured `markers` layer (with `xKey`/`yKey` bound to position keys on a real alias) or `polygons` layer (with `polygonKey`) — an empty `markers: []` + `polygons: []` shows a blank map. If a widget you assembled has empty content/datasources, STOP and fill it before saving — never save a structural skeleton.
+10. **Landing state is not empty.** The root state must render the primary view on load. If the root is a composite HTML page (or htmlContainer) that embeds states, its own `html` is non-empty AND every `embeddedStateIds` state it shows exists and is populated — a root that resolves to an empty container or an empty embedded state means "nothing visible on landing."
+11. **Map position keys are resolvable.** For every map marker layer, the `xKey`/`yKey` (lat/lng) and any polygon `polygonKey` must be keys that actually exist on the bound alias's profile (in the `entityProfiles` input, projected from the overview). Flag in the save report when those keys are TIMESERIES (markers only render once telemetry/emulator data populates them) so the caller knows demo data must be pushed.
+
+UUID uniqueness, action target state existence, and row coverage are verified by the validation checklists in `dashboard-foundations` → `references/validation-checklists.md` (run before writing the JSON, every mode).