AI Assistant. Updated doc

src/content/_includes/docs/user-guide/ai-assistant.mdx

@@ -1,12 +1,152 @@
-import { Aside } from '@astrojs/starlight/components';
 import DocLink from '@components/DocLink.astro';
 import Banner from '~/components/Banner.astro';
+import ImageGallery from '~/components/ImageGallery.astro';
 import { Products } from '~/models/site.models';
+import { Steps, Aside } from '@astrojs/starlight/components';
 
 <Banner variant="peFeature" product={props.product}>AI Assistant is available in <DocLink product={Products.PE} path="user-guide/ai-assistant" target="_blank">ThingsBoard Professional</DocLink> and <a href="/installations/?product=thingsboard-cloud" target="_blank" rel="noopener noreferrer" class="tb-banner-ext"><b>ThingsBoard Cloud</b></a> only.</Banner>
 
-The **AI Assistant** is built into the ThingsBoard UI. It edits **calculated fields** and **alarm rules** in natural language, and generates ready-to-use **dashboards** for any device or asset in one click.
+{props.product === Products.PE && (
+  <Banner variant="pe">Available from ThingsBoard PE <strong>4.3.1.2</strong> and later.</Banner>
+)}
+
+The AI Assistant is a built-in assistant that lets you configure Alarm Rules and Calculated Fields by describing what you want in plain language — no ThingsBoard expertise required. It knows the platform, sees your data, and proposes every change for your approval before applying it.
+
+AI Assistant is currently integrated into two sections:
+- <DocLink product={props.product} path="user-guide/alarm-rules" target="_blank">Alarm Rules</DocLink> — rules that monitor telemetry and attributes, and trigger alarms when configured conditions are met.
+- <DocLink product={props.product} path="user-guide/calculated-fields" target="_blank">Calculated Fields</DocLink> — real-time computations on telemetry and attributes that produce new data keys.
 
 <Aside type="note">
-  See <DocLink product={props.product} path='user-guide/cli' target="_blank">ThingsBoard CLI</DocLink> and <DocLink product={props.product} path='user-guide/ai-solution-creator' target="_blank">AI Solution Creator</DocLink> for related AI-driven workflows.
+  AI Assistant is available to **Tenant Administrators only**. 
+  Customer-level users do not have access to this feature.
 </Aside>
