@awesomate/hosting-mcp 0.2.0 → 0.6.0

package/dist/index.js

@@ -21106,6 +21106,12 @@ var StdioServerTransport = class {
   }
 };
 
+// src/index.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join2, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
 // src/config.ts
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -21208,12 +21214,40 @@ function hubGet(config3, path) {
 function hubPost(config3, path, jsonBody = {}) {
   return hubRequest(config3, "POST", path, jsonBody);
 }
+function hubDelete(config3, path) {
+  return hubRequest(config3, "DELETE", path);
+}
 
 // src/index.ts
 var config2;
+var SERVER_VERSION = (() => {
+  try {
+    const pkg = JSON.parse(
+      readFileSync2(join2(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")
+    );
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+function skillUpdateInfo() {
+  let installedSkillVersion = null;
+  try {
+    installedSkillVersion = readFileSync2(
+      join2(homedir2(), ".claude", "skills", "awesomate-hosting", ".installed-version"),
+      "utf8"
+    ).trim() || null;
+  } catch {
+  }
+  return {
+    serverVersion: SERVER_VERSION,
+    installedSkillVersion,
+    updateAvailable: installedSkillVersion !== SERVER_VERSION
+  };
+}
 var server = new McpServer({
   name: "awesomate-hosting",
-  version: "0.1.0"
+  version: SERVER_VERSION
 });
 function textResult(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
@@ -21231,10 +21265,92 @@ function readTool(name, description, path) {
     }
   });
 }
-readTool(
+server.registerTool(
   "awesomate_get_context",
-  "Call this FIRST each session. Returns the connected Awesomate account: plan, capabilities (shell access), plan limits, scopes this token can exercise, token expiry (warn the user if within 7 days), and cPanel routing when provisioned.",
-  "/api/hosting-access/context"
+  {
+    description: "Call this FIRST each session. Returns the connected Awesomate account: plan, capabilities (shell access), plan limits, scopes this token can exercise, token expiry (warn the user if within 7 days), cPanel routing when provisioned, and skill.updateAvailable \u2014 if true, the local awesomate-hosting skill files are older than this server; tell the user to re-run Connect Claude Code from hub.awesomate.ai/sites to refresh them (this also renews the token).",
+    inputSchema: {}
+  },
+  async () => {
+    try {
+      const ctx = await hubGet(config2, "/api/hosting-access/context");
+      return textResult({ ...ctx, skill: skillUpdateInfo() });
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+readTool(
+  "awesomate_n8n_context",
+  "Call FIRST before any n8n work. Returns the client's n8n instance URL, plan, whether Claude Code n8n access is consented (if consented=false, send the user to settingsUrl and re-check after), builder capability (Support Plus+), instance variant, and build/test quota limits. Companion reads once consented: GET /api/my-n8n/machine/credentials (credential names/types \u2014 never secrets), /credentials/schema/:type, /variables, plus the /api/my-n8n workflows and executions endpoints.",
+  "/api/my-n8n/machine/context"
+);
+server.registerTool(
+  "awesomate_n8n_deploy",
+  {
+    description: "Workflow lifecycle writes on the client's n8n, all consent-gated and audited server-side. Actions: 'validate' (structural + n8n-mcp check of workflowJson \u2014 ALWAYS validate before create_draft), 'create_draft' (creates an INACTIVE '[CLI] ' workflow tagged awm:client-cli; returns its webhook URLs), 'activate'/'deactivate' (activation strips the [CLI] prefix; production webhooks respond only while active; agency-managed workflows are refused), 'promote' (swaps a TESTED draft into the live workflow IN PLACE \u2014 live id + webhookIds preserved so external callers keep working; pass workflowId=the LIVE id and draftId=the tested draft; the draft is archived '[promoted <date>]'; response includes operationId for rollback), 'rollback' (restore a promote's pre-swap state \u2014 pass operationId), 'delete_draft' (inactive self-built drafts only). Get explicit user approval before activate, promote, rollback, and delete_draft. 429 quota_exceeded = daily plan limit; 403 consent_required \u2192 send user to settingsUrl.",
+    inputSchema: {
+      action: external_exports.enum(["validate", "create_draft", "activate", "deactivate", "promote", "rollback", "delete_draft"]),
+      workflowJson: external_exports.record(external_exports.unknown()).optional().describe("For validate: the full workflow JSON. For create_draft: must contain name, nodes, connections (settings optional)."),
+      workflowId: external_exports.string().optional().describe("Required for activate/deactivate/delete_draft; for promote this is the LIVE workflow id"),
+      draftId: external_exports.string().optional().describe("promote only: the tested draft to swap into the live workflow"),
+      operationId: external_exports.string().optional().describe("rollback only: the operationId returned by promote")
+    }
+  },
+  async ({ action, workflowJson, workflowId, draftId, operationId }) => {
+    try {
+      if (action === "validate") {
+        return textResult(await hubPost(config2, "/api/my-n8n/machine/workflows/validate", { workflow: workflowJson }));
+      }
+      if (action === "create_draft") {
+        return textResult(await hubPost(config2, "/api/my-n8n/machine/workflows/draft", workflowJson ?? {}));
+      }
+      if (action === "rollback") {
+        if (!operationId) return errorResult(new Error("operationId is required for rollback"));
+        return textResult(
+          await hubPost(config2, `/api/my-n8n/machine/operations/${encodeURIComponent(operationId)}/rollback`, {})
+        );
+      }
+      if (!workflowId) return errorResult(new Error(`workflowId is required for ${action}`));
+      if (action === "activate" || action === "deactivate") {
+        return textResult(
+          await hubPost(config2, `/api/my-n8n/machine/workflows/${encodeURIComponent(workflowId)}/activate`, {
+            active: action === "activate"
+          })
+        );
+      }
+      if (action === "promote") {
+        if (!draftId) return errorResult(new Error("draftId is required for promote"));
+        return textResult(
+          await hubPost(config2, `/api/my-n8n/machine/workflows/${encodeURIComponent(workflowId)}/promote`, { draftId })
+        );
+      }
+      return textResult(
+        await hubDelete(config2, `/api/my-n8n/machine/workflows/${encodeURIComponent(workflowId)}`)
+      );
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_n8n_test",
+  {
+    description: "Fire a synthetic test payload at an ACTIVE self-built workflow's production webhook and get back the webhook response plus the executionId it caused (then poll GET /api/my-n8n/executions/:id for node-by-node results). Sends the X-Awesomate-Test header. Real side effects DO run (emails actually send) \u2014 warn the user, use their own address, prefix subjects with [TEST]. Only works on awm:client-cli-tagged workflows.",
+    inputSchema: {
+      workflowId: external_exports.string(),
+      payload: external_exports.record(external_exports.unknown()).optional().describe("JSON body to POST to the webhook (format-valid, obviously-fake values)")
+    }
+  },
+  async ({ workflowId, payload }) => {
+    try {
+      return textResult(
+        await hubPost(config2, `/api/my-n8n/machine/workflows/${encodeURIComponent(workflowId)}/test-fire`, { payload })
+      );
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
 );
 readTool(
   "awesomate_get_hosting_status",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.2.0",
-  "description": "Awesomate Hosting MCP server — lets Claude manage your Awesomate WordPress hosting, plan, and limits",
+  "version": "0.6.0",
+  "description": "Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, and n8n automations",
   "license": "UNLICENSED",
   "type": "module",
   "publishConfig": {

package/skill/awesomate-hosting/SKILL.md

@@ -32,11 +32,20 @@ context note three things and cache them for the session:
 - **`patExpiresAt`** — if it's within ~7 days, tell the user to open
   **hub.awesomate.ai/sites → Connect Claude Code** and re-run the setup prompt to
   refresh the token. If any tool returns a 401, do the same.
+- **`skill.updateAvailable`** — if true, this skill's local files are older than
+  the MCP server. Mention it once (don't nag): re-running Connect Claude Code
+  from **hub.awesomate.ai/sites** refreshes the skill and renews the token in
+  one go. Not urgent — finish the user's actual request first.
 - **`cpanel`** routing (host/user), present once hosting is provisioned.
 
 If `awesomate_get_context` fails with a connectivity error, it's the user's
 network or the API base — not an auth problem; say so.
 
+If this skill is loaded but **no `awesomate_*` tools exist in the session at
+all**, the MCP server was registered after Claude Code started (the bootstrap
+just ran). Don't investigate settings files or reinstall anything — ask the
+user to restart Claude Code and try again.
+
 ## 1. The plan model (so your nudges are accurate)
 
 | Plan | WP sites | Custom domains | Shell / Claude Code | Notes |

package/skill/awesomate-hosting/scripts/bootstrap.mjs

@@ -68,23 +68,54 @@ function writeCreds(creds) {
  * failure here never aborts the rest of setup.
  */
 function installSkill() {
-  // bootstrap.mjs lives at <skill>/scripts/bootstrap.mjs → the skill dir is `..`.
-  const skillSrc = dirname(dirname(fileURLToPath(import.meta.url)));
-  if (!existsSync(join(skillSrc, 'SKILL.md'))) {
-    console.log('• Skill files not found next to bootstrap — skipping skill install (MCP still works).');
-    return false;
+  // bootstrap.mjs lives at <skill>/scripts/bootstrap.mjs → the skill dir is
+  // `..` and every sibling of it under the package's skill/ dir is another
+  // bundled skill (e.g. awesomate-n8n). Install them all. When bootstrap is
+  // re-run from an already-installed copy (~/.claude/skills/...), the parent
+  // is the user's whole skills folder — in that case only reinstall this one
+  // skill, never its unrelated siblings.
+  const hostingSkill = dirname(dirname(fileURLToPath(import.meta.url)));
+  const skillRoot = dirname(hostingSkill);
+  // Only the package layout (skill/<name>/) has bundled siblings; from an
+  // installed copy the parent is the user's skills folder full of unrelated
+  // skills, so fall back to just this skill.
+  const bundled = skillRoot.endsWith('/skill')
+    ? readdirSync(skillRoot)
+    : [hostingSkill.split('/').pop()];
+  // Package version, stamped into each installed skill as .installed-version.
+  // The MCP server (always latest via unpinned npx) compares it against its own
+  // version and reports skill.updateAvailable in awesomate_get_context.
+  let pkgVersion = null;
+  if (skillRoot.endsWith('/skill')) {
+    try {
+      pkgVersion = JSON.parse(readFileSync(join(dirname(skillRoot), 'package.json'), 'utf8')).version ?? null;
+    } catch { /* non-fatal — marker just won't be written */ }
   }
-  const dest = join(homedir(), '.claude', 'skills', 'awesomate-hosting');
-  mkdirSync(dirname(dest), { recursive: true });
-  cpSync(skillSrc, dest, { recursive: true, force: true });
-  // Make the shell/mjs helpers executable (npm can publish them non-+x).
-  const scriptsDir = join(dest, 'scripts');
-  if (existsSync(scriptsDir)) {
-    for (const f of readdirSync(scriptsDir)) {
-      if (/\.(sh|mjs)$/.test(f)) { try { chmodSync(join(scriptsDir, f), 0o755); } catch { /* non-fatal */ } }
+  let installed = 0;
+  for (const name of bundled) {
+    const src = join(skillRoot, name);
+    if (!existsSync(join(src, 'SKILL.md'))) continue;
+    const dest = join(homedir(), '.claude', 'skills', name);
+    if (src === dest) { installed += 1; continue; } // already running from the installed copy
+    mkdirSync(dirname(dest), { recursive: true });
+    cpSync(src, dest, { recursive: true, force: true });
+    // Make the shell/mjs helpers executable (npm can publish them non-+x).
+    const scriptsDir = join(dest, 'scripts');
+    if (existsSync(scriptsDir)) {
+      for (const f of readdirSync(scriptsDir)) {
+        if (/\.(sh|mjs)$/.test(f)) { try { chmodSync(join(scriptsDir, f), 0o755); } catch { /* non-fatal */ } }
+      }
     }
+    if (pkgVersion) {
+      try { writeFileSync(join(dest, '.installed-version'), `${pkgVersion}\n`); } catch { /* non-fatal */ }
+    }
+    console.log(`✓ Installed the "${name}" skill to ${dest}.`);
+    installed += 1;
+  }
+  if (installed === 0) {
+    console.log('• Skill files not found next to bootstrap — skipping skill install (MCP still works).');
+    return false;
   }
-  console.log(`✓ Installed the "awesomate-hosting" skill to ${dest}.`);
   return true;
 }
 

package/skill/awesomate-n8n/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: awesomate-n8n
+description: Build, test, and manage the user's Awesomate-hosted n8n automations from Claude Code. Use when the user mentions their n8n instance, workflows, automations, executions, webhooks, workflow errors, "{slug}.awesomate.io", or asks to build/change an automation or explain why one failed. Companion to the awesomate-hosting skill — same connection, same PAT.
+---
+
+# Awesomate n8n — your automations from Claude Code
+
+The user's business runs n8n workflows on an Awesomate-hosted instance. This
+skill lets you read, explain, diagnose, **build, test, and activate** those
+workflows through the Awesomate hub. Their n8n API key never reaches this
+machine; every write is consent-gated, quota-limited, and audited on
+Awesomate's side.
+
+**What you can do:** everything in the read table below, plus (Support Plus
+and above, with consent): validate workflow JSON, create inactive `[CLI]`
+drafts, test-fire their webhooks, activate/deactivate, **promote a tested
+draft into a live workflow in place** (id + webhook URLs preserved), roll a
+promote back, and delete drafts — via the `awesomate_n8n_deploy` and
+`awesomate_n8n_test` tools.
+
+## 0. First run (every session)
+
+Call `awesomate_n8n_context` once before any n8n work and cache the result:
+
+- `consented: false` → give the user the `settingsUrl` link (Settings →
+  Privacy → "Allow Claude Code to Build n8n Workflows"), wait for them to
+  confirm, then call context again.
+- `403 missingScopes` → their token predates n8n support or their plan lacks
+  it — reconnect from hub.awesomate.ai/sites (Connect Claude Code card).
+- `capabilities.builder: false` → reads only; building is Support Plus+.
+- `capabilities.variant` → `FFMPEG` variants include the media community
+  nodes (localFiles, better-ffmpeg); Standard does not. Never assume a node
+  exists on the target — verify in existing workflows or ask.
+- `limits` → your daily build/test quotas and the active-workflow cap;
+  respect them, don't burn tests.
+
+Read [references/node-recipes.md](references/node-recipes.md) BEFORE
+designing or diagnosing — it's the live truth for this platform ($vars not
+$env, `$json.body`, task-runner limits, activation semantics).
+
+## 1. Reads
+
+PAT as `Authorization: Bearer <pat>` (from `~/.awesomate/credentials.json`)
+against `apiBase`. Never echo the PAT into the conversation.
+
+| What | Endpoint |
+|---|---|
+| Session context (tool) | `awesomate_n8n_context` |
+| List workflows | `GET /api/my-n8n/workflows` |
+| One workflow (full JSON) | `GET /api/my-n8n/workflows/:id` |
+| Executions | `GET /api/my-n8n/workflows/:id/executions` · detail: `GET /api/my-n8n/executions/:execId` |
+| Credential inventory (names/types only) | `GET /api/my-n8n/machine/credentials` |
+| Credential type schema | `GET /api/my-n8n/machine/credentials/schema/:type` |
+| `$vars` keys | `GET /api/my-n8n/machine/variables` |
+
+## 2. The build loop (follow ALL six phases)
+
+**Phase 1 — Discovery.** Understand inputs/outputs, trigger, success
+criteria, error handling. Check the credential inventory and `$vars` FIRST —
+reuse what exists. Email decision tree: existing Gmail/Google credential in
+inventory → reference its ID · none → offer an API-key credential (SMTP /
+Resend / SendGrid — instant) OR guided Gmail OAuth: the user connects it in
+their n8n UI at `{instanceUrl}/home/credentials`, you re-check the inventory
+to verify before continuing. Never claim a credential works because it
+exists — the inventory shows names, not validity.
+
+**Phase 2 — Design.** Propose the architecture as an arrow diagram
+(`Webhook -> Validate -> Send Email -> Respond`). Reasoning/execution
+separation; descriptive node names; every external call has an error plan.
+For externally-called workflows use a **webhook trigger with an explicit
+path** (e.g. `signup-v1`) — not a Form Trigger.
+
+**Phase 3 — Confirmation.** Present the design and wait for explicit
+approval. Never create anything on their instance without it.
+
+**Phase 4 — Implementation.** Compose the workflow JSON, then
+`awesomate_n8n_deploy {action:'validate', workflowJson}` and fix every
+error-severity issue before creating. Then
+`{action:'create_draft', workflowJson:{name, nodes, connections}}` — the hub
+prefixes `[CLI] `, tags `awm:client-cli`, pre-assigns webhookIds, applies
+the required workflow settings, and returns the production webhook URLs.
+
+**Phase 5 — Testing (mandatory — validation alone is never done).**
+1. Get approval to go live for testing, then `{action:'activate', workflowId}`
+   (production webhooks only respond while active; activation drops the
+   `[CLI]` prefix).
+2. `awesomate_n8n_test {workflowId, payload}` with a realistic, obviously
+   fake payload (`test+<runId>@…`, "TEST SUBMISSION"). Real side effects run:
+   emails actually send — send to the user's own address, `[TEST]` subject,
+   tell them first. For non-email side effects (CRM writes, payments): STOP
+   and ask before testing.
+3. Fetch the returned executionId's detail and INSPECT node-by-node output —
+   a green final status is not inspection. Test at least: happy path, empty
+   payload, malformed payload. Confirm error branches actually routed.
+4. Report: what ran, with what data, what passed, what needs the human to
+   verify (e.g. "check your inbox").
+
+**Phase 6 — Wrap-up.** Give the user the workflow URL
+(`{instanceUrl}/workflow/{id}`), the webhook URL, and what to do next. If
+the test drafts aren't needed, `{action:'delete_draft'}` (deactivated only).
+
+## 3. The upgrade loop (changing a LIVE self-built workflow)
+
+Never edit a live workflow directly, and never "activate the copy" — the
+copy has different webhook URLs and every external caller would break.
+Instead:
+
+1. Fetch the live workflow's JSON, duplicate it into a new draft
+   (`create_draft` with the modified JSON — new name, e.g. same name; the
+   hub adds `[CLI]` + fresh test webhookIds automatically).
+2. Apply the requested changes to the draft; validate.
+3. Activate the DRAFT and test it on its own (test) URLs —
+   `awesomate_n8n_test` — full testing policy applies.
+4. Present the user a human-readable diff: nodes added/removed/changed,
+   credential changes, behaviour summary. **Wait for explicit approval.**
+5. `awesomate_n8n_deploy {action:'promote', workflowId:<LIVE id>,
+   draftId:<draft id>}` — the hub snapshots both workflows, swaps the
+   draft's body into the live id (preserving its webhookIds so external
+   URLs never change), restores activation, and archives the draft as
+   `[promoted <date>]`. Save the returned `operationId`.
+6. Verify: `awesomate_n8n_test` against the LIVE workflow — the ORIGINAL
+   URL must still respond. On any failure:
+   `{action:'rollback', operationId}` restores both workflows to their
+   pre-promote state, then investigate.
+7. Cleanup: once the user confirms, `delete_draft` the archived
+   `[promoted …]` draft (it's deactivated and still CLI-tagged), or leave
+   it as a manual fallback if they prefer.
+
+Promote only works between self-built (`awm:client-cli`) workflows. To
+upgrade a workflow the user built in the n8n UI, duplicate it into a CLI
+draft first and treat the new workflow as the live one going forward (its
+URL will differ — coordinate the cutover with the user).
+
+## 4. Diagnosing a failing workflow
+
+Executions list → execution detail → which node failed and why → walk the
+item data BACKWARDS (the cause is often an upstream mis-mapped field) →
+check against node-recipes.md → explain in the user's terms with the exact
+fix. Self-built workflows: fix via the upgrade loop above. Agency-managed workflows (`agency_managed` error): read
+and explain freely, but changes go through Awesomate support.
+
+## 5. Hard rules
+
+- **Never ask for their n8n API key.** Unreachable = consent/scope/plan —
+  route to settings or reconnect.
+- **Explicit approval gates:** before create_draft (design confirmation),
+  before activate, before promote, before rollback, before delete, before
+  any test with non-email side effects.
+- **Agency-deployed workflows are read-only** (the hub enforces it; don't
+  fight the 403).
+- **Respect quotas** (429 quota_exceeded = plan's daily cap — tell the user,
+  don't retry-loop).
+- **WordPress forms** (via the awesomate-hosting skill): have the form POST
+  server-side from WP to the webhook (a small forwarder snippet), not from
+  the browser — no CORS, hides the webhook URL, spam-filterable. Full
+  pattern + per-builder recipes:
+  [references/wp-form-handler.md](references/wp-form-handler.md).

package/skill/awesomate-n8n/references/node-recipes.md

@@ -0,0 +1,87 @@
+# Awesomate n8n platform notes — read before diagnosing or designing
+
+The fleet runs standard n8n 2.x. n8n 2.0 changed defaults that older tutorials
+(and model memory) get wrong — these notes are the live truth for THIS
+platform. When something here conflicts with what you remember about n8n,
+trust this file.
+
+## Environment rules (Awesomate-specific)
+
+1. **`$env` is blocked fleet-wide** (`N8N_BLOCK_ENV_ACCESS_IN_NODE`). `$env`
+   in a Code node OR a regular field expression throws "access to environment
+   variables is denied", and `$evaluateExpression()` is gone too. Use
+   `{{ $vars.key || 'fallback' }}` or a Set/Config node literal. The instance's
+   `$vars` keys are listed by `GET /api/my-n8n/machine/variables`.
+2. **Task runners are on by default** (2.0+): Code nodes have no `$helpers` —
+   no `$helpers.httpRequest`, no `getBinaryDataBuffer`. HTTP calls belong in
+   HTTP Request nodes; binary work belongs in dedicated nodes.
+3. **Media/community nodes are variant-gated.** `CUSTOM.localFiles`,
+   better-ffmpeg, and mediafx exist only on FFMPEG-variant instances
+   (Support Plus+ — `capabilities.variant` in the context tool). A workflow
+   referencing them on a Standard instance shows the node as "unknown".
+4. **Python Code nodes have no external libraries.** JavaScript covers 95% of
+   cases; recommend it by default.
+
+## The classics (most failures are one of these)
+
+5. **Webhook data lives at `$json.body`**, not `$json`. A webhook workflow
+   where every downstream field is empty almost always reads
+   `{{ $json.orderId }}` instead of `{{ $json.body.orderId }}`.
+6. **Code nodes must return `[{ json: {...} }]`** — an array of items each
+   wrapped in `json`. Returning a bare object/array is the #1 Code-node error.
+7. **Property dependencies**: some fields only apply with their siblings set —
+   e.g. HTTP Request `sendBody: true` requires a `contentType`. When a node
+   "ignores" a configured value, look for the missing sibling switch.
+8. **`resource` + `operation` travel together.** Partial edits that set one
+   without the other can leave the node silently misconfigured (n8n's
+   sanitizer may strip `operation`). When editing node JSON, always write both.
+
+## Triggers & webhooks
+
+9. **Production webhook** = `{instanceUrl}/webhook/{path}` and only responds
+   while the workflow is ACTIVE. **Test webhook** (`/webhook-test/`) only
+   works while someone is watching the editor — it is not a headless test path.
+10. **Form Trigger ignores custom paths on 2.x** — forms serve at
+    `/form/<webhookId>`, and the webhookId regenerates when a workflow is
+    duplicated or re-imported. External forms should post to a webhook
+    trigger with an explicit `path`, not a Form Trigger.
+11. **Activation is its own operation.** In workflow JSON the `active` field
+    is read-only; a workflow saved with `active: true` is NOT thereby active.
+12. **Multi-trigger workflows**: a manual execution starts from the webhook
+    trigger. To exercise a schedule branch, the webhook trigger has to be
+    temporarily disabled (and re-enabled after!).
+
+## Reading executions like an engineer
+
+13. Success status ≠ correct behaviour. Open the execution detail and check
+    which nodes ran, what each output, and whether `onError` branches routed.
+14. An error execution names the failing node and error — but the CAUSE is
+    often upstream (empty input from a mis-mapped field two nodes back).
+    Walk the item data backwards.
+15. Recommended workflow settings for anything that matters:
+    `{"executionOrder": "v1", "saveExecutionProgress": true,
+    "saveDataErrorExecution": "all", "saveDataSuccessExecution": "all"}` —
+    without the save flags there may be nothing to inspect after a failure.
+
+## Credentials
+
+16. The n8n API never returns credential secrets, and neither does the hub —
+    the inventory is names/types/inferred purpose only.
+17. OAuth credentials (Gmail, Google Sheets, Slack…) can only be completed in
+    the n8n browser UI — the consent screen needs a human. API-key
+    credentials (SMTP, Resend, SendGrid, HTTP header auth…) don't have that
+    constraint. This matters when advising which email/integration path is
+    fastest to set up.
+18. "Credential could not be found" on a node usually means a sharing issue
+    (the credential exists but isn't shared with the workflow owner), not a
+    deleted credential.
+
+## Design principles (for when you sketch workflows with the user)
+
+- Separate reasoning from execution: AI nodes decide and route; Code/HTTP/
+  integration nodes do the work. Five chained 90%-accurate AI steps ≈ 59%.
+- Descriptive node names ("Get Customer from CRM", never "HTTP Request 1").
+- Every external call needs an error plan: retry, fallback, or notify — and
+  notification chains must terminate, never loop back into the workflow.
+- One webhook path per purpose, versioned in the path if it will evolve
+  (`/webhook/signup-v1`).

package/skill/awesomate-n8n/references/wp-form-handler.md

@@ -0,0 +1,149 @@
+# WordPress form → n8n webhook: the forwarder pattern
+
+The reliable way to wire a WordPress form to an n8n workflow on this
+platform. The form NEVER posts to the n8n webhook from the browser — it
+posts to a small server-side forwarder on the WP site, which relays to the
+webhook.
+
+Why the forwarder (not a direct browser POST):
+- **No CORS** — same-origin from the browser; WP→n8n is server-to-server.
+- **The webhook URL stays hidden** from page source and bots.
+- **Spam filtering** (honeypot + nonce) happens before n8n ever sees a hit.
+- **One place to update** if the webhook path ever changes.
+
+Prerequisites: the n8n workflow exists and is ACTIVE (build it with the
+awesomate-n8n build loop first — webhook trigger with explicit path, e.g.
+`signup-v1`, `httpMethod: POST`, respond node returning `{"ok": true}`).
+WP access comes from the awesomate-hosting skill (SSH + wp-cli).
+
+## 1. The forwarder (mu-plugin — survives theme changes)
+
+Install via SSH as `wp-content/mu-plugins/awm-form-forwarder.php`. Snapshot
+the site first (`awesomate_snapshot_site`). Template — replace the webhook
+URL and the expected fields:
+
+```php
+<?php
+/**
+ * Plugin Name: Awesomate Form Forwarder
+ * Description: Relays site form submissions server-side to an n8n webhook.
+ */
+add_action('rest_api_init', function () {
+    register_rest_route('awm/v1', '/form/signup', [
+        'methods'  => 'POST',
+        'permission_callback' => '__return_true',
+        'callback' => function (WP_REST_Request $req) {
+            // Honeypot: bots fill every field; humans never see this one.
+            if (!empty($req->get_param('company_website'))) {
+                return new WP_REST_Response(['ok' => true], 200); // silent drop
+            }
+            // Nonce from the page keeps external scripts out.
+            if (!wp_verify_nonce($req->get_param('awm_nonce'), 'awm_form_signup')) {
+                return new WP_REST_Response(['error' => 'Session expired — reload the page'], 403);
+            }
+            $email = sanitize_email($req->get_param('email'));
+            $name  = sanitize_text_field($req->get_param('name'));
+            if (!is_email($email) || $name === '') {
+                return new WP_REST_Response(['error' => 'Please fill in all fields'], 422);
+            }
+            $resp = wp_remote_post('https://SLUG.awesomate.io/webhook/signup-v1', [
+                'timeout' => 15,
+                'headers' => ['Content-Type' => 'application/json'],
+                'body'    => wp_json_encode([
+                    'name' => $name, 'email' => $email,
+                    'page' => esc_url_raw($req->get_header('referer') ?: ''),
+                    'submitted_at' => gmdate('c'),
+                ]),
+            ]);
+            if (is_wp_error($resp) || wp_remote_retrieve_response_code($resp) >= 400) {
+                return new WP_REST_Response(['error' => 'Could not submit right now — please email us directly'], 502);
+            }
+            return new WP_REST_Response(['ok' => true], 200);
+        },
+    ]);
+});
+```
+
+Endpoint: `POST {site}/wp-json/awm/v1/form/signup`. One route per form —
+duplicate the `register_rest_route` block with a new path + webhook.
+
+The nonce must be printed into the page. Add alongside the form (per-builder
+below) or via `wp_footer`:
+
+```php
+add_action('wp_footer', function () {
+    echo '<script>window.AWM_FORM_NONCE = "' . wp_create_nonce('awm_form_signup') . '";</script>';
+});
+```
+
+## 2. The form, per builder
+
+Detect the builder first: `wp plugin list` / `wp theme list` (via the
+hosting skill). Style with the site's existing design tokens — inspect an
+existing page's buttons/inputs and match.
+
+**Bricks**: build a native Bricks form element (fields: name, email; plus a
+hidden `company_website` honeypot field). Bricks' built-in submit actions
+don't reliably POST custom JSON — attach a small custom JS snippet that
+intercepts submit and `fetch()`es the forwarder.
+
+**Elementor Pro**: Form widget → Actions After Submit → **Webhook** → the
+FORWARDER URL (not the n8n URL). Add a hidden honeypot field. Nonce: Elementor's
+webhook action can't send it — either relax the nonce check to same-origin
+referer validation for Elementor sites, or use the custom-JS submit instead.
+
+**Fallback (no pro form plugin)**: HTML block with a hand-built form +
+`fetch()`:
+
+```html
+<form id="awm-signup" novalidate>
+  <label>Name <input name="name" required></label>
+  <label>Email <input name="email" type="email" required></label>
+  <input name="company_website" tabindex="-1" autocomplete="off"
+         style="position:absolute;left:-9999px" aria-hidden="true">
+  <button type="submit">Sign up</button>
+  <p class="awm-msg" role="status"></p>
+</form>
+<script>
+document.getElementById('awm-signup').addEventListener('submit', async (e) => {
+  e.preventDefault();
+  const form = e.target, btn = form.querySelector('button'), msg = form.querySelector('.awm-msg');
+  btn.disabled = true; btn.textContent = 'Sending…';
+  const data = Object.fromEntries(new FormData(form));
+  data.awm_nonce = window.AWM_FORM_NONCE || '';
+  try {
+    const r = await fetch('/wp-json/awm/v1/form/signup', {
+      method: 'POST', headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify(data),
+    });
+    const body = await r.json();
+    if (r.ok) { form.style.display = 'none'; msg.textContent = 'Thanks — you\'re signed up!'; }
+    else { msg.textContent = body.error || 'Something went wrong — try again.'; btn.disabled = false; btn.textContent = 'Sign up'; }
+  } catch { msg.textContent = 'Network error — please try again.'; btn.disabled = false; btn.textContent = 'Sign up'; }
+});
+</script>
+```
+
+UX bar for every variant: disabled button + label change while submitting,
+inline thank-you state (swap the form out), and an error state that gives a
+fallback contact method.
+
+## 3. End-to-end verification (both hops, in order)
+
+1. n8n hop alone: `awesomate_n8n_test` against the workflow — execution
+   success, node-by-node inspected.
+2. WP hop: `curl -s -X POST {site}/wp-json/awm/v1/form/signup -H 'Content-Type: application/json' -d '{"name":"TEST SUBMISSION","email":"test+e2e@example.com","awm_nonce":"..."}'`
+   (mint a nonce via wp-cli: `wp eval 'echo wp_create_nonce("awm_form_signup");'`).
+3. Confirm a NEW execution appeared for the workflow and the email arrived
+   (`[TEST]` subject, user's own inbox).
+4. Honeypot check: same curl + `"company_website":"http://spam.example"` →
+   200 ok but NO new execution.
+5. Hand the user: page URL, forwarder endpoint, workflow URL, and where the
+   submissions go.
+
+## 4. When the workflow is upgraded later
+
+The forwarder points at the webhook PATH, and promote preserves it — a
+promoted upgrade needs NO WordPress change. Only if a workflow is rebuilt
+under a new path does the forwarder's `wp_remote_post` URL need updating
+(one line, then re-run step 2-3 above).