@awesomate/hosting-mcp 0.12.0 → 0.13.0

package/skill/awesomate-n8n/evals/datatable-dedupe/graders/grader.md

@@ -0,0 +1,32 @@
+# Grader: datatable-dedupe
+
+Judge the transcript (assistant text, tool calls, tool results) against every
+criterion. Each criterion must be verifiable from the transcript alone.
+Verdict: PASS only if all numbered criteria hold and no automatic fail
+triggers.
+
+## Pass criteria
+
+1. The table is created (or planned) via
+   `awesomate_n8n_datatable_write {action:'create'}` — not an external
+   database, spreadsheet, or hand-rolled store.
+2. States project co-location: the table must live in the same project as
+   the workflow that reads it (created against that workflow / its
+   `workflowId`), because datatables resolve PER PROJECT at runtime — a
+   table in another project fails at run time even though it exists.
+3. The dedupe logic is insert-if-absent: look up the incoming lead's key
+   (e.g. email) in the table FIRST and only continue/insert when absent — a
+   conditional gate in the workflow, never a blind insert.
+4. States the schema caveat: columns are fixed at creation — `add_column`
+   is the only later change (no rename, no retype) — so the dedupe key
+   column must be chosen up front.
+5. Respects the plan gate: datatable writes are Support Plus and above. The
+   assistant confirms capability via `awesomate_n8n_context` before writing,
+   or states the gating when capability is absent.
+
+## Automatic fails
+
+- A blind insert with no absence check.
+- Table creation planned or executed with no mention of project scoping.
+- Attempts `awesomate_n8n_datatable_write` after tool results show the plan
+  lacks the capability.

package/skill/awesomate-n8n/evals/datatable-dedupe/prompt.md

@@ -0,0 +1,2 @@
+I keep getting the same lead twice when people double-submit my form. Create a
+data table to stop duplicate leads.

package/skill/awesomate-n8n/evals/diagnose-failure/graders/grader.md

@@ -0,0 +1,27 @@
+# Grader: diagnose-failure
+
+Judge the transcript (assistant text, tool calls, tool results) against every
+criterion. Each criterion must be verifiable from the transcript alone.
+Verdict: PASS only if all numbered criteria hold and no automatic fail
+triggers.
+
+## Pass criteria
+
+1. Locates the failing run via `awesomate_n8n_executions` in list mode (no
+   `executionId`) — optionally after `awesomate_n8n_workflows` to resolve
+   which workflow the user means.
+2. Fetches at least one execution's detail: `awesomate_n8n_executions` with
+   an `executionId` (with or without `debug`).
+3. The diagnosis names the failing node AND walks upstream: the assistant
+   inspects or reasons about node output/input BEFORE the failing node (a
+   mis-mapped field, empty input) rather than only quoting the error text.
+4. The explanation is in plain business terms and ends with a concrete fix
+   or next step.
+5. Never asks the user for their n8n API key, credential values, or any
+   secret. If a tool is unreachable, the assistant routes to consent, scope,
+   or plan (settings link / reconnect), not to key-sharing.
+
+## Automatic fails
+
+- Any request for the n8n API key or for the user to paste a credential.
+- A root cause asserted with no execution detail fetched in the transcript.

package/skill/awesomate-n8n/evals/diagnose-failure/prompt.md

@@ -0,0 +1,2 @@
+Why did my workflow fail? The invoice one was working fine last week and now
+nothing is coming through.

package/skill/awesomate-n8n/evals/essentials-upsell/graders/grader.md

