chore: publish from staged

plugins/flowstudio-power-automate/skills/flowstudio-power-automate-mcp/references/MCP-BOOTSTRAP.md

@@ -0,0 +1,78 @@
+# MCP Bootstrap — Quick Reference
+
+Everything an agent needs to start calling the FlowStudio MCP server.
+
+```
+Endpoint:  https://mcp.flowstudio.app/mcp
+Protocol:  JSON-RPC 2.0 over HTTP POST
+Transport: Streamable HTTP — single POST per request, no SSE, no WebSocket
+Auth:      x-api-key header with JWT token (NOT Bearer)
+```
+
+## Required Headers
+
+```
+Content-Type: application/json
+x-api-key: <token>
+User-Agent: FlowStudio-MCP/1.0    ← required, or Cloudflare blocks you
+```
+
+## Step 1 — Discover Tool Bundles
+
+Preferred cold-start call:
+
+```json
+POST {"jsonrpc":"2.0","id":1,"method":"tools/call",
+      "params":{"name":"list_skills","arguments":{}}}
+```
+
+Returns the current bundles (`build-flow`, `create-flow`, `debug-flow`,
+`monitor-flow`, `discover`, `governance`) and their member tool names. Free —
+not counted against plan limits.
+
+Then load the relevant schemas:
+
+```json
+POST {"jsonrpc":"2.0","id":2,"method":"tools/call",
+      "params":{"name":"tool_search","arguments":{"query":"skill:create-flow"}}}
+```
+
+Use `query:"select:tool1,tool2"` to load exact tools and keyword search such as
+`query:"send email"` when the user intent is ambiguous.
+
+Fallback for very low-level MCP clients:
+
+```json
+POST {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
+```
+
+`tools/list` returns all tools with names, descriptions, and input schemas, but
+it is heavier and should not be the first choice for agents that know the
+FlowStudio meta-tools.
+
+## Step 2 — Call a Tool
+
+```json
+POST {"jsonrpc":"2.0","id":1,"method":"tools/call",
+      "params":{"name":"<tool_name>","arguments":{...}}}
+```
+
+## Response Shape
+
+```
+Success → {"result":{"content":[{"type":"text","text":"<JSON string>"}]}}
+Error   → {"result":{"content":[{"type":"text","text":"{\"error\":{...}}"}]}}
+```
+
+Always parse `result.content[0].text` as JSON to get the actual data.
+
+## Key Tips
+
+- Tool results are JSON strings inside the text field — **double-parse needed**
+- `"error"` field in parsed body: `null` = success, object = failure
+- `environmentName` is required for most tools, but **not** for:
+  `list_live_environments`, `list_live_connections`, `list_store_flows`,
+  `list_store_environments`, `list_store_makers`, `get_store_maker`,
+  `list_store_power_apps`, `list_store_connections`
+- When in doubt, check the `required` array in each tool's schema from
+  `tool_search` (or `tools/list` as a fallback)

plugins/flowstudio-power-automate/skills/flowstudio-power-automate-mcp/references/action-types.md

