@awesomate/hosting-mcp/skill/awesomate-n8n/references/platform-notes.md

Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases

# 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. In-memory
   binary mode is gone too.
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, and re-validate after every partial update.

## 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": false,
    "saveDataErrorExecution": "all", "saveDataSuccessExecution": "all"}` —
    without the save-data flags there may be nothing to inspect after a
    failure. Keep `saveExecutionProgress` OFF: it checkpoints the whole
    workflow state to the database after every node — on loops that write-
    amplifies brutally (a single runaway workflow once wrote ~2TB). The hub
    enforces `false` on drafts it creates. Any `splitInBatches` loop should
    also set `executionTimeout` so a wedged run can't grind forever.
16. **Node-level inspection**: `awesomate_n8n_executions {executionId,
    debug: true}` decodes an execution into per-node input/output and the
    real error. Use it instead of guessing from the summary. It is gated on
    the client's `error_content_analysis` privacy toggle (default OFF) — on
    a consent refusal, ask the user to enable it under **n8n → Settings →
    Privacy** at `hub.awesomate.ai/settings?tab=privacy` (Privacy moved off the plain
    `/settings` page; old `?tab=privacy` links redirect there);
    never work around the gate.

## Credentials

17. The n8n API never returns credential secrets, and neither does the hub —
    the inventory is names/types/inferred purpose only.
18. 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.
19. "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.

## Datatables (PROJECT-scoped — critical)

20. **Datatables resolve per project at runtime.** A workflow in project A
    referencing a table in project B fails every run with
    `Could not find the data table: '<id>'` while the table, its columns,
    and its permissions are all perfectly intact. Every structural check
    passes; only the project link is wrong. **When the ID matches and
    permissions are fine, check scope, not existence.**
21. **Create tables inside the workflow's project.** Tables are made in
    n8n itself (Data tables in the left menu, while in the project that owns
    the workflow), or through the n8n MCP server when it offers a data-table
    tool. No Awesomate tool creates one. Read the result back with
    `awesomate_n8n_inspect {what: "datatables"}` and reference it by name.
22. List existing tables (ids, columns, rows) with
    `awesomate_n8n_inspect {what: "datatables"}` before creating duplicates.

## Publishing & validation

23. **Never activate a copy to replace a live workflow.** Change the live
    one on its own id through the n8n MCP server and republish it (SKILL.md
    §4); activating a duplicate mints new webhookIds and silently breaks
    every external caller. E2E verification = publish, hit the production
    webhook, poll `awesomate_n8n_executions`.
24. **Known validation false positives** (via `awesomate_n8n_node_docs
    validate_node`):
    community/CUSTOM nodes report "unknown" (expected — see variant gating,
    rule 3); graph cycles flag `valid: false`, but cycle-based polling loops
    are legitimate. Filter known false positives — don't "fix" a working
    workflow to satisfy the validator.

## Embedded chat

25. Embedded chat trigger config: `mode: "webhook"` +
    `responseMode: "lastNode"`. Allowed-origins (CORS) list: no trailing
    slashes, no spaces after commas — either one breaks the widget silently.

## 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`).