@ericrisco/rsc 0.1.37 → 0.1.39

package/skills/n8n/references/auth-and-selfhost.md

@@ -0,0 +1,62 @@
+# n8n auth, self-host vs cloud, and pointing n8n-mcp
+
+## Get an API key
+
+1. In n8n, open **Settings → n8n API**.
+2. **Create an API key.** Prefer a **scoped** key — pick only the resource scopes the automation needs
+   (e.g. `workflow:read`, `workflow:create`, `workflow:execute`, `execution:read`). An unscoped key can
+   do everything the user can, including delete.
+3. Copy it once (it is shown once) and store it as `N8N_API_KEY`. Rotate by deleting + recreating.
+
+Every REST call carries it as a header: `X-N8N-API-KEY: <key>`. It is NOT a bearer token and NOT in
+the query string.
+
+```bash
+export N8N_API_KEY="n8n_api_..."
+export N8N_API_URL="https://your-instance.app.n8n.cloud"   # host root; append /api/v1 for REST
+```
+
+## Self-host vs cloud — what actually differs
+
+| | Self-host | Cloud (`*.app.n8n.cloud`) |
+|---|---|---|
+| API base | `{host}/api/v1` (e.g. `http://localhost:5678/api/v1`) | `https://<tenant>.app.n8n.cloud/api/v1` |
+| API surface | **identical** | **identical** |
+| Interactive Swagger | **Yes** at `/api/v1/docs` | **No** — work from docs.n8n.io |
+| Where data lives | your infra | n8n's | 
+| Enabling the API | on by default; can be toggled via `N8N_PUBLIC_API_DISABLED=true` | always on |
+| Base URL override | `WEBHOOK_URL` / `N8N_HOST`/`N8N_PROTOCOL`/`N8N_PORT` shape the host + webhook URLs | fixed |
+
+The only thing that changes between environments is the host and (self-host) the Swagger page.
+Scripts written against one work against the other by swapping `N8N_API_URL`.
+
+Webhook URLs on self-host derive from `WEBHOOK_URL` (or host/protocol/port). If your production webhook
+URLs look wrong (localhost behind a proxy), that env var is usually why.
+
+## Pointing n8n-mcp at your instance
+
+`n8n-mcp` reads the **same two env vars** for its management tier:
+
+```bash
+N8N_API_URL=https://your-instance.app.n8n.cloud
+N8N_API_KEY=n8n_api_...
+```
+
+Ways to run it:
+
+- **Hosted** — `dashboard.n8n-mcp.com`: add an instance (URL + key), get an MCP endpoint. Fastest trial;
+  free tier caps daily tool calls.
+- **Local (npx)** — run the `n8n-mcp` package and register it in your MCP client's config
+  (Claude Code / Claude Desktop / Cursor / Windsurf), passing the two env vars.
+- **Docker** — the repo ships an image; inject the env vars.
+
+Node-knowledge tools work with **no** auth; only the management tools need the two vars. Confirm the
+link with `n8n_health_check` — it reports reachability and which features (e.g. the `/execute`
+endpoint) the target instance supports.
+
+## Governance quick-set
+
+- **Scope the key** at creation (least privilege) — see above.
+- **`DISABLED_TOOLS`** on n8n-mcp to gate destructive tools — see `n8n-mcp-tools.md`.
+- **Never** commit `N8N_API_KEY` or inline node-credential secrets in a workflow payload; reference
+  credentials from the n8n credential store by id/name.

package/skills/n8n/references/n8n-mcp-tools.md

