@ericrisco/rsc 0.1.37 → 0.1.38

package/skills/automation-strategy/references/orchestration-and-antipatterns.md

@@ -0,0 +1,107 @@
+# Orchestration strategy & anti-patterns — depth for §4–§5
+
+Engine-agnostic policy. These are the guarantees you *require of* an automation before it ships and
+the failure modes you audit for when a fleet is breaking. The per-platform **recipes** (which node,
+which toggle, exact retry settings) live in `../../automation-flows/SKILL.md` and each platform skill
+— this file is the discipline, not the wiring.
+
+## The orchestration guarantees
+
+### 1. Idempotency & dedup
+
+Event delivery is **at-least-once**: webhooks are re-sent, retries replay, users double-click. Assume
+every event can arrive two or more times. A non-idempotent write executed twice = double charge,
+duplicate row, duplicate email.
+
+- Require a **stable dedup key** — the provider's event id or a natural external id, never a
+  timestamp or a hash of "roughly the same thing".
+- Check the key **before** any non-idempotent action; record it **after** success.
+- Prefer idempotent operations where the platform/API allows (upsert-by-key beats blind insert;
+  idempotency keys on payment APIs).
+
+```text
+Bad:  event → create record                    (re-delivery → two records)
+Good: event → seen(key)? → if new: create → mark key seen
+```
+
+### 2. Error paths, retries & backoff
+
+Every automation has a defined destination for failure. Classify the error first:
+
+- **Transient** (network timeout, 429 rate-limit, 5xx) → retry with **exponential backoff + jitter**,
+  a **max attempts cap**, and a total time budget. Respect `Retry-After` when present.
+- **Permanent** (400, 401/403 auth, 404, validation) → do **not** retry; retrying just burns runs and
+  delays the alert. Route straight to the dead-letter path.
+
+Distinguishing the two is the single highest-leverage error decision — blind retry-everything is a
+common cause of both runaway bills and masked auth failures.
+
+### 3. Dead-letter
+
+After retries are exhausted, the failed item must land somewhere **durable and inspectable** — a
+queue, a table, the platform's "incomplete executions" store — with enough context (the payload, the
+error, the timestamp) to diagnose and **replay** it. Failures dropped on the floor are silent data
+loss; you find out when a customer does.
+
+### 4. Observability & alerting
+
+- Emit **success/failure counts** per automation; a run rate that quietly drops is a signal.
+- **Heartbeat scheduled jobs and alert on silence.** A cron that stops firing produces no error — it
+  produces *nothing*, which is the failure you never hear about. Alert when an expected run doesn't
+  happen within its window (dead-man's-switch).
+- Route alerts to a **named owner / on-call channel**, not an inbox nobody reads. An alert nobody
+  receives is not observability.
+
+### 5. Secrets handling
+
+- Store credentials in the **platform credential store or a vault**, referenced by name — never
+  pasted inline in a node/step where an export or a screenshot leaks them.
+- **Least privilege** — scope each token to what the automation actually needs.
+- **Rotation plan** — tokens expire; a rotation nobody owns becomes a 2 a.m. outage. Engineering
+  detail lives in `../../secure-coding/SKILL.md`.
+
+### 6. Versioning & environments
+
+- Separate **dev/staging from prod**. Test against non-prod data; don't debug against live customers.
+- **Export/snapshot before editing** a live automation — editing prod is a production change.
+- Keep a **rollback**: the previous known-good version, and a way to get back to it fast.
+
+### 7. Avoid fan-out storms
+
+- **Cap concurrency**, batch where possible, and **rate-limit** outbound calls to respect downstream
+  quotas.
+- Watch for **echo loops**: flow A writes a record that triggers flow B that writes a record that
+  triggers flow A. Break the cycle with a guard (a marker field, an event-source check).
+- Guard against one event **fanning out into thousands** of downstream calls that trip rate limits or
+  detonate the bill. Debounce bursts.
+
+## Anti-patterns — detection & remediation
+
+| Anti-pattern | How you notice it | Remediation |
+| --- | --- | --- |
+| **No error path** | first API blip and the run just stops; found out from a customer | define a failure destination + retry policy + alert before shipping |
+| **Silent failure** | dashboards green, but the work isn't happening; false confidence | alert on failure AND on silence (heartbeat / dead-man's-switch) |
+| **No kill-switch** | a misfiring flow floods a downstream system and there's no fast stop | every outward-writing automation gets a documented pause/disable toggle (and whoever's on-call knows where it is) |
+| **Over-automation** | maintenance time exceeds the manual time it replaced | re-run the §1 gate; retire it or revert to a checklist |
+| **Automating a broken process** | the automation "works" but the outputs are still wrong, just faster | stop, standardize the process on paper, then re-encode |
+| **Hidden single point of failure** | it breaks when one person leaves or one personal token expires | service accounts, documented dependencies, no personal-account glue |
+| **No owner** | nobody can say how it works or notices when it breaks | assign an owner + a one-page runbook (what it does, deps, how to pause, how to replay) |
+| **Choosing platform by familiarity** | the bill "exploded"; billing unit mismatched the run shape | re-select by billing unit for the real shape (see platform matrix) |
+| **Retry-everything** | runaway run counts, masked auth failures | classify transient vs permanent; only retry transient, with backoff + cap |
+| **Secrets inline** | credentials visible in an export/screenshot; can't rotate cleanly | move to credential store/vault, reference by name, plan rotation |
+
+## Fleet-health audit ("our automations keep breaking")
+
+When someone arrives with a *fleet* that keeps breaking rather than one flow, walk this list — the
+breakage is almost always a missing discipline, not a bad node:
+
+1. **Inventory & ownership** — is there a list of every automation with a named owner? Orphans first.
+2. **Error paths** — how many have a real failure destination + alert vs die silently?
+3. **Idempotency** — which do non-idempotent writes with no dedup key? (double-processing symptoms)
+4. **Observability** — is anything watching run rates and heartbeats, or do you learn from customers?
+5. **Secrets/expiry** — any recent breaks that trace to an expired token or a personal account?
+6. **Environments** — are people editing prod directly with no snapshot/rollback?
+7. **Fan-out / loops** — any echo loops or bursts tripping rate limits?
+
+Fix the systemic gap (usually error paths + observability + ownership) rather than patching flows one
+at a time. Then feed the corrected guarantees into the build skill as requirements.

