docs: add Tago AI documentation section

docs/tagoio/analysis/console-for-debug.md

@@ -16,7 +16,7 @@ Use the console to monitor the variables and status of your script. You can see
 - Download Button: downloads the console output as a text file.
 
 :::tip
-The **TagoAI Assistant** can also be used to debug your script by asking about errors or unexpected behavior using the Analysis console.
+[Tago AI](/docs/tagoio/tago-ai/) can also help debug your script — ask about errors or unexpected behavior and it will use the Analysis console as context.
 :::
 
 ## How it works

docs/tagoio/analysis/script-editor.md

@@ -28,10 +28,12 @@ When you save the script, it will be deployed on TagoIO servers. You can then cl
 
 To learn more about our examples, you can visit our [Script Examples](/docs/tagoio/analysis/script-examples.md) article, or access the [Analysis](https://admin.tago.io/analysis), click on the "+ Add Analysis" button in the top right corner, and select a code example.
 
-## TagoAI Assistant
+## Tago AI Assistant
 
-The TagoAI Assistant helps you write, debug, and generate code for your Analysis scripts.
-You can open it by clicking the star-shaped TagoAI Assistant button in the top-right corner of the script editor.
+The Tago AI Assistant helps you write, debug, and generate code for your Analysis scripts.
+You can open it by clicking the star-shaped Tago AI button in the top-right corner of the script editor.
+
+For an overview of the assistant, available modes, and privacy controls, see [Tago AI](/docs/tagoio/tago-ai/).
 
 ![TagoAI Assistant](/docs_imagem/tagoio/rounded-image-1769103890139.png)
 

docs/tagoio/profiles/services/index.md

@@ -26,6 +26,7 @@ Currently, the following services are available for selection on your account. S
 | E-mail               |        Message | Monthly             | Messages sent out.                                                                          |
 | SMS                  |        Message | Monthly             | Messages sent out.                                                                          |
 | End user (RUN user)  |           User | Maximum at any time | End users registered in your RUN applications.                                              |
+| TagoAI Requests      |        Request | Monthly             | Each message sent to Tago AI using the TagoIO default provider.                             |
 
 ## Service Alerts
 

docs/tagoio/profiles/services/tago-ai-service.md

@@ -0,0 +1,27 @@
+---
+title: "Tago AI Service"
+description: "How TagoIO counts Tago AI requests, monthly limits per plan, and how using your own AI provider bypasses the limit."
+tags: ["tagoio"]
+keywords: [tagoio, iot, tago ai, ai requests, service limits]
+---
+
+Each message you send to [Tago AI](/docs/tagoio/tago-ai/) counts as one request. This limit defines the maximum number of requests a profile can make during a one-month period when using the TagoIO default AI provider. Unused requests in a billing cycle do not carry over to the next cycle.
+
+## Monthly limits
+
+| Plan    | Requests per month |
+| ------- | -----------------: |
+| Free    |                 40 |
+| Starter |                150 |
+| Scale   |                500 |
+
+## Using your own AI provider
+
+When a profile is configured with its own AI provider under **Profile Settings → Services → AI Provider**, Tago AI requests go through your provider account and are billed directly by that provider. The TagoIO monthly limits above do not apply in that case.
+
+See [Using your own AI provider](/docs/tagoio/tago-ai/ai-provider.md) for setup details.
+
+## Limits and warnings
+
+- If the monthly TagoAI request limit for a profile is exceeded, no further Tago AI requests will be processed from that profile until either the limit is increased or the billing period ends.
+- TagoIO sends warning notifications each time a service reaches 80%, 90%, and 100% of its limit.

docs/tagoio/tago-ai/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Tago AI",
+  "position": 11,
+  "collapsed": true
+}

docs/tagoio/tago-ai/ai-provider.md