@@ -0,0 +1,84 @@
+# n8n-mcp — tool reference & governance
+
+`n8n-mcp` (github.com/czlonkowski/n8n-mcp, ~22k★, the de-facto community standard) is an MCP server
+that gives an agent two things: **offline knowledge** of n8n's node/expression catalogue, and
+**management** of a live instance via its REST API. Distinct from n8n's own first-party built-in MCP
+node, which lets a *workflow* act as an MCP server/client — that is not this.
+
+Tool names and counts move; **verify against the running server's tool list** (or
+`dashboard.n8n-mcp.com` / the repo docs) before relying on any one name.
+
+## Two tiers, two auth requirements
+
+| Tier | Needs auth? | Purpose |
+|---|---|---|
+| **Node-knowledge tools** | **No** | Search/describe nodes, get property essentials, validate a node's config, browse templates — all offline. Safe to expose broadly. |
+| **Management tools** | **Yes** — `N8N_API_URL` + `N8N_API_KEY` | CRUD/validate/test/run/inspect a real instance. These are the ones governance applies to. |
+
+Set the same two env vars the REST API uses:
+
+```bash
+N8N_API_URL=https://your-instance.app.n8n.cloud   # host root, whole value
+N8N_API_KEY=n8n_api_...
+```
+
+Without them the server still runs — you just get the node-knowledge tier only.
+
+## Node-knowledge tools (no auth)
+
+- `search_nodes`, `list_nodes`, `list_ai_tools` — find the right node.
+- `get_node_essentials`, `get_node_info`, `get_node_documentation` — properties & docs for a node type.
+- `validate_node_operation`, `validate_node_minimal` — check a single node's config before you wire it.
+- `search_templates`, `get_template` — reuse community workflow templates.
+
+Use these to author node JSON correctly instead of guessing `typeVersion`/property shapes.
+
+## Management tools (need `N8N_API_URL` + `N8N_API_KEY`)
+
+| Tool | Does |
+|---|---|
+| `n8n_create_workflow` | Create from a full workflow object. |
+| `n8n_get_workflow` | Fetch one workflow (export before delete/replace). |
+| `n8n_list_workflows` | List/filter workflows. |
+| `n8n_update_full_workflow` | Replace the whole workflow (like REST `PUT`). |
+| `n8n_update_partial_workflow` | **Atomic ordered batch of targeted edits** — if any op fails, nothing is saved. Prefer this for edits. |
+| `n8n_delete_workflow` | **Hard delete.** Export first. |
+| `n8n_validate_workflow` | Structural/connection/expression validation of a workflow object. |
+| `n8n_autofix_workflow` | Repair common errors and return fixed JSON. |
+| `n8n_test_workflow` | Trigger a run for testing. |
+| `n8n_executions` | List/inspect execution runs. |
+| `n8n_workflow_versions` | Version history of a workflow. |
+| `n8n_deploy_template` | Deploy a catalogue template to the instance. |
+| `n8n_manage_credentials` | Create/manage credentials (secrets not readable back). |
+| `n8n_manage_datatable` | Manage n8n data tables. |
+| `n8n_health_check` | Confirm API reachability + which features the instance supports. |
+| `n8n_audit_instance` | Security audit (built-in audit API + deep workflow scan). |
+
+**Note on activate/deactivate:** n8n-mcp intentionally does not surface these as tools (activation has
+live side effects). Flip a workflow live with the REST `POST /workflows/{id}/activate` endpoint (see
+`rest-api-cheatsheet.md`) or the UI. Verify the current tool list in case this changes.
+
+## Governance — `DISABLED_TOOLS`
+
+For agent-facing deployments, disable destructive/write tools with a comma-separated env var:
+
+```bash
+# read-only agent: no create/replace/delete/autofix/test/template/credential/datatable writes
+DISABLED_TOOLS=n8n_create_workflow,n8n_update_full_workflow,n8n_update_partial_workflow,n8n_delete_workflow,n8n_autofix_workflow,n8n_deploy_template,n8n_test_workflow,n8n_manage_credentials,n8n_manage_datatable
+```
+
+Layer it with a **scoped API key** (grant only `workflow:read`/`execution:read` for a monitoring
+agent) so a disabled tool can't be worked around and the key itself can't mutate. Two independent
+locks: the tool gate and the key scope.
+
+## Sketch: agent-driven deploy
+
+```
+search_nodes / get_node_essentials     → get the exact node property shapes
+n8n_validate_workflow { workflow }      → catch structural errors offline
+n8n_autofix_workflow  { workflow }      → auto-repair, re-validate
+n8n_create_workflow   { name, nodes, connections, settings }  → capture returned id
+n8n_test_workflow     { id }            → confirm it runs
+# then activate via REST /workflows/{id}/activate (no MCP tool for it)
+n8n_executions        { workflowId: id } → confirm the live run
+```

package/skills/n8n/references/rest-api-cheatsheet.md

