docs(iot-hub): implementation plan for ${item-link:uuid} markdown component

Step-by-step task plan covering the placeholder utility, the link card component, module wiring, three integration sites (item readme, device install instructions, solution install instructions), translations, and manual visual QA.
6 months ago · f887a2ee2d
1 changed files with 974 additions and 0 deletions
--- a/docs/superpowers/plans/2026-05-06-iot-hub-item-link.md
+++ b/docs/superpowers/plans/2026-05-06-iot-hub-item-link.md
@ -0,0 +1,974 @@
+# IoT Hub `${item-link:uuid}` Markdown Component — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a `${item-link:<uuid>}` markdown placeholder that renders an IoT Hub marketplace item card (thumbnail + name + creator) inline in readmes and install instructions, opening the linked item in a new tab.
+
+**Architecture:** A pure-string utility rewrites `${item-link:<uuid>}` to a `<tb-iot-hub-item-link-card itemId="...">` Angular component tag before the markdown reaches `tb-markdown`. The component is declared in a small `IotHubItemLinkModule` that each `tb-markdown` instance receives as `additionalCompileModules`. The component owns its own fetch (via `IotHubApiService.getPublishedVersion`), state (`loading` / `loaded` / `unavailable`), and click target (`/iot-hub/{itemId}` with `target="_blank"`).
+
+**Tech Stack:** Angular 20 (TypeScript, Material), `tb-markdown` (NgModule-based dynamic compilation), `IotHubApiService` (existing), Tailwind for utility classes, component-scoped SCSS.
+
+**Spec:** `docs/superpowers/specs/2026-05-06-iot-hub-item-link.md`
+
+**File structure:**
+
+New files:
+- `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-markdown.utils.ts` — `replaceItemLinkPlaceholders` + regex
+- `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-link-card/iot-hub-item-link-card.component.ts`
+- `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-link-card/iot-hub-item-link-card.component.html`
+- `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-link-card/iot-hub-item-link-card.component.scss`
+- `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-link-card/iot-hub-item-link.module.ts`
+
+Modified files:
+- `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-components.module.ts` — import `IotHubItemLinkModule`
+- `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.ts` — call utility in `loadReadme()`, expose compile modules
+- `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.html` — bind `[additionalCompileModules]` on readme `<tb-markdown>`
+- `ui-ngx/src/app/modules/home/components/iot-hub/device-install-dialog/device-install-dialog.component.ts` — add `^item-link:(uuid)$` branch in `resolveVariables()`, expose compile modules
+- `ui-ngx/src/app/modules/home/components/iot-hub/device-install-dialog/device-install-dialog.component.html` — bind `[additionalCompileModules]`
+- `ui-ngx/src/app/modules/home/components/solution/solution-install-dialog.component.ts` — pre-process `details`, expose compile modules
+- `ui-ngx/src/app/modules/home/components/solution/solution-install-dialog.component.html` — bind `[additionalCompileModules]`
+- `ui-ngx/src/assets/locale/locale.constant-en_US.json` — add `iot-hub.item-link-unavailable`
+
+---
+
+## Task 1: Create placeholder utility
+
+**Files:**
+- Create: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-markdown.utils.ts`
+
+- [ ] **Step 1: Create the utility file**
+
+Create `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-markdown.utils.ts`:
+
+```typescript
+///
+/// Copyright © 2016-2026 The Thingsboard Authors
+///
+/// Licensed under the Apache License, Version 2.0 (the "License");
+/// you may not use this file except in compliance with the License.
+/// You may obtain a copy of the License at
+///
+///     http://www.apache.org/licenses/LICENSE-2.0
+///
+/// Unless required by applicable law or agreed to in writing, software
+/// distributed under the License is distributed on an "AS IS" BASIS,
+/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+/// See the License for the specific language governing permissions and
+/// limitations under the License.
+///
+
+export const ITEM_LINK_PLACEHOLDER_REGEX =
+  /\$\{item-link:([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\}/g;
+
+export const ITEM_LINK_KEY_REGEX =
+  /^item-link:([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/;
+
+export function itemLinkCardTag(itemId: string): string {
+  return `<tb-iot-hub-item-link-card itemId="${itemId}"></tb-iot-hub-item-link-card>`;
+}
+
+export function replaceItemLinkPlaceholders(markdown: string): string {
+  if (!markdown) {
+    return markdown;
+  }
+  return markdown.replace(ITEM_LINK_PLACEHOLDER_REGEX, (_match, uuid) => itemLinkCardTag(uuid));
+}
+```
+
+- [ ] **Step 2: Sanity-check the regex**
+
+Write a temporary script `/tmp/check-item-link-regex.js` with this exact content:
+
+```javascript
+const re = /\$\{item-link:([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\}/g;
+const cases = [
+  ['${item-link:11111111-2222-3333-4444-555555555555}', 'valid'],
+  ['${item-link:not-a-uuid}',                          'invalid'],
+  ['Two: ${item-link:11111111-2222-3333-4444-555555555555} and ${item-link:aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee}', 'two valid'],
+  ['```\n${item-link:11111111-2222-3333-4444-555555555555}\n```',  'inside code fence (still replaced — documented behavior)']
+];
+for (const [input, label] of cases) {
+  console.log(label + ':', input.replace(re, (_m, u) => '<TAG itemId=' + u + '>'));
+}
+```
+
+Run it:
+```bash
+node /tmp/check-item-link-regex.js
+```
+
+Expected output:
+```
+valid: <TAG itemId=11111111-2222-3333-4444-555555555555>
+invalid: ${item-link:not-a-uuid}
+two valid: Two: <TAG itemId=11111111-2222-3333-4444-555555555555> and <TAG itemId=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee>
+inside code fence (still replaced — documented behavior): ```
+<TAG itemId=11111111-2222-3333-4444-555555555555>
+```
+```
+
+Then delete the script: `rm /tmp/check-item-link-regex.js`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-markdown.utils.ts
+git commit -m "feat(iot-hub): add item-link placeholder utility for markdown"
+```
+
+---
+
+## Task 2: Create item-link card component (skeleton + loaded states, image-thumbnail items)
+
+**Files:**
+- Create: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-link-card/iot-hub-item-link-card.component.ts`
+- Create: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-link-card/iot-hub-item-link-card.component.html`
+- Create: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-link-card/iot-hub-item-link-card.component.scss`
+
+- [ ] **Step 1: Create the directory**
+
+```bash
+mkdir -p ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-link-card
+```
+
+- [ ] **Step 2: Create `iot-hub-item-link-card.component.ts`**
+
+```typescript
+///
+/// Copyright © 2016-2026 The Thingsboard Authors
+///
+/// Licensed under the Apache License, Version 2.0 (the "License");
+/// you may not use this file except in compliance with the License.
+/// You may obtain a copy of the License at
+///
+///     http://www.apache.org/licenses/LICENSE-2.0
+///
+/// Unless required by applicable law or agreed to in writing, software
+/// distributed under the License is distributed on an "AS IS" BASIS,
+/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+/// See the License for the specific language governing permissions and
+/// limitations under the License.
+///
+
+import { Component, Input, OnInit } from '@angular/core';
+import { IotHubApiService } from '@core/http/iot-hub-api.service';
+import { MpItemVersionView } from '@shared/models/iot-hub/iot-hub-version.models';
+import { ItemType } from '@shared/models/iot-hub/iot-hub-item.models';
+
+type CardState = 'loading' | 'loaded' | 'unavailable';
+
+const COMPACT_TYPES: ReadonlySet<ItemType> = new Set([
+  ItemType.CALCULATED_FIELD,
+  ItemType.ALARM_RULE,
+  ItemType.RULE_CHAIN
+]);
+
+@Component({
+  selector: 'tb-iot-hub-item-link-card',
+  standalone: false,
+  templateUrl: './iot-hub-item-link-card.component.html',
+  styleUrls: ['./iot-hub-item-link-card.component.scss']
+})
+export class TbIotHubItemLinkCardComponent implements OnInit {
+
+  @Input() itemId!: string;
+
+  state: CardState = 'loading';
+  item: MpItemVersionView | null = null;
+
+  constructor(private iotHubApiService: IotHubApiService) {}
+
+  ngOnInit(): void {
+    if (!this.itemId) {
+      this.state = 'unavailable';
+      return;
+    }
+    this.iotHubApiService
+      .getPublishedVersion(this.itemId, { ignoreErrors: true, ignoreLoading: true })
+      .subscribe({
+        next: item => {
+          this.item = item;
+          this.state = item ? 'loaded' : 'unavailable';
+        },
+        error: () => {
+          this.state = 'unavailable';
+        }
+      });
+  }
+
+  isCompact(): boolean {
+    return !!this.item && COMPACT_TYPES.has(this.item.type);
+  }
+
+  getImageUrl(): string | null {
+    return this.item?.image
+      ? this.iotHubApiService.resolveResourceUrl(this.item.image)
+      : null;
+  }
+
+  getCompactIcon(): string {
+    if (!this.item) {
+      return 'category';
+    }
+    if (this.item.icon) {
+      return this.item.icon;
+    }
+    switch (this.item.type) {
+      case ItemType.CALCULATED_FIELD: return 'functions';
+      case ItemType.ALARM_RULE: return 'notification_important';
+      case ItemType.RULE_CHAIN: return 'account_tree';
+      default: return 'category';
+    }
+  }
+
+  getTypeIcon(): string {
+    if (!this.item) {
+      return 'category';
+    }
+    switch (this.item.type) {
+      case ItemType.WIDGET: return 'widgets';
+      case ItemType.DASHBOARD: return 'dashboard';
+      case ItemType.SOLUTION_TEMPLATE: return 'integration_instructions';
+      case ItemType.CALCULATED_FIELD: return 'functions';
+      case ItemType.ALARM_RULE: return 'notification_important';
+      case ItemType.RULE_CHAIN: return 'account_tree';
+      case ItemType.DEVICE: return 'memory';
+      default: return 'category';
+    }
+  }
+
+  getCompactColor(): string {
+    return this.item?.color || '#048ad3';
+  }
+
+  getHref(): string {
+    return `/iot-hub/${this.itemId}`;
+  }
+}
+```
+
+- [ ] **Step 3: Create `iot-hub-item-link-card.component.html`**
+
+```html
+<!--
+
+    Copyright © 2016-2026 The Thingsboard Authors
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+-->
+@switch (state) {
+  @case ('loading') {
+    <div class="tb-iot-hub-item-link-card tb-iot-hub-item-link-card--skeleton" aria-busy="true">
+      <div class="tb-iot-hub-item-link-thumb tb-iot-hub-item-link-skeleton-block"></div>
+      <div class="tb-iot-hub-item-link-text">
+        <span class="tb-iot-hub-item-link-skeleton-line"></span>
+        <span class="tb-iot-hub-item-link-skeleton-line tb-iot-hub-item-link-skeleton-line--short"></span>
+      </div>
+    </div>
+  }
+  @case ('loaded') {
+    <a [href]="getHref()"
+       target="_blank"
+       rel="noopener noreferrer"
+       class="tb-iot-hub-item-link-card">
+      @if (isCompact()) {
+        <div class="tb-iot-hub-item-link-thumb tb-iot-hub-item-link-thumb--compact"
+             [style.background]="getCompactColor()">
+          <tb-icon class="tb-iot-hub-item-link-thumb-icon">{{ getCompactIcon() }}</tb-icon>
+        </div>
+      } @else {
+        <div class="tb-iot-hub-item-link-thumb">
+          @if (getImageUrl(); as imgUrl) {
+            <img [src]="imgUrl" alt="">
+          } @else {
+            <mat-icon class="tb-iot-hub-item-link-thumb-fallback">{{ getTypeIcon() }}</mat-icon>
+          }
+        </div>
+      }
+      <div class="tb-iot-hub-item-link-text">
+        <span class="tb-iot-hub-item-link-name">{{ item?.name }}</span>
+        <span class="tb-iot-hub-item-link-author">
+          <mat-icon>person</mat-icon>
+          {{ item?.creatorDisplayName }}
+        </span>
+      </div>
+    </a>
+  }
+  @case ('unavailable') {
+    <div class="tb-iot-hub-item-link-card tb-iot-hub-item-link-card--unavailable">
+      <div class="tb-iot-hub-item-link-thumb tb-iot-hub-item-link-thumb--unavailable">
+        <mat-icon>link_off</mat-icon>
+      </div>
+      <div class="tb-iot-hub-item-link-text">
+        <span class="tb-iot-hub-item-link-name">{{ 'iot-hub.item-link-unavailable' | translate }}</span>
+      </div>
+    </div>
+  }
+}
+```
+
+- [ ] **Step 4: Create `iot-hub-item-link-card.component.scss`**
+
+```scss
+/**
+ * Copyright © 2016-2026 The Thingsboard Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+:host {
+  display: block;
+  margin: 12px 0;
+}
+
+.tb-iot-hub-item-link-card {
+  display: inline-flex;
+  align-items: center;
+  gap: 12px;
+  width: 320px;
+  max-width: 100%;
+  padding: 8px 12px;
+  border: 1px solid rgba(0, 0, 0, 0.08);
+  border-radius: 8px;
+  background: #fff;
+  text-decoration: none;
+  color: inherit;
+  transition: background-color 120ms ease, border-color 120ms ease, box-shadow 120ms ease;
+
+  &:hover:not(.tb-iot-hub-item-link-card--unavailable):not(.tb-iot-hub-item-link-card--skeleton) {
+    background: rgba(4, 138, 211, 0.04);
+    border-color: rgba(4, 138, 211, 0.32);
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.06);
+  }
+
+  &--unavailable {
+    opacity: 0.6;
+    cursor: default;
+  }
+
+  &--skeleton {
+    cursor: default;
+  }
+}
+
+.tb-iot-hub-item-link-thumb {
+  flex: 0 0 48px;
+  width: 48px;
+  height: 48px;
+  border-radius: 6px;
+  background: #f4f6f8;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+
+  img {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    display: block;
+  }
+
+  &--compact {
+    color: #fff;
+  }
+
+  &--unavailable {
+    color: rgba(0, 0, 0, 0.45);
+  }
+}
+
+.tb-iot-hub-item-link-thumb-icon {
+  font-size: 26px;
+  width: 26px;
+  height: 26px;
+  line-height: 26px;
+  color: #fff;
+}
+
+.tb-iot-hub-item-link-thumb-fallback {
+  font-size: 26px;
+  width: 26px;
+  height: 26px;
+  color: rgba(0, 0, 0, 0.45);
+}
+
+.tb-iot-hub-item-link-text {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  gap: 2px;
+}
+
+.tb-iot-hub-item-link-name {
+  font-size: 14px;
+  font-weight: 500;
+  line-height: 1.3;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.tb-iot-hub-item-link-author {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 12px;
+  color: rgba(0, 0, 0, 0.6);
+  line-height: 1.3;
+
+  mat-icon {
+    font-size: 14px;
+    width: 14px;
+    height: 14px;
+  }
+}
+
+.tb-iot-hub-item-link-skeleton-block,
+.tb-iot-hub-item-link-skeleton-line {
+  background: linear-gradient(
+    90deg,
+    rgba(0, 0, 0, 0.06) 0%,
+    rgba(0, 0, 0, 0.12) 50%,
+    rgba(0, 0, 0, 0.06) 100%
+  );
+  background-size: 200% 100%;
+  animation: tb-iot-hub-item-link-shimmer 1.4s ease-in-out infinite;
+  border-radius: 4px;
+}
+
+.tb-iot-hub-item-link-skeleton-line {
+  display: block;
+  height: 12px;
+  width: 180px;
+  margin: 4px 0;
+
+  &--short {
+    width: 96px;
+  }
+}
+
+@keyframes tb-iot-hub-item-link-shimmer {
+  0%   { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-link-card
+git commit -m "feat(iot-hub): add TbIotHubItemLinkCardComponent for markdown item links"
+```
+
+---
+
+## Task 3: Create the wrapper module and register it
+
+**Files:**
+- Create: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-link-card/iot-hub-item-link.module.ts`
+- Modify: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-components.module.ts`
+
+- [ ] **Step 1: Create `iot-hub-item-link.module.ts`**
+
+```typescript
+///
+/// Copyright © 2016-2026 The Thingsboard Authors
+///
+/// Licensed under the Apache License, Version 2.0 (the "License");
+/// you may not use this file except in compliance with the License.
+/// You may obtain a copy of the License at
+///
+///     http://www.apache.org/licenses/LICENSE-2.0
+///
+/// Unless required by applicable law or agreed to in writing, software
+/// distributed under the License is distributed on an "AS IS" BASIS,
+/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+/// See the License for the specific language governing permissions and
+/// limitations under the License.
+///
+
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { SharedModule } from '@shared/shared.module';
+import { TbIotHubItemLinkCardComponent } from './iot-hub-item-link-card.component';
+
+@NgModule({
+  declarations: [TbIotHubItemLinkCardComponent],
+  imports: [CommonModule, SharedModule],
+  exports: [TbIotHubItemLinkCardComponent]
+})
+export class IotHubItemLinkModule {}
+```
+
+- [ ] **Step 2: Register module in `IotHubComponentsModule`**
+
+Modify `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-components.module.ts` — add the import and add `IotHubItemLinkModule` to the `imports` array.
+
+After the existing imports near line 32, add:
+
+```typescript
+import { IotHubItemLinkModule } from './iot-hub-item-link-card/iot-hub-item-link.module';
+```
+
+Then update the `imports` array of the `@NgModule` decorator from:
+
+```typescript
+  imports: [
+    CommonModule,
+    SharedModule
+  ],
+```
+
+to:
+
+```typescript
+  imports: [
+    CommonModule,
+    SharedModule,
+    IotHubItemLinkModule
+  ],
+```
+
+- [ ] **Step 3: Build to verify the module wires up**
+
+```bash
+cd ui-ngx && npx ng build --configuration=development 2>&1 | tail -40
+```
+
+Expected: build succeeds (warnings allowed; no errors mentioning `TbIotHubItemLinkCardComponent` or `IotHubItemLinkModule`).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-link-card/iot-hub-item-link.module.ts \
+        ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-components.module.ts
+git commit -m "feat(iot-hub): wrap item-link card in IotHubItemLinkModule"
+```
+
+---
+
+## Task 4: Add translation key
+
+**Files:**
+- Modify: `ui-ngx/src/assets/locale/locale.constant-en_US.json`
+
+- [ ] **Step 1: Add the translation key**
+
+Open `ui-ngx/src/assets/locale/locale.constant-en_US.json`. Locate the `"iot-hub": { ... }` block that begins around line 3701 (the one that opens with `"iot-hub": "IoT Hub",`). Add a new entry next to similar one-liner keys (e.g., right after `"installed-from-iot-hub": "Installed from IoT Hub",` near line 3719):
+
+```json
+        "item-link-unavailable": "Item unavailable",
+```
+
+Make sure the surrounding commas are correct — the new line ends with a comma, and the line above also ends with a comma.
+
+- [ ] **Step 2: Verify JSON is valid**
+
+```bash
+node -e "JSON.parse(require('fs').readFileSync('ui-ngx/src/assets/locale/locale.constant-en_US.json', 'utf8')); console.log('OK');"
+```
+Expected output: `OK`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add ui-ngx/src/assets/locale/locale.constant-en_US.json
+git commit -m "feat(iot-hub): add item-link-unavailable translation key"
+```
+
+---
+
+## Task 5: Wire into item detail dialog (readme)
+
+**Files:**
+- Modify: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.ts`
+- Modify: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.html`
+
+- [ ] **Step 1: Update the .ts file to pre-process readme and expose compile modules**
+
+In `iot-hub-item-detail-dialog.component.ts`:
+
+Add to the imports near the existing `resolveDocLinkPlaceholders` import:
+
+```typescript
+import { replaceItemLinkPlaceholders } from './iot-hub-markdown.utils';
+import { IotHubItemLinkModule } from './iot-hub-item-link-card/iot-hub-item-link.module';
+import { Type } from '@angular/core';
+```
+
+(`Type` may already be imported via Angular core; merge into the existing `@angular/core` import if so.)
+
+Inside the class, near the other readonly fields (after `readonly ItemType = ItemType;`), add:
+
+```typescript
+  readonly itemLinkCompileModules: Type<any>[] = [IotHubItemLinkModule];
+```
+
+Update the existing `loadReadme()` method body (currently at line 307-312):
+
+```typescript
+  private loadReadme(): void {
+    const versionId = this.item.id as string;
+    this.iotHubApiService.getVersionReadme(versionId, { ignoreLoading: true }).subscribe(
+      content => this.readmeContent = replaceItemLinkPlaceholders(
+        this.resolveDocLinks(this.prefixResourceUrls(content || ''))
+      )
+    );
+  }
+```
+
+- [ ] **Step 2: Update the template to pass compile modules**
+
+In `iot-hub-item-detail-dialog.component.html` at line 302, change:
+
+```html
+          <tb-markdown [data]="readmeContent"></tb-markdown>
+```
+
+to:
+
+```html
+          <tb-markdown [data]="readmeContent"
+                       [additionalCompileModules]="itemLinkCompileModules"></tb-markdown>
+```
+
+Leave the changelog `<tb-markdown>` (line 306) unchanged — changelog is out of scope per the spec.
+
+- [ ] **Step 3: Build**
+
+```bash
+cd ui-ngx && npx ng build --configuration=development 2>&1 | tail -20
+```
+
+Expected: build succeeds.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.ts \
+        ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.html
+git commit -m "feat(iot-hub): render \${item-link} cards in item readme"
+```
+
+---
+
+## Task 6: Wire into device install dialog (instructions)
+
+**Files:**
+- Modify: `ui-ngx/src/app/modules/home/components/iot-hub/device-install-dialog/device-install-dialog.component.ts`
+- Modify: `ui-ngx/src/app/modules/home/components/iot-hub/device-install-dialog/device-install-dialog.component.html`
+
+- [ ] **Step 1: Add imports and compile-modules field**
+
+In `device-install-dialog.component.ts`, add to the imports:
+
+```typescript
+import { IotHubItemLinkModule } from '../iot-hub-item-link-card/iot-hub-item-link.module';
+import { ITEM_LINK_KEY_REGEX, itemLinkCardTag } from '../iot-hub-markdown.utils';
+import { Type } from '@angular/core';
+```
+
+(Merge `Type` into the existing `@angular/core` import line.)
+
+Inside the class, alongside other readonly fields, add:
+
+```typescript
+  readonly itemLinkCompileModules: Type<any>[] = [IotHubItemLinkModule];
+```
+
+- [ ] **Step 2: Add `^item-link:(uuid)$` branch inside `resolveVariables`**
+
+In `resolveVariables()` (currently at line 427-477 in the same file), add a new clause **immediately after** the `gateway.downloadButton` clause (around line 444-446) and before the callout matcher.
+
+Change this section:
+
+```typescript
+      // Special action placeholders
+      if (key === 'gateway.downloadButton') {
+        return '<a href="#" data-action="download-gateway-docker-compose" class="tb-download-btn">⬇ Download docker-compose.yml</a>';
+      }
+      // Callout boxes: ${note(...)}, ${warn(...)}, ${error(...)}
+```
+
+to:
+
+```typescript
+      // Special action placeholders
+      if (key === 'gateway.downloadButton') {
+        return '<a href="#" data-action="download-gateway-docker-compose" class="tb-download-btn">⬇ Download docker-compose.yml</a>';
+      }
+      // IoT Hub item link card: ${item-link:<uuid>}
+      const itemLinkMatch = key.match(ITEM_LINK_KEY_REGEX);
+      if (itemLinkMatch) {
+        return itemLinkCardTag(itemLinkMatch[1]);
+      }
+      // Callout boxes: ${note(...)}, ${warn(...)}, ${error(...)}
+```
+
+- [ ] **Step 3: Update the template**
+
+In `device-install-dialog.component.html` at line 26-28, change:
+
+```html
+          <tb-markdown [data]="ws.markdown"
+                       (ready)="onMarkdownReady(instructionContainer)">
+          </tb-markdown>
+```
+
+to:
+
+```html
+          <tb-markdown [data]="ws.markdown"
+                       [additionalCompileModules]="itemLinkCompileModules"
+                       (ready)="onMarkdownReady(instructionContainer)">
+          </tb-markdown>
+```
+
+- [ ] **Step 4: Build**
+
+```bash
+cd ui-ngx && npx ng build --configuration=development 2>&1 | tail -20
+```
+
+Expected: build succeeds.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add ui-ngx/src/app/modules/home/components/iot-hub/device-install-dialog/device-install-dialog.component.ts \
+        ui-ngx/src/app/modules/home/components/iot-hub/device-install-dialog/device-install-dialog.component.html
+git commit -m "feat(iot-hub): render \${item-link} cards in device install instructions"
+```
+
+---
+
+## Task 7: Wire into solution install dialog (instructions)
+
+**Files:**
+- Modify: `ui-ngx/src/app/modules/home/components/solution/solution-install-dialog.component.ts`
+- Modify: `ui-ngx/src/app/modules/home/components/solution/solution-install-dialog.component.html`
+
+- [ ] **Step 1: Update the .ts file**
+
+Replace the contents of `ui-ngx/src/app/modules/home/components/solution/solution-install-dialog.component.ts` with:
+
+```typescript
+///
+/// Copyright © 2016-2026 The Thingsboard Authors
+///
+/// Licensed under the Apache License, Version 2.0 (the "License");
+/// you may not use this file except in compliance with the License.
+/// You may obtain a copy of the License at
+///
+///     http://www.apache.org/licenses/LICENSE-2.0
+///
+/// Unless required by applicable law or agreed to in writing, software
+/// distributed under the License is distributed on an "AS IS" BASIS,
+/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+/// See the License for the specific language governing permissions and
+/// limitations under the License.
+///
+
+import { Component, Inject, Type } from '@angular/core';
+import { MAT_DIALOG_DATA, MatDialogRef } from '@angular/material/dialog';
+import { Router } from '@angular/router';
+import { SolutionTemplateInstalledItemDescriptor } from '@shared/models/iot-hub/iot-hub-installed-item.models';
+import {
+  IotHubItemLinkModule
+} from '@home/components/iot-hub/iot-hub-item-link-card/iot-hub-item-link.module';
+import {
+  replaceItemLinkPlaceholders
+} from '@home/components/iot-hub/iot-hub-markdown.utils';
+
+export interface SolutionInstallDialogData {
+  descriptor: SolutionTemplateInstalledItemDescriptor;
+  instructions?: boolean;
+}
+
+@Component({
+  selector: 'tb-solution-install-dialog',
+  templateUrl: './solution-install-dialog.component.html',
+  styleUrls: ['./solution-install-dialog.component.scss'],
+  standalone: false
+})
+export class SolutionInstallDialogComponent {
+
+  details: string;
+  dashboardId: string | null;
+  instructions: boolean;
+
+  readonly itemLinkCompileModules: Type<any>[] = [IotHubItemLinkModule];
+
+  constructor(
+    @Inject(MAT_DIALOG_DATA) public data: SolutionInstallDialogData,
+    private dialogRef: MatDialogRef<SolutionInstallDialogComponent>,
+    private router: Router
+  ) {
+    this.details = replaceItemLinkPlaceholders(data.descriptor.details || '');
+    this.dashboardId = data.descriptor.dashboardId?.id || null;
+    this.instructions = !!data.instructions;
+  }
+
+  gotoMainDashboard(): void {
+    if (this.dashboardId) {
+      this.dialogRef.close();
+      this.router.navigateByUrl(`/dashboards/${this.dashboardId}`);
+    }
+  }
+
+  close(): void {
+    this.dialogRef.close();
+  }
+}
+```
+
+- [ ] **Step 2: Update the template**
+
+In `solution-install-dialog.component.html` at line 29, change:
+
+```html
+    <tb-markdown [data]="details" lineNumbers fallbackToPlainMarkdown></tb-markdown>
+```
+
+to:
+
+```html
+    <tb-markdown [data]="details"
+                 [additionalCompileModules]="itemLinkCompileModules"
+                 lineNumbers
+                 fallbackToPlainMarkdown></tb-markdown>
+```
+
+- [ ] **Step 3: Build**
+
+```bash
+cd ui-ngx && npx ng build --configuration=development 2>&1 | tail -20
+```
+
+Expected: build succeeds.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add ui-ngx/src/app/modules/home/components/solution/solution-install-dialog.component.ts \
+        ui-ngx/src/app/modules/home/components/solution/solution-install-dialog.component.html
+git commit -m "feat(iot-hub): render \${item-link} cards in solution install instructions"
+```
+
+---
+
+## Task 8: Manual visual QA
+
+**No file changes — verify the feature end-to-end in a browser.**
+
+- [ ] **Step 1: Start the dev server**
+
+```bash
+cd ui-ngx && npm start
+```
+
+Wait for `Compiled successfully` and `Application bundle generation complete`.
+
+Open `http://localhost:4200` in a browser and log in as a tenant administrator.
+
+- [ ] **Step 2: Verify item readme rendering**
+
+In a separate terminal, query the configured IoT Hub for an item ID you can use as a test target:
+
+```bash
+# Use the same baseUrl that your TB instance uses (typically https://iot-hub.thingsboard.io).
+# Pick any published item you can find via the marketplace UI's network requests in DevTools,
+# e.g. by opening the IoT Hub home page and copying an itemId from a response.
+echo "Pick a known itemId from network responses in the IoT Hub UI"
+```
+
+Then, for the TEST PASS:
+1. Open IoT Hub in the running app, find an item with a non-empty readme (e.g., a Solution Template), open the detail dialog.
+2. In DevTools, intercept the readme response by editing it (Network → block + replay, or temporarily edit `readmeContent` via the Angular DevTools), and inject `${item-link:<knownItemId>}` somewhere in the readme markdown.
+   - Easier alternative: temporarily hardcode a test placeholder in `loadReadme()` by appending `'\n\n${item-link:<knownItemId>}\n'` to the fetched content, just for this QA pass. Revert before committing.
+3. Reload the dialog. Expected:
+   - Skeleton card appears briefly with shimmer.
+   - Card resolves to: 48-px square thumbnail (image or colored compact icon), item name, person icon + creator name.
+   - Hover shows light blue tint and subtle shadow.
+   - Click opens `/iot-hub/<itemId>` in a **new tab**, which lands on the item type page with the detail dialog open.
+   - Middle-click also opens new tab; ctrl-click does the same.
+
+Revert any hardcoded test data before continuing.
+
+- [ ] **Step 3: Verify unavailable state**
+
+Repeat Step 2 but inject a placeholder with a UUID that does not exist (e.g., `${item-link:00000000-0000-0000-0000-000000000000}`). Expected:
+- Card briefly shows skeleton.
+- Resolves to disabled card: dim opacity, `link_off` icon in the thumbnail slot, "Item unavailable" label.
+- Card is not clickable (no `<a>`, no hover blue).
+
+- [ ] **Step 4: Verify invalid placeholder is left untouched**
+
+Inject `${item-link:not-a-uuid}` into the readme. Expected: the rendered markdown shows the literal text `${item-link:not-a-uuid}` (no card, no error). This proves the regex is strict.
+
+- [ ] **Step 5: Verify device install instructions**
+
+Open any IoT Hub Device item, click Install, and walk to a step whose markdown is dynamically rendered. Inject `${item-link:<knownItemId>}` into one of the markdown templates served by the device package (or temporarily prepend it to `step.markdown` in `device-install-dialog.component.ts` near the existing `resolveVariables` call). Expected: same skeleton → loaded card behavior; click opens `/iot-hub/<itemId>` in a new tab.
+
+Revert temporary edits.
+
+- [ ] **Step 6: Verify solution install instructions**
+
+Install (or reopen the install instructions for) a Solution Template that has a `details` markdown. Inject `${item-link:<knownItemId>}` into `details` (temporarily, in the constructor or via a known solution template whose details you control). Expected: same skeleton → loaded behavior; click opens `/iot-hub/<itemId>` in a new tab.
+
+Revert temporary edits.
+
+- [ ] **Step 7: Confirm no regressions in existing markdown**
+
+In each of the three render sites, verify after the QA edits are reverted:
+- Existing `${gateway.downloadButton}` placeholder still renders correctly in the device install instructions (unchanged behavior).
+- Existing callout boxes (`${note(...)}`, `${warn(...)}`, `${error(...)}`) still render in the device install instructions.
+- Existing `prefixResourceUrls` and `resolveDocLinks` continue to resolve image URLs and doc-link placeholders in readmes.
+- Changelog tab in the item detail dialog still renders without an item-link card (it does not bind `additionalCompileModules`).
+
+- [ ] **Step 8: Stop the dev server**
+
+`Ctrl-C` in the terminal running `npm start`.
+
+- [ ] **Step 9: Final commit (if any QA-driven fix-ups were made)**
+
+If QA surfaced any issues that required code changes, commit them with a focused message. Otherwise this step is a no-op.
+
+```bash
+git status
+# If clean, no commit needed.
+```
+
+---
+
+## Self-review checklist (for the implementing agent)
+
+Before declaring complete, verify:
+
+1. **Spec coverage** — every decision in `docs/superpowers/specs/2026-05-06-iot-hub-item-link.md` has a corresponding task above.
+2. **No leftover test scaffolding** — temporary hardcoded `${item-link:...}` placeholders used for QA are reverted.
+3. **License headers** — every new `.ts` file uses `///` style, every new `.html` uses `<!-- -->`, every new `.scss` uses `/** */`.
+4. **Build clean** — `npx ng build --configuration=development` finishes without errors.
+5. **Three sites work, fourth doesn't** — readme, device install, solution install all render the card; changelog tab does **not** (by design — out of scope per spec).