@@ -0,0 +1,46 @@
+---
+title: "Using your own AI provider"
+description: "Configure your own AI provider for Tago AI at the profile level. Choose between OpenAI, Anthropic, AWS Bedrock, Google Gemini, or OpenRouter, with keys stored encrypted in TagoIO Secrets."
+tags: ["tagoio"]
+keywords: [tagoio, iot, tago ai, ai provider, openai, anthropic, bedrock]
+---
+
+By default, Tago AI runs on a model and provider selected by TagoIO. If you want direct control over which model handles your data — for compliance, cost, or model-preference reasons — you can connect your own provider to a profile.
+
+<img src="/docs_imagem/tagoio/tago-ai-provider.png" alt="AI Provider configuration under Profile Settings › Services" width="550px" />
+
+## Where to configure it
+
+Go to **Profile Settings → Services → AI Provider**. The setting is per profile, so different profiles in your account can use different providers or stay on the TagoIO default.
+
+Pick a provider from the **Select Provider** dropdown, enter the required credentials, and save. From that point on, Tago AI calls go through your account with that provider.
+
+## Supported providers
+
+You can choose from:
+
+- **Use TagoIO default** — TagoIO handles the model and provider. No configuration needed.
+- **OpenAI**
+- **Anthropic**
+- **AWS Bedrock**
+- **Google Gemini**
+- **OpenRouter**
+
+Each provider asks for its own set of credentials (API key, region, account ID, and so on, depending on the service).
+
+## How your keys are stored
+
+Provider credentials are stored in [TagoIO Secrets](/docs/tagoio/getting-started/secrets.md) and encrypted at rest. They are only read when Tago AI needs to send a request and are not exposed through the Admin once saved.
+
+## Request limits and billing
+
+When a profile uses its own AI provider:
+
+- Requests go through your provider account and are billed by that provider directly.
+- The profile's [TagoAI request limits](/docs/tagoio/profiles/services/tago-ai-service.md) do not apply — you manage rate limits and quotas with your provider.
+
+When a profile uses **Use TagoIO default**, requests count against the monthly TagoAI limit included in the plan.
+
+## Switching back to the default
+
+To stop using your own provider, open the same settings page, select **Use TagoIO default**, and save. Tago AI will resume using the TagoIO-managed provider on the next request.

docs/tagoio/tago-ai/index.md

@@ -0,0 +1,43 @@
+---
+title: "Tago AI"
+description: "Tago AI is an assistant built into the TagoIO Admin. It answers architecture questions, creates and edits resources, writes Analysis code, and helps you debug your data."
+tags: ["tagoio"]
+keywords: [tagoio, iot, tago ai, assistant, ai]
+---
+
+Tago AI is an assistant that lives inside the TagoIO Admin and helps you get work done on the platform. You can ask it questions grounded in the official TagoIO documentation, and you can ask it to carry out tasks for you — create a dashboard, draft Analysis code, inspect a device, or explore your data.
+
+<img src="/docs_imagem/tagoio/tago-ai-interface.png" alt="Tago AI main interface in the TagoIO Admin" width="550px" />
+
+## Where to find it
+
+Tago AI is available throughout the Admin:
+
+- The star-shaped icon in the main sidebar opens the assistant from anywhere.
+- The top bar on the [Analysis](/docs/tagoio/analysis/) and [Dashboards](/docs/tagoio/dashboards/) pages opens it in the current context.
+
+When you open Tago AI from a specific page, it receives telemetric information about what you are currently viewing, so you can ask about the screen in front of you without repeating context.
+
+## What you can do with it
+
+Tago AI is designed to work alongside you as you use TagoIO. You can use it to:
+
+- Ask questions about TagoIO architecture, features, and best practices.
+- Inspect or edit [Devices](/docs/tagoio/devices/), [Dashboards](/docs/tagoio/dashboards/), [Actions](/docs/tagoio/actions/), and [Analysis](/docs/tagoio/analysis/) scripts.
+- Generate Analysis code tailored to your devices and data formats.
+- Debug scripts and investigate unexpected behavior.
+- Run data analysis operations across your devices.
+
+The depth of what Tago AI can change depends on the mode you select. See [Using Tago AI](/docs/tagoio/tago-ai/using-tago-ai.md) for details on modes, chat history, and context awareness.
+
+## Privacy and data handling
+
+Tago AI uses safe defaults to avoid retaining your data. By default, TagoIO selects the model and provider that meet the evaluations and privacy measures we have in place.
+
+If you want direct control over which model and provider process your data, you can configure your own AI provider for a profile. Your provider keys are stored encrypted in [TagoIO Secrets](/docs/tagoio/getting-started/secrets.md) and only used when you send a request to Tago AI. See [Using your own AI provider](/docs/tagoio/tago-ai/ai-provider.md).
+
+## Request limits
+
+Requests to Tago AI count against a monthly limit that depends on your plan. Those limits only apply when using the TagoIO default provider — when you bring your own provider, requests go through your credentials and are not counted against the TagoIO limit.
+
+See [TagoAI Service](/docs/tagoio/profiles/services/tago-ai-service.md) for limits per plan.

