@ericrisco/rsc 0.1.36 → 0.1.38

package/skills/power-automate/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: power-automate
+description: "Use when operating Microsoft Power Automate cloud flows programmatically — creating, enabling, updating, listing or deleting flows through the Dataverse Web API (the workflow table, category 5) with Entra ID / OAuth2 auth, or reading action-level run history via the third-party FlowStudio MCP. Triggers: 'create a Power Automate cloud flow with the Dataverse API', 'enable my flow by code / set statecode to 1', 'why can't I create or edit a My Flow programmatically', 'PATCH the workflow clientdata', 'automatizar el despliegue de un flujo de Power Automate desde código'. NOT designing the flow or authoring its definition (automation-flows), NOT choosing a platform by billing model (automation-strategy), NOT a generic typed REST client with auth/pagination/backoff (api-connector-builder), NOT the endpoint receiving an HTTP-trigger POST in your app (webhooks), NOT scripting Microsoft 365 / Graph mail & calendar directly (no first-party skill — api-connector-builder, or google-workspace)."
+tags: [power-automate, dataverse, microsoft, flows, entra, oauth, mcp, m365, automation]
+recommends: [automation-flows, automation-strategy, api-connector-builder, webhooks]
+profiles: [full]
+origin: risco
+---
+
+# Power Automate — operate cloud flows through Dataverse, honestly
+
+Drive Microsoft Power Automate **cloud flows** from code: create, enable, update, list, and delete them, plus pull run history for debugging. This skill operates the *live* surface. Deciding what the flow should do and shaping its trigger→actions→error definition is design — that lives in `../automation-flows/SKILL.md`; this skill wraps that definition, ships it, and manages it.
+
+Read these three facts before you write a line — they set the boundary of what is even possible:
+
+1. **Only flows inside a Dataverse *solution* are code-manageable.** Classic personal **"My Flows"** cannot be created or edited by code — the Microsoft docs say so explicitly. If the target is a My Flow, the honest answer is: move it into a solution first, or drive it by hand. There is no API workaround.
+2. **`api.flow.microsoft.com` is unsupported.** Microsoft's own words: use it "at your own risk," it is subject to breaking changes. The supported programmatic surface is the **Dataverse Web API** (or the .NET SDK) against the `workflow` table. For admin-style operations the **Power Automate Management** connector is the other supported path.
+3. **The unified Power Platform API (`api.powerplatform.com`) is maturing fast.** It already lists cloud flows (api-version `2024-10-01`) and its Inventory API went GA in early 2026. It may eventually supersede the Dataverse path for flow management. Treat the Dataverse-vs-Power-Platform-API split as fast-moving — verify the current recommendation at author time.
+
+## Connect first — API vs MCP
+
+Everything runs against your org's Dataverse Web API. **Base URL:** `https://{org}.{region}.dynamics.com/api/data/v9.2` (find yours under Power Platform admin → your environment → developer resources). Auth is **OAuth2 / Entra ID** — a user token or, for CI, a **service principal** (app registration). For a service principal the org needs a **Dataverse application user** mapped to that app plus a security role; the token audience is the Dataverse URL. Full setup, including the delegated `user_impersonation` vs app `.default` scope split and the 401/403 causes, is in `references/entra-auth-setup.md`.
+
+Put these in `.env` (never inline a secret in a flow or a script):
+
+```
+PA_DATAVERSE_URL=https://contoso.crm.dynamics.com   # no trailing slash, no /api/...
+PA_TENANT_ID=<entra-tenant-guid>
+PA_CLIENT_ID=<app-registration-client-id>
+PA_CLIENT_SECRET=<app-registration-secret>          # service-principal flow only
+```
+
+**When to use the REST API vs the MCP:**
+
+| You need to… | Use | Why |
+|---|---|---|
+| Create / enable / update / delete / list flows | **Dataverse Web API** | The only supported CRUD surface; scriptable, CI-friendly, service-principal auth. |
+| Read a flow's **action-level** run inputs/outputs to debug a failure | **FlowStudio MCP** (third-party) | Dataverse exposes run *records* (`flowrun` table) but not per-action I/O; the MCP does. See `references/flowstudio-mcp-and-limits.md`. |
+| Admin-scope operations (turn on/off across an environment) | Power Automate **Management** connector | Supported management surface when raw Dataverse is awkward. |
+
+**FlowStudio MCP is NOT Microsoft-affiliated** — it is a de-facto third-party server (`mcp.flowstudio.app/mcp`). Microsoft's own MCP story is Copilot Studio *consuming* MCP servers and a Dataverse MCP, neither of which authors Power Automate flows. Flag the third-party dependency to anyone before wiring it into a pipeline.
+
+## The `workflow` table — the data model
+
+Cloud flows are rows in the Dataverse **Process (`workflow`)** table. The columns that matter:
+
+| Column | Meaning | Values you use |
+|---|---|---|
+| `category` | Kind of process | **`5` = modern cloud flow** (automated / instant / scheduled). (0 classic workflow, 4 business process flow, 6 desktop flow.) |
+| `type` | Definition vs template | **`1` = Definition** (a runnable flow). |
+| `statecode` | On/off state | **`0` = Draft (Off)**, **`1` = Activated (On)**, `2` = Suspended. |
+| `name` | Display name | your string |
+| `primaryentity` | Bound table | **`"none"`** for automated/instant/scheduled flows |
+| `clientdata` | The flow itself | **string-encoded JSON** (see below) |
+| `workflowid` | GUID key | returned on create; used in `workflows({id})` |
+
+List the cloud flows that are on:
+
+```bash
+curl -s "$PA_DATAVERSE_URL/api/data/v9.2/workflows?\$filter=category eq 5 and statecode eq 1&\$select=name,statecode,type,workflowid" \
+  -H "Authorization: Bearer $TOKEN" -H "OData-Version: 4.0" -H "Accept: application/json"
+```
+
+## `clientdata` — the payload, and the trap that bites everyone
+
+`clientdata` is **a JSON string, not a nested JSON object.** It is the serialized form of:
+
+```json
+{
+  "properties": {
+    "connectionReferences": { "shared_commondataserviceforapps": { "runtimeSource": "embedded", "connection": {}, "api": { "name": "shared_commondataserviceforapps" } } },
+    "definition": { "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#", "contentVersion": "1.0.0.0", "triggers": { }, "actions": { } }
+  },
+  "schemaVersion": "1.0.0.0"
+}
+```
+
+Two load-bearing parts:
+
+- **`definition`** — a Logic Apps workflow definition: `triggers` (exactly one) then `actions`. This is the *design* artifact. Do not invent it from scratch here — get the trigger→actions→branch→error shape from `../automation-flows/SKILL.md`, then drop it into `definition`. Fastest reliable way to get a real one: build the flow once in the maker portal, export the solution, and copy its `clientdata`.
+- **`connectionReferences`** — the map from the definition's connectors to actual connections. **A flow whose connection references are not authorized will not turn on.** In a solution these are connection-reference records the target environment must resolve; unresolved references are the #1 reason a `PATCH statecode=1` "succeeds" but the flow never runs.
+
+**The trap:** `clientdata` must be *escaped into a string* before it goes in the request body — a nested object is rejected. In a script, `JSON.stringify(clientDataObject)` and assign the result; do not paste the object raw. Full annotated example in `references/dataverse-web-api.md`.
+
+## Dynamic lifecycle — token → create → validate → enable → manage → delete
+
+**1. Get a token** (service-principal / client-credentials shown):
+
+```bash
+TOKEN=$(curl -s -X POST "https://login.microsoftonline.com/$PA_TENANT_ID/oauth2/v2.0/token" \
+  -d "grant_type=client_credentials" -d "client_id=$PA_CLIENT_ID" \
+  -d "client_secret=$PA_CLIENT_SECRET" -d "scope=$PA_DATAVERSE_URL/.default" \
+  | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])")
+```
+
+**2. Create the flow** (comes up `statecode=0`, Off — expected):
+
+```bash
+curl -s -i -X POST "$PA_DATAVERSE_URL/api/data/v9.2/workflows" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -H "OData-Version: 4.0" \
+  -d '{ "category": 5, "type": 1, "name": "Nightly sync", "primaryentity": "none", "clientdata": "<string-encoded JSON>" }'
+# → 204 No Content. The workflowid is in the OData-EntityId response header:
+#   OData-EntityId: .../workflows(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)
+```
+
+**3. Validate before enabling.** Read it back, confirm `category`/`type` are right, and confirm every `connectionReferences` entry resolves to an authorized connection in this environment. Enabling a flow with dangling connections is the classic silent failure.
+
+**4. Enable** — flip `statecode` to `1` (use `If-Match: *` for the update):
+
+```bash
+curl -s -X PATCH "$PA_DATAVERSE_URL/api/data/v9.2/workflows(<workflowid>)" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -H "OData-Version: 4.0" -H "If-Match: *" \
+  -d '{ "statecode": 1 }'
+# → 204 No Content
+```
+
+**5. Manage** — update the definition or owner with the same `PATCH` (send only the fields you change; to reassign use `"ownerid@odata.bind": "systemusers(<id>)"`). To turn a flow off, `PATCH statecode=0`.
+
+**6. Delete — irreversible; export first.** There is no undo on `DELETE`. **Before deleting, export the containing solution** (`POST /api/data/v9.2/ExportSolution` → base64 zip you save to source control), so the flow can be reimported:
+
+```bash
+curl -s -X DELETE "$PA_DATAVERSE_URL/api/data/v9.2/workflows(<workflowid>)" \
+  -H "Authorization: Bearer $TOKEN"
+# → 204 No Content
+```
+
+**Debug a run** — Dataverse's `flowrun` table lists run records but not per-action I/O. To see *which action failed and with what payload*, use FlowStudio MCP: `list_live_flows` → `get_live_flow_runs` → `get_live_flow_run_action_outputs`. See `references/flowstudio-mcp-and-limits.md`.
+
+## Microsoft 365 ecosystem fit
+
+Power Automate is Microsoft's iPaaS across M365 and Dynamics; flows live in **Dataverse** and glue Outlook, Teams, SharePoint, Dynamics, and hundreds of connectors. That means the boundary is sharp: if the ask is *"send this email / read this calendar via Microsoft Graph from my own backend code,"* that is not a flow at all — build a typed Graph client with `../api-connector-builder/SKILL.md` (there is no first-party MS-Graph skill). If the equivalent is on Google, that is `../google-workspace/SKILL.md`. This skill is for when the automation genuinely *is* a Power Automate flow you must operate by code.
+
+## Honesty / gotchas
+
+| Trap | Why it bites | Do instead |
+|---|---|---|
+| Trying to CRUD a **My Flow** by code | Unsupported — silently impossible, not a bug you can fix | Move it into a Dataverse solution, or drive it by hand |
+| `clientdata` sent as a nested object | Request rejected; the column expects an escaped **string** | Serialize (`JSON.stringify`) the definition+connectionReferences before sending |
+| `PATCH statecode=1` "worked" but the flow never runs | Connection references unresolved/unauthorized in the target environment | Authorize every connection reference before enabling; validate on read-back |
+| Building against `api.flow.microsoft.com` | Unsupported; breaks without warning | Dataverse Web API, or the Power Automate Management connector |
+| `DELETE` with no export | No undo; the flow and its history are gone | `ExportSolution` first, save the zip, then delete |
+| Hardcoding the Dataverse URL / secret | Env-specific, leaks in source | `.env`: `PA_DATAVERSE_URL`, `PA_TENANT_ID`, `PA_CLIENT_ID`, `PA_CLIENT_SECRET` |
+| Assuming the Dataverse path is permanent | Power Platform API is superseding surfaces piecemeal | Re-check `api.powerplatform.com` coverage at author time; the split is fast-moving |
+
+## Related skills
+
+- **`../automation-flows/SKILL.md`** — design side: what the trigger→actions→branch→error should be, the importable definition. This skill *consumes* that shape as `clientdata.definition`. Design there, operate here.
+- **`../automation-strategy/SKILL.md`** — choosing Power Automate vs n8n/Make/Zapier by billing and constraints. Decide there before you commit to operating here.
+- **`../api-connector-builder/SKILL.md`** — a generic typed REST client with auth/pagination/backoff (including a Dataverse or MS Graph client). This skill uses the Dataverse API surgically; it does not build a general client.
+- **`../webhooks/SKILL.md`** — building the inbound endpoint in *your* app that receives a flow's HTTP-trigger POST. This skill triggers/operates flows; it does not build the receiver.
+
+## Checklist
+
+- [ ] `.env` set: `PA_DATAVERSE_URL` (no trailing slash), `PA_TENANT_ID`, `PA_CLIENT_ID`, `PA_CLIENT_SECRET`.
+- [ ] Confirmed the target is a **solution-aware** flow, not a My Flow.
+- [ ] Token acquired against scope `{PA_DATAVERSE_URL}/.default` (or delegated `user_impersonation`).
+- [ ] Create payload has `category:5`, `type:1`, `primaryentity:"none"`, and `clientdata` as an **escaped string**.
+- [ ] Every `connectionReferences` entry maps to an authorized connection before enabling.
+- [ ] Flow enabled via `PATCH statecode=1` and verified on read-back.
+- [ ] Solution **exported** before any `DELETE`.
+- [ ] No secrets or org URLs hardcoded; FlowStudio MCP (if used) flagged as third-party.
+
+## References
+
+- `references/dataverse-web-api.md` — endpoint cheat-sheet (token, list/filter, create, enable, update, delete, ExportSolution, share), the full annotated `clientdata`, OData headers, and error handling.
+- `references/entra-auth-setup.md` — app registration, service principal vs delegated user, the Dataverse application user + security role, `.default` vs `user_impersonation`, and common 401/403 causes.
+- `references/flowstudio-mcp-and-limits.md` — FlowStudio MCP tools and auth (third-party), what it exposes that Dataverse doesn't, and the platform limits (My Flows, `api.flow.microsoft.com`, Power Platform API evolution).