package/skills/automation-strategy/references/platform-selection-matrix.md

@@ -0,0 +1,86 @@
+# Platform selection matrix — n8n · Make · Zapier · Power Automate
+
+Depth for §3. This is a *routing* reference: decide, then hand off to the platform's own skill
+(`../../n8n/`, `../../make/`, `../../zapier/`, `../../power-automate/`) for the live API/MCP work.
+All pricing/version figures move — re-check the vendor page at author time.
+
+## Billing unit is the decision axis
+
+Cost at scale is dominated by the unit each platform charges on. The *same* logical flow costs
+wildly different amounts depending on shape (few-long vs many-short) because of this.
+
+| Platform | Billing unit | What counts as 1 | Cost shape it favors |
+| --- | --- | --- | --- |
+| **n8n** | execution | one whole workflow run, any number of steps | few, long, complex flows; high volume; self-host = $0 |
+| **Make** | credit | each module action (renamed from "operations" 2025-08-27, converted 1:1) | moderate multi-step flows |
+| **Zapier** | task | each action step that runs | many, short, simple flows |
+| **Power Automate** | seat / flow | per-user or per-flow premium licensing; standard connectors bundled with many M365 plans | teams already paying for Microsoft 365 |
+
+**Worked contrast** — a 10-step flow run 10,000×/month:
+
+- **n8n:** 10,000 executions regardless of step count; self-hosted = $0 infra-aside.
+- **Make:** ~100,000 credits (10 module actions × 10k).
+- **Zapier:** ~100,000 tasks (10 actions × 10k) — pushed into high tiers fast.
+- **Power Automate:** governed by seat/flow licensing rather than per-action, so the math is about
+  who's licensed and premium-connector usage, not run count.
+
+For complex high-volume flows, n8n's per-execution model commonly cuts cost 80–90% vs per-task/credit
+platforms. For a Microsoft-centric team, Power Automate can be effectively "free at the margin"
+because it rides existing M365 licenses.
+
+## Full comparison
+
+| Axis | n8n | Make | Zapier | Power Automate |
+| --- | --- | --- | --- | --- |
+| Free / entry | self-host free; cloud Starter ≈ €20/mo | ≈ 1,000 credits free; Core ≈ $9/mo | 100 tasks/mo free; Pro ≈ $19.99/mo | bundled in many M365 plans; premium add-ons |
+| App breadth | ~1,000 nodes + generic HTTP + code | ~1,500, often deep per app | ~8,000+ — widest catalog | strong on MS + growing 3rd-party connectors |
+| Self-host / data residency | **yes — your infra** | no (EU/US regions) | no | Microsoft cloud / Dataverse regions |
+| Who runs/maintains it | technical; you run the box | mid; visual but rich | non-technical-friendly | IT/business in a Microsoft shop |
+| Portability | high (export/import JSON) | low (no portable export) | low (no portable export) | low (tied to MS solutions) |
+| Complex logic / code | code nodes, sandboxed by default (n8n 2.0) | functions + routers | limited (Code by Zapier) | expressions + Azure Functions escape hatch |
+
+## Programmatic + MCP maturity (honest)
+
+The suite's platform skills drive these; here's the strategy-level read on how far each goes.
+
+- **n8n** — public REST API can CRUD and activate workflows programmatically; strongest fit for
+  code-driven ops and GitOps-style management. MCP is community-driven and evolving. Best pick when
+  you want automations that are themselves managed as code. → `../../n8n/SKILL.md`.
+- **Make** — management API plus maturing MCP / AI-agent support; you can manage scenarios via API to
+  a useful degree. → `../../make/SKILL.md`.
+- **Zapier** — rich API for *running actions*, and **Zapier MCP** exposes thousands of app actions to
+  AI agents. **Hard limit: there is no public API to create/author a Zap** — Zap building is UI-only.
+  You can trigger and act, not construct. → `../../zapier/SKILL.md`.
+- **Power Automate** — Flow *management* APIs, plus solutions/ARM/ALM for deploying flows as packaged
+  artifacts. **Hard limit: no clean public API to author an end-user's personal "My flows"**; the
+  supported path is solution-based deployment, not arbitrary per-user flow creation. →
+  `../../power-automate/SKILL.md`.
+
+**Do not build a plan that depends on API-creating a Zap or a personal Power Automate "My flow."**
+Both are UI-authored. If automation-of-the-automation is a requirement, that requirement points at
+**n8n** (and to a lesser extent Make).
+
+## Ecosystem fit — the tie-breaker after billing
+
+- **Microsoft 365 shop** (Teams, SharePoint, Outlook, Dataverse, Excel Online) → **Power Automate**.
+  The native integration and bundled licensing usually beat everything else on both cost and
+  friction. Don't bolt a third-party platform onto a Microsoft estate without a reason.
+- **Data must stay on your own infrastructure** (compliance, residency, air-gapped) → **n8n**
+  self-hosted is the only option here that keeps data on your box.
+- **Obscure or long-tail app**, non-technical owner → **Zapier** for catalog breadth.
+- **Deep per-app capability at mid volume** → **Make**.
+
+## Routing summary
+
+```text
+Microsoft 365 estate?            → Power Automate
+Data must stay on our infra?     → n8n (self-host)
+High volume / complex / code?    → n8n
+Need to manage flows as code?    → n8n (Make second)
+Widest app catalog / non-tech?   → Zapier
+Deep modules, mid volume?        → Make
+```
+
+Then route to that platform's skill for the build/operate work. Portability note: n8n's exportable
+JSON makes exit cheap; the other three lock you in more, so weigh that if you expect to outgrow the
+choice.