+
+## How to Start
+
+<Steps>
+  1. Go to **Alarms &#8702; Alarm rules** (or **Calculated fields**).
+  2. Click the **Configure with AI** button in the upper right corner.
+  3. The AI Assistant panel opens on the right, alongside your configuration.
+  4. Start typing. Conversations are saved automatically — use the chat menu to rename, switch, or delete them.
+</Steps>
+
+<ImageGallery images={[
+  {
+    src: '/src/assets/images/user-guide/ai-assistant/ai-assistant-with-calculated-fields-1.png',
+    alt: 'Opening AI Assistant from the Calculated fields page',
+    caption: 'Click <strong>Configure with AI</strong> on the Calculated fields page to open the AI Assistant and create or manage calculated fields using natural language.',
+  },
+  {
+    src: '/src/assets/images/user-guide/ai-assistant/ai-assistant-with-calculated-fields-2.png',
+    alt: 'AI Assistant panel on the Calculated fields page',
+    caption: 'The AI Assistant opens in a side panel where you can describe the calculated field you want to create and receive AI-generated configuration suggestions.',
+  },
+]} />
+
+## How the Assistant Works
+
+### Context Awareness
+
+The Assistant has access to your tenant data — devices, assets, profiles, customers, telemetry keys, and entity relations. This means you can describe what you want in natural terms and the Assistant figures out the rest:
+
+- Say _"my pumps"_ instead of listing device IDs.
+- Reference a building, floor, or zone — the Assistant traces the relations automatically.
+- If something is missing (a relation, a data key), it tells you what to set up before proceeding.
+
+### Approval Before Changes
+
+The Assistant never modifies your tenant without your confirmation. Before applying any change — creating, updating, or deleting a Calculated Field or Alarm Rule, or recalculating historical data — it shows an approval card in the chat that describes exactly what will be done and to which entity. No change is applied until you click **Approve**.
+
+If a proposal isn't quite right, click **Deny** and say what to change.
+
+## Using the Assistant
+
+The Assistant performs different types of tasks. You can freely combine them in the same chat.
+
+### Ask Questions
+
+Not sure how to implement what you have in mind? Or don't understand why something isn't working? Just ask. The Assistant knows Calculated Fields and Alarm Rules inside out and can see your actual devices, profiles, and data — so questions can be about the platform in general or your specific setup:
+
+> _"I want to know when one pump is drawing more power than the others on the same line — can ThingsBoard detect that, and how?"_
+
+> _"The High Temperature alarm on my Chiller profile never triggers, even though the temperature clearly goes above the threshold — what's wrong?"_
+
+### Create and Manage Configurations
+
+Describe what you want to end up with, and the Assistant creates it — Calculated Fields, Alarm Rules, or both, including any <DocLink product={props.product} path="user-guide/tbel" target="_blank">TBEL</DocLink> scripts. No need to pick field types, condition modes, or write logic yourself.
+
+> _"On each floor's meter I collect raw water-flow readings. Derive hourly and daily consumption per floor, roll them up into a building-wide total, and raise a warning alarm on any floor whose daily use runs more than 50% above its weekly average."_
+
+The same approach works for changes and deletions:
+
+> _"We're switching the energy meters from kWh to MWh. Update the consumption calculated fields to the new unit, and adjust every alarm rule whose threshold depends on them so the limits still mean the same thing."_
+
+## How to Get the Best Results
+
+The Assistant asks clarifying questions when something is unclear, so vague requests still work. That said, a well-formed request gets to the result faster. A few things that help:
+
+**Name the entity clearly.** The Assistant can find entities from partial clues — a name, type, profile, or location. The more specific you are, the fewer back-and-forth questions you'll get.
+
+> Instead of: _"Create a temperature alarm."_
+>
+> Try: _"Create a temperature alarm for the Cold Storage device profile."_
+
+**Describe the goal, not the steps.** Focus on what you want to achieve — not how to build it. The Assistant picks the right approach on its own.
+
+> Instead of: _"Create a calculated field on each tank that divides the level key by the maxLevel attribute and multiplies by 100."_
+>
+> Try: _"I want to know how full each storage tank is as a percentage, not just its raw level reading."_
+
+**Include the numbers.** Thresholds, units, time windows, and severities are the only details the Assistant cannot infer. Providing them upfront skips a round of clarifying questions.
+
+> Instead of: _"Alert me when the freezer gets too warm."_
+>
+> Try: _"Raise a critical alarm when freezer temperature stays above -15 °C for more than 10 minutes; clear it below -18 °C."_
+
+**Stay in the same chat.** The Assistant remembers everything from the current conversation — entities, choices, context. Follow-ups can be short: _"Do the same for the Warehouse profile"_ or _"Lower that threshold to 80"_. Start a new chat only for a completely unrelated task.
+
+## Scope and Limitations
+
+The Assistant configures **Alarm Rules** and **Calculated Fields** only. Everything else — Dashboards, Device Profiles, Relations, Rule Chains — remains outside its scope. If your request depends on something missing (a relation, a profile), the Assistant tells you what to set up manually and continues from there.
+
+**Raised alarms are read-only:** the Assistant can find and inspect them, but acknowledging, clearing, and assigning alarms remain manual actions.
+
+## AI Credits
+
+Each request to the Assistant consumes AI credits — the amount varies by complexity.
+
+{(props.product === Products.CE || props.product === Products.PE) && (
+  <>
+    <p>To check your usage and available credits, go to <strong>API Usage</strong> in your ThingsBoard instance and find the <strong>AI credits</strong> row. The page also shows your hourly, daily, and monthly activity charts.</p>
+    <p>The number of available AI credits is defined by your subscription plan and may be further limited by your system administrator in the <DocLink product={props.product} path="user-guide/tenant-profiles/" target="_blank">Tenant Profile</DocLink>.</p>
+    <ImageGallery images={[
+      {
+        src: '/src/assets/images/user-guide/ai-assistant/api-usage-ai-credits.png',
+        alt: 'API Usage page showing the AI credits row',
+        caption: 'Track AI credits on the API Usage page — view current usage, limit, and hourly, daily, and monthly activity charts.',
+      },
+    ]} />
+  </>
+)}
+
+{(props.product === Products.PAAS || props.product === Products.PAAS_EU) && (
+  <>
+    <p>To check your balance, click the <strong>AI Credits</strong> indicator in the Assistant panel. The pop-up shows your usage, monthly limit, and reset date:</p>
+    <blockquote><p><em>"You've used 9.8K of your 4M AI Credits this month. Limit resets on Jun 29, 2026."</em></p></blockquote>
+    <p>If your credits are exhausted, click <strong>Update</strong> to upgrade your plan.</p>
+    <p>For a full breakdown of limits per plan, see <DocLink product={props.product} path="reference/subscriptions/#api-limits-monthly" target="_blank">API Limits</DocLink>.</p>
+    <ImageGallery images={[
+      {
+        src: '/src/assets/images/user-guide/ai-assistant/ai-credits-1.png',
+        alt: 'AI Credits usage notification',
+        caption: 'The AI Credits dialog shows your current monthly usage, remaining quota, reset date, and an option to upgrade your subscription.',
+      },
+    ]} />
+  </>
+)}
+
+## Next Steps
+
+- <DocLink product={props.product} path="user-guide/calculated-fields" target="_blank">Calculated Fields</DocLink> and <DocLink product={props.product} path="user-guide/alarm-rules" target="_blank">Alarm Rules</DocLink> — explore the features the Assistant configures, and fine-tune them by hand when needed.
+- <DocLink product={props.product} path="user-guide/ai-solution-creator" target="_blank">AI Solution Creator</DocLink> — generate a complete IoT solution from a plain-language description: entities, Dashboards, Alarm Rules, and Calculated Fields in one go.
+- <DocLink product={props.product} path="user-guide/cli" target="_blank">ThingsBoard CLI</DocLink> — run AI-driven workflows from the command line, with full support for coding agents.