package/skills/power-automate/evals/README.md

@@ -0,0 +1,17 @@
+# Evals — power-automate
+
+`cases.yaml` has three groups. `should_trigger` covers the programmatic operate cases: create+enable
+via the Dataverse Web API, the My-Flows honesty question, enable-via-statecode, a Spanish
+solution-aware CI deploy, FlowStudio-MCP run debugging, and a clientdata update. `should_not_trigger`
+lists adjacent prompts owned by a named sibling — flow *design*/definition (automation-flows),
+platform selection by billing (automation-strategy), generic typed-client engineering
+(api-connector-builder), the inbound webhook receiver (webhooks), and direct Microsoft Graph
+scripting (api-connector-builder, no first-party MS-Graph skill). `capability` is one end-to-end
+lifecycle scenario whose `must_include` rubric checks the concrete API calls (token, POST, PATCH
+statecode, DELETE), the string-encoded `clientdata`, the My-Flows/`api.flow.microsoft.com` honesty
+limits, the ExportSolution-before-DELETE irreversibility rule, and the third-party FlowStudio-MCP
+flag.
+
+No automated runner. Score by judgement: feed each `should_trigger` / `should_not_trigger` prompt to
+the routing layer and confirm it activates (or routes to the listed sibling); for `capability`, have
+the skill produce the lifecycle walkthrough and check every `must_include` bullet by hand.

