@n8n/instance-ai 1.19.3 → 1.20.1

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