@@ -0,0 +1,94 @@
+# n8n public REST API — cheat sheet
+
+Base URL: `{host}/api/v1`. Auth header on every call: `X-N8N-API-KEY: $N8N_API_KEY`.
+Same surface on self-host and `*.app.n8n.cloud`. Self-host has interactive Swagger at
+`{host}/api/v1/docs`; cloud does not. Verify shapes at author time — n8n ships often.
+
+Set once:
+
+```bash
+export N8N_API_URL="https://your-instance.app.n8n.cloud"   # or http://localhost:5678
+export N8N_API_KEY="n8n_api_..."
+auth=(-H "X-N8N-API-KEY: $N8N_API_KEY")
+```
+
+## Workflows
+
+| Verb & path | What it does | Notes |
+|---|---|---|
+| `POST /workflows` | Create | Body needs `name, nodes, connections, settings`. `active` + `tags` in the body are **ignored** (read-only). Returns the new object incl. `id`. |
+| `GET /workflows/{id}` | Get one | The full exportable JSON. Use to back up before delete/replace. |
+| `GET /workflows` | List | Query: `limit` (default ~100), `cursor`, `active=true|false`, `tags`, `name`, `projectId`. Paginate with the returned `nextCursor`. |
+| `PUT /workflows/{id}` | **Full replace** | Send the WHOLE object; omitted fields are dropped. GET → mutate → PUT. |
+| `DELETE /workflows/{id}` | **Hard delete** | No trash, no undo. Export first. |
+| `POST /workflows/{id}/activate` | Activate | The ONLY way to go live — the body `active` flag never does it. |
+| `POST /workflows/{id}/deactivate` | Deactivate | Same, in reverse. |
+| `POST /workflows/{id}/execute` | Run by id | **Recent (PR #20234); older instances 404.** Runs `executeManually`; **accepts no custom input** — needs `workflow:execute` scope. |
+| `PUT /workflows/{id}/tags` | Set tags | Tags are managed here, not in the create/update body. |
+| `PUT /workflows/{id}/transfer` | Move to a project | Enterprise/projects. |
+
+```bash
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows" "${auth[@]}" \
+  -H "Content-Type: application/json" -d @workflow.json
+curl -sS "$N8N_API_URL/api/v1/workflows?limit=50&active=true" "${auth[@]}"
+curl -sS "$N8N_API_URL/api/v1/workflows/$ID" "${auth[@]}" > backup-$ID.json
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/activate" "${auth[@]}"
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/execute"  "${auth[@]}"
+curl -sS -X DELETE "$N8N_API_URL/api/v1/workflows/$ID" "${auth[@]}"
+```
+
+Paginate:
+
+```bash
+cursor=""
+while :; do
+  page=$(curl -sS "$N8N_API_URL/api/v1/workflows?limit=100&cursor=$cursor" "${auth[@]}")
+  echo "$page" | jq -r '.data[].id'
+  cursor=$(echo "$page" | jq -r '.nextCursor // empty')
+  [ -z "$cursor" ] && break
+done
+```
+
+## Executions
+
+| Verb & path | What it does |
+|---|---|
+| `GET /executions` | List runs. Query: `workflowId`, `status` (`success|error|waiting`), `limit`, `cursor`, `includeData=true`. |
+| `GET /executions/{id}` | One run; `?includeData=true` for the full item data. |
+| `DELETE /executions/{id}` | Delete a run's stored data. |
+
+```bash
+curl -sS "$N8N_API_URL/api/v1/executions?workflowId=$ID&status=error&limit=20" "${auth[@]}"
+```
+
+## Triggering a run WITH input
+
+`/execute` takes no body data. To pass runtime params, the workflow's trigger must be a **Webhook**
+node; POST to its URL:
+
+- Test URL (only while the editor's "Listen for test event" is armed): `{host}/webhook-test/<path>`
+- Production URL (only once the workflow is active): `{host}/webhook/<path>`
+
+```bash
+curl -sS -X POST "$N8N_HOST/webhook/my-path" -H "Content-Type: application/json" -d '{"orderId":123}'
+```
+
+## Other resources
+
+- `GET/POST/DELETE /credentials` — create/delete credentials and `GET /credentials/schema/{type}` for
+  the field shape. **You cannot read secrets back.** Reference existing creds from a workflow by id/name.
+- `GET/POST/PUT/DELETE /tags`, `/projects`, `/variables`, `/users` (admin), `/source-control/pull`,
+  `/audit` (instance security audit).
+
+## API-key scopes (least privilege)
+
+Create a **scoped** key in Settings → n8n API. Scopes are grouped by resource, e.g. `workflow:read`,
+`workflow:create`, `workflow:update`, `workflow:delete`, `workflow:execute`, `execution:read`,
+`credential:create`, `tag:*`. Grant only what a given automation needs — e.g. a read-only dashboard
+key gets `workflow:read` + `execution:read` and nothing that can mutate or run.
+
+## Error responses
+
+`401` bad/missing key · `403` key lacks the scope · `404` no such id (or `/execute` on an instance
+too old to have it) · `400` malformed body (e.g. missing `connections`) · `500` server-side (often a
+node the instance doesn't have installed).

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."