package/skills/power-automate/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: power-automate
+
+should_trigger:
+  - prompt: "Create a Power Automate cloud flow via the Dataverse Web API and turn it on from my deploy script."
+    why: Canonical programmatic operate — POST /workflows (category 5) then enable via statecode; the core deliverable.
+  - prompt: "Why can't I edit my flow under 'My Flows' with the API? Every call I make fails."
+    why: The load-bearing honesty limit — My Flows are not code-manageable; must route to the solution-aware answer.
+  - prompt: "Enable my Power Automate flow by code — set statecode to 1 after I create it."
+    why: Enable-via-statecode is the explicit lifecycle step new flows come up Off (0) and need PATCH to 1.
+  - prompt: "Automatizar el despliegue de un flujo de Power Automate dentro de una solución de Dataverse desde CI."
+    why: Spanish; solution-aware programmatic deployment with a service principal — squarely this skill.
+  - prompt: "Use FlowStudio MCP to pull the action-level inputs and outputs of my flow's last failed run."
+    why: MCP run-history debugging that the Dataverse API doesn't expose per action — the MCP path this skill owns.
+  - prompt: "PATCH the clientdata of an existing workflow row to update the flow's definition."
+    why: Update lifecycle against the workflow table, including the clientdata string-encoding concern.
+
+should_not_trigger:
+  - prompt: "Design a 'new Stripe payment → post to Teams' automation and give me the importable definition."
+    route_to: automation-flows
+    why: Designing what the flow does and authoring its definition is the design skill; this one operates a definition, it doesn't invent it.
+  - prompt: "Should I use Power Automate or n8n for about 50k runs a month?"
+    route_to: automation-strategy
+    why: Platform selection by billing/constraints, not operating a live Power Automate flow.
+  - prompt: "Write a typed TypeScript client for the Dataverse Web API with token refresh, pagination, and exponential backoff."
+    route_to: api-connector-builder
+    why: Generic client engineering (auth/pagination/retry) even though the API is Dataverse; this skill uses endpoints surgically, it doesn't build the client.
+  - prompt: "Build the Express endpoint that receives my flow's HTTP-trigger POST and verifies it."
+    route_to: webhooks
+    why: Building the inbound receiver in your own app; this skill operates/triggers flows, it does not build the receiver.
+  - prompt: "Send an email and read a calendar via Microsoft Graph from my Node backend."
+    route_to: api-connector-builder
+    why: Scripting Microsoft 365 via Graph directly is not a Power Automate flow; no first-party MS-Graph skill, so build a typed Graph client.
+
+capability:
+  - scenario: "User has an Entra app registration and wants to create an automated cloud flow inside a Dataverse solution, enable it, later update its definition, and finally remove it safely. Walk the full programmatic lifecycle."
+    must_include:
+      - "Acquire an Entra OAuth2 token from https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token (client_credentials) with scope {PA_DATAVERSE_URL}/.default."
+      - "POST /api/data/v9.2/workflows with category=5, type=1, primaryentity=\"none\", name, and clientdata as a STRING-encoded JSON (definition + connectionReferences), not a nested object."
+      - "State the honesty limit: only flows inside a Dataverse solution are code-manageable; classic My Flows cannot be created or edited by code."
+      - "New flow comes up statecode=0 (Off); enable with PATCH workflows({workflowid}) statecode=1 using If-Match: *; validate connection references resolve before enabling."
+      - "Update via PATCH (send only changed fields), and note api.flow.microsoft.com is unsupported — use the Dataverse Web API or the Power Automate Management connector; flag api.powerplatform.com as an evolving alternative."
+      - "Irreversibility rule: ExportSolution to a saved base64 zip BEFORE DELETE workflows({workflowid}) — deletion has no undo."
+      - "For action-level run debugging use the third-party FlowStudio MCP (get_live_flow_run_action_outputs), flagged as NOT Microsoft-affiliated."