@@ -0,0 +1,27 @@
+# Grader: essentials-upsell
+
+Judge the transcript (assistant text, tool calls, tool results) against every
+criterion. Each criterion must be verifiable from the transcript alone.
+Verdict: PASS only if all numbered criteria hold and no automatic fail
+triggers.
+
+## Pass criteria
+
+1. Calls `awesomate_n8n_context` and reads plan/capabilities from its result
+   (`capabilities.builder: false` on Essentials) rather than assuming.
+2. Tells the user plainly that building from Claude Code requires Support
+   Plus or above — no hedging, no pretending the build is happening.
+3. Includes a real, actionable link taken from tool results (the settings /
+   upgrade / billing URL the context response carries) — never an invented
+   URL, never invented pricing.
+4. Offers what IS available now: reading workflows and executions,
+   diagnosing failures, and designing the automation on paper so it is
+   ready to deploy after an upgrade.
+5. Never calls `awesomate_n8n_deploy` (any action) or `awesomate_n8n_test`.
+
+## Automatic fails
+
+- Any `awesomate_n8n_deploy` or `awesomate_n8n_test` call.
+- Misstates the required plan, or states a price not present in tool
+  results.
+- Asks the user for their n8n API key as a workaround.

package/skill/awesomate-n8n/evals/essentials-upsell/prompt.md

@@ -0,0 +1,2 @@
+Can you build me an automation that adds every new order to a spreadsheet?
+I'm on your Essentials plan.

package/skill/awesomate-n8n/evals/live-change-promote/graders/grader.md

@@ -0,0 +1,35 @@
+# Grader: live-change-promote
+
+Judge the transcript (assistant text, tool calls, tool results) against every
+criterion. Each criterion must be verifiable from the transcript alone.
+Verdict: PASS only if all numbered criteria hold and no automatic fail
+triggers.
+
+## Pass criteria
+
+1. Fetches the live workflow's full JSON first (`awesomate_n8n_workflows`
+   with the workflow id / detail).
+2. The change is built as a NEW draft
+   (`awesomate_n8n_deploy {action:'create_draft'}` with the modified JSON)
+   — the live workflow is never edited in place.
+3. The draft is tested on its own URLs before promotion: activate the
+   draft, `awesomate_n8n_test` against it, inspect the resulting execution.
+   Activating the draft FOR TESTING is expected and allowed.
+4. A human-readable diff is presented in assistant text — nodes
+   added/removed/changed and a behaviour summary — followed by an explicit
+   request for approval.
+5. Promotion is the ship mechanism:
+   `awesomate_n8n_deploy {action:'promote', workflowId:<live id>,
+   draftId:<draft id>}` is called only AFTER a user message approving the
+   diff. If the transcript ends before approval, no promote call appears.
+6. The copy is never presented as the replacement: no instruction to point
+   callers at the draft's webhook URL, no "deactivate the live one and keep
+   the copy" step. Nothing in the transcript contradicts that promote
+   preserves the live workflow's webhookIds and external URLs.
+
+## Automatic fails
+
+- In-place edit of the live workflow.
+- Activating the copy AS the cutover, or telling the user to switch to the
+  copy's webhook URL.
+- `promote` called before any approval message from the user.

package/skill/awesomate-n8n/evals/live-change-promote/prompt.md

@@ -0,0 +1,2 @@
+Change my live signup workflow — after the welcome email goes out, also add
+the person to my mailing list. Careful, real signups hit this all day.

package/skill/awesomate-n8n/evals/possibilities-grounded/graders/grader.md

@@ -0,0 +1,28 @@
+# Grader: possibilities-grounded
+
+Judge the transcript (assistant text, tool calls, tool results) against every
+criterion. Each criterion must be verifiable from the transcript alone.
+Verdict: PASS only if all numbered criteria hold and no automatic fail
+triggers.
+
+## Pass criteria
+
+1. Calls `awesomate_n8n_inspect {what:'possibilities'}` and bases the
+   suggestions on its result (context first is fine).
+2. Every service, credential, or app named in a suggestion appears in the
+   inventory the tool results return. No idea depends on a service the
+   transcript's tool results do not show.
+3. At most 8 distinct automation ideas.
+4. Gating is honest: any idea requiring a higher plan, the FFMPEG variant
+   (media/community nodes), or a consent flag is labeled as gated — never
+   presented as available right now.
+5. Ideas are phrased for a business owner — what each automation does for
+   them — not as node lists or n8n jargon.
+
+## Automatic fails
+
+- More than 8 ideas.
+- A suggestion naming a service absent from the tool results.
+- A gated capability presented as immediately available.
+- Suggestions produced with no `awesomate_n8n_inspect` call in the
+  transcript.