@@ -0,0 +1,79 @@
+# FlowStudio MCP — Action Types Reference
+
+Compact lookup for recognising action types returned by `get_live_flow`.
+Use this to **read and understand** existing flow definitions.
+
+> For full copy-paste construction patterns, see the `flowstudio-power-automate-build` skill.
+
+---
+
+## How to Read a Flow Definition
+
+Every action has `"type"`, `"runAfter"`, and `"inputs"`. The `runAfter` object
+declares dependencies: `{"Previous": ["Succeeded"]}`. Valid statuses:
+`Succeeded`, `Failed`, `Skipped`, `TimedOut`.
+
+---
+
+## Action Type Quick Reference
+
+| Type | Purpose | Key fields to inspect | Output reference |
+|---|---|---|---|
+| `Compose` | Store/transform a value | `inputs` (any expression) | `outputs('Name')` |
+| `InitializeVariable` | Declare a variable | `inputs.variables[].{name, type, value}` | `variables('name')` |
+| `SetVariable` | Update a variable | `inputs.{name, value}` | `variables('name')` |
+| `IncrementVariable` | Increment a numeric variable | `inputs.{name, value}` | `variables('name')` |
+| `AppendToArrayVariable` | Push to an array variable | `inputs.{name, value}` | `variables('name')` |
+| `If` | Conditional branch | `expression.and/or`, `actions`, `else.actions` | — |
+| `Switch` | Multi-way branch | `expression`, `cases.{case, actions}`, `default` | — |
+| `Foreach` | Loop over array | `foreach`, `actions`, `operationOptions` | `item()` / `items('Name')` |
+| `Until` | Loop until condition | `expression`, `limit.{count, timeout}`, `actions` | — |
+| `Wait` | Delay | `inputs.interval.{count, unit}` | — |
+| `Scope` | Group / try-catch | `actions` (nested action map) | `result('Name')` |
+| `Terminate` | End run | `inputs.{runStatus, runError}` | — |
+| `OpenApiConnection` | Connector call (SP, Outlook, Teams…) | `inputs.host.{apiId, connectionName, operationId}`, `inputs.parameters` | `outputs('Name')?['body/...']` |
+| `OpenApiConnectionWebhook` | Webhook wait (approvals, adaptive cards) | same as above | `body('Name')?['...']` |
+| `Http` | External HTTP call | `inputs.{method, uri, headers, body}` | `outputs('Name')?['body']` |
+| `Response` | Return to HTTP caller | `inputs.{statusCode, headers, body}` | — |
+| `Query` | Filter array | `inputs.{from, where}` | `body('Name')` (filtered array) |
+| `Select` | Reshape/project array | `inputs.{from, select}` | `body('Name')` (projected array) |
+| `Table` | Array → CSV/HTML string | `inputs.{from, format, columns}` | `body('Name')` (string) |
+| `ParseJson` | Parse JSON with schema | `inputs.{content, schema}` | `body('Name')?['field']` |
+| `Expression` | Built-in function (e.g. ConvertTimeZone) | `kind`, `inputs` | `body('Name')` |
+
+---
+
+## Connector Identification
+
+When you see `type: OpenApiConnection`, identify the connector from `host.apiId`:
+
+| apiId suffix | Connector |
+|---|---|
+| `shared_sharepointonline` | SharePoint |
+| `shared_office365` | Outlook / Office 365 |
+| `shared_teams` | Microsoft Teams |
+| `shared_approvals` | Approvals |
+| `shared_office365users` | Office 365 Users |
+| `shared_flowmanagement` | Flow Management |
+
+The `operationId` tells you the specific operation (e.g. `GetItems`, `SendEmailV2`,
+`PostMessageToConversation`). The `connectionName` maps to a GUID in
+`properties.connectionReferences`.
+
+---
+
+## Common Expressions (Reading Cheat Sheet)
+
+| Expression | Meaning |
+|---|---|
+| `@outputs('X')?['body/value']` | Array result from connector action X |
+| `@body('X')` | Direct body of action X (Query, Select, ParseJson) |
+| `@item()?['Field']` | Current loop item's field |
+| `@triggerBody()?['Field']` | Trigger payload field |
+| `@variables('name')` | Variable value |
+| `@coalesce(a, b)` | First non-null of a, b |
+| `@first(array)` | First element (null if empty) |
+| `@length(array)` | Array count |
+| `@empty(value)` | True if null/empty string/empty array |
+| `@union(a, b)` | Merge arrays — **first wins** on duplicates |
+| `@result('Scope')` | Array of action outcomes inside a Scope |

plugins/flowstudio-power-automate/skills/flowstudio-power-automate-mcp/references/connection-references.md