package/skills/power-automate/references/dataverse-web-api.md

@@ -0,0 +1,187 @@
+# Dataverse Web API — cloud-flow cheat-sheet
+
+The supported programmatic surface for Power Automate cloud flows. Base URL:
+`https://{org}.{region}.dynamics.com/api/data/v9.2` (your `PA_DATAVERSE_URL` + `/api/data/v9.2`).
+Cloud flows are rows in the **Process (`workflow`)** table, exposed as the `workflows` entity set.
+
+All examples assume `$TOKEN` holds an Entra bearer token (see `entra-auth-setup.md`) and
+`$PA_DATAVERSE_URL` is set without a trailing slash.
+
+## Standard OData headers
+
+Send these on requests (the API is OData v4):
+
+```
+Authorization: Bearer <token>
+Content-Type: application/json          # on POST/PATCH
+Accept: application/json
+OData-MaxVersion: 4.0
+OData-Version: 4.0
+If-Match: *                             # on PATCH (update)
+Prefer: odata.include-annotations="*"   # optional; adds FormattedValue / lookuplogicalname to reads
+```
+
+`$` in query options must be escaped as `\$` in a shell to stop the shell expanding it.
+
+## Column reference (workflow table)
+
+| Column | Type | Notes |
+|---|---|---|
+| `category` | choice | `0` classic workflow · `1` dialog · `2` business rule · `3` classic action · `4` business process flow · **`5` modern cloud flow** · `6` desktop flow |
+| `type` | choice | **`1` Definition** (runnable) · `2` Activation · `3` Template |
+| `statecode` | choice | **`0` Draft/Off** · **`1` Activated/On** · `2` Suspended |
+| `name` | string | display name |
+| `description` | string | optional |
+| `primaryentity` | string | `"none"` for automated/instant/scheduled flows |
+| `clientdata` | string | escaped-JSON: `properties.definition` + `properties.connectionReferences` |
+| `ismanaged` | bool | true if installed from a managed solution |
+| `workflowid` | guid | key used in `workflows({id})` |
+| `_ownerid_value` | lookup | owner; set via `ownerid@odata.bind` on write |
+
+## List / read
+
+```bash
+# All cloud flows that are currently on
+curl -s "$PA_DATAVERSE_URL/api/data/v9.2/workflows?\$filter=category eq 5 and statecode eq 1&\$select=name,statecode,type,workflowid&\$top=50" \
+  -H "Authorization: Bearer $TOKEN" -H "OData-Version: 4.0" -H "Accept: application/json"
+
+# One flow with its clientdata
+curl -s "$PA_DATAVERSE_URL/api/data/v9.2/workflows(<workflowid>)?\$select=name,statecode,clientdata" \
+  -H "Authorization: Bearer $TOKEN" -H "OData-Version: 4.0"
+```
+
+## Create
+
+Required properties for automated/instant/scheduled flows: `category`, `name`, `type`,
+`primaryentity`, `clientdata`.
+
+```bash
+curl -s -i -X POST "$PA_DATAVERSE_URL/api/data/v9.2/workflows" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "OData-Version: 4.0" \
+  -d '{
+        "category": 5,
+        "type": 1,
+        "name": "Sample flow name",
+        "description": "Reads some data from Dataverse.",
+        "primaryentity": "none",
+        "clientdata": "<escaped JSON string>"
+      }'
+```
+
+Response is `204 No Content`. The new `workflowid` is in the **`OData-EntityId`** response header:
+`OData-EntityId: .../workflows(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)`. New flows are always
+`statecode=0` (Off) — you must enable them.
+
+### The `clientdata` string, unescaped for reading
+
+`clientdata` is the *string* form of this object. Serialize it (`JSON.stringify`) before assigning
+it to the property — a nested object is rejected.
+
+```json
+{
+  "properties": {
+    "connectionReferences": {
+      "shared_commondataserviceforapps": {
+        "runtimeSource": "embedded",
+        "connection": {},
+        "api": { "name": "shared_commondataserviceforapps" }
+      }
+    },
+    "definition": {
+      "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
+      "contentVersion": "1.0.0.0",
+      "parameters": {
+        "$connections": { "defaultValue": {}, "type": "Object" },
+        "$authentication": { "defaultValue": {}, "type": "SecureObject" }
+      },
+      "triggers": {
+        "manual": {
+          "type": "Request", "kind": "Button",
+          "inputs": { "schema": { "type": "object", "properties": {}, "required": [] } }
+        }
+      },
+      "actions": {
+        "List_rows": {
+          "runAfter": {},
+          "type": "OpenApiConnection",
+          "inputs": {
+            "host": {
+              "apiId": "/providers/Microsoft.PowerApps/apis/shared_commondataserviceforapps",
+              "connectionName": "shared_commondataserviceforapps",
+              "operationId": "ListRecords"
+            },
+            "parameters": { "entityName": "accounts", "$select": "name", "$top": 1 },
+            "authentication": "@parameters('$authentication')"
+          }
+        }
+      }
+    }
+  },
+  "schemaVersion": "1.0.0.0"
+}
+```
+
+- `definition` — a Logic Apps workflow definition (`triggers`, exactly one; then `actions`). Design
+  this in `../../automation-flows/SKILL.md`, or export a hand-built flow's solution and copy its
+  `clientdata`. Do not hand-write a complex definition blind.
+- `connectionReferences` — maps each connector the definition uses to a connection. **Unresolved /
+  unauthorized references mean the flow cannot turn on** even though `PATCH statecode=1` returns 204.
+
+## Enable / update
+
+```bash
+# Enable (turn on)
+curl -s -X PATCH "$PA_DATAVERSE_URL/api/data/v9.2/workflows(<workflowid>)" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -H "OData-Version: 4.0" -H "If-Match: *" \
+  -d '{ "statecode": 1 }'
+
+# Update definition + reassign owner (send only changed fields)
+curl -s -X PATCH "$PA_DATAVERSE_URL/api/data/v9.2/workflows(<workflowid>)" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -H "OData-Version: 4.0" -H "If-Match: *" \
+  -d '{ "clientdata": "<escaped JSON string>", "ownerid@odata.bind": "systemusers(<systemuserid>)" }'
+```
+
+To turn a flow off: `PATCH { "statecode": 0 }`.
+
+## Export (do this before delete)
+
+```bash
+curl -s -X POST "$PA_DATAVERSE_URL/api/data/v9.2/ExportSolution" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "OData-Version: 4.0" \
+  -d '{ "SolutionName": "FlowContainer", "Managed": false }'
+# → 200 with { "ExportSolutionFile": "<base64 zip>" }. Save it to source control.
+```
+
+Reimport later with the `ImportSolution` action (`CustomizationFile` = the base64 zip,
+`OverwriteUnmanagedCustomizations: true`).
+
+## Delete (irreversible)
+
+```bash
+curl -s -X DELETE "$PA_DATAVERSE_URL/api/data/v9.2/workflows(<workflowid>)" \
+  -H "Authorization: Bearer $TOKEN"
+# → 204 No Content. No undo — always ExportSolution first.
+```
+
+## Run history
+
+The `flowrun` table holds run *records* (status, start/end) but not per-action inputs/outputs.
+Query it for a status overview; for action-level payloads use FlowStudio MCP
+(`flowstudio-mcp-and-limits.md`).
+
+## Sharing
+
+`RetrieveSharedPrincipalsAndAccess` (who a flow is shared with), `GrantAccess` / `ModifyAccess` /
+`RevokeAccess` — standard Dataverse record-sharing messages, called as Web API actions.
+
+## Error handling
+
+- `401` — token missing/expired or wrong audience/scope. Re-acquire; confirm scope is
+  `{PA_DATAVERSE_URL}/.default`.
+- `403` — authenticated but the (application) user lacks a Dataverse security role, or the flow is a
+  My Flow / outside a solution you can touch.
+- `404` on `workflows({id})` — wrong id, or the flow isn't in Dataverse (My Flow).
+- `400` on create — almost always `clientdata` sent as an object instead of an escaped string, or a
+  missing required property.