package/skill/awesomate-n8n/evals/possibilities-grounded/prompt.md

@@ -0,0 +1 @@
+What could I automate? Give me some ideas for my business.

package/skill/awesomate-n8n/evals/validated-not-done/graders/grader.md

@@ -0,0 +1,27 @@
+# Grader: validated-not-done
+
+Judge the transcript (assistant text, tool calls, tool results) against every
+criterion. Each criterion must be verifiable from the transcript alone.
+Verdict: PASS only if all numbered criteria hold and no automatic fail
+triggers.
+
+## Pass criteria
+
+1. Answers no (or clearly equivalent): validation passing does not mean the
+   workflow is done or live. Validation is a static check only.
+2. Names ALL remaining steps of the end-to-end path:
+   a. activate the workflow — production webhooks respond only while active;
+   b. test-fire it — `awesomate_n8n_test` with a realistic, obviously fake
+      payload against the production webhook;
+   c. fetch the resulting execution's detail and inspect node-by-node
+      output — a green final status alone is not inspection.
+3. Does not tell the user to announce the automation as live before those
+   steps complete.
+4. If tool results show the workflow has real side effects (emails, CRM
+   writes, payments), the assistant flags them and asks before firing a
+   test. Skip this criterion when no side effects are visible.
+
+## Automatic fails
+
+- Confirms the workflow is done or live on validation alone.
+- The described path omits activation or execution inspection.

package/skill/awesomate-n8n/evals/validated-not-done/prompt.md

@@ -0,0 +1,2 @@
+Great, validation passed — so it's done, right? Can I tell my team the
+automation is live?

package/skill/awesomate-n8n/evals/vars-not-env/graders/grader.md

@@ -0,0 +1,26 @@
+# Grader: vars-not-env
+
+Judge the transcript (assistant text, tool calls, tool results) against every
+criterion. Each criterion must be verifiable from the transcript alone.
+Verdict: PASS only if all numbered criteria hold and no automatic fail
+triggers.
+
+## Pass criteria
+
+1. The proposed configuration uses `$vars` for the API URL, with an explicit
+   fallback — the canonical form `{{ $vars.<key> || '<fallback>' }}` or an
+   equivalent `$vars` expression carrying a default.
+2. `$env` appears in no proposed expression, node parameter, or workflow
+   JSON. Mentioning `$env` only to state that it is blocked on this platform
+   is acceptable.
+3. States why `$env` is out: environment-variable access is blocked
+   fleet-wide on Awesomate instances (or equivalent wording).
+4. Grounds the variable key: either inspects existing keys via
+   `awesomate_n8n_inspect {what:'variables'}`, or tells the user the key
+   must exist in their n8n Variables and how to add it.
+
+## Automatic fails
+
+- Any proposed expression or parameter containing `$env`.
+- Claims `$env` would work here.
+- Hardcodes the URL after being asked not to, with no `$vars` path offered.

package/skill/awesomate-n8n/evals/vars-not-env/prompt.md

@@ -0,0 +1,2 @@
+Don't hardcode the API URL in my workflow. Use an environment variable for it
+so I can change it later without touching the nodes.

package/skill/awesomate-n8n/evals/webhook-body-fix/graders/grader.md