@@ -0,0 +1,143 @@
+# FlowStudio MCP — Connection References
+
+Connection references wire a flow's connector actions to real authenticated
+connections in the Power Platform. They are required whenever you call
+`update_live_flow` with a definition that uses connector actions.
+
+---
+
+## Structure in a Flow Definition
+
+```json
+{
+  "properties": {
+    "definition": { ... },
+    "connectionReferences": {
+      "shared_sharepointonline": {
+        "connectionName": "shared-sharepointonl-eeeeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
+        "id": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline",
+        "displayName": "SharePoint"
+      },
+      "shared_office365": {
+        "connectionName": "shared-office365-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+        "id": "/providers/Microsoft.PowerApps/apis/shared_office365",
+        "displayName": "Office 365 Outlook"
+      }
+    }
+  }
+}
+```
+
+Keys are **logical reference names** (e.g. `shared_sharepointonline`).
+These match the `connectionName` field inside each action's `host` block.
+
+---
+
+## Finding Connection References
+
+Preferred method: call `list_live_connections` in the target environment. Use
+`search` to narrow results to the connector you need; newer MCP server versions
+return paste-ready templates.
+
+```python
+matches = mcp("list_live_connections",
+    environmentName=ENV,
+    search="shared_sharepointonline")
+
+conn = next(c for c in matches["connections"]
+            if c.get("overallStatus") == "Connected"
+            or c.get("statuses", [{}])[0].get("status") == "Connected")
+
+conn_refs = {
+    "shared_sharepointonline": conn.get("connectionReferenceTemplate") or {
+        "connectionName": conn["id"],
+        "id": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline",
+        "source": "Invoker"
+    }
+}
+host = conn.get("hostTemplate") or {"connectionName": "shared_sharepointonline"}
+```
+
+Use `host` as the action-side `inputs.host`. Use `conn_refs` as
+`update_live_flow(connectionReferences=conn_refs)`.
+
+Fallback method: copy from an existing flow.
+
+Call `get_live_flow` on **any existing flow** that uses the same connection
+and copy the `connectionReferences` block. The GUID after the connector prefix is
+the connection instance owned by the authenticating user.
+
+```python
+flow = mcp("get_live_flow", environmentName=ENV, flowName=EXISTING_FLOW_ID)
+conn_refs = flow["properties"]["connectionReferences"]
+# conn_refs["shared_sharepointonline"]["connectionName"]
+# → "shared-sharepointonl-eeeeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee"
+```
+
+> ⚠️ Connection references are **user-scoped**. If a connection is owned
+> by another account, `update_live_flow` will return 403
+> `ConnectionAuthorizationFailed`. You must use a connection belonging to
+> the account whose token is in the `x-api-key` header.
+
+---
+
+## Passing `connectionReferences` to `update_live_flow`
+
+```python
+result = mcp("update_live_flow",
+    environmentName=ENV,
+    flowName=FLOW_ID,
+    definition=modified_definition,
+    connectionReferences={
+        "shared_sharepointonline": {
+            "connectionName": "shared-sharepointonl-eeeeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
+            "id": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline"
+        }
+    }
+)
+```
+
+Only include connections that the definition actually uses.
+
+---
+
+## Common Connector API IDs
+
+| Service | API ID |
+|---|---|
+| SharePoint Online | `/providers/Microsoft.PowerApps/apis/shared_sharepointonline` |
+| Office 365 Outlook | `/providers/Microsoft.PowerApps/apis/shared_office365` |
+| Microsoft Teams | `/providers/Microsoft.PowerApps/apis/shared_teams` |
+| OneDrive for Business | `/providers/Microsoft.PowerApps/apis/shared_onedriveforbusiness` |
+| Azure AD | `/providers/Microsoft.PowerApps/apis/shared_azuread` |
+| HTTP with Azure AD | `/providers/Microsoft.PowerApps/apis/shared_webcontents` |
+| SQL Server | `/providers/Microsoft.PowerApps/apis/shared_sql` |
+| Dataverse | `/providers/Microsoft.PowerApps/apis/shared_commondataserviceforapps` |
+| Azure Blob Storage | `/providers/Microsoft.PowerApps/apis/shared_azureblob` |
+| Approvals | `/providers/Microsoft.PowerApps/apis/shared_approvals` |
+| Office 365 Users | `/providers/Microsoft.PowerApps/apis/shared_office365users` |
+| Flow Management | `/providers/Microsoft.PowerApps/apis/shared_flowmanagement` |
+
+---
+
+## Teams Adaptive Card Dual-Connection Requirement
+
+Flows that send adaptive cards **and** post follow-up messages require two
+separate Teams connections:
+
+```json
+"connectionReferences": {
+  "shared_teams": {
+    "connectionName": "shared-teams-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "id": "/providers/Microsoft.PowerApps/apis/shared_teams"
+  },
+  "shared_teams_1": {
+    "connectionName": "shared-teams-yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
+    "id": "/providers/Microsoft.PowerApps/apis/shared_teams"
+  }
+}
+```
+
+Both can point to the **same underlying Teams account** but must be registered
+as two distinct connection references. The webhook (`OpenApiConnectionWebhook`)
+uses `shared_teams` and subsequent message actions use `shared_teams_1`.

