@damiangilgonzalez/harness 1.3.7

package/skills/mysql/references/online-ddl-and-migrations.md

@@ -0,0 +1,120 @@
+# Online DDL and migrations (the MySQL mechanics)
+
+This file owns the MySQL-only knobs — `ALGORITHM=`, `LOCK=`, pt-online-schema-change, gh-ost — that
+make a schema change run without an outage. The vendor-neutral *strategy* (expand-contract, batched
+backfill, dual-write) lives in `db-migrations`; this is the InnoDB machinery that strategy rides on.
+
+## ALGORITHM / LOCK matrix per operation
+
+Every `ALTER TABLE` resolves to one of three algorithms. **Always state it explicitly** — if you
+omit `ALGORITHM=`, MySQL silently picks the cheapest one that works, and "cheapest that works" can
+quietly be `COPY`, which locks and rebuilds a multi-GB table.
+
+| Operation | Best algorithm | Notes |
+|---|---|---|
+| Add column at the end | `INSTANT` | metadata-only since 8.0.12; near-free |
+| Add column in the middle | `INSTANT` (8.0.29+) | older versions fall back to INPLACE/COPY |
+| Drop a column | `INSTANT` (8.0.29+) | else INPLACE |
+| Rename a column | `INSTANT` | metadata-only |
+| Set / drop a column DEFAULT | `INSTANT` | metadata-only |
+| Add a secondary index | `INPLACE, LOCK=NONE` | rebuilds the index without blocking writes |
+| Drop an index | `INPLACE` (often INSTANT) | metadata change |
+| Change column NULL → NOT NULL | `INPLACE` | requires the data to already satisfy it |
+| Change column data type / charset | `COPY` | full table rebuild — this is the dangerous one |
+| Add / drop a PRIMARY KEY | `COPY` (usually) | rebuilds the clustered index and every secondary |
+| Change ROW_FORMAT / KEY_BLOCK_SIZE | `INPLACE` (rebuild) | not blocking but rewrites the table |
+
+```sql
+-- Always be explicit. If the operation can't be done with the algorithm you named, the statement
+-- FAILS LOUDLY instead of silently degrading to a locking COPY.
+ALTER TABLE orders ADD COLUMN note VARCHAR(255) NULL, ALGORITHM=INSTANT, LOCK=NONE;
+
+-- Adding a secondary index on a live table: rebuild without blocking writes.
+ALTER TABLE orders ADD INDEX idx_user_created (user_id, created_at),
+  ALGORITHM=INPLACE, LOCK=NONE;
+```
+
+There is a hard limit on `INSTANT` add-column: each `INSTANT` add increments a row-version counter,
+and after a number of them the table needs a rebuild before more `INSTANT` adds are allowed. Check
+`information_schema.INNODB_TABLES.INSTANT_COLS` / row-version columns if `INSTANT` starts refusing.
+
+## When INSTANT/INPLACE can't do it non-blockingly → gh-ost or pt-osc
+
+For a `COPY`-only change on a large *hot* table (type change, PK change, charset migration), don't
+run it in place at peak. Use an external tool that builds a shadow table, copies rows in chunks,
+keeps it in sync, and swaps atomically.
+
+### gh-ost (GitHub) — binlog-based, triggerless
+
+gh-ost reads the binlog to keep the shadow table in sync, so it adds no triggers to your hot table
+and throttles cleanly on replica lag.
+
+```bash
+# Always --dry-run (omit --execute) first; read the plan, then add --execute.
+gh-ost \
+  --host=primary.db --database=shop --table=orders \
+  --alter="MODIFY COLUMN total DECIMAL(19,4) NOT NULL" \
+  --max-load="Threads_running=25" \
+  --critical-load="Threads_running=100" \
+  --max-lag-millis=1500 \
+  --throttle-control-replicas="replica1.db,replica2.db" \
+  --chunk-size=1000 \
+  --cut-over=default \
+  --postpone-cut-over-flag-file=/tmp/ghost.postpone \
+  --execute
+# Touch/remove the postpone file to control exactly when the atomic cutover happens.
+```
+
+gh-ost needs `binlog_format=ROW` and either a connection to a replica or `--allow-on-master` with
+binlog access. It can't follow a table that already has triggers.
+
+### pt-online-schema-change (Percona) — trigger-based
+
+Use pt-osc when gh-ost can't read the binlog (no replica, restricted binlog). It installs AFTER
+INSERT/UPDATE/DELETE triggers on the original table to mirror writes into the shadow copy.
+
+```bash
+pt-online-schema-change \
+  --alter "MODIFY COLUMN total DECIMAL(19,4) NOT NULL" \
+  --max-lag=1.5 --check-slave-lag replica1.db \
+  --chunk-time=0.5 \
+  --dry-run \
+  D=shop,t=orders
+# Replace --dry-run with --execute once the dry run is clean.
+```
+
+Caveat: pt-osc's triggers conflict with any pre-existing triggers on the table, and foreign keys
+referencing the table need `--alter-foreign-keys-method` chosen deliberately (rebuild_constraints
+vs drop_swap) — a wrong choice can briefly break FK integrity at cutover.
+
+### Choosing between them
+
+| Situation | Tool |
+|---|---|
+| You have a replica and ROW binlog, no existing triggers | gh-ost (lighter, no triggers on hot table) |
+| No replica / restricted binlog access | pt-osc (triggers) |
+| Table already has triggers | pt-osc with care, or refactor first |
+| Foreign keys point at the table | pt-osc with an explicit `--alter-foreign-keys-method` |
+
+## Rollback
+
+- An `INSTANT`/`INPLACE` `ALTER` is a single transaction-like operation: if it fails it leaves the
+  table unchanged. There is no half-applied state to clean up.
+- gh-ost / pt-osc: before cutover, the original table is untouched — abort freely (gh-ost: remove
+  the panic flag or kill it; the `_gho`/`_new` shadow + `_del` old table are left for you to drop).
+  *After* cutover, "rollback" means running the reverse `ALTER` as a new migration. Design the
+  reverse step before you cut over.
+
+## How this composes with db-migrations expand-contract
+
+The vendor-neutral pattern from `db-migrations` is: **expand** (add the new column/index, both old
+and new readable), **migrate** (backfill + dual-write), **contract** (drop the old). Each phase maps
+to a specific MySQL mechanic here:
+
+- *Expand* = an `ALGORITHM=INSTANT` add-column / `INPLACE` add-index — cheap, non-blocking.
+- *Backfill* = chunked `UPDATE ... WHERE id BETWEEN ? AND ?` in small batches (never one giant
+  `UPDATE` that holds gap locks across the whole table); or let gh-ost do it for a type change.
+- *Contract* = an `INSTANT` drop-column once nothing reads the old one.
+
+Keep each phase a separate, forward-only migration so the reverse is always a clean step.
+`db-migrations` owns *why* and *in what order*; this skill owns *which `ALGORITHM=` / which tool*.

