thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/scaffold/.claude/skills/create-solution/SKILL.md

@@ -0,0 +1,793 @@
+---
+name: create-solution
+description: "Create a full ThingsBoard IoT solution via CLI. Use when the user asks to create, build, or generate an IoT solution, smart system, monitoring system, or similar (e.g., 'create a smart house solution', 'build a fleet tracking system', 'create an IoT solution for warehouse monitoring'). Do NOT use for creating individual entities like a single device or profile."
+user-invocable: true
+---
+
+# Create ThingsBoard IoT Solution
+
+Orchestrator for designing and generating a full IoT solution. All design and all `tb` calls go through sub-skills. The five top-level steps, the approval gates, and shared patterns are defined once in **Pipeline Config** below; each Step section references that block instead of redefining anything.
+
+## Pipeline Config
+
+Single source of truth for the orchestrator's policy. Every step references this block instead of redefining patterns inline.
+
+### Generation steps
+
+The catalog of top-level step subjects that may appear as `TaskCreate` items in Step 1. The actual set chosen for a run is decided by the rules in **Step 1 → Show the plan** — not every run uses every entry.
+
+- **Kickoff** (exactly one per run):
+  - `Consult user`
+  - `Consult user (skipped — autonomous mode)`
+  - `Discovered, pulled, and reverse-engineered <N> entities from instance`
+  - `Refreshed and reverse-engineered <slug>`
+- `Design solution architecture` — profiles, relations, customers, users, roles, CFs, alarms.
+- **Generation task** — pick the smallest accurate subject covering what Step 3 will produce. Examples: `Create entities, calculated fields, alarms, and demo telemetry`, `Create calculated field(s)`, `Add alarm rule(s)`, `Add telemetry key(s) on existing profile(s)`, `Add device(s)`. Combinations: name the dominant artifact types, e.g. `Create calculated field(s) and alarm rule(s)`.
+- `Build extension` (only when `extension-enabled = true`).
+- `Design dashboards` (one per IAM role).
+- `Create dashboards` (all in parallel).
+
+Each task represents one discrete step the user is told about; sub-skills emit plain-text narration for their substeps. Mark each task `in_progress` when entering its step and `completed` when leaving — this rule applies everywhere and is not repeated per step.
+
+### Approval gates
+
+The orchestrator pauses for user input at **exactly three points**:
+
+- **After Step 2** — the designed solution architecture (entity hierarchy + tables + CFs + alarms). Blocks until approved.
+- **After Step 3** — entities/CFs/alarms have been generated. Defaults toward continuing; the user can choose to pause and inspect files.
+- **After Step 4** — the designed dashboard use cases per role. Blocks until approved.
+
+No other step pauses. For Steps 2 and 4, the sub-skill always designs silently and writes its JSON file(s) — it has no approval logic of its own. The orchestrator reads the file(s), renders a structured presentation (diagram or grouped sections — never the raw JSON), and owns the gate. On revision, re-invoke the same sub-skill with `revise=true`, re-read the updated file(s), re-emit the `[paused]` marker, ask again, loop until approved.
+
+In `mode=autonomous`, skip the pause at all three gates: print a one-line `[auto]` summary (Steps 2 and 4) or simply continue (Step 3).
+
+## Extension-enabled flag
+
+Carry a second run-wide boolean `extension-enabled ∈ {true, false}` (default `false`). Like `mode`, it can flip at any step and is passed into downstream sub-skills.
+
+**Explicit triggers** (no auto-detection — only these flip the flag to `true`):
+
+- Literal words anywhere in user input: `extension`, `custom backend`, `Java`, `Spring`, `scheduled job`, `/api/extension`.
+- Phrases: `add an extension`, `build me an extension`, `extend ThingsBoard`.
+- The user invokes `/create-extension`.
+
+If none of these appear, leave the flag `false` and never bring up extensions beyond the one inform-line in Step 1b. Heuristic signal-scanning is forbidden.
+
+When the flag flips mid-run, acknowledge in one line, then route per the **Extension trigger-point table** below — the orchestrator already past a step may need to re-dispatch a design stage (`extension-design` → IAM cascade) and/or insert Step 3.5 / re-run Step 4 / Step 5 for affected dashboards.
+
+### Extension trigger-point table
+
+| Trigger point | Behavior |
+|---|---|
+| **Before Step 2 begins** | `design-solution-architecture` runs with `extension-enabled=true`; new `extension-design` stage runs between relations and IAM. |
+| **After Step 2 approved** | Re-dispatch `design-solution-architecture` with `revise=true, --stage extension-design`; cascade IAM (custom roles fold in); re-present, re-approve, then proceed. |
+| **After Step 3 (entities generated)** | Run only the `extension-design` stage; cascade IAM with a delta-revise so new custom roles exist before Step 3.5 references them; then run Step 3.5 (Build extension). |
+| **After Step 4 (dashboards designed)** | Run Step 3.5 (Build extension); then re-invoke `design-dashboards` with `extension-only=true` so widget actions overlay onto the already-approved use cases (everything else preserved). |
+| **After Step 5 (dashboards generated)** | Run Step 3.5 (extension-design + build extension), then re-invoke `design-dashboards` with `extension-only=true` to overlay `widgetActions` onto the existing `<workdir>/design/dashboards.json`, then re-invoke `create-dashboard` for the affected dashboards (those whose `widgetActions` reference the new endpoints). No paste-snippets-manually footgun — the re-generation owns the wiring. |
+
+### Mode variable
+Carry a single `mode ∈ {interactive, autonomous}` through the whole run. Decided in Step 1a (asked before anything else) and reused at all three gates above.
+
+**Autonomous triggers in the original request** skip Step 1a's mode question and set `mode=autonomous`: `auto`, `autonomous`, `no interview`, `just build it`, `just do it`, `yolo`, `no approval`, `skip questions`.
+
+**Mid-run switch.** If the user later says `just continue`, `stop asking`, `skip approvals`, or `yolo`, flip `mode` to `autonomous` for the rest of the run — acknowledge in one line, resume from the current step.
+
+### Scale variable
+
+Carry a run-wide `scale ∈ {single-target, prototype, production-scale}` (default `prototype`) through the whole run. It controls how many entities of each profile the demo includes:
+
+- `single-target` — exactly one of each profile. For requests targeting a single physical thing (e.g. "monitor my one solar inverter").
+- `prototype` — 1–5 entities per profile, pattern-driven; pick the smallest count that lets dashboards, metrics, and relations actually demonstrate the pattern (a fleet-tracking demo may want the upper end for a usable map; a simple sensor solution may want one or two). **This is the default when the user doesn't specify and doesn't choose otherwise.**
+- `production-scale` — counts the user explicitly states. The orchestrator carries the stated per-profile counts forward verbatim.
+
+The variable is set once — in Step 1a from the original-request pre-scan (when counts are explicit), or in 1b via the Scale interview question (when they aren't). On skip or in `mode=autonomous` without a pre-scan match, `scale` falls through to `prototype`.
+
+**Propagation via User Requirements.** Scale is a cross-cutting user requirement. The architecture skill records the resolved value as a bullet under `## User Requirements` in `architecture-overview.md` — phrased like other entries in that section (e.g. **Scale — small working prototype, 1–5 entities per profile (user stated via interview). Affects:** Demo Entities counts, emulator instance fan-out, dashboard density). All downstream subagents (`entity-profiles-designer`, `relations-designer`, `metrics-designer`, `alarms-designer`, `device-emulator-generator`, `attribute-values-generator`, `dashboard-json-generator`) already read `User Requirements` and treat it as overriding their built-in defaults — no new plumbing is needed.
+
+### Source variable
+
+Carry a run-wide `source ∈ {fresh, instance-import}` (default `fresh`) through the whole run. It decides where Step 1 gets its inputs from.
+
+- `fresh` — the existing flow: domain interview drives the design, every entity is invented from scratch.
+- `instance-import` — entities already exist on the user's ThingsBoard instance. Steps 1d and 1f (discover + pull via the `pull-solution` skill, then reverse-engineer and fold the user's ask in via `additions`) run instead of the interview.
+
+Decided in Step 1a.5 (asked after the approval-mode question). Like `mode` and `extension-enabled`, it can flip mid-run if the user changes their mind ("actually, also pull my building asset into this"). Mid-run switches re-enter Step 1d → 1f layered onto the current state.
+
+**Autonomous-mode pre-scan triggers in the original request.** Set `source = instance-import` automatically when any of these appear:
+- Literal phrases: `my existing`, `on the instance`, `already deployed`, `currently on`, `from my server`, `pull from instance`.
+- A reference to a named entity that looks like an instance reference: `my Pump-42`, `our fleet of trucks`, `the building at HQ`.
+
+If none appear, leave `source = fresh` and let Step 1a.5 ask. This pre-scan happens in Step 1a alongside the existing extension-enabled and scale pre-scans.
+
+### Decision-making rule
+
+Whenever a design choice is ambiguous and the user hasn't given an explicit signal (or skipped the interview / switched to autonomous), **pick the sensible default silently and move on**. Do not list assumptions, do not flag judgment calls, do not pause to ask. The user sees every result at its gate and can correct any wrong default in one reply. Applies to every sub-skill — `design-solution-architecture`, `design-dashboards`.
+
+### Question UI
+
+Any question with a fixed set of options — the mode question, the three approval gates, and option-based interview questions — MUST be asked via the `AskUserQuestion` tool so the user gets clickable buttons. Do **not** print `(1) … (2) …` or `(a) … (b) … (c) …` choices as plain text. Open-ended questions with no preset options (e.g. "what's being monitored?") stay as plain text since `AskUserQuestion` requires at least 2 options. The "Other" option that `AskUserQuestion` adds automatically lets users type custom feedback.
+
+### Finalization pattern (README + commit)
+
+After every step that writes files to `solutions/<slug>/` — Step 3, Step 3.5, Step 5, and any revision — invoke `Skill` `commit-step` with `solution=<slug>` and a short `step` descriptor used verbatim as the commit subject. This refreshes the README from disk and creates a checkpoint commit. Always run **after** `tb validate <slug>` passes (a broken solution must not be committed) and **before** the push notice (the commit is part of "the step is done"). If the sub-skill reports `no changes to commit`, that's fine — proceed. If it errors, surface verbatim and stop.
+
+### Push notice pattern
+
+Applies to Steps 3 and 5. After generation completes, `tb validate <slug>` passes, and `commit-step` has captured the checkpoint, print one line telling the user how to deploy, then continue immediately to the next step. Do NOT pause, do NOT wait for confirmation, do NOT run `tb push` yourself.
+
+````
+Generated <what>. To deploy, run `tb push <slug>`. Add `--run-tasks` to also generate demo telemetry and backfill calculated fields.
+````
+
+If `tb validate <slug>` reported errors, do **not** print the notice — surface the errors and stop.
+
+## Step 1 — Consultation
+
+### 1.0 Resume-detection preflight
+
+Run this **before** the 1a approval-mode question. Infer `<workdir>` from:
+
+1. If the user's cwd is inside a `solutions/<slug>/`, that slug is `<workdir>`.
+2. Else if the user named an existing solution explicitly in the request, that slug is `<workdir>`.
+3. Else there's no resume to detect — drop through to 1a normally.
+
+When a `<workdir>` is inferred, inspect it with one short bash block:
+
+```bash
+workdir="<absolute-path-to-solutions/slug>"
+
+if [ ! -d "$workdir" ]; then
+  state="missing"
+else
+  # Has entities = at least one *.json under any entity subdir
+  has_entities="false"
+  for d in devices assets device-profiles asset-profiles customers users roles entity-groups dashboards rule-chains; do
+    if [ -d "$workdir/$d" ] && compgen -G "$workdir/$d/*.json" > /dev/null; then
+      has_entities="true"
+      break
+    fi
+  done
+  # Design files present = all six exist under design/
+  missing=""
+  for f in architecture-overview.md entity-profiles.json relations.json iam.json metrics.json alarms.json; do
+    [ -f "$workdir/design/$f" ] || missing="$missing $f"
+  done
+  has_design="true"
+  [ -n "$missing" ] && has_design="false"
+  if [ "$has_entities" = "false" ] && [ "$has_design" = "false" ]; then
+    state="empty"
+  else
+    state="entities=$has_entities design=$has_design missing=$missing"
+  fi
+fi
+
+echo "$state"
+```
+
+Map the printed `state` to the resume table (spec § 4):
+
+| Printed `state` | Behavior |
+|---|---|
+| `missing` | No resume — drop through to 1a normally. |
+| `empty` | Workdir exists but has neither entities nor design files. Treat as fresh / not started — drop through to 1a normally. |
+| `entities=true design=true …` | **Refresh from instance** (1.0a). Then skip 1b/1c/1d/1f. Run 1g (revise-fold the ask, since design already exists) and continue to Step 2. |
+| `entities=true design=false missing=…` | **Refresh from instance** (1.0a). Then skip 1a.5/1b/1c/1d/1g. Run 1f (reverse-engineer from refreshed local files, folding the ask in via `additions`) and continue to Step 2. |
+| `entities=false design=true …` | No refresh (nothing to refresh). Skip 1b/1c/1d/1f. Drop into Step 3 directly. |
+
+### 1.0a Refresh from instance (resume preflight)
+
+Run only when resume detection finds entity files locally (rows 3 and 4 of the table above).
+
+Invoke `tb pull` (bare-group form) to refresh every locally-tracked entity in the solution:
+
+```bash
+tb pull --solution <slug>
+```
+
+This issues a single `/api/solution/export` call for every entity tracked under `<workdir>/`, refreshing them from the instance.
+
+Behavior by result:
+
+- Exit 0, no errors → log one line `"Refreshed N entities from instance."` and continue.
+- `tb pull` reports a dirty-git error (some local files have uncommitted changes that would be overwritten) → emit `[paused] waiting: refresh decision` and call `AskUserQuestion`:
+  - `question`: `"Your local solution has uncommitted changes. Refresh from instance anyway? Local edits will be overwritten."`
+  - `header`: `"Refresh"`
+  - `options`:
+    - `Refresh and overwrite local edits` → re-run with `tb pull --solution <slug> --force`. Log `"Refreshed N entities from instance (overwrote local edits)."`.
+    - `Keep local edits — skip refresh` → continue without refreshing. Log `"WARNING: local edits preserved; design may be out of sync with instance."`.
+    - `Abort` → stop the whole run with `"Aborted by user. Commit or stash local edits and re-run."`.
+- **`External ids not found … have they been pushed yet?`** → this is the **pulled-not-pushed** case, **not** a missing-entity error. The solution was populated by `tb pull`, so its local entity IDs are the server's **internal** IDs; the bulk refresh sends them as *external* IDs, which only resolve for solutions that were *pushed*. **Do not** treat this as deletion and **do not** prompt to drop files. Instead refresh by **internal UUID**: read each tracked entity file's `id.id` and entity type, group by type, and run one `tb pull <type> <uuid> …` per type (the by-UUID form resolves internal IDs). If the solution was just pulled moments ago in this same flow and is already current, skip the refresh entirely with one calm line — `"Solution was pulled (not pushed); local files are already current — skipping refresh."` — and continue. This branch takes precedence over the HTTP 404 handling below whenever the server message carries the "have they been pushed yet?" hint.
+- HTTP 404 **without** the "pushed yet?" hint (a locally-tracked entity that was previously pushed no longer exists on the server) surfaces via the existing `_format_missing_ids_message` renderer in `commands/pull.py` — surface the missing IDs verbatim and ask whether to drop the corresponding local files or abort. (Out of scope for v1: if user picks "drop", just delete the corresponding files; if "abort", stop.)
+- HTTP 403 → surface "Profile lacks VERSION_CONTROL READ permission" and stop.
+
+In `mode = autonomous`, dirty-edits default to **Keep local edits — skip refresh** plus the warning. Never auto-overwrite uncommitted edits without an explicit user choice.
+
+### 1a. Approval mode (if not already forced autonomous)
+
+**Ask this question first, alone in its own message, before doing anything else — including reading capability docs or creating tasks.** Do not batch it with interview questions, the plan, or other content — the mode answer determines what happens next.
+
+Emit `[paused] waiting: approval mode`, then call `AskUserQuestion` (per **Pipeline Config → Question UI**):
+
+- `question`: `"How do you want to approve the design?"`
+- `header`: `"Approval mode"`
+- `options`:
+  - `Approve at each step` — `"I'll stop after the architecture design and after the dashboard design and wait for your approval before continuing."`
+  - `Build everything now` — `"I'll show you each design result but won't stop. You can switch to this anytime by saying 'just continue' or 'stop asking'."`
+
+Map: `Approve at each step` → `mode=interactive`; `Build everything now` → `mode=autonomous`. Default if ambiguous or skipped: **interactive**.
+
+### 1a.5. Source
+
+Run **only when `source` was not already set by the Step 1a pre-scan** AND the Step 1.0 resume preflight did not already lock in a `<workdir>` from cwd. Asked alone in its own message, after 1a's mode answer is in.
+
+**First classify intent — `create` means a NEW solution.** A request phrased as *create / build / generate / make (me) a `<domain>` solution* means a **new** solution. Default it to new and do **not** offer to update an unrelated existing one — "create" is not "update." Treat the request as a possible *update* only when it (a) uses update verbs (*add to / extend / update / change / modify*), or (b) names or clearly refers to an existing solution.
+
+**Scan existing solutions, then check each for relevance to the request:**
+
+```bash
+# cwd is the project root by contract
+existing=$(ls -dt solutions/*/ 2>/dev/null | xargs -n1 -I{} basename {} | tr '\n' ' ')
+existing_count=$(ls -d solutions/*/ 2>/dev/null | wc -l)
+```
+
+For each existing slug, judge whether it is **relevant** to this request — its name/domain meaningfully overlaps the requested domain (request "smart building" vs slug `smart-building-monitoring` = relevant; vs slug `waste-management` = **not** relevant), or the user named it. **Recency alone is not relevance** — offering the most-recent solution as an update target when its domain is unrelated is exactly the bug this rule prevents.
+
+Emit `[paused] waiting: solution source`, then call `AskUserQuestion`. Pick the branch by intent + relevance:
+
+- **Clear create-new request with no relevant existing solution** (the common case — e.g. "create a smart building solution" while only `waste-management` exists), **or `existing_count == 0`** → do **not** show any "Update existing" option. Ask only the source question:
+  - `Build from scratch` — `"I'm designing the entities from scratch — nothing on the instance yet."`
+  - `Use entities from my instance` — `"I have some entities on my instance already; build around them."`
+
+- **Request relates to or names an existing solution** (a relevant slug was found, or update verbs were used) → offer updating the **relevant** solution(s) (most-recent first, capped at 2), plus the two source options:
+  - `Update existing solution: <relevant-slug>` — `"Open solutions/<slug>/ and add this on top of what's already there. I'll refresh from the instance first to pick up any UI edits."`
+  - `Build from scratch` — same as above.
+  - `Use entities from my instance` — same as above.
+
+- **Genuinely ambiguous request** (generic "make me a solution" with no clear new domain) AND existing solutions present → offer the 2 most-recent as update options plus the two source options. When `existing_count > 2`, append `"(<existing_count> total solutions exist locally — pick \`Other\` and type the slug if you need a different one.)"` to the question text.
+
+`AskUserQuestion` has a 4-option hard cap; never list more than 2 update targets, and only ever list *relevant* ones.
+
+Map answers:
+
+- `Build from scratch` → `source = fresh`.
+- `Use entities from my instance` → `source = instance-import`.
+- `Update existing solution: <slug>` → set `<workdir> = solutions/<slug>`, leave `source = fresh` (the source variable describes how a *new* workdir is populated; an existing one is described by the resume flow). Then **skip the rest of 1a.5, skip 1b/1c/1d**, and jump directly to the resume flow: run **§ 1.0a Refresh from instance**, then fold in the ask via exactly one of — **§ 1f** (reverse-engineer + fold the ask in via `additions`) when design files are missing, or **§ 1g** (revise-fold the ask) when the design already exists — then continue to Step 2.
+- `Other` with a free-text slug that names an existing solution dir → treat exactly like `Update existing solution: <slug>`. If the typed slug doesn't exist as a sub-dir of `solutions/`, surface a one-line error (`"No solution named <slug> found under solutions/. Re-run and pick a listed option."`) and stop.
+
+Default if ambiguous or skipped: **fresh**.
+
+In `mode = autonomous` with no pre-scan match: default to `source = fresh`. Do **not** auto-pick an existing solution — the user should request that explicitly via their original request (e.g. "add a CF to my `factory-monitoring` solution"), which the Step 1a pre-scan should catch and route to the resume preflight via the "named solution" rule in § 1.0.
+
+### Evaluate `extension-enabled` from the original request
+
+Before 1a runs, scan the original user request for the explicit triggers listed in the **Extension-enabled flag** section above (literal words `extension`, `custom backend`, `Java`, `Spring`, `scheduled job`, `/api/extension`; phrases like `add an extension`, `build me an extension`, `extend ThingsBoard`; invocation of `/create-extension`). Set `extension-enabled = true` if any are present, else `false`. This single pass owns the initial value of the run-wide flag — do not heuristically re-scan later turns; rely on the user to say one of the trigger phrases to flip it. Acknowledge in one line **only** when the flag flipped to `true`, e.g.:
+
+> Got it — extension wiring is on. I'll plan an extension surface as part of the design.
+
+When the flag is already `true` here, downstream steps skip the extension inform-line entirely (1b) and route per the **Extension trigger-point table** above.
+
+### Evaluate `scale` from the original request
+
+Also before 1a runs, scan the original user request for explicit per-entity counts — phrases like `3 sensors`, `200 turbines`, `monitor 50 vehicles`, `10-machine demo`, `our fleet of 40 trucks`. If found, set `scale = production-scale` and remember the stated counts; they flow into the architecture phase via the `## User Requirements` section.
+
+If no explicit count is present, leave `scale` unset. The interview (1b) will ask the user; on skip — or in `mode=autonomous` without a pre-scan match — `scale` falls through to `prototype`.
+
+Do not heuristically re-scan later turns; rely on the user's interview answer (or a mid-run instruction) to change `scale`.
+
+### Read the shared capability doc
+
+After `mode` is set, `Read` the shared platform-capabilities doc — it stays in conversation for the whole run and is referenced by Step 2:
+
+- `@$TB_RESOURCES/prompts/solutions/solution-ba/resources/solution-capabilities.md` — platform-wide IoT capabilities: indoor/outdoor positioning rules, customer-hierarchy guidance, metric-type overview, alarm-pattern overview, solution-description structure.
+
+### Show the plan
+
+Build the task list with `TaskCreate` ONCE, at the moment the orchestrator can name every step that will actually run. The announcement point depends on the run shape:
+
+- `source = fresh`: announce after Step 1c (slug derivation). By then mode, scale, and extension-enabled are all locked in.
+- `source = instance-import`: announce after Step 1f (reverse-engineer + fold-in). By then `pull-solution` has discovered and pulled the connected graph, design files are reverse-engineered, and any net-new artifact is folded in — so the orchestrator knows exactly which Step 3 generators will produce output.
+- Resume mode: announce after the fold-in step (1f or 1g), or directly after the resume preflight when no fold-in is needed.
+
+Until that announcement point, the orchestrator narrates progress in plain text (`Discovering entities on instance...`, `Pulled 12 entities...`, `Reverse-engineering design...`) — no upfront placeholder list.
+
+Compose the task list from the catalog in **Pipeline Config → Generation steps**, in order. Skip every entry that doesn't apply:
+
+1. **Kickoff** — always exactly one. Pick the one that fits the run shape:
+   - `Consult user` (fresh, interactive)
+   - `Consult user (skipped — autonomous mode)` — marked `completed` immediately (fresh, autonomous)
+   - `Discovered, pulled, and reverse-engineered <N> entities from instance` — marked `completed` immediately (instance-import; this work is done by announcement time)
+   - `Refreshed and reverse-engineered <slug>` — marked `completed` immediately (resume with entities present)
+2. **`Design solution architecture`** — include only when this run will run a non-trivial design pass:
+   - `source = fresh` → always include.
+   - `source = instance-import` OR resume → include only when the ask was folded in (via Step 1f `additions` or Step 1g revise) AND the net-new artifact materially changes the design (new profile, new role, new CF, new alarm). Skip for pure dashboard requests on existing entities.
+3. **Generation task** — include only when at least one Step 3 generator will produce non-empty output. Pick the smallest accurate subject from the catalog: 
+   - Full breadth → `Create entities, calculated fields, alarms, and demo telemetry`.
+   - Single category → e.g. `Create calculated field(s)`, `Add alarm rule(s)`, `Add telemetry/attribute key(s) on existing profile(s)`, `Add device(s)`.
+   - Combinations → list the dominant artifact types, e.g. `Create calculated field(s) and alarm rule(s)`.
+4. **`Build extension`** — only when `extension-enabled = true`.
+5. **`Design dashboards`** and **`Create dashboards`** — include when this run is expected to design or regenerate dashboards:
+   - `source = fresh` AND the user did not say "no dashboards" → both.
+   - User's original request explicitly asks for a dashboard → both.
+   - Resume/import AND the predicted Step 3.7 classification is High impact (added a new profile/role/user) → both.
+   - Otherwise → omit. If the Step 3.7 outcome can't be predicted until it actually runs (the Maybe-impact branch), include the tasks tentatively and remove them via `TaskUpdate(status=deleted)` once 3.7 decides to skip.
+
+After choosing the set, dispatch all `TaskCreate` calls in a **single message** so the user sees the full roadmap at once. Then run the remaining steps, marking each task `in_progress` on entry and `completed` on exit (per the **Pipeline Config → Generation steps** rule).
+
+In `mode = autonomous`, the same rules apply — the task list is honest about what will run; only the *pauses* are skipped.
+
+### 1b. Domain interview
+
+Before any question — **only when `extension-enabled == false`** — print this inform-line verbatim (it's an information line, not a prompt — do not wait for a reply):
+
+> Heads up: if you need backend logic ThingsBoard can't express natively (e.g. role/user profiles with default dashboards, cross-customer aggregation, custom widget actions, custom validation on entity changes), say **add an extension** at any point and I'll wire one in.
+
+Skip the inform-line entirely when `extension-enabled == true` — the user has already opted in, and the line would be redundant and confusing.
+
+Otherwise print the line **once per run**. In autonomous mode (where 1b is otherwise skipped), still print this exact line once at the top of the run when `extension-enabled == false` — informational, no pause.
+
+In `mode=autonomous`, skip 1b entirely — the original request + `solution-capabilities.md` are the only inputs.
+
+In `mode=interactive`, ask targeted questions — at most 3 per message. Option-based questions go through `AskUserQuestion` (per **Pipeline Config → Question UI**); the only open-ended question is plain text. Include a `Skip — you decide` option in every `AskUserQuestion` call; the user can also reply `skip` in chat.
+
+Introduce the skip option on the first batch:
+
+> "You can answer these, or reply **skip** at any time and I'll decide everything from your original request using the platform rulebook."
+
+Question templates:
+
+- **Domain & entities** (plain text) — what's being monitored or controlled? Open-ended; examples: sensors, meters, gateways, vehicles, machines.
+- **Hierarchy** (`AskUserQuestion`, `header: "Hierarchy"`):
+  - `Standalone devices only`
+  - `Devices inside a container asset` — building / floor / fleet / site / vehicle
+  - `Skip — you decide`
+- **Customers & users** (`AskUserQuestion`, `header: "Customers"`) — load-bearing; always ask when the request doesn't make it obvious:
+  - `Tenant-only` — one installation I own / one organization managing everything
+  - `Customer-hierarchy` — platform serving multiple independent customers / tenants / sites
+  - `Skip — you decide`
+- **Scale** (`AskUserQuestion`, `header: "Scale"`) — **ask only when `scale` is still unset** after the pre-scan in Step 1a. How many entities should the demo include?
+  - `Small working prototype` — 1–5 entities per profile, all features wired, enough to demonstrate the pattern end-to-end. *(recommended default)*
+  - `Single instance per profile` — exactly one of each profile. For monitoring a specific physical thing.
+  - `Production scale` — I'll specify counts (follow up with a plain-text question asking for per-profile counts).
+  - `Skip — you decide` — defaults to small working prototype.
+
+  Maps to: `Small working prototype` → `scale=prototype`; `Single instance per profile` → `scale=single-target`; `Production scale` → `scale=production-scale` (ask counts as plain text, capture them into conversation context so the architecture skill can put them in the `## User Requirements` and `## Demo Entities` sections).
+- **Alarms & metrics** (`AskUserQuestion`, `header: "Alarms & metrics"`) — any specific derived values or thresholds to track?
+  - `Yes — I'll describe` (the user then replies in chat with the details)
+  - `No / propose sensible defaults`
+  - `Skip — you decide`
+
+Telemetry and attributes are usually obvious from the entities themselves — ask only if genuinely unclear.
+
+Rules:
+- Infer what you can from the domain; skip obvious questions.
+- The Scale question is asked only when the Step 1a pre-scan didn't set `scale` from an explicit count in the original request. If the user picks `Production scale`, follow up in plain text to gather per-profile counts; the architecture skill records these in `## User Requirements` and `## Demo Entities` of `architecture-overview.md`.
+- Emit `[paused] waiting: your answers on <short topic>` before each question batch.
+- **Skip triggers** — any of `skip`, `skip interview`, `you decide`, `doesn't matter`, `I don't know`, plus the run-wide autonomous triggers from **Pipeline Config → Mode variable**. Any of these ends the interview immediately: switch to `mode=autonomous` for the rest of the run and infer every remaining decision.
+
+### 1c. Consolidate
+
+Derive a kebab-case `slug`:
+
+- When `source = fresh`: slugify the solution domain (e.g. `coffee-machine-monitoring`).
+- When `source = instance-import`: **don't derive or create anything here.** Step 1d delegates to `pull-solution`, which owns slug derivation (from the anchors it matched and the user approved) and creating the solution dir. The only thing 1c passes forward is an explicit `--solution <name>` override, if the user gave one — hand it to `pull-solution` as `slug=<name>`.
+
+The user can always override the auto-derived slug by passing `--solution <name>` in their original request.
+
+For `source = fresh`, create the solution directory now, before any design phase begins. Run cwd MUST be the project root for the entire skill and every sub-skill it dispatches — never `cd` into the solution dir; `tb` commands target it via `--solution <slug>`. (For `source = instance-import`, this happens inside Step 1d instead.)
+
+```bash
+tb config mode local
+tb solution new <slug>
+workdir="$(realpath solutions/<slug>)"
+mkdir -p "$workdir/design"
+```
+
+`workdir` is the absolute path to the solution dir, passed verbatim as input to Step 2 and every subsequent phase. Sub-skills must use it verbatim — do not re-derive from `slug` or cwd.
+
+The design phases write artifacts under `<workdir>/design/`: Step 2 emits `architecture-overview.md` + five typed JSON files (`entity-profiles.json`, `relations.json`, `iam.json`, `metrics.json`, `alarms.json`); Step 4 emits `dashboards.json`. The `design/` subdirectory is ignored by `tb push`.
+
+### 1d. Discover and pull (only when `source = instance-import`)
+
+Skip entirely when `source = fresh`.
+
+Delegate discovery, matching, batch confirmation, and pulling to the `pull-solution` skill — do **not** inline a picklist or `tb pull` here. The user approves or suggests a proposed batch; they never hand-pick entities one by one.
+
+Invoke `Skill` `pull-solution` with:
+- the user's original request (so it derives search terms / breadth),
+- `mode=<mode>`,
+- `slug=<slug>` **only if** Step 1c already produced one (e.g. the user passed `--solution <name>`); otherwise omit it and let `pull-solution` derive the slug from the approved anchors and create the solution dir.
+
+`pull-solution` runs its Discover-mode flow: dispatches `instance-entity-discoverer`, matches the request against the instance (by name, profile, and type), previews the connected graph with a dry-run, and presents **one** batch-confirmation gate where the user approves the proposed set or suggests changes in natural language. For a vague ask with no usable terms, it proposes a sensible batch (a dominant container's subtree, or the full discovered set) rather than asking the user to choose. It owns the reach-check for multi-hop relations, and in `mode=autonomous` it pulls the matched batch without pausing.
+
+When it returns, the connected graph (anchors + profiles, parent assets, customers, relations, embedded CFs / alarm rules / entity groups) is materialized under `solutions/<slug>/`. Capture the resolved slug and set the run-wide workdir:
+
+```bash
+workdir="$(realpath solutions/<slug>)"
+mkdir -p "$workdir/design"
+```
+
+If `pull-solution` was cancelled (user declined the batch) or matched nothing usable, stop the import with the message it surfaced — do not fall through to a fresh interview.
+
+### 1f. Reverse-engineer design — and fold in the user's ask (when `source = instance-import` OR resume with missing design files)
+
+Invoke `Skill` `design-solution-architecture` with args: `slug=<slug>, workdir=<workdir>, mode=autonomous, extension-enabled=<true|false>, from-existing=true`.
+
+**Fold the user's net-new ask into this same call.** When the user's original request names a *net-new* artifact on top of the imported entities, also pass `additions=<brief>` so the design is reverse-engineered **and** the new artifact added in one pass — no separate revise round-trip. Map the request to the affected artifact(s) using this table and describe each in the brief:
+
+| Phrase in user request | Folds into |
+|---|---|
+| `add an alarm`, `create an alarm rule` | an alarm |
+| `add a calculated field`, `create a CF` | a calculated field |
+| `add an attribute`, `set an attribute` | a profile telemetry/attribute key |
+| `add a new device profile`, `add a new sensor type` | a new device/asset profile |
+| `add a role`, `add a user profile` | a role / user profile |
+| `add an entity / device / asset` | a new profile + a `## Demo Entities` row |
+| `create a dashboard` (no other artifact) | nothing — pass no `additions`; dashboards are Step 4 |
+
+When the request names nothing net-new, omit `additions` entirely — `from-existing` then runs as a pure extract.
+
+Wait for the skill to return. It will have written under `<workdir>/design/`:
+- `architecture-overview.md`
+- `entity-profiles.json`
+- `relations.json`
+- `iam.json`
+- `metrics.json`
+- `alarms.json`
+- (when `extension-enabled=true`) `extension-design.json`
+
+Read each file's top-level `warnings: [string]` array, if present, and stash them for the Step 2 gate. When `additions` was passed, also read each file's `added: [string]` array — those entry names drive the `[imported]`/`[new]` labelling in Step 2.
+
+### 1g. Fold in the user's ask when the design already exists (resume only)
+
+Runs **only** in the resume case where design files were already present and Step 1f was skipped (resume table row `entities=true design=true`). When Step 1f ran, the ask was already folded in via its `additions` arg — **do not** run 1g as well.
+
+In this resume case there is no extract pass to piggyback on, so fold the ask in with a revise call. Using the same request→artifact mapping table from Step 1f, for each net-new artifact invoke `Skill` `design-solution-architecture` with `revise=true, --stage <stage>, from-existing=true` and a brief describing the new entry; it appends to the existing stage file rather than rewriting it. Dispatch one revise call per stage when multiple artifacts are named. Remember the names of the artifacts you folded in — Step 2 labels them `[new]`.
+
+In both `mode = autonomous` and `mode = interactive`, 1g runs silently — the new entry is visible at the Step 2 gate.
+
+## Step 2 — Solution design
+
+Invoke `Skill` `design-solution-architecture` with args: `slug`, `workdir`, `mode=autonomous`, `extension-enabled=<true|false>`. The skill drafts the architecture overview using the conversation context, then dispatches subagents for entity profiles, relations + IAM (parallel when `extension-enabled=false`; relations → extension-design → IAM serialised when `extension-enabled=true`, so any `entityDependencies.customRoles` fold into IAM as first-class roles), metrics, and alarms. Each stage writes a per-stage file under `<workdir>/design/`: `architecture-overview.md`, `entity-profiles.json`, `relations.json`, `iam.json`, `metrics.json`, `alarms.json`, plus `extension-design.json` when extensions are enabled.
+
+### Present the solution design
+
+Read all six files: `<workdir>/design/architecture-overview.md` plus `<workdir>/design/{entity-profiles,relations,iam,metrics,alarms}.json`. When `extension-enabled=true`, also read `<workdir>/design/extension-design.json`.
+
+1. **Entity hierarchy (indented tree)** — render a plain-text indented tree inside a fenced code block. Customer profiles are outer containers; their owned user profiles and entity profiles nest inside. Asset-to-asset and asset-to-device containment relations nest further. Non-containment relations render as inline arrows under the source entry.
+
+    Rules:
+    - **Root.** `Tenant` is always the root.
+    - **Tenant-level children:** tenant-admin user profiles (every `iam.json.roles` entry with `permissions: CRUD`), then customer profiles if `entity-profiles.json.customerProfiles` is non-empty; otherwise the top-level entity profiles (those that never appear as `child` in a containment relation).
+    - **Inside each customer profile block:** customer-scope user profiles, then the entity profiles the customer owns. Nest containment relations (`Contains`, `[Parent]Has[Child]`) from `relations.json.entityRelations` as further children.
+    - **Multi-customer replication.** When multiple customer profiles exist, repeat the inner subtree under each one — that's intentional, not a duplication bug.
+    - **Non-containment relations.** Render under the source entry indented one level with `↓ <type>` pointing at the target profile.
+    - **Box-drawing.** Use `├─`, `└─`, `│` for tree edges; `↓` for relation arrows.
+    - **Profile annotations.** Mark entity profiles with `(DEVICE)` / `(ASSET)`; mark user profiles with their IAM permission level (`CRUD` / `RU` / `R`).
+
+    Example (multi-customer, one device profile per customer):
+
+    ````
+    Tenant
+    ├─ User: CoffeeMachineAdministrator (CRUD)
+    │
+    ├─ Customer Profile: CafeOwner
+    │  ├─ User: CoffeeMachineOperator (RU)
+    │  │   ↓ Operates
+    │  └─ Device Profile: CoffeeMachine (DEVICE)
+    │
+    └─ Customer Profile: ChainHQ
+       ├─ User: ChainSupervisor (R)
+       └─ Device Profile: CoffeeMachine (DEVICE)
+    ````
+
+2. **Profiles** — list each profile with its `telemetry` and `attributes` from `entity-profiles.json`.
+3. **Customers and users** — read from `entity-profiles.json.customerProfiles` and `userProfiles`. `customerMode` is derived: `customer-hierarchy` if `customerProfiles` is non-empty, else `tenant-only`.
+4. **IAM roles** — list from `iam.json.roles` with `name`, `userProfile`, `permissions`, `description`.
+5. **Calculated fields** — group by `attachedTo` profile. For each: `name`, `type`, `inputs`, `output`, expression summary.
+6. **Alarms** — group by `attachedTo` profile. For each: severity entries and clear condition.
+7. **(when `extension-enabled=true`) Extension surface** — conditional sub-section. Omit entirely when `extension-enabled=false` and renumber Warnings to 7. Read `<workdir>/design/extension-design.json`. Render three sub-sections:
+    - **Endpoints** — list each entry as `<METHOD> <path> [<auth>] — <purpose>`.
+    - **Scheduled tasks** — list each `scheduledTasks` entry; skip the sub-section when the array is empty.
+    - **Custom roles** — list `entityDependencies.customRoles`. These names should also appear in the IAM block (4) as first-class roles — flag any mismatch as a warning.
+8. **Warnings** — if `metrics.json.warnings` is non-empty, list each as a caveat.
+
+### Imported / new labelling (when `source = instance-import` OR resume)
+
+When this Step 2 run is presenting a reverse-engineered design (any case where `from-existing=true` was used for Step 1f), label each entry in the rendered tree, profiles list, IAM roles list, CF list, and alarms list with one of:
+
+- `[imported]` — the entry was extracted from an entity already on the instance.
+- `[new]` — the entry was folded in by this run's ask.
+
+How to know which is which: an entry is `[new]` if it was added during fold-in — i.e. its name appears in a stage file's top-level `added: [string]` array (the Step 1f `additions` path), or it is one of the artifacts Step 1g folded in via revise (the resume path). Every other entry is `[imported]`.
+
+Render a one-line legend above the tree:
+
+```
+Legend: [imported] = entity already on your instance · [new] = added in this run
+```
+
+For pure fresh runs (no `from-existing=true`), skip the legend and the tags — the existing rendering is unchanged.
+
+### Approval gate
+
+Defined in **Pipeline Config → Approval gates** (blocks until approved).
+
+If `mode=interactive`:
+- Emit `[paused] waiting: approval of solution design`
+- Call `AskUserQuestion` (per **Pipeline Config → Question UI**):
+  - `question`: `"Please check the design summary above and the full files saved under <workdir>/design/. Does the design look right — profiles, relations, customers, users, roles, calculated fields, alarms<EXT>? Anything to add, remove, or change before I start generating?"** Replace `<EXT>` with `, extension surface` when `extension-enabled=true`, else with the empty string."`
+  - `header`: `"Design approval"`
+  - `options`:
+    - `Approve and continue` — `"Start generating entities, calculated fields, and alarms."`
+    - `Revise` — `"I want to change something — I'll describe what."`
+- On `Revise` (or "Other" custom feedback), see **Revisions** at the bottom.
+
+If `mode=autonomous`:
+- Print `[auto] solution design: <P> profiles, <R> relations, <ROLE> roles, <CF> calculated fields, <AL> alarms` and proceed.
+
+Where `<P>` = `len(deviceProfiles) + len(assetProfiles)`, `<R>` = `len(relations.entityRelations)`, `<ROLE>` = `len(iam.roles)`, `<CF>` = `len(metrics.calculatedFields)`, `<AL>` = `len(alarms.alarms)`.
+
+## Step 3 — Generate entities, CFs, and alarms
+
+### Sub-skill calls
+
+Each sub-skill orchestrates its own parallelism internally and reads its inputs from `<workdir>/design/`. Briefs are minimal — `solution=<slug>, workdir=<workdir>` for most; `reprocess-calculated-fields` takes `solution=<slug>, mode=local` (no `workdir`).
+
+1. `Skill` `generate-entities` with `solution=<slug>, workdir=$workdir` — materializes profiles, devices, assets, customers, users, roles, entity groups, and structural relations. Wait for it to return before the parallel batch.
+
+**Emulator opt-in for imported devices.** When `source = instance-import` OR (resume mode AND any imported device has at least one DEVICE profile), ask the user once before dispatching `generate-emulators`:
+
+Emit `[paused] waiting: emulator opt-in`, then call `AskUserQuestion`:
+- `question`: `"Generate demo emulator tasks for the imported devices too? Useful on dev/test instances; safe to say no on prod."`
+- `header`: `"Emulators"`
+- `options`:
+  - `Yes — add emulators`
+  - `No — leave imported devices alone`
+
+Map: Yes → pass `import-emulator-opt-in=true` to `generate-emulators`; No → omit the flag.
+
+In `mode = autonomous`, default to **No**. Net-new devices in the same run always get emulators regardless of this answer.
+
+2. **In parallel** (single assistant message), dispatch whichever apply. Skip any whose precondition is unmet; if all four are unmet, skip the batch entirely.
+   - `Skill` `generate-attributes` with `solution=<slug>, workdir=$workdir` — only when at least one `entity-profiles.json` profile has a `telemetry` item with `telemetryType == "ATTRIBUTE"`.
+   - `Skill` `generate-emulators` with `solution=<slug>, workdir=$workdir` — only when `entity-profiles.json` has at least one `DEVICE` profile with non-empty `telemetry`.
+   - `Skill` `generate-calculated-fields` with `solution=<slug>, workdir=$workdir` — only when `metrics.json.calculatedFields` is non-empty.
+   - `Skill` `generate-alarms` with `solution=<slug>, workdir=$workdir` — only when `alarms.json.alarms` is non-empty.
+3. If step 2's `generate-calculated-fields` ran, `Skill` `reprocess-calculated-fields` with `solution=<slug>, mode=local`. **Local mode only** — writes task files; no server call. Must run **after** step 2 has fully completed because `cf-reprocess-generator` scans saved CF files under `solutions/<slug>/**`. **Note (resume/import mode):** When `source = instance-import` OR resume mode, **do not** dispatch reprocess automatically here. Step 3.6 owns that decision via an explicit user prompt.
+
+If any sub-skill errors, stop and report. Wait for all dispatches in step 2 to finish before deciding whether to run step 3.
+
+### Validate, checkpoint, notify
+
+Run `tb validate <slug>`. On error, surface the output verbatim and stop. On success, invoke `Skill` `commit-step` with `solution=<slug>, step="Add entities, calculated fields, and alarms"` (per **Pipeline Config → Finalization pattern**), then print the push notice from **Pipeline Config → Push notice pattern**.
+
+### Approval gate
+
+Defined in **Pipeline Config → Approval gates** (defaults toward continuing).
+
+If `mode=interactive`:
+- Emit `[paused] waiting: continue to dashboard design`
+- Call `AskUserQuestion` (per **Pipeline Config → Question UI**):
+  - `question`: `"Entities, calculated fields, and alarms have been generated and saved under <workdir>/. Continue to dashboard design?"`
+  - `header`: `"Continue?"`
+  - `options`:
+    - `Continue to dashboards` — `"Looks good — go ahead with the dashboard design."`
+    - `Pause to inspect files` — `"Wait — I want to check the generated files first."`
+- On `Continue to dashboards`, advance to Step 4.
+- On `Pause to inspect files` (or custom feedback requesting changes), see **Revisions** at the bottom.
+
+If `mode=autonomous`:
+- Do not pause. Advance to Step 3.5 (when extensions are enabled) or Step 4.
+
+## Step 3.5 — Build extension (only when `extension-enabled=true`)
+
+If `extension-enabled` is `false`, skip this step entirely.
+
+Otherwise:
+
+1. Resolve the project root from `workdir`:
+
+   ```bash
+   project_root="$(dirname "$(dirname "$workdir")")"
+   ```
+
+   (`workdir` is `<project-root>/solutions/<slug>`; two `dirname` walks back to the project root.)
+
+2. Invoke `Skill` `create-extension` with:
+    - `workdir=$project_root` — the sub-skill operates on the project root, not the solution dir.
+    - `brief=$workdir/design/extension-design.json` — absolute path to the design file from Step 2.
+    - `invoked-by-create-solution=true` — suppresses the sub-skill's after-return dashboard-wiring offer; this orchestrator owns dashboards.
+
+3. The `create-extension` skill ensures `<project_root>/extension/` is unpacked (running `tb extension new` if missing), resolves the edition, and dispatches the `extension-builder` agent against the brief. Wait for the sub-skill to return.
+
+4. Surface the sub-skill's compact summary verbatim. On error, surface the error verbatim and stop — do not print the push notice and do not advance.
+
+5. Invoke `Skill` `commit-step` with `solution=<slug>, step="Build extension"` (per **Pipeline Config → Finalization pattern**). Note: the extension lives at `<project_root>/extension/`, not under `solutions/<slug>/`, so the sub-skill's commit will likely be a no-op for the solution dir — that's fine; the orchestrator's contract is to call `commit-step` after every step regardless. The extension's own files are committed by the user / their workflow.
+
+6. Print one push notice (followed by an immediate advance — do NOT pause):
+
+   ```
+   Generated extension feature(s). Build with `tb extension build`, run with `tb extension run`. When ready to publish, run `tb extension push --image-name <registry-target>` (e.g. `myuser/<extension-name>`).
+   ```
+
+Advance to Step 4.
+
+## Step 3.6 — Emulator and CF reprocessing decisions (when `source = instance-import` OR resume mode)
+
+Skip entirely when `source = fresh` — the existing flow auto-handles reprocessing when CFs are generated, and emulators are generated for every new device by default. This step exists only to surface explicit user choices when the run added artifacts on top of entities that already exist on the user's instance.
+
+Aggregate `added` from Step 3's generators (per the Task 13 return contracts). Then route based on what was added:
+
+| Condition | Ask |
+|---|---|
+| `added.telKeys` non-empty (new telemetry / attribute / CF-output keys on profiles that already exist on the instance) | **Two questions** — emulator first, then reprocess. See below. |
+| `added.cfs` non-empty AND `added.telKeys` empty (new CFs added but no new keys) | **Single question** — reprocess only. See below. |
+| Neither | No prompt — proceed to Step 3.7. |
+
+### Emulator question (when new keys were added)
+
+Emit `[paused] waiting: emulator update`, then call `AskUserQuestion`:
+
+- `question`: `"You added new telemetry key(s): <keys>. Regenerate the demo emulator tasks for the affected device(s) so they emit the new keys too?"`
+- `header`: `"Emulator update"`
+- `options`:
+  - `Yes — regenerate emulators` — re-dispatch `Skill generate-emulators` with `import-emulator-opt-in=true` and a brief naming the affected devices. The skill respects its skip-by-filesystem rule: it overwrites only the emulator task files for the named devices.
+  - `No — leave emulators alone` — log one line `"Emulator tasks unchanged; new keys will only appear when real devices report them."` and continue.
+
+### Reprocess question (when new keys OR new CFs were added)
+
+After the emulator question (or directly, in the no-new-keys case), emit `[paused] waiting: CF reprocess decision`, then call `AskUserQuestion`:
+
+- `question`: `"Reprocess calculated field(s) over historical telemetry so back-data is filled in?"` *(when only new CFs)* OR `"Reprocess any calculated fields that depend on the new key(s) so their history is recomputed?"` *(when new keys triggered this branch)*
+- `header`: `"CF reprocess"`
+- `options`:
+  - `Yes — reprocess` — invoke `Skill reprocess-calculated-fields` with `solution=<slug>, mode=local` and a brief naming the affected CFs (the new ones, or every CF whose `arguments` reference one of the new keys). The skill writes task files only; nothing runs against the server until `tb push --run-tasks`.
+  - `No — skip reprocessing` — log one line `"No reprocessing tasks generated; CFs will compute forward from new telemetry only."` and continue.
+
+### Autonomous defaults
+
+In `mode = autonomous`:
+- Emulator question → default **Yes** (regenerate emulators so dashboards show data immediately).
+- Reprocess question → default **Yes** (backfill historical data).
+
+Each decision logged as one `[auto]` line.
+
+## Step 3.7 — Dashboard impact analysis
+
+After Step 3 completes and before Step 4 runs, aggregate the `added` summaries returned by each generator (per the Task 13 return contract — each generator emits a `GENERATED added=...` line) into:
+
+```
+added = {
+  profiles: [...],
+  roles: [...],
+  users: [...],
+  cfs: [...],          # objects: {name, outputKey}
+  alarms: [...],
+  attrKeys: [...],     # objects: {entity, key}
+  telKeys: [...],      # objects: {entity, key} — if generate-emulators added any new keys
+}
+```
+
+**Pulled-dashboards guard (instance-import / resume).** First check `<workdir>/dashboards/` for already-pulled dashboard files. If it's non-empty, the solution *has* dashboards even when the design file `<workdir>/design/dashboards.json` doesn't exist yet. In that case run Step 4 in **`from-existing=true`** mode (reverse-engineer + fold in any change) and Step 5 in update-in-place mode — do **not** fall into the "no dashboards yet, design them?" row below. The table below applies only when no dashboards exist on disk.
+
+Then classify against the existing `<workdir>/design/dashboards.json` (if any):
+
+| Condition | Impact | Action |
+|---|---|---|
+| `dashboards.json` exists AND `added.alarms` non-empty AND nothing else net-new | **None** | Log `"Alarms added; existing dashboards render them automatically."` Skip Steps 4 and 5. |
+| `dashboards.json` exists AND only `added.profiles` is empty (no new profiles/roles/users) AND any of `added.cfs / attrKeys / telKeys` non-empty | **Maybe** | Ask `AskUserQuestion`: `"You added new key(s): <keys>. Should they be shown on the dashboards?"` — Yes → invoke `Skill design-dashboards` with `revise=true, regen-targets=<dashboard-names-that-reference-the-key-or-the-affected-profile>`; then run Step 5 only for those dashboards. No → skip Steps 4 and 5. |
+| `dashboards.json` exists AND `added.profiles` OR `added.roles` OR `added.users` non-empty | **High** | Ask `AskUserQuestion`: `"You added a new <profile/role/user>. Should I design new dashboards (or extend existing ones) for it?"` — Yes → run Steps 4 and 5 as today. No → skip. |
+| `dashboards.json` doesn't exist AND user's original request mentioned the word `dashboard` | n/a | Run Steps 4 and 5 as today (current behavior). |
+| `dashboards.json` doesn't exist AND user's original request did NOT mention `dashboard` | n/a | Ask `AskUserQuestion`: `"There are no dashboards in this solution yet. Would you like me to design them?"` — Yes → Steps 4 and 5. No → skip and wrap up. In `mode=autonomous`, default to **Yes**. |
+
+In `mode=autonomous`, the Maybe/High questions become silent decisions: **Yes** for High, **No** for Maybe. Each logged as one `[auto]` line.
+
+## Step 4 — Design dashboards
+
+**Step 3.7 skip note.** If Step 3.7 decided to skip Step 4 entirely (impact = None, or the user picked "No" at the dashboards prompt), Step 4 does not run. Mark the Step-4 task as `completed` with subject suffix `(skipped — no dashboard impact)` via `TaskUpdate`. Proceed to Step 5. (Step 5 will also skip itself when `dashboards.json` has no new entries.)
+
+Invoke `Skill` `design-dashboards` with `workdir` + `extension-enabled=<true|false>`. It reads `<workdir>/design/{architecture-overview,entity-profiles,relations,iam,metrics,alarms}.json` (plus `<workdir>/design/extension-design.json` and `<project_root>/extension/README.md` when `extension-enabled=true`) and writes `<workdir>/design/dashboards.json` — no JSON dump in conversation. (Empty `dashboards` array if the original request said `no dashboards` or equivalent — the final dashboard-creation step becomes a no-op in that case.) When `extension-enabled=true`, dashboards may carry an optional `widgetActions` array wiring buttons to extension endpoints.
+
+**Follow existing dashboards (instance-import / resume).** If the pulled solution already has dashboards on disk (`<workdir>/dashboards/*.json` is non-empty), pass `from-existing=true` so `design-dashboards` reverse-engineers those dashboards as the baseline instead of inventing one per role — exactly like the entity design follows imported entities. When the user's ask (or an entity added this run) implies a dashboard change, also pass `additions=<brief>` describing it; `design-dashboards` folds it onto the existing dashboard(s) and records changed/new entries in each dashboard's `added` array. Do not create a per-role dashboard for roles that already have one, and add a brand-new dashboard only when the user explicitly asked for one. The Step 2 `[imported]`/`[new]` labelling applies to dashboards too, sourced from the `added` arrays.
+
+### Present dashboards
+
+Read `<workdir>/design/dashboards.json` and render, for each dashboard: `name`, `assignedTo`, `overview`, and use cases grouped by category (Entity Overview, Entity Management, Monitoring & Statistics, Alarm Handling, Navigation). Do **not** print raw JSON — point the user to the file path.
+
+### Approval gate
+
+Defined in **Pipeline Config → Approval gates** (blocks until approved).
+
+If `mode=interactive`:
+- Emit `[paused] waiting: approval of dashboard use cases`
+- Call `AskUserQuestion` (per **Pipeline Config → Question UI**):
+  - `question`: `"Please check the summary above and the full design saved to <workdir>/design/dashboards.json. Do these use cases cover what each role needs?"`
+  - `header`: `"Dashboard approval"`
+  - `options`:
+    - `Approve and create dashboards` — `"Looks good — go ahead and build the dashboards."`
+    - `Revise` — `"I want to change something — I'll describe what."`
+- On `Revise` (or custom feedback), see **Revisions** at the bottom.
+
+If `mode=autonomous`:
+- Print `[auto] dashboards: <name1>, <name2>, ...` and proceed.
+
+## Step 5 — Create dashboards
+
+**Partial regeneration mode.** When Step 3.7 dispatched `design-dashboards` with `regen-targets=[...]`, Step 5 should generate JSON only for the dashboards in that list — not every dashboard in `dashboards.json`. The orchestrator filters the dashboards array before dispatching `generate-dashboard-json` in parallel.
+
+Read `<workdir>/design/dashboards.json`. If its `dashboards` array is empty, this step is a no-op — proceed to wrap-up.
+
+**Update existing dashboards in place; don't recreate.** This applies to **any** dashboard already on disk under `<workdir>/dashboards/` — whether pulled from the instance or generated by Claude in a previous run. Before dispatching, match each `dashboards.json` entry (by title) against the files there. For a matching dashboard:
+- If this run did **not** change it (its name isn't in any `added` array, and the user didn't ask to change it), **skip it** — leave the existing dashboard untouched. Regenerating an unchanged dashboard would needlessly discard its view.
+- If this run **did** change it (an `added` entry, or the user explicitly asked to update that dashboard), dispatch `generate-dashboard-json` with `mode=update` and `existingDashboardPath=<the existing file>` so the change is applied surgically and the existing view is preserved — never a from-scratch rebuild.
+
+Dispatch with the default `mode=create` (a fresh build) **only** for dashboards that don't exist on disk — i.e. brand-new dashboards the user explicitly asked for, or dashboards in a fresh solution that has never been generated. Never recreate a dashboard that already exists just to apply a change.
+
+### Extension-aware widget JS (only when `extension-enabled=true`)
+
+If `extension-enabled=true`, the dashboards' `widgetActions` are populated. Pass `workdir` along with the existing args to `create-dashboard` so the downstream `generate-dashboard-json` skill picks the right widget snippet (it owns the PE/PaaS → snippet mapping).
+
+Also read the design files needed to build the per-dashboard briefs:
+- `<workdir>/design/iam.json` — to resolve each dashboard's `assignedTo` to the full role object (`{name, userProfile, permissions}`).
+- `<workdir>/design/relations.json` — provides `entityRelations`.
+- `<workdir>/design/entity-profiles.json` — provides `entityProfiles` (flatten `deviceProfiles` + `assetProfiles`, projecting `{name, entityType, telemetry as timeSeriesKeys, attributes as attributeKeys}` per profile).
+
+Dispatch one `Skill` `generate-dashboard-json` call per dashboard, **all in a single message** so they run in parallel. For each dashboard, build the brief from its entry in `dashboards.json`:
+
+- `solution` — the run-wide `<slug>`
+- `dashboardName` — `dashboards[i].name`
+- `overview` — `dashboards[i].overview`
+- `useCases` — flatten `dashboards[i].useCases` (the five-category object) into a single string array
+- `dashboardRole` — the `iam.json.roles` entry whose `name` matches `dashboards[i].assignedTo`
+- `entityRelations` — `relations.json.entityRelations`
+- `entityProfiles` — projected list described above
+- `demoRequirements` — optional; pass through any relevant counts/requirements if present in `architecture-overview.md`'s Demo Entities table
+- `userRequirements` — `dashboards[i].userRequirements` when present in `dashboards.json`; omit the field otherwise
+- `mode` / `existingDashboardPath` — per the "Update existing dashboards in place" rule above: pass `mode=update` + `existingDashboardPath=<workdir>/dashboards/<file>` for a changed pre-existing dashboard; omit both (default `create`) for a brand-new or fresh-run dashboard. (Skip changed-nothing pre-existing dashboards entirely — don't dispatch them.)
+
+Wait for all to finish; if any error, surface them together before continuing.
+
+Run `tb validate <slug>`. On error, surface the output verbatim and stop. On success, invoke `Skill` `commit-step` with `solution=<slug>, step="Add dashboards"` (per **Pipeline Config → Finalization pattern**), then print the push notice from **Pipeline Config → Push notice pattern**.
+
+## Wrap-up
+
+`tb validate <slug>` already ran before each push notice — no final validation needed. The wrap-up covers the same ground as the manual "Report what was created" guidance in `CLAUDE.md` (entity counts, where files live, validation status), minus the push reminder which the per-step push notices already delivered.
+
+Print one concise summary containing:
+
+- **Counts of what was created**, grouped by type: device profiles, asset profiles, devices, assets, customers, users, roles, calculated fields, alarms, dashboards (omit zero-count types).
+- **Solution directory path** (`<workdir>`) so the user knows where to inspect the files.
+- **Validation status** — "Validation passed" (since the run could only reach wrap-up if every per-step `tb validate <slug>` passed) plus any warnings surfaced earlier in the run.
+- **Extension surface** (only when `extension-enabled=true`): one line noting the extension lives at `<project_root>/extension/` and is built with `tb extension build` / run with `tb extension run`.
+
+Use a single short narrative paragraph rather than bullets. Template:
+
+````
+Created <slug> solution: <N> device profile(s), <N> device(s), <N> dashboard(s)<… other non-zero types>. Validation passed. Review files in <workdir>.
+````
+
+Do **not** remind the user to run `tb push` — the per-step push notices (Step 3, Step 5) already delivered that. Repeating it here is noise. The exception is when the run ended early due to an error, in which case there is no wrap-up at all.
+
+## Revisions
+
+If the user picks `Revise` at any gate, or asks to change something after a step's task is `completed`:
+
+1. Move the affected task back to `in_progress`.
+2. Re-invoke the corresponding sub-skill with `revise=true`:
+   - **Step 2** — `design-solution-architecture` with `revise=true, --stage <name>` where `<name>` is one of: `architecture-overview`, `entity-profiles`, `relations`, `extension-design`, `iam`, `metrics`, `alarms`. The orchestrator handles cascading dependent stages per its built-in dependency table. Re-read updated files, re-emit the `[paused]` marker, ask again, loop until approved.
+   - **Step 4** — `design-dashboards` with `revise=true`. When the changed dashboard already exists on disk under `<workdir>/dashboards/`, the Step 5 re-generation that follows must run in **update-in-place** mode (`mode=update`, `existingDashboardPath=…`) per Step 5's rule — apply the change surgically, never recreate the dashboard. This holds whether the dashboard was pulled from the instance or generated by an earlier run.
+   - Steps 3 and 5 are generation, not design — revisions go back to Step 2 (the source of truth) or Step 4.
+3. Re-read the updated file(s), re-emit the `[paused]` marker, and re-ask the gate's `AskUserQuestion`. Loop until approved.
+4. If the revision invalidates a downstream step (e.g. removing a profile used by a CF, alarm, or dashboard), flag it and ask whether to also re-run that step.
+5. If Step 3's push notice was already printed and the revision touches entities/CFs/alarms, tell the user they should re-push after the revision — re-print the push notice. Same for dashboards (Step 5).
+6. After re-generation produces new files, invoke `Skill` `commit-step` with `solution=<slug>, step="Revise: <short summary>"` (per **Pipeline Config → Finalization pattern**) so the README and history reflect the revised state.
+7. On re-approval, mark the task `completed` again and resume.
+
+### Late extension opt-in (after Step 5)
+
+If the user flips `extension-enabled` to `true` AFTER Step 5 already completed (i.e. dashboards have been generated):
+
+1. Run Step 3.5 (Build extension) to materialise `<project_root>/extension/` and the requested endpoints.
+2. Re-invoke `design-dashboards` with `extension-only=true` so it overlays `widgetActions` onto the existing `<workdir>/design/dashboards.json` without regenerating other use cases.
+3. Re-invoke `create-dashboard` ONLY for the dashboards whose `widgetActions` reference the new endpoints — leave untouched dashboards alone. This re-generation owns the wiring; do not ask the user to paste snippets manually.
+4. Re-validate with `tb validate <slug>`. On success, invoke `Skill` `commit-step` with `solution=<slug>, step="Revise: wire extension widgetActions into dashboards"` (per **Pipeline Config → Finalization pattern**), then print the Step 5 push notice once.