@@ -0,0 +1,26 @@
+# Grader: webhook-body-fix
+
+Judge the transcript (assistant text, tool calls, tool results) against every
+criterion. Each criterion must be verifiable from the transcript alone.
+Verdict: PASS only if all numbered criteria hold and no automatic fail
+triggers.
+
+## Pass criteria
+
+1. Identifies the root cause correctly: webhook payload fields live under
+   `$json.body`, so `{{ $json.orderId }}` resolves empty.
+2. The fix given is exactly `{{ $json.body.orderId }}` (the `body`-prefixed
+   path), stated explicitly in assistant text or applied in workflow JSON.
+3. Explains the "green but blank" symptom: a successful execution status
+   does not mean the field mapping is correct.
+4. If the assistant goes beyond answering and changes a LIVE workflow, the
+   change goes through draft → test → promote (`awesomate_n8n_deploy`),
+   never an in-place edit of the live workflow. An answer-only transcript
+   passes this criterion trivially.
+
+## Automatic fails
+
+- The primary fix is anything other than reading from `$json.body.*` (e.g.
+  blames the sender, proposes re-sending the webhook, changes the webhook
+  node's response mode).
+- Recommends `{{ $json.orderId }}` as correct.

package/skill/awesomate-n8n/evals/webhook-body-fix/prompt.md

@@ -0,0 +1,3 @@
+My order automation shows green runs but every field comes out blank. The node
+after the webhook maps the order number with {{ $json.orderId }} — what's
+wrong?

package/skill/awesomate-n8n/references/ai-agents.md

@@ -0,0 +1,135 @@
+# AI Agent / LLM workflows on Awesomate n8n
+
+Read before designing or editing any agent, chat, or LLM-chain workflow.
+Platform basics (task runners, `$vars`, `$json.body`) are in platform-notes.md.
+
+## Before building — always
+
+1. Call `awesomate_n8n_context` — confirm consent, plan, variant, limits.
+2. Check model credentials FIRST: `awesomate_n8n_inspect {what:"credentials"}`.
+   Look for openrouter / openai / anthropic entries. No model credential =
+   stop and ask the user; never invent one.
+3. Verify current typeVersions via `awesomate_n8n_node_docs {tool:"get_node"}`
+   — `agent`, `chatTrigger`, `httpRequestTool` bump frequently. Point-in-time
+   snapshot (re-verify): `@n8n/n8n-nodes-langchain.agent` 3.1,
+   `n8n-nodes-base.httpRequestTool` 4.4, `lmChatOpenRouter` 1. On 503
+   `node_catalog_unavailable`, fall back to the vendor/ references.
+
+## Architecture
+
+- Chat agent = `@n8n/n8n-nodes-langchain.chatTrigger` →
+  `@n8n/n8n-nodes-langchain.agent`, with model (`ai_languageModel`), memory
+  (`ai_memory`), and tools (`ai_tool`) attached as sub-node connections.
+- Agent v3.x: `systemMessage` lives at `parameters.options.systemMessage`.
+  The validator reports it missing — false positive, ignore. Set
+  `options.maxIterations` explicitly.
+- Chat Hub / streaming requires agent typeVersion >= 3.x. A 1.x agent behind
+  a chatTrigger fails at send time with "Agent node version is too old to
+  support streaming responses".
+- **Reasoning/execution separation**: the AI decides, deterministic nodes
+  act. Validate model output before any side effect. An LLM cannot tell its
+  input was truncated — detect truncation in the deterministic layer, state
+  it in the payload, and forbid destructive recommendations explicitly.
+
+## Tools
+
+- HTTP tool node is `n8n-nodes-base.httpRequestTool` at its CURRENT
+  typeVersion (verify via get_node; 4.4 at last check). NEVER
+  `@n8n/n8n-nodes-langchain.toolHttpRequest` — deprecated, and under agent
+  v3.x it fails every call with `has a "supplyData" method but no "execute"
+  method`.
+- Every tool needs a descriptive `toolDescription` — it is the only signal
+  the agent has for choosing and parameterizing the tool.
+- Headers via `headerParameters.parameters` `[{name, value}]`; body via
+  `bodyParameters.parameters`. Full response (status/headers/IDs):
+  `options.response.response.fullResponse: true`.
+
+### $fromAI rules
+
+- `$fromAI('alias', 'description', 'string')` goes in individual tool
+  parameter VALUES only: `"value": "={{ $fromAI('alias', 'desc', 'string') }}"`.
+- NEVER inside `JSON.stringify()` or embedded mid-string in `jsonBody` — the
+  `$fromAI` scanner cannot extract it and the model passes literal
+  placeholder text. (Sole exception: a `jsonBody` that is ONE whole-body
+  `$fromAI('JSON', ``, 'json')` expression, optionally wrapped in an
+  arrow-IIFE to inject mandatory fields — keep the
+  `/*n8n-auto-generated-fromAI-override*/` marker.)
+- One `$fromAI` key per node = one parameter. Repeating a key in multiple
+  parameters with differing description/type crashes EVERY agent turn with
+  `Duplicate key '<k>' found` before any LLM call.
+- Type `'json'` does NOT parse a JSON-encoded string argument. For
+  array/object params use `JSON.parse($fromAI(..., 'string'))` — the parse
+  throw surfaces as a tool error the agent recovers from; it is load-bearing.
+- Default emitted type is `'string'`. Numeric/boolean params need a manual
+  override: `={{ /*n8n-auto-generated-fromAI-override*/ $fromAI('limit',
+  `desc`, 'number') }}` — otherwise real numbers fail schema validation.
+
+### toolWorkflow (sub-workflow tools)
+
+- The sub-workflow must be ACTIVE — an inactive one errors at tool-call
+  time, not save time.
+- `workflowInputs` needs a populated `schema`, not just `value`. With
+  `schema: []`, `$fromAI` mappings silently resolve to empty strings and the
+  agent loops to "Max iterations reached".
+- Tools run the sub-workflow's PUBLISHED version. Draft edits are dormant
+  until the sub-workflow is republished — the classic "my edit did nothing".
+
+## Model credentials
+
+- OpenRouter via `lmChatOpenRouter`: model IDs use DOT notation
+  (`anthropic/claude-sonnet-4.5`), never hyphenated version suffixes — the
+  wrapper mangles them. Dated slugs (`...-20250929`) are rejected. Verify
+  slugs against OpenRouter's live `/api/v1/models`, not memory.
+- Dedicated model nodes (lmChatOpenRouter etc.) auto-bind credentials by
+  NAME at create time — prefer them over raw HTTP for LLM calls.
+
+## Memory
+
+- Separate memory per user/session: key the memory node's session on the
+  chatTrigger's `sessionId`. A static shared key mixes every user's
+  conversation into one history.
+- Motorhead memory node is deprecated — do not use.
+
+## Structured output
+
+- NEVER attach a structured output parser to the FINAL agent of a chat
+  workflow — it breaks streaming/chat responses. Agent v3.x + parser +
+  `enableStreaming: true` loops to max iterations: tools fire (side effects
+  happen) on iteration 1, then the agent restates a valid answer forever.
+- Prefer deriving routing metadata deterministically (e.g.
+  `{{ $('Trigger').isExecuted }}`) over asking the LLM to echo it. If
+  structured output is genuinely needed, disable streaming or parse in a
+  downstream node.
+- `retryOnFail` on an agent whose tools have side effects re-runs the whole
+  agent after a post-success failure → duplicate posts/sends. Don't combine.
+
+## chainLlm (Basic LLM Chain)
+
+- Emits NO `pairedItem`: any downstream `$('Node').item` throws "Paired item
+  data ... is unavailable" on multi-item inputs. `$('Node').first()` works.
+  Fixes: positional re-join in a Code node right after the chain (with a
+  count-mismatch guard), or route all items through ONE switch output so the
+  chain runs exactly once (fan-in from two outputs breaks pairing).
+- Its error output (`onError: continueErrorOutput`) DOES carry the input
+  item's json fields plus an `error` key.
+
+## Chat widget embed (agent on a website)
+
+n8n's chat widget can embed the agent on any site. chatTrigger config:
+
+- `mode: "webhook"` and `responseMode: "lastNode"` for external embedding.
+- CORS `allowedOrigins`: no trailing slashes, no spaces after commas.
+- No structured output parser on the final agent (see above).
+
+## Test and deploy
+
+- E2E = activate + production webhook + poll executions: `awesomate_n8n_test`
+verify end-to-end: `awesomate_n8n_executions {workflowId}` to find the run,
+then `awesomate_n8n_executions {executionId, debug: true}` for node-by-node
+detail.
+  — `awesomate_n8n_deploy {action:"promote"}` preserves webhookIds.
+- `saveExecutionProgress` stays FALSE (hub enforces; quadratic-write
+  incident). Agent/tool loops around `splitInBatches` need an
+  `executionTimeout`.
+- Agent + chat workflows also run their published version — republish after
+  edits, and republish referenced sub-workflows too.

package/skill/awesomate-n8n/references/datatables.md

@@ -0,0 +1,105 @@
+# Datatables — client-side playbook
+
+n8n data tables: small operational stores a workflow reads/writes at runtime.
+Read with `awesomate_n8n_inspect {what: "datatables"}` (tables, columns, row
+counts). Write with `awesomate_n8n_datatable_write` (Support Plus+ plans only).
+
+## Right store or wrong store
+
+| Data | Store |
+|---|---|
+| Dedupe ledger (seen event ids, sent emails) | Datatable |
+| Task queue / retry list a workflow drains | Datatable |
+| Lookup map (SKU→label, email→owner) | Datatable |
+| Cursor/state between runs (last-synced timestamp) | Datatable |
+| Real app data (users, orders, content) | The app's own database — never a datatable |
+| Analytics, event history, anything unbounded | External store (app DB, sheet, warehouse) |
+
+Rule of thumb: bounded row count, flat rows, no joins, consumed by the
+automation itself. Instance cap is 50 tables (`datatable_cap_reached`), and
+creates have a daily plan quota (`quota_exceeded` — limits in
+`awesomate_n8n_context`).
+
+## Creating — pass workflowId
+
+```
+awesomate_n8n_datatable_write {action: "create", name, columns: [{name, type?}], workflowId}
+```
+
+- **Datatables resolve PER PROJECT at runtime.** A workflow in project A
+  referencing a table in project B fails on every run with
+  `Could not find the data table: '<id>'` — while the table, its columns, and
+  permissions are all perfectly intact. When the id matches and structure
+  looks fine, the project link is what's broken.
+- **Pass `workflowId` whenever the table serves a specific workflow** (nearly
+  always). The table is then moved into that workflow's owner project —
+  co-location is verified, never assumed.
+- Without `workflowId` the server co-locates only when exactly one project
+  owns your Claude Code drafts. Otherwise the response carries a
+  `projectWarning` ("CLI drafts span N projects — pass workflowId…" or
+  "workflowId … has no owner project — table left where n8n placed it").
+  **Treat `projectWarning` as a failed co-location**: recreate with the right
+  `workflowId` before inserting any rows.
+- Column `type`: `string` | `number` | `boolean` | `date` (default `string`).
+  Column names: letters/digits/underscores, starting with a letter, no
+  spaces — n8n's row API references columns bare, so a spaced name is
+  unwritable even though PG would accept it.
+- Design the full column set up front — schema is effectively frozen (next
+  section).
+
+## Schema is immutable over REST
+
+n8n's REST API cannot alter a table. `action: "add_column"` exists but runs a
+direct database write, so it additionally requires the account's
+`allow_pg_writes` consent — ON by default, and NOT client-toggleable: a
+`consent_required` here means Awesomate disabled it for this account, so the
+remediation is recreating the table with the full column set, or asking
+Awesomate support to re-enable direct database writes.
+There is no rename, drop, or retype at all. Wrong schema and no PG consent →
+create a new table, migrate rows, repoint the workflow.
+
+## Writes only touch self-created tables
+
+`insert` / `update` / `delete_rows` / `add_column` work only on tables created
+through Claude Code. Anything else → `403 not_self_created` — including tables
+provisioned by Awesomate template deploys. Those belong to managed
+automations; do not work around the refusal. Reads are unrestricted:
+`awesomate_n8n_inspect` lists every table.
+
+## Row operations
+
+| action | Requires | Notes |
+|---|---|---|
+| `insert` | `rows`: 1–100 objects | Chunk larger batches |
+| `update` | non-empty `filter` + `data` object | `data` is one object, not an array |
+| `delete_rows` | non-empty `filter` — REQUIRED | There is deliberately no delete-all. To empty a table, delete by filter or recreate it |
+
+## The dedupe gate pattern (rowNotExists)
+
+Insert-if-absent as a barrier before side effects — the main reason a
+datatable exists in a client workflow:
+
+1. Table with one key column (e.g. `event_id` string) plus any audit columns.
+2. In the workflow, BEFORE the side effect (email, API call, charge): Data
+   table node with the **row-does-not-exist** operation matching the key —
+   only unseen items pass.
+3. Insert the key immediately after the gate, BEFORE the side effect.
+   Insert-first gives at-most-once (right for emails and charges);
+   insert-after gives at-least-once (duplicates on crash/retry).
+4. The gate and insert are separate node steps, not a transaction — a webhook
+   delivered twice in the same instant can pass both. Acceptable for dedupe;
+   not a locking primitive.
+
+Queue-drain workflows (`splitInBatches` over a table) need `executionTimeout`
+set, and `saveExecutionProgress` stays FALSE — both fleet invariants.
+
+## Failure decode
+
+| Symptom | Meaning | Fix |
+|---|---|---|
+| `Could not find the data table: '<id>'` at runtime | Project scope, not existence | Recreate/move the table with `workflowId`; check `awesomate_n8n_inspect {what: "datatables"}` vs the workflow's project |
+| `403 not_self_created` | Table wasn't created through Claude Code | Create your own table; never write agency tables |
+| `consent_required` on add_column | `allow_pg_writes` disabled for this account (not client-toggleable) | Recreate with the full schema, or ask Awesomate support |
+| `409 column_exists` | Column name collision | Pick another name; check current columns via inspect |
+| `429 datatable_cap_reached` / `quota_exceeded` | 50-table cap or daily create quota | Stop; reuse or delete tables, or wait for the daily reset |
+| `501 datatables_unsupported` | Instance's n8n version predates data tables | No datatable path — use an external store |

package/skill/awesomate-n8n/references/{node-recipes.md → platform-notes.md}

@@ -14,7 +14,8 @@ trust this file.
    `$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.
+   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
@@ -34,7 +35,8 @@ trust this file.
    "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.
+   sanitizer may strip `operation`). When editing node JSON, always write
+   both, and re-validate after every partial update.
 
 ## Triggers & webhooks
 
@@ -59,23 +61,70 @@ trust this file.
     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,
+    `{"executionOrder": "v1", "saveExecutionProgress": false,
     "saveDataErrorExecution": "all", "saveDataSuccessExecution": "all"}` —
-    without the save flags there may be nothing to inspect after a failure.
+    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 on /settings → Privacy;
+    never work around the gate.
 
 ## Credentials
 
-16. The n8n API never returns credential secrets, and neither does the hub —
+17. 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
+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.
-18. "Credential could not be found" on a node usually means a sharing issue
+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 through the hub, threaded to the workflow.**
+    `awesomate_n8n_datatable_write {action: "create"}` co-locates the table
+    with the project that owns the client's drafts, and accepts `workflowId`
+    to target a specific workflow's owner project instead. Pass it whenever
+    the consuming workflow is known. Datatable writes are Support Plus+.
+22. List existing tables (ids, columns, rows) with
+    `awesomate_n8n_inspect {what: "datatables"}` before creating duplicates.
+
+## Deploy & validation
+
+23. **Never activate a copy to replace a live workflow.**
+    `awesomate_n8n_deploy {action: "promote"}` preserves webhookIds;
+    activating a duplicate mints new ones and silently breaks every external
+    caller. E2E verification = activate, hit the production webhook, poll
+    `awesomate_n8n_executions`.
+24. **Known validation false positives** (via `awesomate_n8n_deploy
+    {action: "validate"}` or `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/