package/skills/mysql/references/replication-and-ha.md

@@ -0,0 +1,115 @@
+# Replication and HA
+
+MySQL 8.4 / MariaDB 11.8 replication mechanics: binlog formats, GTID, the topologies, lag diagnosis,
+and failover. Backup *strategy* as a discipline lives in `backups`; this owns the binlog/PITR and
+replication-setup mechanics.
+
+## Binlog format — ROW, and why
+
+| Format | What it logs | Verdict |
+|---|---|---|
+| `ROW` | The actual before/after row images | **The only safe default.** Deterministic; replicas apply exactly what happened. |
+| `STATEMENT` | The literal SQL text | Non-deterministic statements (`NOW()`, `UUID()`, `LIMIT` without `ORDER BY`, triggers) replicate *differently* on the replica → silent data drift. |
+| `MIXED` | STATEMENT, switching to ROW when it detects non-determinism | Better than STATEMENT but the detection is imperfect; prefer ROW outright. |
+
+```ini
+# my.cnf — the replication baseline.
+[mysqld]
+server_id              = 1            # unique per host in the topology
+log_bin                = mysql-bin
+binlog_format          = ROW
+gtid_mode              = ON
+enforce_gtid_consistency = ON
+binlog_expire_logs_seconds = 604800   # 7 days of binlog retained for replicas/PITR
+```
+
+## GTID-based replication, end to end
+
+A GTID (Global Transaction ID) tags every committed transaction with `source_uuid:sequence`. The
+replica records which GTIDs it has applied, so with `SOURCE_AUTO_POSITION=1` it requests exactly the
+transactions it's missing — no manual log-file/position bookkeeping, and each transaction applies
+**at most once** (auto-skip on reconnect/failover).
+
+**MySQL 8.4 adds tagged GTIDs**: an optional third, colon-separated component
+(`source_uuid:tag:sequence`) that groups related transactions — useful to mark, filter, or
+selectively skip a logical batch.
+
+```sql
+-- On the replica (8.4 syntax: CHANGE REPLICATION SOURCE TO, not the old CHANGE MASTER TO).
+CHANGE REPLICATION SOURCE TO
+  SOURCE_HOST='primary.db',
+  SOURCE_USER='repl',
+  SOURCE_PASSWORD='***',
+  SOURCE_SSL=1,                 -- caching_sha2_password needs TLS
+  SOURCE_AUTO_POSITION=1;       -- GTID auto-positioning
+START REPLICA;
+SHOW REPLICA STATUS\G
+```
+
+The replication user authenticates with `caching_sha2_password` by default, so the channel must use
+`SOURCE_SSL=1` or the first-time auth fails.
+
+## Topology chooser
+
+| Topology | Durability on primary loss | Use when |
+|---|---|---|
+| **Async** (default) | Can lose the last un-replicated transactions | Read scaling, geo replicas, where small data-loss-on-failover is acceptable |
+| **Semi-synchronous** | Primary waits for ≥1 replica to *receive* (not apply) each commit | You need "committed means at least one replica has it" without full consensus cost |
+| **Group Replication / InnoDB Cluster** | Quorum-committed (Paxos-style); automatic failover | You need automatic failover and a single logical primary with managed membership |
+
+InnoDB Cluster = Group Replication + MySQL Shell (`dba.createCluster()`) for orchestration + **MySQL
+Router** as the connection front-end that routes writes to the primary and reads to replicas. Apps
+connect to the Router's port (6446 read-write / 6447 read-only), never directly to a node, so a
+failover is transparent to the application.
+
+```ini
+# Semi-sync (loadable component in 8.4): primary waits for one replica to ACK receipt.
+[mysqld]
+rpl_semi_sync_source_enabled  = 1
+rpl_semi_sync_source_timeout  = 1000   # ms before falling back to async if no ACK
+rpl_semi_sync_replica_enabled = 1
+```
+
+## Replica-lag diagnosis — read the field, don't eyeball
+
+```sql
+SHOW REPLICA STATUS\G
+-- Read in this order:
+--   Replica_IO_Running  / Replica_SQL_Running  → both must be 'Yes'
+--   Last_IO_Error / Last_SQL_Error             → why it stopped
+--   Seconds_Behind_Source                      → coarse; NULL means BROKEN, not "0 lag"
+```
+
+`Seconds_Behind_Source` is a blunt instrument (it's relative to the SQL thread's current event, and
+goes NULL the moment a thread stops). For real, per-worker lag use performance_schema:
+
+```sql
+SELECT WORKER_ID,
+       LAST_APPLIED_TRANSACTION,
+       APPLYING_TRANSACTION,
+       APPLYING_TRANSACTION_ORIGINAL_COMMIT_TIMESTAMP
+FROM performance_schema.replication_applier_status_by_worker;
+
+-- End-to-end lag = now() - the original commit timestamp of the transaction being applied.
+```
+
+If lag is structural, enable multi-threaded apply (`replica_parallel_workers > 0`,
+`replica_parallel_type = LOGICAL_CLOCK`) so the replica applies independent transactions in parallel.
+
+## Failover
+
+- **Async/semi-sync, manual**: pick the most-caught-up replica (highest applied GTID set), point the
+  other replicas and the app at it, `RESET REPLICA ALL` on the new primary. GTID auto-positioning
+  means surviving replicas resync from exactly where they were.
+- **InnoDB Cluster**: failover is automatic — the group elects a new primary; MySQL Router redirects
+  writes. Your job is to monitor `cluster.status()` and re-add the recovered node with
+  `cluster.rejoinInstance()`.
+- Always confirm the old primary is truly down (fenced) before promoting — a split brain where two
+  nodes both accept writes is the worst outcome, far worse than a few seconds of downtime.
+
+## Read-replica routing
+
+Route reads to replicas but **never read your own just-written row from a lagging async replica** —
+that's the read-after-write consistency trap. Either route a user's reads to the primary for a short
+window after their write, or use `WAIT_FOR_EXECUTED_GTID_SET()` on the replica to block until it has
+caught up to the GTID your write produced. InnoDB Cluster's Router can be configured for this.

