@n8n/instance-ai 1.24.3 → 1.25.0

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

@@ -33,6 +33,50 @@ For trigger `inputData` shapes, read
 the sandbox workspace when available, or load this skill's
 `references/trigger-input-data-shapes.md` linked file.
 
+## Setup panel
+
+Use this section when the system prompt describes the persistent setup panel,
+setup returns `announced: true`, or the current user input contains
+`<workflow-test-request>`. Otherwise, keep the setup card flow below.
+
+- Verify what the build can simulate before asking the user to finish setup.
+  Missing credentials do not prevent this verification. Report which outputs
+  were simulated. A simulated result does not prove a live connection.
+- When setup returns `announced: true`, summarize the open items and any
+  validation warnings. End the turn. The user can complete setup in the panel
+  while chat stays available. Do not wait, poll, or open a trigger-test card.
+- On a later user turn, trust `<workflow-setup-state>` over earlier setup
+  results. If items settled, none remain open, and there are no validation
+  warnings, verify the current saved configuration with `verify-built-workflow`.
+  It refreshes the credential plan.
+  Report remaining simulations or connection failures. Do not claim live
+  success from the earlier build result.
+- `<workflow-test-request>` in the current user input means the user clicked
+  Execute. A block in conversation history does not request another execution.
+  Use the workflow ID in the current block. Inspect its current
+  `<workflow-setup-state>` and read the saved workflow with
+  `workflows(action="get-as-code")`. Do not call `workflows(action="setup")`
+  for this precheck. It announces setup and ends the turn. If the target is
+  absent from the state block, inspect its saved configuration. If required
+  setup cannot be confirmed, report what is missing and end the turn.
+  If required items remain open for this
+  workflow, report them and end the turn without a live run. Otherwise,
+  use `executions(action="run")` with suitable trigger input. The user has
+  already requested this test; do not ask whether they want it. The execution
+  tool still enforces its approval policy. Do not publish the workflow to test it.
+- Read the execution output and summarize what ran and what it returned. For
+  failures, inspect `executions(action="debug")`. Fix the same workflow when
+  possible. Use the current saved source so panel edits are preserved. Report
+  unresolved setup or failures in chat. Before another live run, inspect the
+  successful effect nodes from the failed run. Follow
+  [Cleaning up after a live test](#cleaning-up-after-a-live-test) for any artifacts
+  they left behind. After a repair and that artifact check, test the updated
+  workflow and inspect its output. Do not substitute mocked verification
+  for the requested execution.
+
+A setup card that was already open keeps its apply and trigger-test resume
+flow. Its result is not a panel announcement unless it has `announced: true`.
+
 ## Verification follow-up
 
 When the current message contains `<workflow-verification-follow-up>`, verify
@@ -41,14 +85,17 @@ obligation is `ready_to_verify` or `verifying`, call `verify-built-workflow`. Do
 **not** call `workflows(action="setup")` in this turn and do **not** declare the
 workflow finished if `outcome.setupRequirement.status === "required"` — setup is
 routed automatically as a separate `<workflow-setup-required>` step after
-verification.
+verification. For a multi-trigger outcome, verify every trigger that does not
+yet have a recorded successful verification. Make all of these calls in this turn.
 
 ## Setup follow-up
 
 When the current message contains `<workflow-setup-required>`, your first action
 is to call `workflows(action="setup")` with the `workflowId` from the payload. Do
 not verify, do not ask, do not write a message first — the inline setup card in
-the AI Assistant panel is the user-visible surface. If it returns `deferred:
+the n8n Assistant panel is the user-visible surface. If the result has
+`announced: true`, use the persistent panel instructions above and end the turn.
+If it returns `deferred:
 true`, respect the user's choice and do not retry with any other setup tool.
 A result carrying `skippedByUser` names credentials the user already passed on:
 never re-open setup for those, in this turn or any later one — see
@@ -93,7 +140,7 @@ it has you fetch, never from memory:
 - `placeholders` — one entry per marker: `name`, user-facing `title`, an
   optional `info` clarifying the value itself — its format or which of the
   provider's tokens it is (e.g. "Starts with tvly-"). Never where to obtain
-  it, and never a URL or domain: the user asks the AI Assistant for that from
+  it, and never a URL or domain: the user asks the n8n Assistant for that from
   the credential form. `type` is `password` unless clearly non-secret (at
   least one placeholder must stay `password`). Add `optional: true` only when
   the provider documents the value as optional (e.g. an org/region
@@ -101,7 +148,7 @@ it has you fetch, never from memory:
   omitted from the request.
 - `docsUrl` — the provider page where a logged-in user CREATES/COPIES the
   secret (e.g. `https://replicate.com/account/api-tokens`) — never the API
-  reference. Not shown in the form: the AI Assistant help thread uses it to
+  reference. Not shown in the form: the n8n Assistant help thread uses it to
   send the user to the exact page. Found via the `credential-recipe-research`
   procedure; omit when it finds nothing conclusive.
 - `testUrl` — a documented side-effect-free GET that rejects a bad key with
@@ -193,6 +240,14 @@ workflow does not need to be active. Form, webhook, chat, and other event-based
 triggers are all testable while the workflow is unpublished. Never publish a
 workflow as a precondition for running it.
 
+**Webhook input must carry the fields the workflow reads.** A flat `inputData`
+becomes the request `body` only; `query`, `headers` and `params` stay empty. When
+any expression reads `$json.query.*`, `$json.headers.*` or `$json.params.*`, pass
+the request envelope `{ body: {...}, query: {...}, headers: {...}, params: {...} }` (or a
+`fixtureOverrides` entry on the trigger node). Otherwise the field resolves empty,
+the run still succeeds, and that field is unverified — say so instead of
+reporting it as working.
+
 Do not proactively offer, recommend, or mention publishing until a successful
 execution has run every required node on the claimed path without mocked
 credentials, simulated node output, fixture overrides, or temporary pin data
@@ -201,6 +256,14 @@ publish-readiness evidence. If the user explicitly asks to publish before a
 live execution succeeds, warn that the live path remains untested, then follow
 the requested publish flow.
 
+`workflows(action="publish")` enforces this. While the latest verification left
+nodes unreached or simulated, the call is refused and returns
+`verificationDisclosure` — the coverage facts, generated from the run. Relay
+those facts to the user and offer a live end-to-end test. Publish only if they
+still ask, by calling publish again with `acknowledgeUnverified: true`. Never
+set that flag to skip the disclosure. The user also sees the same facts in the
+publish approval prompt, so a summary that contradicts them is visible to them.
+
 Execution evidence can come from a run you started or a run the user started.
 If the user says they ran the workflow manually, call
 `executions(action="list", workflowId)`, identify the relevant run, and inspect
@@ -210,7 +273,7 @@ when the inspected result confirms success and that every required node on the
 claimed path ran. Do not count it if mocked, simulated, fixture, or pinned output
 was used. You may offer publishing after that confirmation.
 
-For workflows produced by `build-workflow`, **always verify with
+For post-build verification of workflows produced by `build-workflow`, **always verify with
 `verify-built-workflow`, never with raw `executions(action="run")`.** It reuses
 the build outcome simulation plan, mocked credentials, and temporary pin data, so
 destructive nodes are pinned and it is safe to call repeatedly. A raw
@@ -250,17 +313,43 @@ For a workflow with more than one trigger (`triggerNodes` has multiple entries),
   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.
+- Each pass reports `nodesNotReached` only for its selected trigger's main-flow
+  branch. Coverage is the **union** across successful passes. Run every trigger
+  before you report a workflow coverage gap. Different triggers can select
+  different outputs of a shared Switch or If node.
+- A failed rerun removes that trigger's earlier coverage. Verify that trigger
+  again before you claim that the workflow is verified.
+- Report each trigger and whether its branch ran. Use the combined `claim` to
+  describe the result (see "Claiming success").
 - When the user asked for a live run, pass `triggerNodeName` to
   `executions(action="run")` the same way — one run per trigger — and report
   each branch's result.
 
+### Fixing a workflow that is already published
+
+The publishing rules above assume a new workflow. A repair of a workflow that
+is already published is different. That workflow runs in production right now,
+and it runs the version published before your fix. Your save creates a draft,
+and the draft is not live. The published version keeps running, broken, until
+somebody publishes the fix.
+
+For a repair on a published workflow:
+
+- Telling the user the fix is not live yet is not an offer to publish. Say it.
+- Do NOT report the workflow as fixed, live, running, or working in production
+  while the published version is the older one. Say the fix is in the draft.
+- `verify-built-workflow` returns `claim.liveState`. `live-stale` means the
+  published version is older than the draft you just verified. The result also
+  carries `liveStateNote`. Relay it.
+- Without a claim, call `workflows(action="get", workflowId)` and compare
+  `versionId` (the draft) with `activeVersionId` (the published version). They
+  differ while the fix is not live. A null `activeVersionId` means the workflow
+  is not published at all.
+- Ask whether to publish the fix. Publish only after the user agrees.
+- Name the version in a retest invitation: the draft, or the published version.
+  "Send another email to test it" is wrong when the fix is still a draft — the
+  test would run the broken version and look like the fix failed.
+
 ## After build-workflow succeeds
 
 1. Read `workflowId`, `workItemId`, `triggerNodes`, `verificationReadiness`,
@@ -276,16 +365,23 @@ For a workflow with more than one trigger (`triggerNodes` has multiple entries),
      `workflow-builder` skill and patch the same workflow with `build-workflow`
      using the existing `workflowId` and `workItemId`; then inspect and verify
      again.
-   - If `verificationReadiness.status === "already_verified"`, treat the
-     workflow as verified and do **not** call `verify-built-workflow` again.
+   - If `verificationReadiness.status === "already_verified"`, do not repeat
+     automatic verification. Read the saved claim before describing the workflow
+     as verified. For tracked multi-trigger builds, follow the verification
+     obligation until every trigger has a successful pass.
 
 - If `verificationReadiness.status === "ready"`, call
   `verify-built-workflow` with the `workflowId`, the `workItemId` when you
   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.
+- If `verificationReadiness.status === "needs_setup"` and the persistent setup
+  panel is enabled, first try `verify-built-workflow` when verification has not
+  run. It can verify simulated paths or report that a simulation plan is
+  unavailable. Then announce setup with `workflows(action="setup")`. Do not use
+  a live execution to work around a blocker.
+- If `verificationReadiness.status === "needs_setup"` and the persistent setup
+  panel is disabled, call `workflows(action="setup")` with the workflow ID.
+  The user configures the workflow through the inline setup card.
 - If `verificationReadiness.status === "not_verifiable"`, do not infer
   lower-level verification conditions; use the readiness guidance to give a
   clear warning or manual-test note. This is a warning completion state, not
@@ -317,10 +413,26 @@ For a workflow with more than one trigger (`triggerNodes` has multiple entries),
      budget is exhausted.
    - Relay `simulationNote` (nodes whose output was simulated) to the user
      whenever it is present.
+   - Read `resolvedParameterWarnings`. A simulated node's preview is fixture
+     data: it never proves an expression resolved. Each warning names a
+     parameter that resolved to empty or threw on the real input — the usual
+     causes are a trigger input that lacks the field (body-only webhook input
+     for a `$json.query.*` expression) or a wrong expression. Fix the input
+     shape or the expression, re-run, and never report that field as working
+     while a warning stands. Each warning carries the execution ID that was
+     checked. Use that ID with `executions(action="get-resolved-node-parameters")`
+     to inspect the same input.
+   - Read `skippedParameterChecks`. These nodes have unchecked dynamic fields.
+     The list shows at most 20 checks. `skippedParameterCheckCount` includes
+     omitted checks, which also leave dynamic fields unverified.
+     State that limitation even if the run succeeded and no parameter warnings
+     were returned. Do not request parameter values when sharing is disabled.
 3. After verification handling, if `setupRequirement.status === "required"` and
    setup has not already run for this build, call `workflows(action="setup")`
    with the workflowId.
-4. When `workflows(action="setup")` opens the inline setup card, the card is the
+4. When `workflows(action="setup")` returns `announced: true`, summarize the
+   panel state and end the turn. The live-test follow-up waits for a later user
+   turn or Execute request. When the tool opens the inline setup card, the card is the
    user-visible surface. Do not tell the user to open the editor, use the canvas,
    or click a Setup button; the user does not need to navigate anywhere.
 5. When `workflows(action="setup")` returns `deferred: true`, or reports
@@ -350,7 +462,9 @@ For a workflow with more than one trigger (`triggerNodes` has multiple entries),
    proved it works end-to-end with full coverage.
 9. Only call `workflows(action="publish")` when the user explicitly asks to
    publish. Never publish automatically or proactively offer publishing before
-   the publish-readiness requirement above is met.
+   the publish-readiness requirement above is met. A repair of a workflow that
+   is already published is the exception — follow
+   [Fixing a workflow that is already published](#fixing-a-workflow-that-is-already-published).
 10. After a direct new primary workflow is successfully published, follow
     [Error workflow follow-up](#error-workflow-follow-up).
     Do not replace this explicit opt-in with a generic "add
@@ -417,6 +531,9 @@ After workflow setup completes or is applied, if the latest verification for
 that workflow used mocked credentials, simulated node output, fixture overrides,
 temporary pin data, or another mocked input, ask whether the user wants a live
 test without mocks. Ask only about the live test. Do not run it automatically.
+An explicit test request in the current user input, including
+`<workflow-test-request>`, already answers
+this question. Run the requested test through `executions(action="run")`.
 Do not offer publishing as an alternative or describe the workflow as ready to
 use or publish.
 
@@ -476,9 +593,39 @@ result.
 
 ## Claiming success
 
-Do not tell the user a workflow is "fixed", "verified", "tested", "working", or
-has "no errors" unless you have a passing `verify-built-workflow`,
-`executions(action="run")`, or inspected user-run execution that exercised the
+For tracked multi-trigger builds, `claim` combines the saved successful passes.
+A `verified` claim requires every trigger to pass and real coverage for every planned node.
+Verify `claim.pendingTriggers` within the attempt limit. `nodesNotReached`
+outside the claim describes only the current trigger's branch.
+
+`verify-built-workflow` returns a `claim`, and its `level` decides what you may
+say:
+
+- `verified` — you may call the workflow verified, tested, or working.
+- `partial`, `unproven`, or `failed` — you may NOT. Name what is unconfirmed
+  instead.
+
+`claim.liveState` decides separately whether you may call the workflow live. A
+run always executes the draft, so `verified` says nothing about production:
+
+- `live-stale` — the published version is older than the draft you verified.
+  Do NOT call the workflow live, running, or working in production. Say the fix
+  is in the draft, and see
+  [Fixing a workflow that is already published](#fixing-a-workflow-that-is-already-published).
+- `live-current` — the published version is the one you verified.
+- `unpublished` — the workflow does not run in production at all.
+
+**`success: true` does not mean verified.** It means the run ended without an
+error, and a run with every write simulated also ends without an error. Read
+`claim.level`, not `success`.
+
+Nothing else tells the user how strong the claim is. Your message is the only
+place they learn it, so name the unreached and simulated nodes yourself, and say
+what stays unconfigured and what that means when the workflow runs.
+
+Without a claim, do not tell the user a workflow is "fixed", "verified",
+"tested", "working", or has "no errors" unless you have a passing
+`executions(action="run")` or an inspected user-run execution that exercised the
 path being claimed. Do not call a workflow "ready to use" or "ready to publish"
 unless a passing execution met the publish-readiness requirement above. A
 successful `build-workflow`/save, a static `workflows(action="validate")`, or
@@ -489,7 +636,10 @@ applies to rows or records written to an external system: never make quantitativ
 claims ("22 rows written", "columns matched") that you did not read back from
 the effect node's actual output (`executions(action="get-node-output")`) or from
 the target system itself — a successful run status does not prove the _right
-data_ was written, only that nodes ran. If you could not run the
+data_ was written, only that nodes ran. Output of a simulated or pinned node is
+fixture data: never quote it as what the workflow produced, and never cite it as
+proof that an expression resolved — use `resolvedParameterWarnings` or
+`executions(action="get-resolved-node-parameters")` for that. If you could not run the
 failing path or inspect the artifact, say so plainly — "I couldn't verify X
 because Y" — and name what is unconfirmed. An honest "could not verify" beats an
 unverified success claim.

package/skills/progressive-building/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: progressive-building
+dependencies:
+  tools:
+    - build-workflow
+    - verify-built-workflow
+    - workflows
+    - executions
+description: >-
+  Load before build-workflow and before scoping or planning new workflows and
+  feature additions, including requests spanning multiple workflows. Implement
+  one increment per user message. Finish setup and inspect a successful real
+  execution before offering another increment. Then wait for the next user
+  reply. Partial setup is incomplete. A first setup or test refusal pauses
+  building. Follow the skill's full-build exceptions. Also supports workflow edits
+  and repairs. For workflows that create or write Data Tables, load
+  data-table-manager first. Requests only to
+  run, inspect, or manage existing resources use their normal tools and skills.
+---
+
+# Progressive building
+
+Apply this policy when creating or extending workflows and repairing those
+builds. It overrides conflicting scoping and setup narration in the building
+and post-build guidance above. Keep their validation, approval, credential,
+publish, and cleanup rules. Write to the user in their conversation language.
+
+Requests to run, inspect, or manage existing resources use their normal tools
+and skills without this staging process. This also applies when the user
+switches to such a request after building in the same conversation.
+
+## Choose the first version
+
+Acknowledge the full request before selecting the smallest useful outcome.
+Build a working part of the requested workflow. Do not create a throwaway demo.
+Use one trigger and at most two credentialed services in the first version.
+Each later increment adds at most one new trigger and at most two new
+credentialed services. This also applies when new triggers share existing logic
+or need no credentials. Count the trigger's credential. Count services even
+when their credentials are connected.
+Parameters and placeholders do not count. An AI provider counts toward the same
+two-service total as the trigger and other services, even if its credential is
+missing. Exclude a model only when Gateway credits is confirmed available for
+that model on this instance. If it needs a provider API key, count it.
+
+Keep this limit internal. Explain what the first version does and what comes
+next. Preserve the user's services. Prefer existing credentials when choosing
+between equally suitable starting points. Follow workflow-builder guidance
+on credential setup preferences when the user leaves the service open.
+
+Ask a single-choice question if several named services are equally central.
+Otherwise state a reasonable starting assumption. Do not offer a multi-select
+list that adds services or triggers to the first version.
+
+The `planning` skill and `create-tasks` tool are unavailable in this mode.
+Keep additional workflows as later roadmap items.
+
+## Build, set up, and run
+
+1. Build the selected version. Use the existing verification and setup flow.
+2. Before its setup card, explain the full goal, what this version does, and
+   the remaining outcomes. Do this on automatic `<workflow-setup-required>`
+   turns too. Then open setup. Do not add more work while setup is incomplete.
+3. Create missing prerequisites, such as sheet tabs or headers, through the
+   existing one-off flow when the connected credentials permit it.
+4. After setup, offer only a live run for manual or schedule triggers. The execution
+   approval card supplies consent. For event triggers, explain how to start
+   listening for a test event and perform the event, then ask the user to report
+   back. Inspect the resulting execution with `executions`.
+5. Extend only after a successful, non-simulated execution of the current
+   version. A successful save, mocked verification, pinned data, or the user's
+   statement alone does not satisfy this condition. Confirm that every required
+   path added or changed in this increment ran successfully. Unchanged paths do
+   not need another run.
+   Report simulated verification as simulated, not as end-to-end
+   success. Repair failures before extending.
+6. After one increment's verification and setup, end the turn. Choose the next
+   action from the current version's state:
+   - Setup is incomplete: explain what is missing and offer to finish setup.
+     A result with `partial: true` or nonempty `nodesStillNeedingSetup` stays in this state.
+     Respect skipped credentials. If setup was deferred, pause without reopening it.
+   - Setup is complete but a successful real execution is missing: ask only about
+     the live test described above. Do not offer to build the next increment instead.
+   - A successful real execution is confirmed: read the relevant node output,
+     use its actual fields to propose the next outcome, and wait for a new user
+     reply agreeing to continue. Edit the same workflow and source file when
+     extending it.
+   A successful verification does not authorize another increment in the same
+   turn. The original list of requested outcomes does not replace this pause.
+
+Keep a short Done/Next roadmap in substantive replies about this build. Mark an
+outcome as done only after execution evidence confirms it. Do not claim the
+whole request is complete while outcomes remain.
+Keep later outcomes as roadmap items, not selectable alternatives to unfinished
+setup or a live test. A reply such as "continue" or "what's next?" keeps the
+current setup or live-test step. It is not a full-build request or another decline.
+
+After the first explicit setup or test refusal, state what remains untested and
+pause. Do not offer another increment or ask the user to repeat the refusal.
+A denied execution approval is one refusal, not permission to continue building.
+
+## Finish without staging when asked
+
+Build a precise, complete implementation specification in one pass. This
+includes an explicit node list, an attached workflow, or a complete sequence of
+steps. A list of desired capabilities or entry points alone does not qualify.
+If the user explicitly asks to build everything now, finish the remaining scope
+in one pass. Do not infer this instruction from a list of requested additions.
+
+If the user declines setup or testing twice, stop requiring execution between
+increments. Finish the requested scope and offer setup at the end. Respect
+previously skipped credentials. State which parts remain untested.

package/skills/workflow-builder/SKILL.md

@@ -112,7 +112,7 @@ numbers, custom URLs, notification targets, chat IDs) and resource IDs where
 named none. Never hardcode fake values (`user@example.com`, `YOUR_API_KEY`,
 bearer tokens, sample channel/chat IDs or recipient lists) and never ask for
 setup values before the first successful build — placeholders cover them, and
-`workflows(action="setup")` opens an inline setup card in the AI
+`workflows(action="setup")` opens an inline setup card in the n8n
 Assistant panel afterwards for the user to fill in.
 Do not replace concrete user-provided or discoverable values with
 placeholders: if the prompt gives a real URL, channel name, table name, label,
@@ -146,8 +146,7 @@ setup steps or node semantics from memory when those sources can answer.
    instead of improvising.
 3. **Official n8n docs** — for credential setup, product features, hosting, or
    node docs that the knowledge base does not cover, load `n8n-docs-assistant`
-   then load `n8n-docs` via `load_tool` (search "n8n docs" if it is not
-   visible) and call `n8n-docs`. Prefer docs over web search for n8n-specific
+   and call `n8n-docs`. Prefer docs over web search for n8n-specific
    questions.
 
 For workflows with multiple external systems, multiple requested effects,
@@ -217,6 +216,12 @@ follow its build → publish → assign steps.
    and later `fixtureOverrides` can exercise those scenarios. Do not simulate
    every external read by default; use this when branch coverage or deterministic
    proof depends on controlling the upstream data.
+   Decide grouping now, while writing the source: `.group(...)` lives in the code, so
+   it cannot be added after the build. See [Node Groups](#node-groups) for the
+   criteria, and reach a decision either way — groups declared, or this workflow does
+   not warrant them. When the canvas will be over the ceiling and no valid group can hold
+   the remaining nodes, pass `groupingDecision: 'not_warranted'` with a `groupingReason`
+   to `build-workflow`; without groups or that reason the build is refused.
 7. Before the first `build-workflow` (and again after substantive edits), run
    SDK validation on the workspace source file via
    `workspace_execute_command`:
@@ -586,8 +591,12 @@ unsolicited `sticky()`, forbidden builder constructs (e.g. `.map()`), and
 repeated `.onTrue()` / `.onFalse()` overwrites on the same IF variable. Fix
 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.
+- Native node first: shape, compute, default or format fields with
+  **Edit Fields (Set)** and expressions (full JavaScript); **Filter**, **IF** /
+  **Switch**, **Sort**, **Remove Duplicates**, **Aggregate**, **Split Out**,
+  **Limit** and **Merge** cover the rest. A Code node is only for multi-pass
+  algorithms, `$getWorkflowStaticData` state, fence-stripping model output,
+  try/catch around upstream node access, or a step needing three or more nodes.
 - 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')`,
@@ -598,8 +607,8 @@ every reported error and warning before calling `build-workflow`.
   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
-  `expr()`. Full allowed/forbidden list:
+  literals; do runtime joining, aggregation, or transforms with `expr()` in a
+  native node. Full allowed/forbidden list and "Native node mappings" table:
   `${N8N_WORKSPACE_DIR}/knowledge-base/reference/workflow-sdk-language.md`.
 - Use `@n8n/workflow-sdk`.
 - Do not specify node positions. They are auto-calculated by the layout engine.
@@ -696,18 +705,14 @@ import {
 
 ## Node Groups
 
-Organise multi-stage workflows into named node groups — visual frames on the canvas — so the
-result is readable the first time the user sees it. Group each clear stage (ingest → transform
-→ deliver); small workflows don't need groups. Give every group a one-sentence
-`description` — groups are collapsed by default, so name + description is what the user sees
-first.
+{{GROUPING_GUIDANCE_PLACEHOLDER}}
 
-`.group(name, members, { description })` on the workflow builder; members are the node handles.
-Read `knowledge-base/reference/node-groups.md` for the exact rules (trigger nodes excluded,
-one connected section, AI sub-nodes stay with their Agent) before creating groups. Agent save
-tools drop an invalid group from the saved workflow and report a warning, so fix the source
-instead of re-emitting it. When editing an existing workflow, keep existing `.group(...)` calls
-and their descriptions intact unless the change is about grouping.
+Declare a group with `.group(name, members, { description })` on the workflow builder; members
+are the node handles. Before you emit a `.group(...)`, read
+`${N8N_WORKSPACE_DIR}/knowledge-base/reference/node-groups.md` — it carries the rules that make
+a group valid and the contract for editing an existing workflow's groups. Do not restate those
+rules from memory: an invalid group is dropped from the saved workflow with a warning, so the
+source has to be fixed rather than re-emitted.
 
 ## Workflow Rules
 
@@ -921,6 +926,13 @@ isImportant.onFalse(sendHolding);
 For Switch, wire cases the same way — `.to(switchNode).onCase(0, a).onCase(1, b)`
 or inline — using zero-based `.onCase(index, target)` for each rule output.
 
+Error routes work the same way on any node: `.to(fetchNode).onError(notify)`
+routes the error output and leaves the cursor on `fetchNode`, so a following
+`.to(next)` continues the main branch and a second `.onError()` adds another
+handler. The inline form `.to(fetchNode.onError(notify))` is equivalent. Both
+forms set `onError: 'continueErrorOutput'` on the node for you. Call
+`.onError()` once for each handler — it takes one handler, not an array.
+
 For Split in Batches, use it for per-item side effects and loop back with
 `nextBatch`. Do not add a separate IF gate just to check whether items exist.
 
@@ -938,8 +950,9 @@ For AI Agent workflows:
 - `placeholder('hint')`: marks a parameter value for user input (use directly as
   the parameter value; `workflow-sdk validate` flags wrapping it in `expr()`).
 - `.output(n)`: selects a zero-based output index.
-- `.onError(handler)`: connects a node's error output to a handler. Requires
-  `onError: 'continueErrorOutput'` in the node config.
+- `.onError(handler)`: connects a node's error output to a handler, on the node
+  or on the workflow builder. It sets `onError: 'continueErrorOutput'` on the
+  node, so you do not declare that in the config.
 - `nodeJson(node, 'field.path')`: creates an explicit expression reference to a
   specific node's JSON output.
 - Subnode factories follow the same pattern as `languageModel()` and `tool()`:
@@ -982,10 +995,21 @@ store its own public endpoint.
 
 ## Completion
 
+Do not report a build as done until you have made the grouping decision described in
+[Node Groups](#node-groups) and checked what the build did with it. A dropped-group warning
+names what was invalid — a duplicate name, a member that does not exist, a boundary the rules
+reject: fix what the warning reports and build again. A `GROUPING_DECISION_MISSING` error means
+the build was refused: fix the source, or pass the opt-out with a reason. A
+`GROUP_DROPPED_OVER_CEILING` error also refuses the build: a declared group was invalid and the
+canvas is still over the ceiling. Fix the boundary the message names — the opt-out does not
+apply. If the top level is still above
+{{TOP_LEVEL_ITEM_CEILING_PLACEHOLDER}} items with groups in place, name each remaining item and
+why it cannot join a group.
+
 For a successful build, finish with one concise sentence naming the workflow and
 what changed. Include the workflow ID when it is available. If setup is
 required, say plainly that setup is needed; do not tell the user to open a setup
-wizard or navigate away from the AI Assistant panel. When the workflow exposes
+wizard or navigate away from the n8n Assistant panel. When the workflow exposes
 a Webhook, Form, or Chat Trigger, follow [Trigger URL Sharing](#trigger-url-sharing)
 and include the correct end-user URL (or in-editor chat guidance) in that
 summary.

package/dist/agent/sub-agent-briefing.d.ts

@@ -1,20 +0,0 @@
-import { type IterationLog } from '../storage/iteration-log';
-export interface RunningTaskSummary {
-    taskId: string;
-    role: string;
-    goal?: string;
-}
-export interface SubAgentBriefingInput {
-    task: string;
-    conversationContext?: string;
-    artifacts?: Record<string, unknown>;
-    additionalContext?: string;
-    requirements?: string;
-    iteration?: {
-        log: IterationLog;
-        threadId: string;
-        taskKey: string;
-    };
-    runningTasks?: RunningTaskSummary[];
-}
-export declare function buildSubAgentBriefing(input: SubAgentBriefingInput): Promise<string>;

package/dist/agent/sub-agent-briefing.js

@@ -1,39 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildSubAgentBriefing = buildSubAgentBriefing;
-const iteration_log_1 = require("../storage/iteration-log");
-async function buildSubAgentBriefing(input) {
-    const parts = [];
-    parts.push(`<task>\n${input.task}\n</task>`);
-    if (input.conversationContext) {
-        parts.push(`<conversation-context>\n${input.conversationContext}\n</conversation-context>`);
-    }
-    if (input.artifacts && Object.keys(input.artifacts).length > 0) {
-        parts.push(`<artifacts>\n${JSON.stringify(input.artifacts)}\n</artifacts>`);
-    }
-    if (input.additionalContext) {
-        parts.push(input.additionalContext);
-    }
-    if (input.requirements) {
-        parts.push(input.requirements);
-    }
-    if (input.runningTasks && input.runningTasks.length > 0) {
-        const taskLines = input.runningTasks
-            .map((t) => `  <running-task taskId="${t.taskId}" role="${t.role}">${t.goal ?? ''}</running-task>`)
-            .join('\n');
-        parts.push(`<thread-state>\n${taskLines}\n</thread-state>`);
-    }
-    if (input.iteration) {
-        try {
-            const entries = await input.iteration.log.getForTask(input.iteration.threadId, input.iteration.taskKey);
-            const formatted = (0, iteration_log_1.formatPreviousAttempts)(entries);
-            if (formatted) {
-                parts.push(formatted);
-            }
-        }
-        catch {
-        }
-    }
-    return parts.join('\n\n');
-}
-//# sourceMappingURL=sub-agent-briefing.js.map

package/dist/agent/sub-agent-briefing.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"sub-agent-briefing.js","sourceRoot":"","sources":["../../src/agent/sub-agent-briefing.ts"],"names":[],"mappings":";;;AAAA,4DAAqF;AAwC9E,KAAK,gCAAgC,KAA4B;IACvE,MAAM,KAAK,GAAa,EAAE,CAAC;IAG3B,KAAK,CAAC,IAAI,CAAC,WAAW,KAAK,CAAC,IAAI,WAAW,CAAC,CAAC;IAG7C,IAAI,KAAK,CAAC,mBAAmB,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,2BAA2B,KAAK,CAAC,mBAAmB,2BAA2B,CAAC,CAAC;IAC7F,CAAC;IAGD,IAAI,KAAK,CAAC,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChE,KAAK,CAAC,IAAI,CAAC,gBAAgB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IAC7E,CAAC;IAGD,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACrC,CAAC;IAGD,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAChC,CAAC;IAGD,IAAI,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzD,MAAM,SAAS,GAAG,KAAK,CAAC,YAAY;aAClC,GAAG,CACH,CAAC,CAAC,EAAE,EAAE,CACL,2BAA2B,CAAC,CAAC,MAAM,WAAW,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,EAAE,iBAAiB,CACvF;aACA,IAAI,CAAC,IAAI,CAAC,CAAC;QACb,KAAK,CAAC,IAAI,CAAC,mBAAmB,SAAS,mBAAmB,CAAC,CAAC;IAC7D,CAAC;IAGD,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACrB,IAAI,CAAC;YACJ,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CACnD,KAAK,CAAC,SAAS,CAAC,QAAQ,EACxB,KAAK,CAAC,SAAS,CAAC,OAAO,CACvB,CAAC;YACF,MAAM,SAAS,GAAG,IAAA,sCAAsB,EAAC,OAAO,CAAC,CAAC;YAClD,IAAI,SAAS,EAAE,CAAC;gBACf,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACvB,CAAC;QACF,CAAC;QAAC,MAAM,CAAC;QAET,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC3B,CAAC"}

package/dist/tools/evals/analyze-agent-input-columns.service.d.ts

@@ -1,6 +0,0 @@
-import type { WorkflowJSON } from '@n8n/workflow-sdk';
-export interface AgentInputColumns {
-    agentNodeName: string;
-    inputColumns: string[];
-}
-export declare function analyzeAgentInputColumns(workflow: WorkflowJSON, agentNodeName: string): AgentInputColumns;