docs/tagoio/tago-ai/using-tago-ai.md

@@ -0,0 +1,65 @@
+---
+title: "Using Tago AI"
+description: "A guide to working with Tago AI in the TagoIO Admin: starting chats, context awareness, chat history, expanding the panel, and switching between Read, Write, and Full modes."
+tags: ["tagoio"]
+keywords: [tagoio, iot, tago ai, chat, modes, assistant]
+---
+
+This page walks you through the Tago AI interface — how to start a conversation, reuse previous ones, and choose how much the assistant is allowed to change on your behalf.
+
+## Starting a chat
+
+Open Tago AI from the star icon in the sidebar, or from the top bar of the [Analysis](/docs/tagoio/analysis/) and [Dashboards](/docs/tagoio/dashboards/) pages. You can start a new chat at any time using the **New Chat** button.
+
+Each chat keeps its own history, so you can split unrelated tasks into separate conversations and come back to them later.
+
+## Context awareness
+
+Tago AI receives telemetric information about the page you are currently on. If you open it from a dashboard, it knows which dashboard you are looking at. If you open it from an analysis, it sees the script you are editing.
+
+This means you can ask things like "why is this widget empty?" or "refactor this function to handle missing payloads" without pasting context yourself.
+
+## Expanding and retracting the panel
+
+The chat panel sits on the right side of the Admin. Use the expand control in the top-right corner of the panel to give the chat more room, or collapse it when you need the full screen for your work.
+
+## Chat history
+
+<img src="/docs_imagem/tagoio/tago-ai-history.png" alt="Tago AI chat history panel" width="550px" />
+
+Tago AI keeps your previous chats so you can revisit what you asked before. The history panel groups chats by recency and lets you search across them.
+
+Chat history is capped at **20 chats per profile**. When you reach the limit, the oldest chat is deleted first as new ones are created. If you want to preserve a conversation long-term, copy the relevant parts out before it rolls off.
+
+## Modes
+
+Tago AI has three modes that control what it is allowed to do on your platform. You can switch modes from the bottom of the chat panel before sending a message.
+
+### Read
+
+Read mode only fetches information. Tago AI can list your devices, inspect dashboards, review Analysis scripts, and read data — but it will not create or change anything.
+
+Use Read when you are exploring, asking questions, or want to be sure the assistant will not touch your resources.
+
+### Write
+
+Write mode allows Tago AI to edit existing resources and create new ones. It can draft an Analysis script, build a dashboard, register a device, or update an Action.
+
+Write mode does not delete anything. It is the recommended mode for most day-to-day work.
+
+### Full
+
+Full mode adds deletion to what Write mode already allows. Tago AI can remove devices, dashboards, analyses, and other resources as part of completing a task.
+
+:::warning
+
+Full mode can delete resources in your profile. Deletions in TagoIO are not recoverable from the Admin, so only use Full mode when you understand what you are asking for and have a recent [backup](/docs/tagoio/my-account/backups.md) if the data matters.
+
+:::
+
+## Tips for better results
+
+- Be specific about the device, dashboard, or analysis you want to act on. Names and IDs help.
+- Start in Read mode to confirm the plan, then switch to Write or Full to carry it out.
+- Ask Tago AI to explain what it is about to change before it changes it if you want a safety net.
+- Keep one task per chat so the history stays useful when you come back.