package/skills/mysql/scripts/verify.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — mysql skill gate. Run from your PROJECT root.
+#
+# What it does (read-only, idempotent, never writes, NEVER connects to a database):
+#   Discovers *.sql and *.cnf / my.cnf files and heuristically lints them for the MySQL/InnoDB
+#   foot-guns this skill warns about:
+#     - CHARACTER SET utf8 / CHARSET=utf8 that is not utf8mb4 (silent emoji truncation)   [warn]
+#     - ENGINE=MyISAM on CREATE TABLE (no transactions/FKs)                               [warn]
+#     - likely random-UUID / CHAR(36) PRIMARY KEY (InnoDB clustered-index bloat)          [warn]
+#     - default_authentication_plugin = mysql_native_password in config                   [warn]
+#     - an indexed column wrapped in a function in WHERE (DATE(col)/LOWER(col), non-sargable) [warn]
+#     - binlog_format = STATEMENT in a committed config                                   [FAIL]
+#     - unbalanced parens/single-quotes in a SQL statement                                [FAIL]
+#   Optionally runs `sqlfluff --dialect mysql` if sqlfluff is installed.
+#
+# Exit code: non-zero ONLY on (a) unbalanced delimiters, (b) a committed binlog_format=STATEMENT,
+# or (c) a real sqlfluff lint error. Every schema heuristic is advisory [warn], never a failure.
+# An empty/clean target exits 0 with no false failure.
+#
+# Portability: stock macOS bash 3.2 — no mapfile, no associative arrays. Arrays are initialised so
+# they are safe to expand under `set -u`. Pure grep/awk; no network, no mysql client.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+note() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+ROOT="$(pwd)"
+
+# --- discover files (exclude vendor dirs) -----------------------------------------------------
+SQL_FILES=()
+while IFS= read -r -d '' f; do SQL_FILES+=("$f"); done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' \) -prune -o \
+    -type f -name '*.sql' -print0 2>/dev/null
+)
+
+CNF_FILES=()
+while IFS= read -r -d '' f; do CNF_FILES+=("$f"); done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' \) -prune -o \
+    -type f \( -name '*.cnf' -o -name 'my.cnf' \) -print0 2>/dev/null
+)
+
+if [ "${#SQL_FILES[@]}" -eq 0 ] && [ "${#CNF_FILES[@]}" -eq 0 ]; then
+  ok "no *.sql or *.cnf files found — nothing to lint"
+  exit 0
+fi
+
+# --- strip comments + string literals for the balance heuristic -------------------------------
+# Pure awk so it behaves identically on BSD (macOS) and GNU awk. Removes -- line comments,
+# /* */ block comments, and '...' single-quoted literals (handling '' escapes) so the
+# paren/quote balance check does not trip on legitimate content.
+strip_sql() {
+  awk '
+    BEGIN { inblock = 0; instr = 0 }
+    {
+      line = $0; out = ""; i = 1; n = length(line)
+      while (i <= n) {
+        ch  = substr(line, i, 1)
+        ch2 = substr(line, i, 2)
+        if (inblock) { p = index(substr(line,i), "*/"); if (p==0){i=n+1;continue} i+=p+1; inblock=0; continue }
+        if (instr)   {
+          if (ch == "\x27") {
+            if (substr(line,i,2) == "\x27\x27") { i+=2; continue }   # escaped quote
+            instr = 0; i++; continue
+          }
+          i++; continue
+        }
+        if (ch2 == "--") { i = n + 1; continue }
+        if (ch2 == "/*") { inblock = 1; i += 2; continue }
+        if (ch == "\x27") { instr = 1; i++; continue }
+        out = out ch; i++
+      }
+      print out
+    }
+  ' "$1"
+}
+
+# --- per-SQL-file checks ----------------------------------------------------------------------
+for f in ${SQL_FILES[@]+"${SQL_FILES[@]}"}; do
+  # legacy utf8 (not utf8mb4)
+  if grep -Eiq '(CHARACTER[[:space:]]+SET|CHARSET[[:space:]]*=)[[:space:]]*utf8([^m]|$|mb3)' "$f"; then
+    note "$f: legacy 'utf8' (utf8mb3) charset — silently truncates emoji. Use utf8mb4."
+  fi
+  # MyISAM
+  if grep -Eiq 'ENGINE[[:space:]]*=[[:space:]]*MyISAM' "$f"; then
+    note "$f: ENGINE=MyISAM — no transactions/FKs, crash-unsafe. Use InnoDB."
+  fi
+  # likely random-UUID / CHAR(36) PK
+  if grep -Eiq 'CHAR\(36\)[^,)]*PRIMARY[[:space:]]+KEY|PRIMARY[[:space:]]+KEY[^,)]*CHAR\(36\)' "$f"; then
+    note "$f: CHAR(36) PRIMARY KEY — likely a random UUID PK; bloats InnoDB secondary indexes. Prefer BIGINT AUTO_INCREMENT or UUIDv7 as BINARY(16)."
+  fi
+  # function-wrapped indexed column in WHERE (non-sargable)
+  if grep -Eiq 'WHERE[[:space:]].*(DATE|LOWER|UPPER|YEAR|MONTH|CAST|CONVERT)[[:space:]]*\([[:alnum:]_.`]+\)[[:space:]]*=' "$f"; then
+    note "$f: a function-wrapped column in WHERE (e.g. WHERE DATE(col)=...) is non-sargable — the index can't be used. Rewrite to a range, or add a functional/generated-column index."
+  fi
+  # balance check on comment/literal-stripped SQL
+  stripped="$(strip_sql "$f")"
+  opens="$(printf '%s' "$stripped" | tr -cd '(' | wc -c | tr -d ' ')"
+  closes="$(printf '%s' "$stripped" | tr -cd ')' | wc -c | tr -d ' ')"
+  quotes="$(printf '%s' "$stripped" | tr -cd "\047" | wc -c | tr -d ' ')"
+  if [ "$opens" != "$closes" ]; then
+    err "$f: unbalanced parentheses ($opens '(' vs $closes ')')."
+  fi
+  if [ $(( quotes % 2 )) -ne 0 ]; then
+    err "$f: unbalanced single-quotes after stripping comments/literals."
+  fi
+done
+
+# --- per-config-file checks -------------------------------------------------------------------
+for f in ${CNF_FILES[@]+"${CNF_FILES[@]}"}; do
+  if grep -Eiq '^[[:space:]]*binlog_format[[:space:]]*=[[:space:]]*STATEMENT' "$f"; then
+    err "$f: binlog_format = STATEMENT — non-deterministic statements drift on replicas. Use ROW."
+  fi
+  if grep -Eiq '^[[:space:]]*default_authentication_plugin[[:space:]]*=[[:space:]]*mysql_native_password' "$f"; then
+    note "$f: default_authentication_plugin = mysql_native_password — disabled by default in 8.4, removed in 9.0. Use caching_sha2_password + TLS."
+  fi
+done
+
+# --- optional sqlfluff --------------------------------------------------------------------------
+if [ "${#SQL_FILES[@]}" -gt 0 ]; then
+  if command -v sqlfluff >/dev/null 2>&1; then
+    if sqlfluff lint --dialect mysql ${SQL_FILES[@]+"${SQL_FILES[@]}"} >/dev/null 2>&1; then
+      ok "sqlfluff (dialect mysql): no lint errors"
+    else
+      err "sqlfluff (dialect mysql) reported lint errors — run: sqlfluff lint --dialect mysql <file>"
+    fi
+  else
+    skip "sqlfluff not installed — skipping SQL lint (advisory)"
+  fi
+fi
+
+if [ "$EXIT" -eq 0 ]; then
+  ok "verify passed (advisory warnings, if any, are non-blocking)"
+fi
+exit "$EXIT"