package/skills/harness/references/providers.yaml

@@ -3384,6 +3384,106 @@ providers:
       CREDENTIALS.md: |
         Dashboard: https://app.n8n.cloud/settings/api (or self-hosted equivalent).
         `N8N_API_KEY` — secret. Required for all REST API calls.
+        API surface: workflows CRUD + `/activate` `/deactivate` + `/workflows/{id}/execute`
+        (recent; no custom input — use a Webhook trigger for runtime params). See the `n8n` skill.
+
+  - id: MAKE
+    category: automatizacion
+    detectors:
+      imports: []
+      env_vars: ["MAKE_API_TOKEN", "MAKE_ZONE"]
+      deps: []
+    dashboard_url: "https://www.make.com/en/help/tools/api"
+    env_example: |
+      MAKE_ZONE=eu1.make.com        # your zone: eu1/eu2/us1/us2 (wrong zone => auth error)
+      MAKE_API_TOKEN=               # Profile > API/token; scopes are fixed at creation
+      MAKE_TEAM_ID=
+    files:
+      test_connection.sh: |
+        #!/usr/bin/env bash
+        set -euo pipefail
+        SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+        set -a; source "$SCRIPT_DIR/.env"; set +a
+        : "${MAKE_ZONE:?MAKE_ZONE not set (e.g. eu1.make.com)}"
+        : "${MAKE_API_TOKEN:?MAKE_API_TOKEN not set}"
+        NAME=$(curl -fsS "https://${MAKE_ZONE%/}/api/v2/users/me" -H "Authorization: Token $MAKE_API_TOKEN" | python3 -c 'import json,sys; print(json.load(sys.stdin)["authUser"]["name"])')
+        echo "OK — Make API reachable on $MAKE_ZONE (user: $NAME)."
+      README.md: |
+        # MAKE
+        Make.com (formerly Integromat). Scenarios via /api/v2; blueprint is a stringified JSON
+        round-trip. Base URL is zone-scoped. See the `make` skill for dynamic create/manage.
+      CREDENTIALS.md: |
+        Dashboard: Profile > API (https://www.make.com/en/help/tools/api).
+        `MAKE_API_TOKEN` — secret; token scopes are immutable after creation. Wrong `MAKE_ZONE`
+        returns an auth error even with a valid token. Endpoints are case-sensitive.
+
+  - id: ZAPIER
+    category: automatizacion
+    detectors:
+      imports: []
+      env_vars: ["ZAPIER_MCP_URL", "ZAPIER_MCP_API_KEY"]
+      deps: []
+    dashboard_url: "https://mcp.zapier.com"
+    env_example: |
+      ZAPIER_MCP_URL=https://mcp.zapier.com/api/v1/connect
+      ZAPIER_MCP_API_KEY=           # Bearer key from the Zapier MCP dashboard (2 tasks per call)
+    files:
+      test_connection.sh: |
+        #!/usr/bin/env bash
+        set -euo pipefail
+        SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+        set -a; source "$SCRIPT_DIR/.env"; set +a
+        : "${ZAPIER_MCP_URL:?ZAPIER_MCP_URL not set}"
+        : "${ZAPIER_MCP_API_KEY:?ZAPIER_MCP_API_KEY not set}"
+        # Zapier exposes no account-CRUD REST API; smoke-test the MCP endpoint with an initialize handshake.
+        CODE=$(curl -s -o /dev/null -w '%{http_code}' -X POST "$ZAPIER_MCP_URL" \
+          -H "Authorization: Bearer $ZAPIER_MCP_API_KEY" -H "Content-Type: application/json" \
+          -H "Accept: application/json, text/event-stream" \
+          -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"rsc","version":"1"}}}')
+        case "$CODE" in 2*) echo "OK — Zapier MCP endpoint reachable (HTTP $CODE).";; *) echo "FAIL — HTTP $CODE" >&2; exit 1;; esac
+      README.md: |
+        # ZAPIER
+        Zapier has NO public API for a normal user to create/manage their own Zaps. Programmatic
+        use = Zapier MCP (runs pre-configured actions across 9,000+ apps; does not author Zaps).
+        See the `zapier` skill for the honest boundary and when to use n8n/Make instead.
+      CREDENTIALS.md: |
+        Dashboard: https://mcp.zapier.com — generate an MCP server + Bearer key.
+        `ZAPIER_MCP_API_KEY` — secret (Bearer). Each successful tool call costs 2 Zapier tasks.
+
+  - id: POWER_AUTOMATE
+    category: automatizacion
+    detectors:
+      imports: []
+      env_vars: ["PA_DATAVERSE_URL", "PA_TENANT_ID", "PA_CLIENT_ID", "PA_CLIENT_SECRET"]
+      deps: []
+    dashboard_url: "https://make.powerautomate.com"
+    env_example: |
+      PA_DATAVERSE_URL=https://<org>.crm.dynamics.com   # your Dataverse org URL (region domain varies)
+      PA_TENANT_ID=                 # Entra tenant id
+      PA_CLIENT_ID=                 # Entra app registration (needs a Dataverse application user)
+      PA_CLIENT_SECRET=
+    files:
+      test_connection.sh: |
+        #!/usr/bin/env bash
+        set -euo pipefail
+        SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+        set -a; source "$SCRIPT_DIR/.env"; set +a
+        : "${PA_DATAVERSE_URL:?PA_DATAVERSE_URL not set}"
+        : "${PA_TENANT_ID:?PA_TENANT_ID not set}"; : "${PA_CLIENT_ID:?PA_CLIENT_ID not set}"; : "${PA_CLIENT_SECRET:?PA_CLIENT_SECRET not set}"
+        TOKEN=$(curl -fsS "https://login.microsoftonline.com/${PA_TENANT_ID}/oauth2/v2.0/token" \
+          -d "grant_type=client_credentials&client_id=${PA_CLIENT_ID}&client_secret=${PA_CLIENT_SECRET}&scope=${PA_DATAVERSE_URL%/}/.default" \
+          | python3 -c 'import json,sys; print(json.load(sys.stdin)["access_token"])')
+        N=$(curl -fsS "${PA_DATAVERSE_URL%/}/api/data/v9.2/workflows?\$filter=category%20eq%205&\$top=1" \
+          -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" | python3 -c 'import json,sys; print(len(json.load(sys.stdin)["value"]))')
+        echo "OK — Dataverse reachable; cloud-flow query returned $N row(s)."
+      README.md: |
+        # POWER_AUTOMATE
+        Microsoft Power Automate cloud flows via the Dataverse Web API (solution-aware flows only;
+        `api.flow.microsoft.com` is unsupported). Auth is Entra OAuth. See the `power-automate` skill.
+      CREDENTIALS.md: |
+        Register an Entra app; add it as a Dataverse application user with a security role granting
+        Process (workflow) privileges. `PA_CLIENT_SECRET` — secret. Only flows inside a Dataverse
+        solution are code-manageable; personal "My Flows" are not.
 
 # Categories used to group tools in 01-TOOLS/README.md.
 categories:

package/skills/make/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: make
+description: "Use when operating Make.com (formerly Integromat) programmatically — driving its REST API v2 or the Make MCP server from code or an agent to create, read, update, activate, run, clone, or delete scenarios, connections, hooks, and data stores. Triggers: 'create a Make scenario via the API', 'export a scenario blueprint, mutate it, and push it back', 'start/stop/run a Make scenario from a script', 'clone this Integromat scenario into another team', 'connect the Make MCP server so an agent runs my scenarios as tools', 'my valid Make API token returns an auth error' (zone trap), 'automatiza escenarios de Make.com desde la API'. NOT designing what the flow should do — trigger, branching, mapping, dedup, error path (automation-flows), NOT choosing Make vs n8n vs Zapier by billing model (automation-strategy), NOT operating n8n / Zapier / Power Automate (their skills), NOT a generic typed REST client with pagination/backoff (api-connector-builder) or an inbound webhook receiver in your own app (webhooks)."
+tags: [make, integromat, automation, scenarios, blueprint, mcp, no-code, api, workflows]
+recommends: [automation-flows, automation-strategy, api-connector-builder, webhooks]
+profiles: [full]
+origin: risco
+---
+
+# Make (Integromat) — operate scenarios by REST API and MCP
+
+Drive a live Make.com account from code or an agent: create scenarios from a
+blueprint, activate/run/stop/clone/delete them, and manage the connections,
+hooks, data stores, and teams around them. This skill owns the **operate**
+half — the API v2 calls and the MCP wiring. It does **not** design the flow;
+what a scenario *should do* (trigger, routes, mapping, dedup, error handler)
+lives in [`automation-flows`](../automation-flows/SKILL.md), and the
+Make-vs-n8n-vs-Zapier billing call lives in
+[`automation-strategy`](../automation-strategy/SKILL.md). Bring the design
+here, and this skill turns it into API payloads and MCP tool calls.
+
+Reality up top (verify at author time — Make ships fast):
+
+- **REST API v2 is GA.** Base URL is **zoned**: `https://{zone}.make.com/api/v2`.
+- **The Make MCP server is GA and free on every plan** — you only pay the
+  scenario **credits** a run consumes. Cloud MCP has two tool tiers: run tools
+  (all plans) and management tools (paid).
+
+## Connect first — API token vs MCP
+
+Two ways in, chosen by *who is driving*:
+
+- **REST API v2** — deterministic CRUD from your own scripts/CI. Full control
+  of the blueprint. Use for provisioning, bulk edits, activate/stop pipelines.
+- **Make MCP server** — lets an MCP client (Claude, Cursor, ChatGPT) call your
+  scenarios and (on paid plans) manage them as tools, no glue code. Use when an
+  **agent** is the operator.
+
+`.env` (never inline secrets — read from the environment):
+
+```bash
+MAKE_ZONE=eu2.make.com        # your org's zone — eu1|eu2|us1|us2 (+ celonis). WRONG ZONE = AUTH ERROR.
+MAKE_API_TOKEN=xxxxxxxx        # Profile → API/SDK → API token. Scopes are FIXED at creation.
+MAKE_TEAM_ID=123456            # teamId a scenario is created under (integer)
+MAKE_MCP_TOKEN=yyyyyyyy        # separate MCP token, for the token-URL MCP transport
+```
+
+**Auth header (API):** `Authorization: Token {MAKE_API_TOKEN}` — the literal
+word `Token`, a space, then the token. OAuth2 is the alternative for
+multi-user apps. **Scopes are chosen when the token is minted and cannot be
+widened later** — mint with `scenarios:read scenarios:write` (and
+`connections`, `hooks`, `datastores`, `teams` as needed) up front; a
+too-narrow token means re-minting, not patching.
+
+## The scenario model (just enough to build the payload)
+
+A **scenario** = exactly one trigger module, then a chain of action modules,
+optionally split by **routers** into branches. Data flows by **mapping**:
+a downstream field references an upstream output as `{{2.email}}` (module 2's
+`email`). The whole thing serializes to a **blueprint** — the JSON you GET, edit,
+and POST back. That is the entire operate-side model you need here.
+
+Do **not** design the flow in this skill. Trigger choice (webhook vs polling),
+branch logic, idempotency/dedup on a data store, and the error handler
+(Break → Incomplete Executions, etc.) are all `automation-flows`. Take its
+build sheet, then encode it as a blueprint below.
+
+## API v2 surface
+
+| Group | Endpoints (case-sensitive!) | Use |
+|---|---|---|
+| Scenarios | `GET/POST /scenarios`, `GET/PATCH/DELETE /scenarios/{id}`, `.../start`, `.../stop`, `.../run`, `.../clone`, `.../blueprint` | the core |
+| Connections | `GET/POST /connections`, `.../{id}/test` | app auth the modules use |
+| Hooks | `GET/POST /hooks`, `.../{id}/ping`, `.../learn-start` | inbound webhooks/mailhooks |
+| Data stores | `GET/POST /data-stores`, `.../{id}/data` | dedup keys, state |
+| Templates | `GET /templates`, `.../{id}/blueprint` | starting-point blueprints |
+| Teams / Orgs | `GET /teams`, `GET /organizations/{id}` | scoping + rate limit |
+
+Two rules that bite: **endpoints and query keys are case-sensitive**, and every
+call is **zoned** — the same token against the wrong `{zone}` returns an auth
+error, not a 404, which sends people chasing a token problem that does not exist.
+
+**Rate limits are per plan** (req/min): Core 60 · Pro 120 · Teams 240 ·
+Enterprise 1000. Read your own real ceiling rather than guessing:
+
+```bash
+curl -s -H "Authorization: Token $MAKE_API_TOKEN" \
+  "https://$MAKE_ZONE/api/v2/organizations/$ORG_ID" | jq '.organization.license.apiLimit'
+```
+
+## Dynamic lifecycle — the blueprint round-trip
+
+The core technique: **you rarely hand-write a blueprint.** You GET one from a
+template or an existing scenario, mutate the JSON, and POST/PATCH it back **as a
+string**. `blueprint` and `scheduling` are sent as JSON *strings*, not objects.
+
+### 1. Get a starting blueprint
+
+```bash
+# From an existing scenario (or a template: GET /templates/{id}/blueprint)
+curl -s -H "Authorization: Token $MAKE_API_TOKEN" \
+  "https://$MAKE_ZONE/api/v2/scenarios/$TEMPLATE_ID/blueprint" \
+  | jq '.response.blueprint' > bp.json   # wrapper key: verify .response.blueprint at author time
+```
+
+Mutate `bp.json` with your design — module parameters, the `{{n.field}}`
+mappings, router filters. Keep secrets out; wire credentials via a
+**connection id**, never a literal key in the blueprint.
+
+### 2. Create the scenario (blueprint + scheduling as STRINGS)
+
+```bash
+curl -s -X POST -H "Authorization: Token $MAKE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://$MAKE_ZONE/api/v2/scenarios" \
+  -d "$(jq -n --argjson team "$MAKE_TEAM_ID" \
+        --arg bp "$(jq -c . bp.json)" \
+        --arg sched '{"type":"on-demand"}' \
+        '{teamId:$team, blueprint:$bp, scheduling:$sched}')"
+# scheduling e.g. {"type":"indefinitely","interval":900} (interval seconds) — verify fields at author time.
+# optional: folderId, basedon (template id)
+```
+
+### 3. Validate
+
+The create call itself is the validator — a malformed blueprint returns a 400
+naming the offending module/field. Fix the JSON and re-POST. There is no
+separate schema-lint endpoint; a clean create *is* the pass.
+
+### 4. Dry-run / test before you schedule
+
+Run it once, watching one execution, while still `on-demand` (inactive):
+
+```bash
+curl -s -X POST -H "Authorization: Token $MAKE_API_TOKEN" \
+  "https://$MAKE_ZONE/api/v2/scenarios/$ID/run" \
+  -H "Content-Type: application/json" -d '{"responsive":true}'
+# inspect the returned execution/bundle output before trusting the flow
+```
+
+### 5. Activate
+
+```bash
+# switch scheduling off on-demand first (PATCH), then start
+curl -s -X POST -H "Authorization: Token $MAKE_API_TOKEN" \
+  "https://$MAKE_ZONE/api/v2/scenarios/$ID/start"
+```
+
+### 6. Manage — patch, stop, clone
+
+```bash
+# Update: same round-trip — GET blueprint, mutate, PATCH back as a string
+curl -s -X PATCH -H "Authorization: Token $MAKE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://$MAKE_ZONE/api/v2/scenarios/$ID" \
+  -d "$(jq -n --arg bp "$(jq -c . bp.json)" '{blueprint:$bp}')"
+
+curl -s -X POST -H "Authorization: Token $MAKE_API_TOKEN" ".../scenarios/$ID/stop"
+curl -s -X POST -H "Authorization: Token $MAKE_API_TOKEN" \
+  -H "Content-Type: application/json" ".../scenarios/$ID/clone" \
+  -d '{"teamId": 999, "name": "copy"}'   # clone into another team
+```
+
+### 7. Delete — export first (irreversible)
+
+`DELETE /scenarios/{id}` is permanent; there is no undo and no trash. **Never
+delete a live scenario without exporting its blueprint first.**
+
+```bash
+curl -s -H "Authorization: Token $MAKE_API_TOKEN" \
+  ".../scenarios/$ID/blueprint" | jq '.response.blueprint' > backup-$ID.json  # export
+curl -s -X DELETE -H "Authorization: Token $MAKE_API_TOKEN" ".../scenarios/$ID"
+```
+
+## Make MCP — run and manage scenarios as tools
+
+The Make MCP server hands an MCP client your scenarios as callable tools. Two
+transports:
+
+- **OAuth (remote):** point the client at `https://mcp.make.com` (or the
+  `/stream`, `/sse` variants). Scopes granted at consent decide which tools appear.
+- **MCP token (per-zone):** `https://{zone}.make.com/mcp/u/{MCP_TOKEN}/stateless`
+  (also `/stream`, `/sse`). `/stateless` times out at ~60 s; `/stream` and
+  `/sse` allow ~5 min — a long scenario needs `/stream` or `/sse`.
+
+Tool tiers (exact names move — confirm in the client's tool list at author time):
+
+- **Run tools — all plans.** Enumerate on-demand scenarios and execute one with
+  inputs, returning its output. This is what lets an agent *use* your automation.
+- **Management tools — paid plans.** View/modify scenarios, connections, hooks,
+  data stores, teams, organizations — the CRUD above, surfaced as tools.
+
+Client config sketch (token transport):
+
+```json
+{ "mcpServers": { "make": {
+  "url": "https://eu2.make.com/mcp/u/${MAKE_MCP_TOKEN}/stream"
+} } }
+```
+
+MCP calls consume the scenario's normal **credits** — the server is free, the
+runs are not. **Legacy note:** the local stdio server `integromat/make-mcp-server`
+predates the cloud one and exposes on-demand scenarios as tools over stdio;
+prefer the cloud server unless you specifically need a local process.
+
+## Honesty / gotchas
+
+- **Zone trap.** Wrong `{zone}` → auth error with a perfectly valid token. Check
+  the zone before you suspect the token.
+- **Case-sensitive paths.** `/scenarios` works, `/Scenarios` does not.
+- **`blueprint` and `scheduling` are strings, not objects** — stringify them or
+  the create/update fails.
+- **Token scopes are frozen at creation.** Can't widen later; re-mint instead.
+- **Delete is irreversible** — export the blueprint first, always.
+- **Credits, not operations.** Make's billing unit became **credits** (was
+  "operations"); API-triggered and MCP-triggered runs both burn them.
+- **`.run` on an inactive scenario** is your dry run; scheduled execution needs
+  `.start` — don't confuse the two.
+- **Don't hand-author blueprints from scratch** — round-trip a template; the
+  format is large and undocumented in full.
+
+## Related skills
+
+- [`automation-flows`](../automation-flows/SKILL.md) — **design** the flow
+  (trigger, routes, mapping, dedup, error path). Build it there, encode the
+  blueprint here. Design ↔ operate is the boundary.
+- [`automation-strategy`](../automation-strategy/SKILL.md) — choose Make vs n8n
+  vs Zapier by billing model *before* committing to this skill.
+- [`webhooks`](../webhooks/SKILL.md) — building the inbound endpoint that
+  *receives* events in your own app (vs Make's `hooks` API here).
+- [`api-connector-builder`](../api-connector-builder/SKILL.md) — a generic typed
+  REST client with auth/pagination/backoff, when you outgrow curl.
+- Other platforms: `n8n`, `zapier`, `power-automate` (their own skills).
+
+## Checklist
+
+- [ ] `MAKE_ZONE` matches the org's actual zone (ruled out the zone trap).
+- [ ] API token minted with all scopes needed (scenarios + connections/hooks/
+      datastores as required) — scopes can't be widened later.
+- [ ] Blueprint obtained by round-trip (template/existing), not hand-written.
+- [ ] `blueprint` and `scheduling` sent as JSON **strings**; `teamId` set.
+- [ ] Credentials referenced by connection id — no secrets in the blueprint.
+- [ ] Dry-ran with `/run` and inspected output before `/start`.
+- [ ] Blueprint exported to a file before any `DELETE`.
+- [ ] For MCP: right transport for run length (`/stream`|`/sse` if >60 s), and
+      manager tools confirmed present only if the plan is paid.
+
+## References
+
+- `references/api-v2-cheatsheet.md` — endpoints, auth, scopes, rate limits, the
+  common response envelope, and error codes.
+- `references/blueprint-round-trip.md` — the GET→mutate→POST recipe in depth,
+  blueprint anatomy, and the stringify gotcha.
+- `references/make-mcp-and-auth.md` — MCP transports, tool tiers, client configs,
+  and the token-vs-OAuth decision.

package/skills/make/evals/README.md

@@ -0,0 +1,14 @@
+# Evals — make
+
+`cases.yaml` holds three groups scored by an LLM judge against the rendered
+skill. `should_trigger` confirms Make owns programmatic/MCP operation of a
+Make.com account (create/run/clone/activate/delete scenarios, the blueprint
+round-trip, the zone trap). `should_not_trigger` confirms clean deferral to the
+real siblings — `automation-flows` for flow design, `automation-strategy` for
+platform choice, `n8n` for that platform, `api-connector-builder` for generic
+clients, `webhooks` for inbound receivers. The `capability` case checks the body
+carries the load-bearing facts: the zoned/case-sensitive API, the
+string-not-object blueprint/scheduling, the round-trip, run-before-start,
+export-before-delete irreversibility, frozen token scopes, and the Make MCP
+tiers. Run via the repo's eval runner; treat a miss as a cue to sharpen the
+description's triggers/boundary or fill a body gap.

package/skills/make/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: make
+
+should_trigger:
+  - prompt: "Create a Make.com scenario from a blueprint via the API and activate it from my deploy script."
+    why: Core operate task — POST /scenarios with a blueprint string, then /start.
+  - prompt: "Export a Make scenario blueprint, change the Notion module's mapping, and push it back."
+    why: The blueprint round-trip (GET /blueprint → mutate → PATCH as a string) this skill owns.
+  - prompt: "My Make API token keeps returning an auth error even though it's valid and the scopes look right."
+    why: Classic zone trap — wrong {zone} in the base URL, not a token problem.
+  - prompt: "Connect the Make MCP server so Claude can run my scenarios as tools."
+    why: MCP transport + tool-tier setup; the agent-operator path.
+  - prompt: "Clone this Integromat scenario into another team and stop the original from a cron job."
+    why: /clone and /stop lifecycle endpoints driven programmatically.
+  - prompt: "Automatiza la creación de escenarios en Make.com desde la API, incluyendo teamId y scheduling."
+    why: Spanish phrasing of programmatic scenario creation; required teamId + scheduling string.
+  - prompt: "Read my Make org's real API rate limit before I bulk-update 200 scenarios."
+    why: GET /organizations/{id} → license.apiLimit, plus rate-limit awareness for API operation.
+
+should_not_trigger:
+  - prompt: "Design a Make scenario that dedupes Stripe webhooks and has a proper error path before an external call."
+    route_to: automation-flows
+    why: Flow design (trigger, dedup, error handler) — build it there, then encode the blueprint here.
+  - prompt: "Should I use Make, n8n, or Zapier for 80k runs a month given the billing models?"
+    route_to: automation-strategy
+    why: Platform choice by cost model, not operating a Make account.
+  - prompt: "Create and activate an n8n workflow via its REST API."
+    route_to: n8n
+    why: Different platform; n8n has its own operate skill.
+  - prompt: "Build a typed TypeScript client for a REST API with OAuth refresh, pagination, and exponential backoff."
+    route_to: api-connector-builder
+    why: Generic API-client engineering, not Make-specific operation.
+  - prompt: "Verify the HMAC signature on inbound webhooks arriving at my Express endpoint and queue them."
+    route_to: webhooks
+    why: Inbound receiver in the user's own app, not Make's hooks API.
+
+capability:
+  - scenario: "Programmatically create a Make scenario from a template blueprint, dry-run it, activate it, and later delete it safely — plus offer the Make MCP path for an agent operator."
+    must_include:
+      - "Zoned base URL https://{zone}.make.com/api/v2 with header Authorization: Token {token}, and the zone trap (wrong zone → auth error with a valid token)."
+      - "POST /scenarios requires teamId, plus blueprint and scheduling sent as JSON STRINGS (not objects)."
+      - "Blueprint round-trip: GET /scenarios/{id}/blueprint (or a template), mutate the JSON, send back as a string on create/PATCH."
+      - "Dry-run with POST /scenarios/{id}/run and inspect output before POST /scenarios/{id}/start to activate."
+      - "Irreversibility rule: export the blueprint to a file before DELETE /scenarios/{id} — deletion is permanent."
+      - "Token scopes are fixed at creation and cannot be widened later; endpoints are case-sensitive."
+      - "Make MCP server (GA, free; runs cost credits) via OAuth https://mcp.make.com or token URL https://{zone}.make.com/mcp/u/{MCP_TOKEN}/stateless|stream|sse, with run tools (all plans) vs management tools (paid)."