feat: add FlowStudio monitoring + governance skills, update debug + build + mcp (#1304)

- **New skill: flowstudio-power-automate-monitoring** — flow health, failure
  rates, maker inventory, Power Apps, environment/connection counts via
  FlowStudio MCP cached store tools.
- **New skill: flowstudio-power-automate-governance** — 10 CoE-aligned
  governance workflows: compliance review, orphan detection, archive scoring,
  connector audit, notification management, classification/tagging, maker
  offboarding, security review, environment governance, governance dashboard.
- **Updated flowstudio-power-automate-debug** — purely live API tools (no
  store dependencies), mandatory action output inspection step, resubmit
  clarified as working for ALL trigger types.
- **Updated flowstudio-power-automate-build** — Step 1 uses list_live_flows
  (not list_store_flows) for the duplicate check, resubmit-first testing.
- **Updated flowstudio-power-automate-mcp** — store tool catalog, response
  shapes verified against real API calls, set_store_flow_state shape fix.
- Plugin version bumped to 2.0.0, all 5 skills listed in plugin.json.
- Generated docs regenerated via npm start.

All response shapes verified against real FlowStudio MCP API calls.
All 10 governance workflows validated with real tenant data.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

skills/flowstudio-power-automate-mcp/SKILL.md

@@ -1,13 +1,22 @@
 ---
 name: flowstudio-power-automate-mcp
 description: >-
-  Connect to and operate Power Automate cloud flows via a FlowStudio MCP server.
+  Give your AI agent the same visibility you have in the Power Automate portal — plus
+  a bit more. The Graph API only returns top-level run status. Flow Studio MCP exposes
+  action-level inputs, outputs, loop iterations, and nested child flow failures.
   Use when asked to: list flows, read a flow definition, check run history, inspect
   action outputs, resubmit a run, cancel a running flow, view connections, get a
   trigger URL, validate a definition, monitor flow health, or any task that requires
   talking to the Power Automate API through an MCP tool. Also use for Power Platform
   environment discovery and connection management. Requires a FlowStudio MCP
   subscription or compatible server — see https://mcp.flowstudio.app
+metadata:
+  openclaw:
+    requires:
+      env:
+        - FLOWSTUDIO_MCP_TOKEN
+    primaryEnv: FLOWSTUDIO_MCP_TOKEN
+    homepage: https://mcp.flowstudio.app
 ---
 
 # Power Automate via FlowStudio MCP
@@ -16,6 +25,10 @@ This skill lets AI agents read, monitor, and operate Microsoft Power Automate
 cloud flows programmatically through a **FlowStudio MCP server** — no browser,
 no UI, no manual steps.
 
+> **Real debugging examples**: [Expression error in child flow](https://github.com/ninihen1/power-automate-mcp-skills/blob/main/examples/fix-expression-error.md) |
+> [Data entry, not a flow bug](https://github.com/ninihen1/power-automate-mcp-skills/blob/main/examples/data-not-flow.md) |
+> [Null value crashes child flow](https://github.com/ninihen1/power-automate-mcp-skills/blob/main/examples/null-child-flow.md)
+
 > **Requires:** A [FlowStudio](https://mcp.flowstudio.app) MCP subscription (or
 > compatible Power Automate MCP server). You will need:
 > - MCP endpoint: `https://mcp.flowstudio.app/mcp` (same for all subscribers)
@@ -445,6 +458,6 @@ print(new_runs[0]["status"])   # Succeeded = done
 
 ## More Capabilities
 
-For **diagnosing failing flows** end-to-end → load the `power-automate-debug` skill.
+For **diagnosing failing flows** end-to-end → load the `flowstudio-power-automate-debug` skill.
 
-For **building and deploying new flows** → load the `power-automate-build` skill.
+For **building and deploying new flows** → load the `flowstudio-power-automate-build` skill.

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

@@ -3,7 +3,7 @@
 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 `power-automate-build` skill.
+> For full copy-paste construction patterns, see the `flowstudio-power-automate-build` skill.
 
 ---
 

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

@@ -138,7 +138,7 @@ Response: **direct array** (no wrapper).
 ]
 ```
 
-> **`id` format**: `envId.flowId` --- split on the first `.` to extract the flow UUID:
+> **`id` format**: `<environmentId>.<flowId>` --- split on the first `.` to extract the flow UUID:
 > `flow_id = item["id"].split(".", 1)[1]`
 
 ### `get_store_flow`
@@ -146,7 +146,7 @@ Response: **direct array** (no wrapper).
 Response: single flow metadata from cache (selected fields).
 ```json
 {
-  "id": "envId.flowId",
+  "id": "<environmentId>.<flowId>",
   "displayName": "My Flow",
   "state": "Started",
   "triggerType": "Recurrence",
@@ -204,7 +204,7 @@ Response:
 ```json
 {
   "created": false,
-  "flowKey": "envId.flowId",
+  "flowKey": "<environmentId>.<flowId>",
   "updated": ["definition", "connectionReferences"],
   "displayName": "My Flow",
   "state": "Started",
@@ -353,17 +353,69 @@ Response keys: `flowKey`, `triggerName`, `triggerUrl`, `requiresAadAuth`, `authT
 
 > **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. Pass `state: "Started"` or `state: "Stopped"`.
+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.
 
 ---
 
@@ -424,6 +476,8 @@ Non-obvious behaviors discovered through real API usage. These are things
 - `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,