package/skills/n8n/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: n8n
+description: "Use when operating a live n8n instance programmatically — its REST API (`{host}/api/v1`, `X-N8N-API-KEY`) or the n8n-mcp server — to create, validate, test, activate, update, delete workflows and read executions on self-host or n8n.cloud. NOT designing the flow or its importable JSON (that is `automation-flows`), NOT another platform (`make`, `zapier`)."
+tags: [n8n, automation, workflows, mcp, rest-api, no-code, integrations]
+recommends: [automation-flows, automation-strategy, api-connector-builder, webhooks]
+profiles: [full]
+origin: risco
+---
+
+# n8n — operate a live instance over its REST API and MCP
+
+You already have a workflow *design* — the trigger→steps→error shape and the importable JSON, which is
+`automation-flows`' job and this skill does not re-teach it. This skill is the **operate** half: push
+that JSON into a running n8n, validate it, test it, flip it live, watch its executions, and tear it
+down safely — all without touching the UI. n8n has the richest programmatic story of the no-code
+platforms: a first-party REST API **plus** a mature MCP server, both hitting the same instance.
+
+## Connect first — REST API vs MCP
+
+Two ways to drive the same instance. Pick by who is at the wheel.
+
+| | **Public REST API** | **n8n-mcp** (czlonkowski, de-facto standard) |
+|---|---|---|
+| What it is | n8n's own HTTP API at `{host}/api/v1` | MCP server wrapping that API **+** offline node/expression knowledge |
+| Best for | scripts, CI/CD, deterministic deploys, no extra dependency | an agent (Claude) building/fixing workflows in the loop — it can look up node schemas, then validate/autofix before it writes |
+| Auth | API key in header `X-N8N-API-KEY` | management tools need `N8N_API_URL` + `N8N_API_KEY`; **node-knowledge tools need no auth** |
+| Surface | identical on self-host **and** `*.app.n8n.cloud` | same underlying API; hosted trial at `dashboard.n8n-mcp.com` |
+
+**Version reality (verify at author time — n8n moves fast):**
+- API base is `{host}/api/v1`. Self-host ships interactive Swagger at `/api/v1/docs`; **cloud does not**
+  — on cloud, work from the docs.
+- `POST /workflows/{id}/execute` (run-by-id) is **recent** (n8n PR #20234). Older instances lack it —
+  there, the only programmatic run is POSTing to a Webhook node's URL.
+
+### `.env`
+
+```bash
+# host root only — you append /api/v1 for REST; n8n-mcp reads it whole
+N8N_API_URL=https://your-instance.app.n8n.cloud   # or N8N_HOST for self-host, e.g. http://localhost:5678
+N8N_API_KEY=n8n_api_...                            # Settings → n8n API → Create an API key
+```
+
+Never inline the key in a command that gets logged, and never put a *node* credential (Slack token,
+etc.) in the workflow payload — reference it by the n8n **credential store** id/name (see
+automation-flows' JSON schema). Full key-creation + self-host vs cloud + MCP install:
+`references/auth-and-selfhost.md`.
+
+## The payload you POST
+
+The create/update body is exactly the automation-flows workflow JSON. Required top-level keys on
+**create**: `name`, `nodes`, `connections`, `settings`. Build it per
+`../automation-flows/references/n8n-workflow-json.md` — non-empty `nodes` with one trigger, a wired
+`connections` map, `settings.errorWorkflow`, credentials referenced by store (never inlined).
+
+**Node/expression essentials** (pointer, not a tutorial): node `type` is namespaced
+(`n8n-nodes-base.webhook`), `typeVersion` must match a node version installed on the target instance
+or activation/execution fails; field values use expressions like `={{ $json.email }}` or
+`={{ $node["Webhook"].json.body.id }}`. If you are hand-authoring nodes, let n8n-mcp's node-knowledge
+tools (`search_nodes`, `get_node_essentials`, `validate_node_operation`) fill in the exact property
+shapes rather than guessing — that is the single biggest reason to drive via MCP.
+
+## Dynamic lifecycle
+
+create → **validate** → test → **activate** → manage → delete. A concrete sketch per step, curl and
+n8n-mcp side by side; every endpoint with pagination and scopes is in
+`references/rest-api-cheatsheet.md`.
+
+### 1. Validate (do this BEFORE create)
+
+REST has no validation endpoint — n8n only tells you at create/activate time. MCP does, so validate
+first when it is available:
+
+```
+n8n_validate_workflow   { "workflow": { …the full JSON… } }
+n8n_autofix_workflow    { "workflow": { … } }   # repairs common structural errors, returns fixed JSON
+```
+
+### 2. Create
+
+```bash
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows" \
+  -H "X-N8N-API-KEY: $N8N_API_KEY" -H "Content-Type: application/json" \
+  -d @workflow.json          # body = { name, nodes, connections, settings }
+# → returns the created workflow WITH its "id" — capture it for every step below
+```
+```
+n8n_create_workflow     { "name": "...", "nodes": [ … ], "connections": { … }, "settings": { … } }
+```
+
+### 3. Test / dry-run
+
+- **No input needed** → run by id (recent instances only): `POST /workflows/{id}/execute`.
+- **Needs input** → the execute endpoint accepts none. Make the trigger a **Webhook node** and POST to
+  its URL (test URL `/webhook-test/<path>` while "Listen for test event" is armed; production
+  `/webhook/<path>` once active).
+
+```bash
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/execute" -H "X-N8N-API-KEY: $N8N_API_KEY"
+curl -sS -X POST "$N8N_API_URL/webhook-test/my-path" -H "Content-Type: application/json" -d '{"foo":"bar"}'
+```
+```
+n8n_test_workflow       { "id": "$ID" }
+```
+
+### 4. Activate — the step people miss
+
+`active` (and `tags`) in the create/update body are **read-only and silently ignored**. Setting
+`"active": true` does nothing, which is why the workflow you just created never fires. You MUST call
+the separate endpoint:
+
+```bash
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/activate"   -H "X-N8N-API-KEY: $N8N_API_KEY"
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/deactivate" -H "X-N8N-API-KEY: $N8N_API_KEY"
+```
+n8n-mcp deliberately does not expose activate/deactivate as tools (activation has live side effects).
+Check the current tool list; if absent, call the REST `/activate` endpoint as above.
+
+### 5. Manage
+
+```bash
+curl -sS "$N8N_API_URL/api/v1/workflows?limit=50"      -H "X-N8N-API-KEY: $N8N_API_KEY"  # list (paginate via nextCursor)
+curl -sS "$N8N_API_URL/api/v1/workflows/$ID"           -H "X-N8N-API-KEY: $N8N_API_KEY"  # get
+curl -sS -X PUT "$N8N_API_URL/api/v1/workflows/$ID"    -H "X-N8N-API-KEY: $N8N_API_KEY" \
+  -H "Content-Type: application/json" -d @workflow.json                                  # FULL replace
+curl -sS "$N8N_API_URL/api/v1/executions?workflowId=$ID&limit=20" -H "X-N8N-API-KEY: $N8N_API_KEY"
+```
+```
+n8n_list_workflows {}        n8n_get_workflow { "id": "$ID" }        n8n_executions { "workflowId": "$ID" }
+n8n_update_full_workflow    { "id": "$ID", "nodes": [ … ], "connections": { … } }   # replace everything
+n8n_update_partial_workflow { "id": "$ID", "operations": [ … ] }                    # atomic diff — preferred
+n8n_health_check {}          # confirm API reachable + which features the instance supports
+```
+`PUT` is a **full replace** — GET, mutate the whole object, PUT it back, or you drop the nodes you
+omitted. n8n-mcp's `n8n_update_partial_workflow` applies a targeted, atomic batch instead (safer).
+
+### 6. Delete — irreversible
+
+`DELETE` is a **hard delete: no trash, no undo**, so export the current JSON first, every time — this
+one is absolute because nothing downstream can recover the workflow if you skip it.
+
+```bash
+curl -sS "$N8N_API_URL/api/v1/workflows/$ID" -H "X-N8N-API-KEY: $N8N_API_KEY" > backup-$ID.json  # export FIRST
+curl -sS -X DELETE "$N8N_API_URL/api/v1/workflows/$ID" -H "X-N8N-API-KEY: $N8N_API_KEY"
+```
+```
+n8n_get_workflow { "id": "$ID" }   →  save output  →  n8n_delete_workflow { "id": "$ID" }
+```
+
+The same applies to a full replace: export before `PUT`.
+
+## Governance
+
+If you expose n8n-mcp to an agent, lock down destructive tools with the `DISABLED_TOOLS` env var
+(comma-separated), e.g. `DISABLED_TOOLS=n8n_delete_workflow,n8n_update_full_workflow`. Scope the API
+key itself too — n8n supports scoped keys (e.g. grant `workflow:read` without `workflow:execute`).
+Details in `references/n8n-mcp-tools.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| `"active": true` (or `tags`) in the create/update body | Read-only fields, silently ignored — the #1 "why is my workflow inactive" bug | `POST /workflows/{id}/activate`; set tags via their own endpoint |
+| Passing runtime input to `/workflows/{id}/execute` | It accepts no custom input, and older instances 404 the endpoint entirely | Trigger a Webhook workflow by POSTing to its URL |
+| `PUT` with a partial body, or `DELETE` on a live workflow | Full replace drops every node you omitted; delete is a hard delete with no trash | GET and export first; prefer `n8n_update_partial_workflow` for edits |
+| A `typeVersion` the target instance doesn't have | Create succeeds; it fails only at activate/execute time | Validate via MCP, or test, before activating |
+| Inlining node credential secrets, or expecting to read them back | Credentials are not fully manageable over the public API — it can create some, but never returns a secret | Provision in the UI or via `n8n_manage_credentials`, then reference existing credentials by id/name |
+| Treating a successful API activation as proof it works | The public API historically skips a few UI-side activation validations, so a workflow can be "active" yet non-functional | Run it live after activating and check the execution |
+
+## Route elsewhere
+
+| If the ask is | Skill |
+|---|---|
+| Designing the flow (trigger/steps/error path, dedup) and producing the importable JSON | `automation-flows` — start there if the logic isn't settled |
+| Whether n8n is the right platform at all — cost model, self-host vs cloud | `automation-strategy` |
+| Operating a different platform | `make`, `zapier`, `power-automate` (neither Zapier nor Power Automate can create flows via API — n8n's edge) |
+| A generic typed HTTP client with auth/pagination/backoff — real code, not a workflow | `api-connector-builder` |
+| The inbound webhook receiver in your own app (here webhooks are only n8n triggers) | `webhooks` |

package/skills/n8n/evals/README.md

@@ -0,0 +1,14 @@
+# Evals — n8n
+
+`cases.yaml` has three groups. `should_trigger` covers the operate tasks this skill owns: deploying a
+workflow JSON over the REST API, the read-only-`active` gotcha, wiring n8n-mcp management tools,
+running a workflow by id, hard-delete safety, and validate/autofix — with a Spanish phrasing. Each
+`should_not_trigger` names a real sibling: flow design + importable JSON → automation-flows,
+platform/cost choice → automation-strategy, another platform → make, a typed code client →
+api-connector-builder, an in-app inbound receiver → webhooks. `capability` is one end-to-end deploy
+scenario whose `must_include` rubric pins the current API/MCP calls, the honesty limits (read-only
+`active`, no-input `execute`), and the irreversibility rule (export before hard delete).
+
+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 deploy plan/commands and check every `must_include` bullet by hand.

package/skills/n8n/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: n8n
+
+should_trigger:
+  - prompt: "Push my workflow JSON to n8n over the API with curl and turn it on."
+    why: Canonical operate task — POST /workflows then the separate /activate endpoint. Core deliverable.
+  - prompt: "I set active:true in my POST to /api/v1/workflows but the workflow stays inactive. Why?"
+    why: The read-only-active gotcha — active/tags are ignored on create; must call /workflows/{id}/activate.
+  - prompt: "Wire n8n-mcp into Claude Code so it can call n8n_create_workflow and n8n_update_partial_workflow against my instance."
+    why: MCP operate path — configuring the management tier with N8N_API_URL + N8N_API_KEY.
+  - prompt: "How do I run an n8n workflow by its id from a shell script, and can I pass it input data?"
+    why: POST /workflows/{id}/execute (recent) plus the no-custom-input limit → webhook trigger for params.
+  - prompt: "Delete this workflow from my n8n via the API — is there an undo?"
+    why: Hard-delete irreversibility; must export (GET) first, no trash.
+  - prompt: "desplega este workflow a mi n8n.cloud por la API y valídalo antes de activarlo"
+    why: Spanish; programmatic deploy + validate + activate against cloud — same REST surface.
+  - prompt: "Validate and autofix my n8n workflow before I create it, then list its executions."
+    why: n8n_validate_workflow / n8n_autofix_workflow then n8n_executions — MCP management lifecycle.
+
+should_not_trigger:
+  - prompt: "Design an n8n flow: Stripe payment → Notion row → Slack, with an error path and dedup. Give me the importable JSON."
+    route_to: automation-flows
+    why: Designing the trigger/steps/error shape and producing the JSON is automation-flows; this skill only deploys/operates that JSON.
+  - prompt: "Should I use n8n, Make, or Zapier for 50k runs a month, and self-host or cloud?"
+    route_to: automation-strategy
+    why: Platform/cost-model selection, not operating a specific live n8n instance.
+  - prompt: "Create this scenario in my Make account programmatically."
+    route_to: make
+    why: Operating a different platform (Make) — its own skill; Make also has no create-via-API story like n8n's.
+  - prompt: "Write a TypeScript client for the Acme REST API with API-key auth, cursor pagination, and exponential backoff."
+    route_to: api-connector-builder
+    why: A typed HTTP client in code, not driving n8n's API or MCP.
+  - prompt: "Build the endpoint in my Express app that receives and verifies inbound webhook signatures."
+    route_to: webhooks
+    why: An inbound receiver in the user's own app; here webhooks are only n8n triggers, not something this skill builds.
+
+capability:
+  - scenario: "User has an importable n8n workflow JSON (webhook trigger → HTTP node → Slack) and wants it deployed to their n8n.cloud instance: created, tested, activated, and later safely removed — via the REST API and/or n8n-mcp."
+    must_include:
+      - "Reads N8N_API_URL/N8N_HOST + N8N_API_KEY from env; key from Settings → n8n API; sends it as the X-N8N-API-KEY header (not a bearer token)."
+      - "Builds the create body per automation-flows' n8n-workflow-json schema (name, nodes, connections, settings); node credentials referenced by the credential store, never inlined."
+      - "Creates with POST /workflows (or n8n_create_workflow) and captures the returned id for subsequent calls."
+      - "States that active (and tags) are read-only on create/update and activates with a separate POST /workflows/{id}/activate."
+      - "Notes POST /workflows/{id}/execute takes no custom input (and is a recent endpoint), so runtime params require POSTing to a Webhook node URL."
+      - "Exports the workflow (GET /workflows/{id}) before any DELETE, and states DELETE is a hard delete with no trash."
+      - "When driving via MCP, validates/autofixes (n8n_validate_workflow / n8n_autofix_workflow) before create; notes management tools need the two env vars while node-knowledge tools do not."