@n8n/instance-ai 1.19.2 → 1.20.0

package/skills/credential-recipe-research/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: credential-recipe-research
+description: >-
+  Lookup procedure for Simplified Custom Auth recipe fields — sources the auth
+  template, the key-issuing docsUrl and an auth-rejecting testUrl from the
+  provider's real documentation instead of memory. Load before composing
+  credentialHints for a service without a dedicated credential type (the
+  post-build-flow setup step), or when asked to fix a recipe whose template,
+  key page or test endpoint is wrong.
+recommended_tools:
+  - research
+  - workflows
+---
+
+# Credential Recipe Research
+
+A recipe is only as good as the documentation it came from. This is a
+procedure, not guidance: execute every step with the `research` tool and keep
+only findings you can point to on a fetched page. Guessed URLs are how users
+end up on the wrong page with a key that can't be verified.
+
+Inputs: the service name and the API host(s) the workflow's nodes call.
+
+## 1. Auth scheme (template)
+
+Fetch the provider's authentication docs — `research(action="web-search")`
+with `"<service> API authentication"`, then `fetch-url` the best docs hit.
+Record the scheme EXACTLY as documented: header name, prefix word, casing
+(`Authorization: Key {{api_key}}` vs `Bearer {{api_key}}` vs a custom header
+like `xi-api-key`). If the documented auth is basic, digest, or OAuth, stop:
+that is not expressible as a template — use the matching generic type instead
+(see the workflow-builder skill's credential ladder).
+
+## 2. Key page (docsUrl)
+
+Find where a logged-in user CREATES or COPIES the key. The URL is not shown
+in the form — the AI Assistant help thread presents it as THE place to get
+the value, so a wrong URL sends the user to a dead end with full confidence:
+
+- Search `"<service> dashboard API keys"`, and scan the fetched auth docs for
+  phrases like "get your key from", "Dashboard → API Keys", "console",
+  "settings".
+- The answer normally lives on an app/console/dashboard host —
+  `console.apify.com/settings/integrations`,
+  `elevenlabs.io/app/settings/api-keys`, `replicate.com/account/api-tokens`,
+  `app.tavily.com/home` — not under `/docs`, `/reference`, or
+  `/documentation`.
+- Accept a docs-domain URL only when the fetched page shows keys are actually
+  issued there (some ReadMe-style logged-in portals do).
+- NEVER construct a dashboard path by analogy (`/account/api-keys`,
+  `/dashboard/keys`, …). Dashboards are apps behind a login: a fetch answers
+  200 for any invented route, so the path cannot be verified by fetching.
+  Emit a deep dashboard URL only when it appears VERBATIM on a page you
+  fetched; when the docs only describe navigation ("Dashboard → API Keys")
+  without a literal URL, use the dashboard/app root they reference — a
+  shallower real page beats a deeper invented one.
+- Nothing conclusive after both steps → omit docsUrl. Never pass off the API
+  reference as the key page.
+
+## 3. Verification endpoint (testUrl)
+
+Find a documented, side-effect-free GET that rejects a bad key with 401/403.
+Check the API reference in this order and stop at the first qualifying hit:
+
+1. Account/profile/me endpoints — `/v1/account`, `/v2/users/me`, `/v1/user`.
+2. Usage/quota endpoints — e.g. fal's `/v1/models/usage`, Tavily's `/usage`.
+3. List/discovery endpoints — `/v1/templates`, `/v1/models`, `/v1/voices`.
+
+Rules, all mandatory:
+
+- The endpoint must appear on a page you fetched — never construct a path by
+  analogy with other APIs.
+- Never one of the workflow's own endpoints, never a resource or action URL,
+  never anything that can trigger billable work. Setup rejects workflow-URL
+  collisions, and the probe reports unexpected statuses as "could not be
+  verified" — an invented URL only costs the user trust.
+- Skip endpoints that answer 2xx regardless of the key: auth-optional
+  endpoints (Pexels search) or services that signal auth errors in the
+  response body (Apollo's `auth/health`, TikTok) — a status probe cannot
+  verify through them.
+- Nothing qualifies → omit testUrl. The credential saves fine and the card
+  honestly reports it could not be verified, which beats a false green.
+
+## 4. Compose
+
+Fill `credentialHints` (field list and example in the post-build-flow skill)
+from the findings above only. `suggestedName` names the service ("Apify API
+Token"); never include a real secret.

package/skills/debugging-executions/SKILL.md

@@ -31,7 +31,8 @@ name what is unconfirmed instead of repeating a success claim.
 
 Use `executions(action="run")` with `inputData` matching the trigger's output
 shape — do not rebuild the workflow with a Manual Trigger. For trigger
-`inputData` shapes, read `knowledge-base/reference/trigger-input-data-shapes.md`
+`inputData` shapes, read
+`${N8N_WORKSPACE_DIR}/knowledge-base/reference/trigger-input-data-shapes.md`
 when a sandbox workspace is available.
 
 ## Failed execution

package/skills/intent-recognition/SKILL.md

@@ -5,24 +5,25 @@ description: >-
   owns the top-level control flow — workflow-anchored, agent-anchored,
   needs-clarification, or out-of-scope) and embeds_other (whether the other
   primitive appears embedded inside — an agent step inside a workflow, or a
-  workflow invoked as an agent tool). Must be used before deciding the intent
-  of any automation request, including compound requests with multiple
-  independent automations, mid-build extensions to an existing workflow or
-  agent, one-off questions or reports that need external systems you cannot
-  query directly, and requests that need clarification before an anchor can
-  be chosen, before choosing workflow-builder, planning, or an agent-oriented
-  design.
+  workflow invoked as an agent tool). Must be used whenever the current turn
+  requires choosing or reconsidering the intent of an automation request,
+  including compound requests, independent automations introduced mid-build,
+  one-off questions or reports that need external systems you cannot query
+  directly, and requests that need clarification before an anchor can be
+  chosen. Do not load for routine edits or extensions when the conversation
+  already targets a workflow or Agent.
 ---
 
 # Intent recognition
 
 ## Purpose
 
-Use this skill to classify an automation request before designing or building
-it. This skill must be used before deciding whether a request is
-workflow-anchored, agent-anchored, needs clarification, or out of scope, and
-before deciding whether the other primitive is embedded inside it. The
-deciding question is not a single "workflow or agent" label — it is two
+Use this skill when an automation request still needs to be classified before
+designing or building it, or when a new turn may require reconsidering the
+current artifact. Do not load it again for a routine edit or extension when the
+conversation already targets a workflow or Agent, unless the user introduces
+an independent automation or the new request carries its own anchor signal.
+The deciding question is not a single "workflow or agent" label — it is two
 questions: who owns the top-level control flow, and does the other primitive
 show up inside that flow.
 
@@ -76,8 +77,8 @@ Two orthogonal decisions per request, or per part for compound requests:
 
 - workflow-anchored + `true`: an agent embedded as a workflow step (e.g. a
   scheduled pipeline whose middle step is open-ended investigation).
-- agent-anchored + `true`: workflows invoked as tools of the agent; see Adding
-  tools to an agent to distinguish them from direct tools.
+- agent-anchored + `true`: workflows invoked as tools of the agent; see Agent
+  tool shape to distinguish them from direct tools.
 - `n/a` for needs-clarification and out-of-scope.
 
 **Migration from the old taxonomy**: old **hybrid** → workflow-anchored,
@@ -87,37 +88,29 @@ only when the user wants a persistent, triggerable automation. Old
 **ambiguous** → needs-clarification. Old **workflow** and **agent** map
 directly onto the matching anchor value.
 
-## Adding tools to an agent
+## Agent tool shape
 
 After choosing an agent-anchored design, decide whether each capability should
 be a direct agent tool or a workflow tool:
 
-- **Direct agent tools are the default.** Forward requests to add capabilities
-  to `build-agent` near-verbatim so the delegated builder can choose MCP,
-  node-backed, provider, or custom tools. One node-backed capability or
-  multiple independent node tools stay on the agent build path with
+- **Direct agent tools are the default.** One node-backed capability or multiple
+  independent node tools stay on the Agent build path with
   `embeds_other: false`.
 - Use a **workflow tool** only when one agent tool call must run an ordered
   multi-node procedure, or when the user explicitly needs that workflow
   reusable, manually callable, or usable outside the agent. Build the workflow
   first, pass it to `build-agent` via `workflowContext`, and set
   `embeds_other: true`.
-- Create required **data tables** via `data-table-manager` → `data-tables`
-  before `build-agent` when the agent will store or query tabular data — the
-  builder cannot create tables.
-- Before the first `build-agent` call, create every prerequisite the builder
-  cannot: required data tables and any workflow tools the agent will invoke.
-  Pass built workflows in `workflowContext` and list every prerequisite
-  name/schema in `message`. Then let the builder gather remaining agent-specific
-  requirements (model, credentials, integrations).
-- If a `builderReply` lists missing workflows or tables, create them and call
-  `build-agent` again — never ask the user to create them manually.
 
 Count the nodes required inside one tool invocation, not the total number of
 tools on the agent. For example, looking up and inserting Data Table rows are
 two direct node tools; an atomic lookup-transform-write procedure is one
 workflow tool.
 
+After choosing an agent-anchored design, load `agent-builder` before calling
+`build-agent`. It owns prerequisite creation and the handoff to the delegated
+builder.
+
 ## Decision Steps
 
 0. If the user is mid-build on an existing workflow or agent, apply context
@@ -224,7 +217,7 @@ that agent, never a spawned workflow.
   that drafts a tailored renewal pitch for each account from its usage
   history embeds an agent; a nightly job that condenses each ticket into a
   two-sentence summary does not.
-- For an agent with workflow tools, apply Adding tools to an agent.
+- For an agent with workflow tools, apply Agent tool shape.
 
 **Context continuity** (step 0): inside a workflow build, a request to insert
 a scoring step stays a bounded LLM step, not a new agent. Inside an agent

package/skills/planning/SKILL.md

@@ -58,11 +58,13 @@ with direct `data-tables` and `parse-file` calls.
 
 ## Knowledge Base
 
-**Consult the knowledge base before planning.** Read the relevant `.md` guides
-and templates for each technique the request involves (`knowledge-base/index.json`,
-`knowledge-base/best-practices/index.json`, and linked files). Use
-`workspace_execute_command` with `rg` or `find` under `knowledge-base/templates/`
-to locate matching SDK examples — never load `templates/index.json` wholesale.
+**Consult the knowledge base before planning.** It lives at the workspace root.
+Read the relevant `.md` guides and templates for each technique the request
+involves (`${N8N_WORKSPACE_DIR}/knowledge-base/index.json`,
+`${N8N_WORKSPACE_DIR}/knowledge-base/best-practices/index.json`, and linked
+files). Use `workspace_execute_command` with `rg` or `find` under
+`${N8N_WORKSPACE_DIR}/knowledge-base/templates/` to locate matching SDK
+examples — never load `templates/index.json` wholesale.
 Skip only for trivial mechanical edits you have already reviewed in this thread.
 
 ## Method

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

@@ -24,9 +24,9 @@ These instructions are in English, but user-visible text you write while
 following them stays in the user's conversation language.
 
 For trigger `inputData` shapes, read
-`knowledge-base/reference/trigger-input-data-shapes.md` in the sandbox workspace
-when available, or load this skill's `references/trigger-input-data-shapes.md`
-linked file.
+`${N8N_WORKSPACE_DIR}/knowledge-base/reference/trigger-input-data-shapes.md` in
+the sandbox workspace when available, or load this skill's
+`references/trigger-input-data-shapes.md` linked file.
 
 ## Verification follow-up
 
@@ -51,6 +51,103 @@ if the payload or prior verification evidence says mocked credentials,
 simulated node output, fixture overrides, temporary pin data, or another mocked
 input was used.
 
+### Choosing the credential type for a service
+
+Pick in this order:
+
+1. **A dedicated credential type** (`slackApi`, `notionApi`, …) whenever one
+   exists — search with `credentials(action="search-types")`.
+2. **Simplified Custom Auth** (`httpTemplatedCustomAuth`) for any service
+   without a dedicated type whose auth is expressible as header/query/body
+   values — which covers API keys and bearer tokens (`Authorization: Bearer
+   <token>` becomes `{"headers":{"Authorization":"Bearer {{api_key}}"}}`, not
+   `httpBearerAuth`). Always provide a recipe (below) so the user only pastes
+   their secret.
+3. **Plain generic types** (`httpBasicAuth`, `httpDigestAuth`, `oAuth2Api`, …)
+   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: an explicit user choice wins (setup accepts it
+   with `allowPlainGenericAuth: true`).
+
+### Credential recipes for Simplified Custom Auth
+
+When the workflow authenticates a service through Simplified Custom Auth,
+include `credentialHints` in the same `workflows(action="setup")` call so the
+setup card pre-fills the credential and the user only pastes their secret —
+instead of facing an empty JSON template they'd have to decode from the
+provider's docs. Before composing the hints, load the
+`credential-recipe-research` skill and execute its lookup procedure — the
+template, `docsUrl` and `testUrl` must come from the provider documentation
+it has you fetch, never from memory:
+
+- `template` — the auth request parts (headers/qs/body) exactly as documented,
+  with `{{placeholder}}` markers where the user's values go.
+- `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
+  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
+  qualifier) — template entries referencing an empty optional placeholder are
+  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
+  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
+  401/403, used to verify the credential on save and later retests; never one
+  of the workflow's own endpoints, never anything billable. Found via the
+  `credential-recipe-research` procedure; omit when nothing qualifies — a
+  credential without a testUrl saves fine and honestly shows "could not be
+  verified", which beats a false green.
+- `acceptedStatusCodes` — almost always omit; the user can adjust it later on
+  the credential if a service's auth answers 401/403 to valid GETs.
+- `suggestedName` — display name for the created credential.
+
+Example — fal.ai's docs say requests use `Authorization: Key <FAL_KEY>` and
+`GET https://api.fal.ai/v1/models/usage` is a documented side-effect-free
+endpoint that rejects a bad key (the model-serving host `fal.run` is not a
+key-check endpoint):
+
+```json
+{
+  "action": "setup",
+  "workflowId": "...",
+  "credentialHints": [
+    {
+      "suggestedName": "fal.ai API Key",
+      "template": {
+        "headers": { "Authorization": "Key {{api_key}}" }
+      },
+      "placeholders": [
+        {
+          "name": "api_key",
+          "title": "fal.ai API key",
+          "info": "Key ID and secret, separated by a colon",
+          "type": "password"
+        }
+      ],
+      "docsUrl": "https://fal.ai/dashboard/keys",
+      "testUrl": "https://api.fal.ai/v1/models/usage"
+    }
+  ]
+}
+```
+
+Never put a real secret in a recipe — the user pastes it in the setup card and
+it is stored redacted in the credential. Add `nodeName` when several nodes use
+Simplified Custom Auth for different services. You cannot see the secret, but
+once setup reports the credential applied, treat it as fully configured — the
+`{{placeholder}}` markers live only in the template; the stored values replace
+them at request time. If a live test later fails with an auth error, that is
+the moment to have the user re-open the credential and re-paste the value.
+
+If the user defers setup instead, don't hand them manual field-by-field
+credential instructions for the n8n editor — tell them to reopen setup when
+they're ready: the card pre-fills everything except their key.
+
 ## Publishing and testing
 
 **Publishing is never required for testing.** Both `executions(action="run")` and
@@ -147,27 +244,19 @@ again.
    when the latest verification evidence used mocks or simulations. If this
    follow-up is due, ask only that question now; do not also ask about the error
    workflow in the same response.
-7. For a direct new primary workflow, follow
-   [Error workflow follow-up](#error-workflow-follow-up) after the mocked
-   live-test follow-up is no longer pending for this workflow. If no mocked
-   live-test follow-up is due, ask about the error workflow before any generic
-   testing prompt. Do not replace this explicit opt-in with a generic "add
-   anything else?", publish, or test question.
-8. Ask the user if they want to test the workflow (skip this if
-   `verify-built-workflow` already proved it works end-to-end with full
-   coverage). If you need to ask about both generic testing and an error
-   workflow, ask the error-workflow opt-in first and leave generic testing as a
-   later follow-up unless the user already requested testing.
-9. Only call `workflows(action="publish")` when the user explicitly asks to
+7. If testing has not already been offered or completed, ask whether the user
+   wants to test the workflow. Skip this if `verify-built-workflow` already
+   proved it works end-to-end with full coverage.
+8. Only call `workflows(action="publish")` when the user explicitly asks to
    publish. Never publish automatically.
+9. 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
+   anything else?", publish, or test question.
 
 ## Error workflow follow-up
 
-This follow-up comes after the mocked verification live-test follow-up when that
-follow-up is due, and before generic "want to test it?" prompts. For a direct
-new primary workflow, ask about the error workflow after the user answers,
-declines, or defers any pending live/no-mock testing question. If no mocked
-live-test follow-up is due, ask about the error workflow first.
+This follow-up comes only after a direct new primary workflow is successfully published.
 
 If you just built an Error Trigger workflow because the user opted into adding
 one for a known target workflow, do not ask whether to build another error
@@ -175,7 +264,7 @@ workflow. Continue the publish-before-assign flow for the target workflow:
 ask whether to publish the error workflow and set it on that target workflow,
 then publish and assign only after the user approves.
 
-After saving and handling verification/setup for a direct new primary workflow,
+After successfully publishing a direct new primary workflow,
 ask once whether the user wants to build an error workflow for that workflow.
 Use `ask-user` with a yes/no choice or a concise visible question. Do **not**
 create an error workflow before the user opts in.
@@ -227,15 +316,9 @@ 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. Do not run the live test automatically.
 
-This follow-up has priority over the error-workflow opt-in for a direct new
-primary workflow. If both follow-ups are due, ask about the live/no-mock test
-first and ask the error-workflow question only after the user has answered,
-declined, or deferred the live/no-mock test follow-up.
-
 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 user declines or defers, state what remains untested and do
-not claim live end-to-end verification.
+verification. If the user declines or defers, state what remains untested and do not claim live end-to-end verification.
 
 ## Claiming success
 

package/skills/workflow-builder/SKILL.md

@@ -115,15 +115,19 @@ setup steps or node semantics from memory when those sources can answer.
 1. **Knowledge base** — consult before
    building. Read the relevant `.md` guides and templates for each technique
    the request involves. Skip only for trivial mechanical edits you have
-   already reviewed in this thread.
-   - `knowledge-base/index.json` — catalog of technique guides
-     (`knowledge-base/best-practices/index.json`; read the linked `.md` files)
-     and orchestration reference docs (`knowledge-base/reference/index.json`)
-   - `knowledge-base/templates/` — curated SDK workflow examples: use
-     `workspace_execute_command` with `rg` or `find` to locate matches, then
-     read only the relevant `.ts` files — never load `templates/index.json`
-     wholesale
-   - `node-types/index.txt` — searchable catalog of available n8n nodes
+   already reviewed in this thread. The knowledge base lives at the workspace
+   root (NOT inside this skill's directory) — all paths below are
+   workspace-root-relative:
+   - `${N8N_WORKSPACE_DIR}/knowledge-base/index.json` — catalog of technique
+     guides (`${N8N_WORKSPACE_DIR}/knowledge-base/best-practices/index.json`;
+     read the linked `.md` files) and orchestration reference docs
+     (`${N8N_WORKSPACE_DIR}/knowledge-base/reference/index.json`)
+   - `${N8N_WORKSPACE_DIR}/knowledge-base/templates/` — curated SDK workflow
+     examples: use `workspace_execute_command` with `rg` or `find` to locate
+     matches, then read only the relevant `.ts` files —
+     never load `templates/index.json` wholesale
+   - `${N8N_WORKSPACE_DIR}/node-types/index.txt` — searchable catalog of
+     available n8n nodes
 2. **Runtime skills** — when another skill matches (e.g. `data-table-manager`,
    `debugging-executions`, `post-build-flow`), `load_skill` and follow it
    instead of improvising.
@@ -135,14 +139,19 @@ setup steps or node semantics from memory when those sources can answer.
 
 For workflows with multiple external systems, multiple requested effects,
 digests or reports, non-trivial branching, or Code nodes, read
-`knowledge-base/reference/workflow-builder-guardrails.md` before writing code.
-Use it as the build checklist for source preservation, fan-out/fan-in,
-effect-specific gating, and list itemization.
+`${N8N_WORKSPACE_DIR}/knowledge-base/reference/workflow-builder-guardrails.md`
+before writing code. Use it as the build checklist for source preservation,
+fan-out/fan-in, effect-specific gating, and list itemization.
 
 When mapping downstream fields from an OpenAI node, read
-`knowledge-base/reference/open-ai-output-shape.md` (v2+ text/response uses
-`$json.output[0].content[0].text`; v1 text/message uses `$json.message.content`
-— not `$json.text`).
+`${N8N_WORKSPACE_DIR}/knowledge-base/reference/open-ai-output-shape.md`
+(v2+ text/response uses `$json.output[0].content[0].text`; v1 text/message
+uses `$json.message.content` — not `$json.text`; `json_object`/`json_schema`
+output is already a parsed object, never `JSON.parse` it). When mapping fields
+from an Anthropic node, read
+`${N8N_WORKSPACE_DIR}/knowledge-base/reference/anthropic-output-shape.md`
+(`$json.content` is an array of blocks — read text with
+`$json.content[0].text`, never treat `$json.content` as a string).
 
 ## Workflow-Level Error Workflows
 
@@ -150,9 +159,10 @@ Error workflows are per-target-workflow (`settings.errorWorkflow` must be the
 real workflow ID of a separate **published** workflow with an active Error
 Trigger — never a name, placeholder, `activeVersionId`, or local SDK id).
 n8n has no global error workflow setting; mention that only if the user asks
-about global behavior. Before building or attaching an error workflow, load
-this skill's `references/error-workflows.md` linked file and follow its
-build → publish → assign steps. Do not create one before the user opts in.
+about global behavior. Do not offer or build an error workflow before the
+primary workflow is published. Before building or attaching an error
+workflow, load this skill's `references/error-workflows.md` linked file and
+follow its build → publish → assign steps.
 
 ## Mandatory Process
 
@@ -316,9 +326,30 @@ decision after testing.
 - 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
-  `credentials(action="search-types")` with the service name. Prefer dedicated
-  credential types over generic auth; when generic auth is truly needed,
-  prefer `httpBearerAuth` over `httpHeaderAuth`.
+  `credentials(action="search-types")` with the service name. Pick in this
+  order:
+  1. A **dedicated credential type** whenever search finds one.
+  2. **Simplified Custom Auth** (`httpTemplatedCustomAuth`) for any service
+     without a dedicated type whose auth is expressible as header/query/body
+     values — this covers API keys and bearer tokens. When the provider
+     documents `Authorization: Bearer <token>`, do NOT reach for
+     `httpBearerAuth`: template it as
+     `{"headers":{"Authorization":"Bearer {{api_key}}"}}`. Set the HTTP
+     Request node's `genericAuthType` to `httpTemplatedCustomAuth`, and note
+     the provider's documented auth scheme (header format, key page, a cheap
+     authenticated GET endpoint) while you have the docs open: the setup call
+     needs them for the `credentialHints` recipe (see the post-build-flow
+     skill). Before that setup call, load the `credential-recipe-research`
+     skill and execute its lookup procedure — the recipe's template, docsUrl
+     and testUrl must come from pages fetched there, never from memory. Setup
+     rejects new plain generic credentials on HTTP Request nodes, so picking
+     Bearer/Header/Query/Custom Auth here means rebuilding — unless the user
+     explicitly asked for that plain type: an explicit user choice wins (setup
+     accepts it with `allowPlainGenericAuth: true`), don't argue with it.
+  3. Plain generic types (`httpBasicAuth`, `httpDigestAuth`, `oAuth2Api`, …)
+     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
@@ -445,12 +476,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`.
 
-- Code nodes need not always be necessary. You can use other n8n nodes to do the same thing. 
+- Code nodes need not always be necessary. You can use other n8n nodes to do the same thing.
 - 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:
-  `knowledge-base/reference/workflow-sdk-language.md`.
+  `${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.
 - Use `expr('{{ $json.field }}')` for n8n expressions. Variables must be inside
@@ -534,6 +565,20 @@ import {
 } from '@n8n/workflow-sdk';
 ```
 
+## 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.
+
+`.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 — an invalid
+group is rejected on save. When editing an existing workflow, keep existing `.group(...)` calls
+and their descriptions intact unless the change is about grouping.
+
 ## Workflow Rules
 
 Follow these rules strictly when generating workflows:

package/skills/workflow-builder/references/error-workflows.md

@@ -20,8 +20,8 @@ instance-wide error workflow behavior.
 
 When creating an error workflow to attach to another workflow:
 
-1. Build the target workflow first, then ask whether the user wants an error
-   workflow for it. Do not create one before the user opts in.
+1. Wait until the target workflow is published, then ask whether the user wants
+   an error workflow for it.
 2. Build the error workflow as a separate workflow. It starts with an Error
    Trigger and sends the notification the user requested.
 3. Publish the error workflow with `workflows(action="publish")` before setting