src/content/_includes/docs/user-guide/alarm-rules.mdx

@@ -8,8 +8,9 @@ import MultiProductImageGallery from '~/components/MultiProductImageGallery.astr
 
 Rules can be defined for <DocLink product={props.product} path="user-guide/devices" target="_blank">Devices</DocLink>, <DocLink product={props.product} path="user-guide/assets" target="_blank">Assets</DocLink>, their profiles, or <DocLink product={props.product} path="user-guide/customers" target="_blank">Customers</DocLink>. For an overview of alarm concepts, states, and severity levels, see <DocLink product={props.product} path="user-guide/alarms" target="_blank">Alarms</DocLink>.
 
-<Aside type="tip">
-  Create alarm rules in **Device profiles** or **Asset profiles** rather than on individual entities to avoid duplicating configurations.
+<Aside type="note">
+  Alarm rules can only be created and managed by **Tenant Administrators**.
+  Customer-level users do not have access.
 </Aside>
 
 ## How Alarm Rules Work
@@ -22,6 +23,10 @@ When a message arrives (telemetry update, attribute change, or inactivity event)
 
 The **Alarm rules** page lets you manage all alarm rules in the system — for individual entities and for profiles.
 
+<Aside type="tip">
+  Create alarm rules in **Device profiles** or **Asset profiles** rather than on individual entities to avoid duplicating configurations.
+</Aside>
+
 <Aside type="note">
   The process of creating an alarm rule is the same for Devices, Assets, Device profiles, Asset profiles, and Customers.
 </Aside>

src/content/_includes/docs/user-guide/tenant-profiles.mdx

@@ -1,5 +1,6 @@
 import DocLink from '@components/DocLink.astro';
 import { Steps, Aside } from '@astrojs/starlight/components';
+import { Products } from '~/models/site.models';
 
 A **Tenant profile** defines the resource limits, quotas, and operational behavior applied to tenants in ThingsBoard. It provides resource isolation across tenants, allowing System administrators to enforce fair resource usage, maintain predictable performance, and prevent overload in multi-tenant deployments.
 
@@ -91,6 +92,17 @@ These limits control the total number of processed messages and Rule Engine exec
 
 A value of `0` means unlimited.
 
+{props.product === Products.PE && (
+  <>
+    <h3 id="ai-limits">AI Limits</h3>
+    <p>Defines limits for AI credits:</p>
+    <ul>
+      <li>AI credits maximum number</li>
+    </ul>
+    <p>A value of <code>0</code> means unlimited.</p>
+  </>
+)}
+
 ### Calculated Fields Limits
 
 Defines limits for calculated fields:

src/content/docs/docs/paas/eu/user-guide/ai-assistant.mdx

@@ -1,6 +1,6 @@
 ---
 title: AI Assistant
-description: "Edit calculated fields, alarm rules, and dashboards in natural language with the in-platform AI Assistant."
+description: "Manage Calculated Fields and Alarm Rules in natural language with the in-platform AI Assistant."
 ---
 import PageComponent from '@includes/docs/user-guide/ai-assistant.mdx'
 import { Products } from '~/models/site.models'

src/content/docs/docs/paas/user-guide/ai-assistant.mdx

@@ -1,6 +1,6 @@
 ---
 title: AI Assistant
-description: "Edit calculated fields, alarm rules, and dashboards in natural language with the in-platform AI Assistant."
+description: "Manage Calculated Fields and Alarm Rules in natural language with the in-platform AI Assistant."
 ---
 import PageComponent from '@includes/docs/user-guide/ai-assistant.mdx'
 import { Products } from '~/models/site.models'

src/content/docs/docs/pe/user-guide/ai-assistant.mdx

@@ -1,6 +1,6 @@
 ---
 title: AI Assistant
-description: "Edit calculated fields, alarm rules, and dashboards in natural language with the in-platform AI Assistant."
+description: "Manage Calculated Fields and Alarm Rules in natural language with the in-platform AI Assistant."
 ---
 import PageComponent from '@includes/docs/user-guide/ai-assistant.mdx'
 import { Products } from '~/models/site.models'

src/content/docs/docs/user-guide/ai-assistant.mdx

@@ -1,6 +1,6 @@
 ---
 title: AI Assistant
-description: "Edit calculated fields, alarm rules, and dashboards in natural language with the in-platform AI Assistant."
+description: "Manage Calculated Fields and Alarm Rules in natural language with the in-platform AI Assistant."
 ---
 import PageComponent from '@includes/docs/user-guide/ai-assistant.mdx'
 import { Products } from '~/models/site.models'