@n8n/instance-ai 1.22.0 → 1.23.0

package/skills/post-build-flow/SKILL.md

@@ -225,9 +225,10 @@ to force data through the trigger.
 **Reserve `executions(action="run")` for runs the user explicitly asked for**
 (e.g. "run it now", "execute it against my real data"). Never call it on your own
 to re-test, expand coverage, or "prove the full chain" of a workflow you just
-built or verified: re-run `verify-built-workflow` (with `fixtureOverrides` to
-reach an unverified branch) instead, or report the partial coverage and let the
-user decide whether to run it.
+built or verified: re-run `verify-built-workflow` instead — with
+`triggerNodeName` to reach another trigger's branch, or `fixtureOverrides` to
+reach another branch within one trigger's run — or report the partial coverage
+and let the user decide whether to run it.
 If `fixtureOverrides` is rejected with `invalid_fixture_override`, the target
 node was not classified as simulated in the build outcome. Do not retry the same
 override. If that node's data controls a branch that needs verification and you
@@ -235,18 +236,30 @@ have the source file, load `workflow-builder`, declare representative `output`
 fixtures on the controlling upstream node, rebuild the same workflow, and verify
 again.
 
-**Never edit a saved workflow to reach a branch.** Disabling or deleting nodes to
-steer a test mutates the user's workflow and leaves it broken for as long as the
-test runs — if it is published, its triggers fire against the broken version.
-For a workflow with more than one trigger (`triggerNodes` has multiple entries):
-
+**Never edit or copy a saved workflow to reach a branch.** Disabling, deleting,
+or reordering nodes to steer a test mutates the user's workflow and leaves it
+broken for as long as the test runs — if it is published, its triggers fire
+against the broken version. Building a throwaway second workflow is no better:
+the evidence is gathered against a copy that can drift from the workflow the
+user keeps, and the copy is left behind whenever the cleanup delete fails.
+
+For a workflow with more than one trigger (`triggerNodes` has multiple entries),
+**verify once per trigger**:
+
+- Pass `triggerNodeName` to `verify-built-workflow` and call it once for each
+  entry in `triggerNodes`. Naming no trigger verifies only the auto-detected
+  one. An unresolvable name is rejected outright, so a rejected call means the
+  name is wrong — re-read `triggerNodes`, never fall back to editing.
+- Each pass covers its own trigger's branch, so its `nodesNotReached` will list
+  the other triggers' nodes. That is expected, not a defect: coverage is the
+  **union** across passes. Only treat a node as unverified once no pass reached
+  it.
+- Report per-trigger coverage — name each trigger and whether its branch ran.
+  Claim the workflow is verified only when every trigger's branch has a
+  successful pass.
 - When the user asked for a live run, pass `triggerNodeName` to
-  `executions(action="run")` — one run per trigger — and report each branch's
-  result. Naming no trigger runs only the auto-detected one.
-- `verify-built-workflow` always exercises the auto-detected trigger, so it
-  covers one branch. Say which trigger was verified and which branches were not,
-  and offer the user a live run for the rest. Do not force coverage by editing
-  the workflow.
+  `executions(action="run")` the same way — one run per trigger — and report
+  each branch's result.
 
 ## After build-workflow succeeds
 
@@ -268,7 +281,8 @@ For a workflow with more than one trigger (`triggerNodes` has multiple entries):
 
 - If `verificationReadiness.status === "ready"`, call
   `verify-built-workflow` with the `workflowId`, the `workItemId` when you
-  have it, and the trigger-appropriate `inputData` shape.
+  have it, and the trigger-appropriate `inputData` shape. When `triggerNodes`
+  has more than one entry, call it once per trigger with `triggerNodeName`.
 - If `verificationReadiness.status === "needs_setup"`, call
   `workflows(action="setup")` with the workflowId so the user can configure it
   through the inline setup card in the AI Assistant panel.
@@ -291,7 +305,9 @@ For a workflow with more than one trigger (`triggerNodes` has multiple entries):
      were verified and which were not, and tell the user the unreached part
      needs a manual test. Do not start a live `executions(action="run")`
      yourself to reach those nodes; offer the user a test instead. Never claim
