Develop

src/content/docs/docs/kloudmate-assistant/chat-modes.mdx

@@ -43,7 +43,7 @@ This helps users move from a natural-language request to a structured dashboard
 KloudMate Docs is optimized for documentation search and platform reference questions. Use this mode when you want answers grounded in the KloudMate documentation rather than a general operational conversation.
 
 :::note[Free usage]
-The Docs agent is **free** and does not consume credits. KloudMate Assistant runs on credits. A chat message costs 1 credit and a full investigation costs 5 credits. Every plan includes a monthly allowance: 5 credits on Free and 20 on Pro, and prepaid credits can be purchased anytime. Enterprise teams can bring their own AI provider key instead of using credits.
+The Docs agent is **free** and does not consume credits. KloudMate Assistant runs on credits. A chat message costs 1 credit, a full investigation costs 5 credits, and an [Ask KloudMate Assistant](/workflows/actions/#ask-kloudmate-assistant) step in a workflow costs 1 credit. Every plan includes a monthly allowance: 5 credits on Free and 20 on Pro, and prepaid credits can be purchased anytime. Enterprise teams can bring their own AI provider key instead of using credits.
 :::
 
 This mode is useful for:

src/content/docs/docs/kloudmate-assistant/index.mdx

@@ -19,7 +19,7 @@ KloudMate Assistant supports three core modes of operation:
 
 ### Accessing KloudMate Assistant
 
-To start a chat or run an investigation, click the Assistant icon in the top navigation bar to open the assistant panel.
+To start a chat or run an investigation, click the Assistant icon in the top navigation bar to open the assistant panel. A workflow can also run the Assistant with an [Ask KloudMate Assistant](/workflows/actions/#ask-kloudmate-assistant) step.
 
 Open **Assistant** to review investigations, track AI credit usage, and manage the Assistant's prompts, skills, and MCP integrations. It has tabs for **Investigations**, **Prompts**, **Skills**, **MCP Integrations**, and **Usage**. For details, see:
 

src/content/docs/docs/kloudmate-assistant/usage.mdx

@@ -1,30 +1,27 @@
 ---
 title: "Usage"
-description: "Track AI consumption, manage costs, and gain visibility into how your team interacts with the Assistant."
+description: "See how many AI credits your workspace spends on chat, investigations, and workflow steps, and who spends them."
 sidebar:
   order: 4
 ---
-Usage provides visibility into AI consumption across your workspace and helps you track how the Assistant is being used by your team, manage costs, and stay within quota limits.
+Open **Assistant → Usage** to see how many AI credits your workspace spent in the time range you pick, the last 7 days by default.
 
-![image](./images/usage-1.png)
+A chat message costs 1 AI credit, an investigation costs 5, and an [Ask KloudMate Assistant](/workflows/actions/#ask-kloudmate-assistant) step in a workflow costs 1 each time it answers. They all use the same AI credits.
 
-### Summary Metrics
+If your organization prepays for AI credits, the page also shows the credits available, and someone with the **Owner** role can click **Buy credits**.
 
-At the top of the page, four tiles give you a high-level snapshot of activity in the selected period:
+![The Usage tab under Assistant, with the AI credits available, summary tiles, and charts of daily credit usage](./images/usage-1.png)
 
-- **Total AI Credits:** The total number of AI credits consumed across all Assistant interactions.
-- **Chat Messages:** The total number of conversational messages sent to the Assistant.
-- **Investigations:** The total number of investigations triggered during the period.
-- **Usage Count by Agent:** A breakdown showing how many interactions were handled by each agent type.
+## Summary tiles
 
-### Daily AI Credits Usage
+- **Total AI Credits:** every credit spent in the range.
+- **Chat Messages:** credits spent on chat with the Assistant, not counting workflow steps.
+- **Investigations:** credits spent on investigations, at 5 credits each.
+- **Usage Count:** the number of **Messages Sent**, **Investigations**, and **Workflow Steps** in the range.
 
-A bar chart displays daily AI credit consumption over the selected period. This makes it easy to spot spikes in usage.
+## Daily charts
 
-### Usage by User
-
-A stacked bar chart breaks down daily credit consumption by individual user, identified by their email address. Use it to see which users are driving the most AI activity across the workspace.
-
-### Usage by Agent
-
-A separate chart shows daily credit consumption broken down by agent type, Chat Assistant versus Investigator. This is useful for understanding whether your team relies more on conversational queries or on deep investigation workflows, and can inform decisions around capacity planning and feature adoption.
+- **Daily AI Credits Usage** shows the credits spent each day.
+- **Usage by User** splits the daily credits by person, listed by email address. Credits from workflow steps aren't tied to a person.
+- **Usage by Agent** splits the daily credits between the **Chat Assistant**, the **Investigator**, and **Workflows**. **Chat Assistant** counts chat only, and **Workflows** counts **Ask KloudMate Assistant** steps.
+- **Usage by Type** splits the daily credits between **Chat**, **Investigations**, and **Workflows**.

src/content/docs/docs/troubleshooting.mdx

@@ -101,7 +101,7 @@ No. Every plan includes unlimited users, with no per-host or per-agent fees. You
 Each plan includes a default retention window, and you can extend it. Longer retention for logs and traces raises their storage cost by the multiplier shown in the calculator, so you can trade off how long you keep data against cost. Metrics are billed by sample count, so their retention does not change the price.
 
 ## How do AI credits work?
-KloudMate Assistant runs on credits. A chat message costs 1 credit, and a full investigation costs 5. Every plan includes a monthly allowance — 5 credits on Free and 20 on Pro — and you can buy prepaid credits any time you need more. Enterprise teams can bring their own AI provider key instead of using credits.
+KloudMate Assistant runs on credits. A chat message costs 1 credit, a full investigation costs 5, and an [Ask KloudMate Assistant](/workflows/actions/#ask-kloudmate-assistant) step in a workflow costs 1. Every plan includes a monthly allowance (5 credits on Free and 20 on Pro), and you can buy prepaid credits any time you need more. Enterprise teams can bring their own AI provider key instead of using credits.
 
 ## Do you offer annual billing?
 Yes. Annual billing is available at a discount compared with paying monthly. Get in touch and we will set it up for you.

src/content/docs/docs/workflows/actions.mdx

@@ -1,6 +1,6 @@
 ---
 title: "The action catalog"
-description: "Every step a workflow can run: HTTP requests, sandboxed code, AI prompts, AWS and Azure calls, Slack and Jira, MCP tools, host commands, and lookups of hosts, resources, and alert groups."
+description: "Every step a workflow can run: HTTP requests, sandboxed code, AI prompts, the KloudMate Assistant, AWS and Azure calls, Slack and Jira, MCP tools, host commands, and lookups of hosts, resources, and alert groups."
 sidebar:
   label: "Action catalog"
   order: 6
@@ -37,6 +37,7 @@ Slack actions use a [Slack connection](/platform/settings/connections/providers/
 | Action | What it does |
 |---|---|
 | **Post Message** | Post to a channel or a person, optionally as a thread reply. |
+| **Reply in Thread** | Reply in the thread under a message. |
 | **Update Message** | Edit a message the workflow posted. |
 | **Send Direct Message** | Message a person directly, as the bot. |
 | **Add Reaction** | React to a message. |
@@ -47,12 +48,42 @@ Slack actions use a [Slack connection](/platform/settings/connections/providers/
 | **Look Up User** | Turn a Slack user id into a person. |
 | **Find User by Email** | Turn an email address into a Slack user. |
 
-When the destination is fixed, use **Send Slack Message**. When the workflow decides the channel, replies in a thread, or needs the posted message back so a later step can edit it, use **Post Message**.
+When the destination is fixed, use **Send Slack Message**. When the workflow decides the channel, or needs the posted message back so a later step can edit it, use **Post Message**. To reply in a thread, use **Reply in Thread**.
 
 :::caution
 Some of these need permissions the first Slack install didn't ask for. Looking up users needs profile access, and the channel actions need channel management. If a step fails with `missing_scope`, reconnect the Slack connection. Everything else on that connection keeps working in the meantime.
 :::
 
+#### Reply in Thread
+
+Set **Thread** to the `ts` of the message that starts the thread. If **Thread** renders blank, the step fails instead of posting to the channel.
+
+To reply to the message that started the run, use:
+
+```liquid
+{{ trigger.event.thread_ts | default: trigger.event.ts }}
+```
+
+This also works when that message is itself a reply in a thread.
+
+Turn on **Also send to channel** to show the reply in the channel as well. **Account**, **Channel**, **Text**, and **Blocks** work the same way as on **Post Message**.
+
+#### Post Markdown to Slack
+
+In Slack steps that post or edit a message, **Text** uses Slack's own formatting, so standard Markdown such as `**bold**`, `## headings`, and `[text](url)` links shows as typed. To post Markdown with its formatting, such as an [Ask KloudMate Assistant](#ask-kloudmate-assistant) answer, put it in a `markdown` block in **Blocks**:
+
+```liquid
+[{"type": "markdown", "text": {{ steps.<id>.output.answer | json }}}]
+```
+
+Always add `| json`, with no quotes around the value. It adds the quotes and escapes line breaks and quote marks, so the block stays valid JSON. If **Blocks** isn't a valid JSON list once its `{{ }}` values are filled in, the step fails.
+
+Set **Text** to a short line too, for example `{{ trigger.body.group.title }}: Assistant findings`. Slack shows **Text** in notifications and as a fallback.
+
+Slack allows at most 12,000 characters of `markdown` blocks in one message, and a longer message fails the step. To stay under the limit, use `{{ steps.<id>.output.answer | truncate: 11000 | json }}`. In a `markdown` block, images show as links, and every heading level shows at the same size.
+
+Don't ask the Assistant for Slack formatting or Block Kit JSON in the prompt. It can write blocks that Slack rejects, and it tends to drift back to Markdown.
+
 ### Jira Cloud
 
 | Action | What it does |
@@ -251,6 +282,31 @@ If you leave **Output fields** empty, the instruction describes the shape instea
 
 The extracted fields are at the top level of the step output, so a later step reads `{{ steps.extract.output.severity }}`. Their shape comes from your own list, so the variable picker shows them only after you test the step once.
 
+### Ask KloudMate Assistant
+
+Runs the [KloudMate Assistant](/kloudmate-assistant/) on a prompt and returns its answer. It's the same Assistant you chat with, so it can query your telemetry. For example, use it to look into an alert before the workflow posts about it.
+
+- **Prompt** says what to find out or do. The Assistant can't ask you questions, so say which service and time range to look at, and what you want back.
+- **MCP Integrations** is optional. Pick integrations to give the Assistant their tools, which it runs without asking for approval. Only integrations shared with the workspace are listed. Tools set to **Ask before run** are off. Manage the tools in [Assistant → MCP Integrations](/kloudmate-assistant/settings/#tool-level-settings).
+
+For an alert trigger, a prompt could look like this:
+
+```text
+{{ trigger.body.group.title }} is firing. Look at errors and latency for the affected service over the last 30 minutes. What is the most likely cause?
+```
+
+The step returns the Assistant's `answer` and `tool_calls`, a list of the tools it called with shortened inputs. The answer is Markdown, and later steps read it as `{{ steps.<id>.output.answer }}`. To post it to Slack with its formatting, see [Post Markdown to Slack](#post-markdown-to-slack). To branch on the answer, add an **AI Extract** step after this one.
+
+The step costs 1 AI credit each time it answers. It uses the same [AI credits](/kloudmate-assistant/usage/) as chat with the Assistant, so a workflow that runs often can use up the credits your team needs for chat.
+
+A failed or timed-out step costs nothing. If the organization is out of AI credits, the step fails before it starts. A **Test run** of the workflow spends the credit too, but [testing the step on its own](../test-a-workflow/#test-one-step) only shows the shape of its output.
+
+The step's **Timeout** defaults to 5 minutes. A higher timeout doesn't give the Assistant more time. The step never retries, and you can't put it inside a [Wait until](../control-flow/#wait-until).
+
+:::caution
+If you template untrusted text into the prompt, such as a Slack message or a webhook payload, whoever wrote that text can steer which tools the Assistant calls. With no integrations picked, the Assistant's tools only read data, so the worst case is a wrong answer. If a picked integration has tools that make changes, put an [approval](../approvals-and-input/) before this step.
+:::
+
 ## Utilities
 
 These actions need no connection.
@@ -311,7 +367,7 @@ Run Code never retries, because the code can POST. If a caller might re-run the
 
 ## Retries and failures
 
-Every action step has the settings covered in [Build a workflow](../build-a-workflow/#step-settings). The one difference between actions is retries: anything that changes external state never retries and doesn't offer the setting, so a failed write is never silently repeated.
+Every action step has the settings covered in [Build a workflow](../build-a-workflow/#step-settings). Anything that changes external state never retries and doesn't offer the setting, so a failed write is never silently repeated. The **Timeout** defaults to 60 seconds, or to 5 minutes on **Ask KloudMate Assistant**.
 
 ## Related
 

src/content/docs/docs/workflows/build-a-workflow.mdx

@@ -80,8 +80,8 @@ Action steps have a collapsible **Settings** section under their fields. Control
 | Setting | Default | What it does |
 |---|---|---|
 | **On failure** | Stop the workflow | **Go to the next step** records the error under `steps.<id>.error` and carries on. |
-| **Retry attempts** | 3, or 1 for the AI actions | At most 5. Not offered on an action that changes external state: those run once, so a failed write is never silently repeated. |
-| **Timeout** | 60s | How long one attempt may run, up to 15m. |
+| **Retry attempts** | 3, or 1 for **AI Prompt** and **AI Extract** | At most 5. Not offered on an action that changes external state: those run once, so a failed write is never silently repeated. |
+| **Timeout** | 60s, or 5m for **Ask KloudMate Assistant** | How long one attempt may run, up to 15m. **Ask KloudMate Assistant** stops at 5m even if you set it higher. |
 
 **No retries** gives the same default as leaving **Retry attempts** alone, so you can't set a read-only action to zero retries from the builder.
 

src/content/docs/docs/workflows/control-flow.mdx

@@ -80,7 +80,7 @@ Runs a block of steps repeatedly until a condition holds, then continues. Use it
 
 | Field | What it takes |
 |---|---|
-| **Check until the condition is true** | The steps to run each time. Actions, Branch, and Route steps only. |
+| **Check until the condition is true** | The steps to run each time. Actions (except **Ask KloudMate Assistant**), Branch, and Route steps only. |
 | **Until** | The condition, read against the check block's own step outputs, for example `steps.vm.output.result.status` equals `running`. |
 | **Timeout** | How long the step waits before it fails. Default `10m`, maximum `24h`. |
 

src/content/docs/docs/workflows/index.mdx

@@ -19,6 +19,7 @@ A disk-space alert is a good first workflow. It reads the host from the alert an
 - **Work in your tools**: post and edit Slack messages, create and transition Jira issues, call a tool on an MCP server, or send an HTTP request to anything else.
 - **Notify**: send through an existing Slack, Teams, webhook, or SNS channel, or email an address directly.
 - **Transform and decide**: extract a value with JSONPath, parse CSV and XML, run sandboxed JavaScript, choose between several paths by condition, or have a model pull structured fields out of a payload.
+- **Ask the Assistant**: have the [KloudMate Assistant](./actions/#ask-kloudmate-assistant) look into an alert using your telemetry, then use its answer in later steps.
 - **Wait for a person**: pause for an approval or a filled-in form. Both arrive by email, and each person gets their own link.
 - **Reuse configuration**: refer to a workspace [constant or secret](./variables/) by name instead of pasting a channel id or a token into every workflow.
 - **Store data between runs**: save a cursor, a counter, or a marker such as "this alert was already handled today" for later runs to read.

src/content/docs/docs/workflows/limits.mdx

@@ -30,6 +30,7 @@ Most workflows stay well inside these limits. The ones people hit most are the s
 | Limit | Value |
 |---|---|
 | One step attempt | 60 seconds by default, 15 minutes at most |
+| One **Ask KloudMate Assistant** step | 5 minutes by default and at most |
 | Retries per step | 5 at most |
 | **Wait / Delay** | 24 hours |
 | **Wait until** | 24 hours, with at most 20 checks |

src/content/docs/docs/workflows/run-history.mdx

@@ -63,7 +63,9 @@ You can't re-run a test run this way, because it ran a draft, not a published ve
 
 **Workflows → Usage** shows how workflows are doing across the workspace over the time range you pick, the last 7 days by default. Its tiles show the **Runs** that finished, the **Failed** runs, the **Success Rate %**, and the **Credits** used, above a chart of **Runs and Failures Over Time**. It doesn't count test runs from the builder.
 
-Each run counts 1 credit, and each **AI Prompt**, **AI Extract**, or **AI Route** step it runs adds 2. A workflow that a **Call Workflow** step starts counts as a run of its own. Loop items and parallel branches don't. Workflow credits are separate from the AI credits the [KloudMate Assistant](../../kloudmate-assistant/) uses.
+Each run counts 1 credit, and each **AI Prompt**, **AI Extract**, or **AI Route** step it runs adds 2. A workflow that a **Call Workflow** step starts counts as a run of its own. Loop items and parallel branches don't.
+
+Workflow credits are separate from the [AI credits](../../kloudmate-assistant/usage/) that the KloudMate Assistant uses in chat. An **Ask KloudMate Assistant** step adds no workflow credits, and spends 1 AI credit each time it answers instead.
 
 ## Run retention