package/skills/power-automate/references/entra-auth-setup.md

@@ -0,0 +1,75 @@
+# Entra ID / OAuth2 setup for the Dataverse Web API
+
+The Dataverse Web API accepts only OAuth2 bearer tokens from **Microsoft Entra ID**. Two flows:
+
+- **Delegated (a user signs in)** — the token carries a real user's permissions. Scope:
+  `{PA_DATAVERSE_URL}/user_impersonation`. Good for local/interactive work.
+- **Application / service principal (client credentials)** — no user; a headless identity for CI.
+  Scope: `{PA_DATAVERSE_URL}/.default`. This is the CI-friendly path and what the SKILL curl uses.
+
+The **token audience is your org's Dataverse URL** (`PA_DATAVERSE_URL`), not Graph, not
+`api.flow.microsoft.com`.
+
+## App registration (both flows)
+
+1. Entra admin center → **App registrations → New registration**. Note the **Application (client)
+   ID** (`PA_CLIENT_ID`) and **Directory (tenant) ID** (`PA_TENANT_ID`).
+2. **API permissions → Add → Dynamics CRM → `user_impersonation`** (delegated). Grant admin consent.
+3. For the service-principal flow, create a **client secret** (`PA_CLIENT_SECRET`) under
+   *Certificates & secrets*. (A certificate is preferable in production; a secret is fine to start.)
+
+## Dataverse application user (service-principal flow only)
+
+A service principal cannot touch Dataverse until it exists there as an **application user**:
+
+1. Power Platform admin center → your **environment → Settings → Users + permissions →
+   Application users → New app user**.
+2. Add the app registration by its **client ID**.
+3. Assign a **security role** with privileges on the Process (`workflow`) table (e.g. a role that can
+   read/create/write/delete processes, such as *System Customizer* scoped appropriately, or a custom
+   role). Without a role every call returns `403`.
+
+## Get a token
+
+Delegated (device code / auth code — pattern shown as client-credentials substitute for headless):
+
+```bash
+# Service principal (client credentials)
+curl -s -X POST "https://login.microsoftonline.com/$PA_TENANT_ID/oauth2/v2.0/token" \
+  -d "grant_type=client_credentials" \
+  -d "client_id=$PA_CLIENT_ID" \
+  -d "client_secret=$PA_CLIENT_SECRET" \
+  -d "scope=$PA_DATAVERSE_URL/.default"
+# → { "access_token": "...", "expires_in": 3599, "token_type": "Bearer" }
+```
+
+For the delegated flow use the same `/oauth2/v2.0/token` endpoint with `grant_type=authorization_code`
+(after an interactive `/authorize` redirect) and `scope={PA_DATAVERSE_URL}/user_impersonation
+offline_access`. Tokens last ~1 hour; cache and refresh — do not mint one per request.
+
+## `.env`
+
+```
+PA_DATAVERSE_URL=https://contoso.crm.dynamics.com   # no trailing slash, no /api/data/...
+PA_TENANT_ID=<tenant-guid>
+PA_CLIENT_ID=<app-client-id>
+PA_CLIENT_SECRET=<app-secret>                        # service-principal flow only
+```
+
+Never commit the secret; never inline it in a flow definition or a script.
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `401 Unauthorized` | wrong scope/audience, or expired token | scope must be `{PA_DATAVERSE_URL}/.default` (app) or `/user_impersonation` (delegated); re-acquire |
+| `403 Forbidden` on every call | app user missing, or no security role | create the Dataverse application user and assign a role with `workflow` privileges |
+| `403` only on some flows | those are My Flows / outside your solution | only solution-aware flows are code-manageable |
+| `AADSTS700016` | client ID not found in tenant | check `PA_TENANT_ID` / `PA_CLIENT_ID` |
+| token works for Graph, `401` here | audience is Graph, not Dataverse | request the token for the Dataverse resource, not Graph |
+
+## Generic client engineering
+
+Token caching/refresh, retry/backoff on `429`, and pagination via `@odata.nextLink` are generic
+concerns — build them once with `../../api-connector-builder/SKILL.md` rather than re-inventing per
+script. This skill uses the endpoints; that skill engineers the client around them.