-     end-to-end verification when `nodesNotReached` is non-empty.
+     end-to-end verification when `nodesNotReached` is non-empty — except for
+     nodes another trigger's pass already reached, since per-trigger coverage
+     is the union across passes.
    - If the unreached nodes sit behind IF/Switch logic controlled by a live or
      nondeterministic upstream node, and alternate-branch verification is part
      of this turn's goal, first try one source-file repair: add representative
@@ -319,6 +335,8 @@ For a workflow with more than one trigger (`triggerNodes` has multiple entries):
    when the latest verification evidence used mocks or simulations. If this
    follow-up is due, ask only whether the user wants the live test. Do not
    mention publishing or ask about the error workflow in the same response.
+   If `credentialResolutionNote` says Gateway credits are depleted,
+   that note wins: do not offer a live test.
 7. Before your final summary, scan the **whole conversation** for live runs that
    already wrote test data into an external system — earlier turns included, not
    just this one. For each such record still sitting there, follow
@@ -402,6 +420,10 @@ test without mocks. Ask only about the live test. Do not run it automatically.
 Do not offer publishing as an alternative or describe the workflow as ready to
 use or publish.
 
+If `credentialResolutionNote` says Gateway credits are depleted, that
+note wins over this live-test offer: do not offer a live test. Tell the user
+they must top up Gateway credits or add their own key on the node first.
+
 If the user agrees, use the explicit live execution path (`executions(action="run")`
 for a direct live run) and report the result separately from the earlier mocked
 verification. If the live test fails, treat the workflow as unresolved and do

package/skills/workflow-builder/SKILL.md

@@ -86,8 +86,8 @@ resources, credentials, channel IDs, or timezone; use placeholders or unresolved
 `ask-user` only when a missing choice changes the workflow's intent or topology
 (e.g. which destination service). But when that choice is which service to use
 for a capability the user did not name,