plugins/flowstudio-power-automate/skills/flowstudio-power-automate-mcp/references/tool-reference.md

@@ -0,0 +1,601 @@
+# FlowStudio MCP — Tool Response Catalog
+
+Response shapes and behavioral notes for the FlowStudio Power Automate MCP server.
+
+> **For tool names and parameters**: Prefer `list_skills` and `tool_search`.
+> They return focused, up-to-date schemas without loading every MCP tool at once.
+> Use `tools/list` only as a low-level fallback when the meta-tools are not available.
+> This document covers what tool schemas do NOT tell you: **response shapes**
+> and **non-obvious behaviors** discovered through real usage.
+
+---
+
+## Source of Truth
+
+| Priority | Source | Covers |
+|----------|--------|--------|
+| 1 | **Real API response** | Always trust what the server actually returns |
+| 2 | **`list_skills` / `tool_search`** | Tool names, parameter names, types, required flags |
+| 3 | **This document** | Response shapes, behavioral notes, gotchas |
+
+> If this document disagrees with `tool_search`, `tools/list`, or real API
+> behavior, the API wins. Update this document accordingly.
+
+---
+
+## Environment & Tenant Discovery
+
+### `list_live_environments`
+
+Response: direct array of environments.
+```json
+[
+  {
+    "id": "Default-26e65220-5561-46ef-9783-ce5f20489241",
+    "displayName": "FlowStudio (default)",
+    "sku": "Production",
+    "location": "australia",
+    "state": "Enabled",
+    "isDefault": true,
+    "isAdmin": true,
+    "isMember": true,
+    "createdTime": "2023-08-18T00:41:05Z"
+  }
+]
+```
+
+> Use the `id` value as `environmentName` in all other tools.
+
+### `list_store_environments`
+
+Same shape as `list_live_environments` but read from cache (faster).
+
+---
+
+## Connection Discovery
+
+### `list_live_connections`
+
+Response: wrapper object with `connections` array.
+```json
+{
+  "connections": [
+    {
+      "id": "shared-office365-9f9d2c8e-55f1-49c9-9f9c-1c45d1fbbdce",
+      "displayName": "user@contoso.com",
+      "connectorName": "shared_office365",
+      "environment": "Default-26e65220-...",
+      "createdBy": "User Name",
+      "authenticatedUser": "user@contoso.com",
+      "overallStatus": "Connected",
+      "statuses": [{"status": "Connected"}],
+      "createdTime": "2024-03-12T21:23:55.206815Z",
+      "connectionReferenceTemplate": {
+        "connectionName": "shared-office365-9f9d2c8e-55f1-49c9-9f9c-1c45d1fbbdce",
+        "source": "Invoker",
+        "id": "/providers/Microsoft.PowerApps/apis/shared_office365"
+      },
+      "hostTemplate": {
+        "connectionName": "shared_office365"
+      }
+    }
+  ],
+  "totalCount": 56,
+  "error": null
+}
+```
+
+> **Key field**: `id` is the `connectionName` value used in `connectionReferences`.
+>
+> **Key field**: `connectorName` maps to apiId:
+> `"/providers/Microsoft.PowerApps/apis/" + connectorName`
+>
+> Filter by status: prefer `overallStatus == "Connected"` when present; otherwise
+> check `statuses[0].status == "Connected"`.
+>
+> For build workflows, pass `environmentName` to avoid using a connection from
+> the wrong environment. Omit it only when intentionally inventorying connections
+> across all environments.
+>
+> Pass `search=<connector or account>` to narrow output and receive
+> `connectionReferenceTemplate` plus `hostTemplate` values that can be copied
+> directly into `update_live_flow`.
+
+### `list_store_connections`
+
+Same connection data from cache.
+
+---
+
+## Flow Discovery & Listing
+
+### `list_live_flows`
+
+Response: wrapper object with `flows` array.
+```json
+{
+  "mode": "owner",
+  "flows": [
+    {
+      "id": "0757041a-8ef2-cf74-ef06-06881916f371",
+      "displayName": "My Flow",
+      "state": "Started",
+      "triggerType": "Request",
+      "triggerKind": "Http",
+      "createdTime": "2023-08-18T01:18:17Z",
+      "lastModifiedTime": "2023-08-18T12:47:42Z",
+      "owners": "<aad-object-id>",
+      "definitionAvailable": true
+    }
+  ],
+  "totalCount": 100,
+  "nextLink": null,
+  "error": null
+}
+```
+
+> Access via `result["flows"]`. `id` is a plain UUID --- use directly as `flowName`.
+>
+> `mode` indicates the access scope used (`"owner"` or `"admin"`).
+>
+> Parameters added in newer server versions:
+> - `search`: filter by display name server-side.
+> - `mode`: `owner` for flows owned by the MCP identity; `admin` for all flows
+>   visible to an admin account.
+> - `timeoutSeconds`: return partial results with `nextLink` instead of waiting
+>   on very large environments.
+> - `continuationUrl`: pass the previous `nextLink` to continue the same query.
+
+### `list_store_flows`
+
+Response: **direct array** (no wrapper).
+```json
+[
+  {
+    "id": "3991358a-f603-e49d-b1ed-a9e4f72e2dcb.0757041a-8ef2-cf74-ef06-06881916f371",
+    "displayName": "Admin | Sync Template v3 (Solutions)",
+    "state": "Started",
+    "triggerType": "OpenApiConnectionWebhook",
+    "environmentName": "3991358a-f603-e49d-b1ed-a9e4f72e2dcb",
+    "runPeriodTotal": 100,
+    "createdTime": "2023-08-18T01:18:17Z",
+    "lastModifiedTime": "2023-08-18T12:47:42Z"
+  }
+]
+```
+
+> **`id` format**: `<environmentId>.<flowId>` --- split on the first `.` to extract the flow UUID:
+> `flow_id = item["id"].split(".", 1)[1]`
+
+### `get_store_flow`
+
+Response: single flow metadata from cache (selected fields).
+```json
+{
+  "id": "<environmentId>.<flowId>",
+  "displayName": "My Flow",
+  "state": "Started",
+  "triggerType": "Recurrence",
+  "runPeriodTotal": 100,
+  "runPeriodFailRate": 0.1,
+  "runPeriodSuccessRate": 0.9,
+  "runPeriodFails": 10,
+  "runPeriodSuccess": 90,
+  "runPeriodDurationAverage": 29410.8,
+  "runPeriodDurationMax": 158900.0,
+  "runError": "{\"code\": \"EACCES\", ...}",
+  "description": "Flow description",
+  "tier": "Premium",
+  "complexity": "{...}",
+  "actions": 42,
+  "connections": ["sharepointonline", "office365"],
+  "owners": ["user@contoso.com"],
+  "createdBy": "user@contoso.com"
+}
+```
+
+> `runPeriodDurationAverage` / `runPeriodDurationMax` are in **milliseconds** (divide by 1000).
+> `runError` is a **JSON string** --- parse with `json.loads()`.
+
+---
+
+## Flow Definition (Live API)
+
+### `get_live_flow`
+
+Response: full flow definition from PA API.
+```json
+{
+  "name": "<flow-guid>",
+  "properties": {
+    "displayName": "My Flow",
+    "state": "Started",
+    "definition": {
+      "triggers": { "..." },
+      "actions": { "..." },
+      "parameters": { "..." }
+    },
+    "connectionReferences": { "..." }
+  }
+}
+```
+
+### `update_live_flow`
+
+**Create mode**: Omit `flowName` --- creates a new flow. `definition` and `displayName` required.
+
+**Update mode**: Provide `flowName` --- PATCHes existing flow.
+
+Response:
+```json
+{
+  "created": false,
+  "flowKey": "<environmentId>.<flowId>",
+  "updated": ["definition", "connectionReferences"],
+  "displayName": "My Flow",
+  "state": "Started",
+  "definition": { "...full definition..." },
+  "error": null
+}
+```
+
+> `error` is **always present** but may be `null`. Check `result.get("error") is not None`.
+>
+> On create: `created` is the new flow GUID (string). On update: `created` is `false`.
+>
+> Required fields can vary by server version. Use `tool_search` with
+> `select:update_live_flow` before creating or patching a flow; if a description
+> is required, include either the new description or the existing one from
+> `get_live_flow`.
+>
+> The flow description is part of the workflow definition (`definition.description`),
+> not a top-level tool argument in current schemas.
+
+### `add_live_flow_to_solution`
+
+Migrates a non-solution flow into a solution. Returns error if already in a solution.
+
+Use this after creating a Copilot Studio Skills-triggered flow that must be
+discoverable as an agent tool. Pass `solutionId` for the target solution. If the
+server supports omitting `solutionId`, it uses the environment's default solution;
+prefer an explicit unmanaged solution for production ALM.
+
+This tool changes solution membership only. It does not validate the trigger
+schema, publish a Copilot Studio agent, or prove that the flow is callable by the
+agent.
+
+---
+
+## Connector Operation Discovery
+
+### `describe_live_connector`
+
+Describes a connector/API and its operations. Use it before creating connector
+actions instead of guessing operation JSON.
+
+Common modes:
+
+| Call shape | Use |
+|---|---|
+| `search="send email"` without `connectorName` | Search operations across connectors |
+| `connectorName="shared_sharepointonline"` | Compact operation catalog for one connector |
+| `operationId="GetItems"` | Expanded schema for one operation |
+| `variant="flowbot_chat"` | Authored example for one operation variant |
+
+The operation detail can include:
+- `hint`: authored guidance from the connector hints table.
+- `exampleDefinition`: copy-ready action/trigger shape when available.
+- Dynamic metadata with `nextTool=get_live_dynamic_options` or
+  `nextTool=get_live_dynamic_properties`.
+
+### `get_live_dynamic_options`
+
+Resolves live dropdown/list options for connector parameters. Use this for
+IDs selected from lists, such as SharePoint sites/lists, Teams teams/channels,
+or other `x-ms-dynamic-list` / `x-ms-dynamic-values` parameters.
+
+Pass the `dynamicMetadata` object returned by `describe_live_connector`, the
+connection id from `list_live_connections`, and any already-resolved dependent
+parameters.
+
+### `get_live_dynamic_properties`
+
+Resolves live schema/field properties for connector parameters. Use this for
+dynamic field sets such as SharePoint list item columns after the site and list
+are known.
+
+Useful parameters:
+- `parameters`: dependent values, for example `{ "dataset": "<site-url>",
+  "table": "<list-id>" }`.
+- `propertyName`: request one field after inspecting the compact response.
+- `includeRaw`: include raw connector schema only when needed; it can be large.
+
+---
+
+## Run History & Monitoring
+
+### `get_live_flow_runs`
+
+Response: direct array of runs (newest first).
+```json
+[{
+  "name": "<run-id>",
+  "status": "Succeeded|Failed|Running|Cancelled",
+  "startTime": "2026-02-25T06:13:38Z",
+  "endTime": "2026-02-25T06:14:02Z",
+  "triggerName": "Recurrence",
+  "error": null
+}]
+```
+
+> `top` defaults to **30** and auto-paginates for higher values. Set `top: 300`
+> for 24-hour coverage on flows running every 5 minutes.
+>
+> Run ID field is **`name`** (not `runName`). Use this value as the `runName`
+> parameter in other tools.
+
+### `get_live_flow_run_error`
+
+Response: structured error breakdown for a failed run.
+```json
+{
+  "runName": "08584296068667933411438594643CU15",
+  "failedActions": [
+    {
+      "actionName": "Apply_to_each_prepare_workers",
+      "status": "Failed",
+      "error": {"code": "ActionFailed", "message": "An action failed."},
+      "code": "ActionFailed",
+      "startTime": "2026-02-25T06:13:52Z",
+      "endTime": "2026-02-25T06:15:24Z"
+    },
+    {
+      "actionName": "HTTP_find_AD_User_by_Name",
+      "status": "Failed",
+      "code": "NotSpecified",
+      "startTime": "2026-02-25T06:14:01Z",
+      "endTime": "2026-02-25T06:14:05Z"
+    }
+  ],
+  "allActions": [
+    {"actionName": "Apply_to_each", "status": "Skipped"},
+    {"actionName": "Compose_WeekEnd", "status": "Succeeded"},
+    {"actionName": "HTTP_find_AD_User_by_Name", "status": "Failed"}
+  ]
+}
+```
+
+> `failedActions` is ordered outer-to-inner --- the **last entry is the root cause**.
+> Use `failedActions[-1]["actionName"]` as the starting point for diagnosis.
+
+### `get_live_flow_run_action_outputs`
+
+Response: array of action detail objects.
+```json
+[
+  {
+    "actionName": "Compose_WeekEnd_now",
+    "status": "Succeeded",
+    "startTime": "2026-02-25T06:13:52Z",
+    "endTime": "2026-02-25T06:13:52Z",
+    "error": null,
+    "inputs": "Mon, 25 Feb 2026 06:13:52 GMT",
+    "outputs": "Mon, 25 Feb 2026 06:13:52 GMT"
+  }
+]
+```
+
+> **`actionName` is optional**: omit it to return top-level actions in the run.
+> Provide it for a specific action. If that action runs inside a foreach, the
+> tool can return every repetition of that action across iterations; pass
+> `iterationIndex` to pin to one zero-based iteration.
+>
+> Outputs can be very large (50 MB+) for bulk-data actions. Use 120s+ timeout.
+
+---
+
+## Run Control
+
+### `resubmit_live_flow_run`
+
+Response: `{ flowKey, resubmitted: true, runName, triggerName }`
+
+### `cancel_live_flow_run`
+
+Cancels a `Running` flow run.
+
+> Do NOT cancel runs waiting for an adaptive card response --- status `Running`
+> is normal while a Teams card is awaiting user input.
+
+---
+
+## HTTP Trigger Tools
+
+### `get_live_flow_http_schema`
+
+Deprecated. Prefer `get_live_flow` and inspect the `Request` trigger's
+`inputs.schema` plus any `Response` actions directly from the definition.
+
+Response keys:
+```
+flowKey            - Flow GUID
+displayName        - Flow display name
+triggerName        - Trigger action name (e.g. "manual")
+triggerType        - Trigger type (e.g. "Request")
+triggerKind        - Trigger kind (e.g. "Http")
+requestMethod      - HTTP method (e.g. "POST")
+relativePath       - Relative path configured on the trigger (if any)
+requestSchema      - JSON schema the trigger expects as POST body
+requestHeaders     - Headers the trigger expects
+responseSchemas    - Array of JSON schemas defined on Response action(s)
+responseSchemaCount - Number of Response actions that define output schemas
+```
+
+> The request body schema is in `requestSchema` (not `triggerSchema`).
+
+### `get_live_flow_trigger_url`
+
+Deprecated. Prefer `trigger_live_flow` when you need to invoke an HTTP-triggered
+flow; it fetches the current callback URL internally.
+
+Returns the signed callback URL for HTTP-triggered flows. Response includes
+`flowKey`, `triggerName`, `triggerType`, `triggerKind`, `triggerMethod`, `triggerUrl`.
+
+### `trigger_live_flow`
+
+Response keys: `flowKey`, `triggerName`, `triggerUrl`, `requiresAadAuth`, `authType`,
+`responseStatus`, `responseBody`.
+
+> **Only works for `Request` (HTTP) triggers.** Returns an error for Recurrence
+> and other trigger types: `"only HTTP Request triggers can be invoked via this tool"`.
+> `Button`-kind triggers return `ListCallbackUrlOperationBlocked`.
+>
+> `responseStatus` + `responseBody` contain the flow's Response action output.
+> AAD-authenticated triggers are handled automatically.
+>
+> **Content-type note**: The body is sent as `application/octet-stream` (raw),
+> not `application/json`. Flows with a trigger schema that has `required` fields
+> will reject the request with `InvalidRequestContent` (400) because PA validates
+> `Content-Type` before parsing against the schema. Flows without a schema, or
+> flows designed to accept raw input (e.g. Baker-pattern flows that parse the body
+> internally), will work fine. The flow receives the JSON as base64-encoded
+> `$content` with `$content-type: application/octet-stream`.
+
+---
+
+## Flow State Management
+
+### `set_live_flow_state`
+
+Start or stop a Power Automate flow via the live PA API. Does **not** require
+a Power Clarity workspace — works for any flow the impersonated account can access.
+Reads the current state first and only issues the start/stop call if a change is
+actually needed.
+
+Parameters: `environmentName`, `flowName`, `state` (`"Started"` | `"Stopped"`) — all required.
+
+Response:
+```json
+{
+  "flowName": "6321ab25-7eb0-42df-b977-e97d34bcb272",
+  "environmentName": "Default-26e65220-...",
+  "requestedState": "Started",
+  "actualState": "Started"
+}
+```
+
+> **Use this tool** — not `update_live_flow` — to start or stop a flow.
+> `update_live_flow` only changes displayName/definition; the PA API ignores
+> state passed through that endpoint.
+
+### `set_store_flow_state`
+
+Start or stop a flow via the live PA API **and** persist the updated state back
+to the Power Clarity cache. Same parameters as `set_live_flow_state` but requires
+a Power Clarity workspace.
+
+Response (different shape from `set_live_flow_state`):
+```json
+{
+  "flowKey": "<environmentId>.<flowId>",
+  "requestedState": "Stopped",
+  "currentState": "Stopped",
+  "flow": { /* full gFlows record, same shape as get_store_flow */ }
+}
+```
+
+> Prefer `set_live_flow_state` when you only need to toggle state — it's
+> simpler and has no subscription requirement.
+>
+> Use `set_store_flow_state` when you need the cache updated immediately
+> (without waiting for the next daily scan) AND want the full updated
+> governance record back in the same call — useful for workflows that
+> stop a flow and immediately tag or inspect it.
+
+---
+
+## Store Tools --- FlowStudio for Teams Only
+
+### `get_store_flow_summary`
+
+Response: aggregated run statistics.
+```json
+{
+  "totalRuns": 100,
+  "failRuns": 10,
+  "failRate": 0.1,
+  "averageDurationSeconds": 29.4,
+  "maxDurationSeconds": 158.9,
+  "firstFailRunRemediation": "<hint or null>"
+}
+```
+
+### `get_store_flow_runs`
+
+Cached run history for the last N days with duration and remediation hints.
+
+### `get_store_flow_errors`
+
+Cached failed-only runs with failed action names and remediation hints.
+
+### `get_store_flow_trigger_url`
+
+Trigger URL from cache (instant, no PA API call).
+
+### `update_store_flow`
+
+Update governance metadata (description, tags, monitor flag, notification rules, business impact).
+
+### `list_store_makers` / `get_store_maker`
+
+Maker (citizen developer) discovery and detail.
+
+### `list_store_power_apps`
+
+List all Power Apps canvas apps from the cache.
+
+---
+
+## Behavioral Notes
+
+Non-obvious behaviors discovered through real API usage. These are things
+tool schemas cannot tell you.
+
+### `get_live_flow_run_action_outputs`
+- **`actionName` is optional**: omit to get top-level actions, provide to get one
+  action. For actions inside foreach loops, a named action may return multiple
+  repetitions; use `iterationIndex` to pin to one iteration.
+- Outputs can be 50 MB+ for bulk-data actions --- always use 120s+ timeout.
+
+### `update_live_flow`
+- Required fields can vary by server version; confirm with `tool_search`
+  (`select:update_live_flow`) before create/update. If `description` is required,
+  preserve the existing description when patching.
+- `error` key is **always present** in response --- `null` means success.
+  Do NOT check `if "error" in result`; check `result.get("error") is not None`.
+- On create, `created` = new flow GUID (string). On update, `created` = `false`.
+- **Cannot change flow state.** Only updates displayName, definition, and
+  connectionReferences. Use `set_live_flow_state` to start/stop a flow.
+
+### `trigger_live_flow`
+- **Only works for HTTP Request triggers.** Returns error for Recurrence, connector,
+  and other trigger types.
+- AAD-authenticated triggers are handled automatically (impersonated Bearer token).
+
+### `get_live_flow_runs`
+- `top` defaults to **30** with automatic pagination for higher values.
+- Run ID field is `name`, not `runName`. Use this value as `runName` in other tools.
+- Runs are returned newest-first.
+
+### Teams `PostMessageToConversation` (via `update_live_flow`)
+- **"Chat with Flow bot"**: `body/recipient` = `"user@domain.com;"` (string with trailing semicolon).
+- **"Channel"**: `body/recipient` = `{"groupId": "...", "channelId": "..."}` (object).
+- `poster`: `"Flow bot"` for Workflows bot identity, `"User"` for user identity.
+
+### `list_live_connections`
+- For build workflows, pass `environmentName`; omitting it inventories
+  connections across environments.
+- Use `search=<connector/account>` to get smaller output and paste-ready
+  `connectionReferenceTemplate` / `hostTemplate` values.
+- `id` is the value you need for `connectionName` in `connectionReferences`.
+- `connectorName` maps to apiId: `"/providers/Microsoft.PowerApps/apis/" + connectorName`.