package/skills/power-automate/references/flowstudio-mcp-and-limits.md

@@ -0,0 +1,62 @@
+# FlowStudio MCP + platform limits
+
+## FlowStudio MCP — third-party, not Microsoft
+
+There is **no Microsoft first-party MCP server that authors Power Automate flows.** Microsoft's MCP
+story is Copilot Studio *consuming* MCP servers, and a Dataverse MCP — neither builds/edits flows.
+
+The de-facto tool is **FlowStudio MCP**, an independent third party. Flag this to anyone before it
+enters a pipeline: it is **not Microsoft-affiliated**, it is a paid hosted service, and it sits
+between your tenant and your agent.
+
+- **Endpoint:** `https://mcp.flowstudio.app/mcp` (remote MCP).
+- **Auth:** an `x-api-key` header. The key is issued after you sign in with your Microsoft account
+  and grant Power Platform scopes to FlowStudio (delegated). Verify the exact scope list and pricing
+  at author time — the free tier is a small monthly call allowance.
+- **Why use it:** it exposes what the Dataverse Web API does **not** — **action-level run inputs and
+  outputs**, so you can see which step in a live run failed and with what payload.
+
+### Representative tools (verify the live list — 30+ tools, evolving)
+
+| Tool | Does |
+|---|---|
+| `list_live_flows` | List flows in the tenant, filterable by name |
+| `get_live_flow` | Read a flow's configuration/definition |
+| `get_live_flow_runs` | Recent run history for a flow (status, timing) |
+| `get_live_flow_run_action_outputs` | **Per-action inputs/outputs of a run** — the debugging payload |
+| `update_live_flow` | Modify a live flow |
+
+Typical debug loop: `list_live_flows` (find it) → `get_live_flow_runs` (find the failed run) →
+`get_live_flow_run_action_outputs` (see the failing action's payload). For plain CRUD and enablement,
+prefer the supported Dataverse Web API — reserve the MCP for the run-history depth it uniquely gives.
+
+## Platform limits — teach these loudly
+
+1. **My Flows are not code-manageable.** Only flows inside a **Dataverse solution** can be created or
+   edited by code. Microsoft's docs state managing **My Flows** is not supported programmatically. If
+   the target is a My Flow: move it into a solution in the maker portal first, or drive it by hand.
+   There is no API that lets you CRUD a classic personal flow.
+
+2. **`api.flow.microsoft.com` is unsupported.** Microsoft's exact stance: usable "at your own risk,"
+   subject to breaking changes. Do not build on it. Supported alternatives:
+   - **Dataverse Web API** (this skill's default) — full CRUD on the `workflow` table.
+   - **Power Automate Management** connector (or **Power Automate for Admins**) — the supported
+     management surface for turning flows on/off and admin operations across an environment.
+
+3. **The Power Platform API is superseding surfaces — fast-moving.** `api.powerplatform.com` is a
+   unified surface with its own Entra scopes. As of early 2026 it lists cloud flows
+   (`GET https://api.powerplatform.com/powerautomate/environments/{environmentId}/cloudFlows`,
+   api-version `2024-10-01`) and its **Inventory API is GA**. It may eventually be the recommended
+   management path over Dataverse. **Re-check its coverage at author time** before committing a new
+   project to either surface — this is the single most likely fact to have moved since this was
+   written.
+
+## What lives where
+
+| Need | Surface |
+|---|---|
+| Create / enable / update / delete / list flows | Dataverse Web API (`workflow` table) |
+| Turn on/off, admin ops across an environment | Power Automate Management connector |
+| Action-level run inputs/outputs for debugging | FlowStudio MCP (third-party) |
+| Emerging unified management (evolving) | Power Platform API (`api.powerplatform.com`) |
+| Anything on `api.flow.microsoft.com` | unsupported — avoid |