-discover coverage first and use an n8n credits–covered node instead of asking
-when the user has no credential for a comparable tool (see n8n credits
+discover coverage first and use a Gateway credits–covered node instead of asking
+when the user has no credential for a comparable tool (see Gateway credits
 Preference). Setup details — recipients, accounts,
 resources, channels, credentials, timezone — belong in placeholders or
 unresolved `newCredential()` calls until post-build setup. After the first
@@ -337,10 +337,10 @@ decision after testing.
   never by default — reuse is the right behavior everywhere else.
 - When `build-workflow` returns `resolvedCredentialsByNode`, the build already
   attached a credential to those nodes — either an existing stored credential or
-  an n8n credits–managed one (entries with `id: null` and `__aiGatewayManaged:
+  a Gateway credits–managed one (entries with `id: null` and `__aiGatewayManaged:
   true`). Treat them all as connected: do not ask the user to connect or create
   those credentials, do not route them to credential setup, and mention at most
-  that the credential (or n8n credits) is being used.
+  that the credential (or Gateway credits) is being used.
 - Never use raw credential objects like `{ id: '...', name: '...' }` in SDK
   code; replace them with `newCredential()` when editing roundtripped code.
 - If a required credential type is not listed, call
@@ -368,21 +368,25 @@ decision after testing.
      only for what a template cannot express: basic auth's base64-encoded
      pair, digest's challenge-response, OAuth flows — or when the user
      explicitly asks for a specific plain type.
-- `credentials(action="list", type=...)` may include a synthetic n8n credits
-  entry `{ id: null, name: "n8n credits", type, __aiGatewayManaged: true }`
-  when the type is covered by n8n credits (see n8n credits Preference). It is
-  not a stored credential: never pass it to `newCredential(...)` and never
-  emit `id: null` or the `__aiGatewayManaged` marker in SDK output. Setup
-  applies it automatically when the user has no stored credential of that type.
+- `credentials(action="list", type=...)` may include a Gateway credits entry
+  `{ id: "__AI_GATEWAY_MANAGED__", name: "Gateway credits", type, __aiGatewayManaged: true }`
+  when the type is covered by Gateway credits (see Gateway credits Preference). Treat its
+  `id` like any credential id: to use Gateway credits, write
+  `newCredential('Gateway credits', '__AI_GATEWAY_MANAGED__')` on the node — exactly as
+  you copy a stored credential's id. The build keeps it and attaches Gateway credits,
+  even when the user already has their own credential of that type. Write it
+  whenever the user asks for Gateway credits; otherwise the normal reuse/own-credential
+  rules apply. (When the user has no stored credential of a covered type, the build
+  still auto-attaches Gateway credits even if you didn't write the entry.)
 - These rules apply to outbound service calls. Inbound trigger nodes (Webhook,
   Form, Chat, MCP Trigger) keep authentication at its default `none` unless
   the user explicitly asks to authenticate inbound traffic.
 - Always declare `output` on nodes that use unresolved credentials when mock
   data is needed for verification.
 
-## n8n credits Preference
+## Gateway credits Preference
 
-"n8n credits" is the user-facing name of n8n's managed credential
+"Gateway credits" is the user-facing name of n8n's managed credential
 service. On instances licensed for it, several common AI-provider and
 scraping nodes can run with no API key required on the user's side.
 
@@ -394,10 +398,10 @@ and has no usable credential for a comparable one* — it runs with no API key.
 Keep your normal `suggested`/search pick when the user already has a credential
 for a comparable tool.
 
-The `suggested` list and search *rank* don't prioritize n8n credits coverage
+The `suggested` list and search *rank* don't prioritize Gateway credits coverage
 (individual search results still flag it). When the user asks for a capability
 they have no usable credential for, search that
-capability — or run `nodes(action="list", n8nConnectOnly=true)` — before
+capability — or run `nodes(action="list", gatewayCreditsOnly=true)` — before
 committing, and prefer a covered result.
 
 Respect the constraints it reports:
@@ -407,28 +411,33 @@ Respect the constraints it reports:
     use the marker key `__operation_only__`.
   - Do not set parameters listed in `aiGateway.hiddenProperties`.
 
-**Enumeration (answering "what does n8n credits support?"):**
-  - All supported nodes: `nodes(action="list", n8nConnectOnly=true)` — each
+**Enumeration (answering "what does Gateway credits support?"):**
+  - All supported nodes: `nodes(action="list", gatewayCreditsOnly=true)` — each
     result carries the full `aiGateway` field (minVersion, operations,
     hiddenProperties).
   - All supported credential types:
-    `credentials(action="search-types", n8nConnectOnly=true)`.
+    `credentials(action="search-types", gatewayCreditsOnly=true)`.
   - Operations for a specific supported node: `nodes(action="describe", …)`
     → `aiGateway.operations`.
 
 **Preference rule:** When adding a new node that has no credential assigned
-yet, prefer n8n credits over stored credentials if the credential type is
+yet, prefer Gateway credits over stored credentials if the credential type is
 supported — it works with no API key required and avoids spending the user's
 API quota. The synthetic entry in `credentials(action="list", type=...)` (see
 Credential Rules) is your signal that a type is covered. Do not change
 credentials on nodes that already have one assigned (editing an existing
 workflow, or after the user has made a credential choice).
 
+If `credentialResolutionNote` on the build result says Gateway credits are
+depleted, follow that note: tell the user they must top up Gateway credits
+or add their own key on the node. Do not say the workflow works out of the
+box, and do not offer a live test.
+
 - If the user explicitly specified their own credential (by name or by
   choosing one from a list), use that credential and do not substitute
-  n8n credits.
+  Gateway credits.
 - When speaking to the user in chat, always refer to this feature as
-  "n8n credits" — never "n8n Connect", "AI Gateway", or "gateway". Those are
+  "Gateway credits" — never "n8n credits", "n8n Connect", "AI Gateway", or "gateway". Those are
   internal names only, including the `aiGateway` field on node/credential
   results: read it to make decisions, but never surface that name to the user.
 
@@ -496,6 +505,14 @@ every reported error and warning before calling `build-workflow`.
 
 - Avoid code node where possible, use n8n nodes that help do the same thing.
   If it makes it simpler, go ahead and use code node.
+- Write Code nodes in JavaScript unless the user explicitly asks for Python.
+  `language: 'pythonNative'` runs a locked-down runner that defines only `_items`
+  (all-items mode), `_item` (per-item mode) and `print()` — no `_('Node Name')`,
+  `_input` or `$` helpers. Its imports are allowlisted per deployment and the
+  allowlist is empty by default: write import-free Python unless the **Python
+  Code Nodes** section of your system prompt says this instance allows more.
+  `build-workflow` re-checks the code against the real allowlist and reports
+  anything the runner would reject.
 - SDK builder code is a restricted subset of TypeScript that builds a static
   graph; it is not a Code node and does not run. Build strings with template
   literals; do runtime joining, aggregation, or transforms in a Code node or