@n8n/instance-ai 1.20.2 → 1.21.0

package/skills/one-off-operations/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: one-off-operations
+description: >-
+  Handles one-off operations: the request is a concrete effect that happens
+  once — export or copy data somewhere, a migration, a backfill, a cleanup —
+  with no trigger, schedule, or reuse intent. The workflow is the vehicle, not
+  the deliverable. Users rarely say "one-off"; infer it from the task's shape.
+  Load before building for such a request, or when a build-workflow result
+  contains postBuildFlow.reason "direct-one-off-build-succeeded". Do not load
+  for automations the user will run again — that is the normal build +
+  post-build-flow path.
+recommended_tools:
+  - build-workflow
+  - workflows
+  - executions
+  - ask-user
+  - verify-built-workflow
+---
+
+# One-Off Operations
+
+Use this skill when the request is a **one-off operation**: a concrete effect
+that needs to happen once, where a workflow is only the vehicle to make it
+happen. Typical shapes: "put this data in a spreadsheet", "copy these rows to
+X", "migrate/backfill/clean up Y".
+
+These instructions are in English, but user-visible text you write while
+following them stays in the user's conversation language.
+
+## Recognizing a one-off
+
+Users rarely label a task "one-off" — **infer it from the task's shape**, not
+from explicit phrasing. It is a one-off when the deliverable is a *state
+change*, not an automation:
+
+- The user asks for an effect on data that **already exists and is bounded** —
+  pasted into the chat, sitting in a named node, table, file, or sheet — rather
+  than data that will keep arriving over time.
+- The request is imperative about the here-and-now ("add these rows", "export
+  what's in X", "clean out the duplicates"), with no trigger, schedule, or
+  event vocabulary — no "when", "every", "whenever", "daily", "each time".
+- Nothing suggests the user wants to keep and rerun the workflow; the workflow
+  is never mentioned as the thing they want, only the outcome is.
+
+Explicit markers ("just this once", "I won't need this again") confirm the
+classification but are not required — most one-offs arrive without them.
+Signals against: trigger/schedule vocabulary, "from now on", a named event
+source, or any hint the user wants the automation itself. **When in doubt,
+treat the request as reusable** and follow the normal build flow — a reusable
+workflow that runs once is harmless; a one-off flow applied to an automation
+skips verification the user would have wanted.
+
+A one-off that touches external systems is still workflow-anchored (you cannot
+write to external services directly) — the intent changes the *post-build
+flow*, not the anchor.
+
+## The one-off flow
+
+1. **Build** the workflow with a **manual trigger** — always. A one-off is
+   never published, so an event trigger (webhook, form, schedule) would never
+   fire and only misleads. If the task genuinely needs an event source or a
+   future run time, it is not a one-off — reclassify it as a reusable
+   automation or a scheduled task and use the normal flow. Pass
+   `executionIntent: "one-off"` to `build-workflow`. This marks verification
+   as optional in the build outcome — no verification follow-up is scheduled,
+   and the completion criterion becomes a live run whose output you read back.
+2. **Setup** is unchanged: if the build outcome requires credential or value
+   setup, route it through `workflows(action="setup")` as usual. A one-off
+   still needs real credentials before it can run live.
+3. **Run live** with `executions(action="run")`. The run-approval card is the
+   user's consent gate — for a one-off, the live run IS what the user asked
+   for, so the usual "reserve live runs for explicit user requests" rule is
+   satisfied by the request itself. Do not run before setup is complete.
+4. **Read back before reporting.** After the run, inspect the actual output of
+   the effect nodes with `executions(action="get-node-output")` — the run
+   result data is truncated and not enough for quantitative claims. Check that
+   each write/effect node's input was the intended data (the rows you meant to
+   write), not an upstream node's API response. Report only numbers, columns,
+   and shapes you actually read. If the target system is cheap to read (e.g. a
+   read operation of the same node type), offer a read-back of the destination
+   as final confirmation.
+5. **Offer cleanup.** When the operation succeeded, ask whether to keep the
+   workflow for future reuse or delete it now that the job is done. Never
+   delete without asking. If the user keeps it, mention it stays unpublished
+   unless they say otherwise.
+
+## Optional pre-flight verification
+
+`verify-built-workflow` is available but **not required and never the
+completion criterion** for a one-off. Offer it before the live run only when
+the wiring is complex (branching, merges, non-trivial transformations) or the
+user is cautious about touching real data.
+
+When you do run it, present results honestly:
+
+- Say which nodes were **simulated** — external writes did not happen, and the
+  data flowing into simulated write nodes was NOT validated (their output is a
+  fabricated success fixture).
+- Never call the workflow "verified", "tested", or "working" from a simulated
+  pass alone, and never let it substitute for the live run and read-back.
+
+## Claiming success
+
+Do not make quantitative claims ("22 rows written", "columns matched") that
+you did not read back from actual execution output or the target system. A
+successful run status alone does not prove the *right data* was written — read
+the effect node's real output first. If you could not read it back, say so
+plainly and name what is unconfirmed.

package/skills/planned-task-runtime/SKILL.md

@@ -135,8 +135,9 @@ succeeds and any verified workflow dependency outcome has
 `workflows(action="setup")` with that workflowId before `complete-checkpoint`;
 the inline setup card appears automatically in the AI Assistant panel, so do not
 tell the user to open the editor, use the canvas, or click a Setup button. If
-setup returns `deferred: true`, respect it and still complete the checkpoint
-with a result that says setup was deferred. Do not call
+setup returns `deferred: true`, or reports `skippedByUser`, respect it and still
+complete the checkpoint with a result that says setup was deferred — never call
+setup again for a credential the user skipped. Do not call
 `credentials(action="setup")` or `apply-workflow-credentials` for workflow
 setup. Then call `complete-checkpoint(taskId, status, result)` **exactly once**
 to report the outcome (`status: "succeeded"` on pass, `"failed"` on a verification

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

@@ -20,6 +20,11 @@ especially when the build result contains `postBuildFlow.required: true`, or whe
 the current message contains `<workflow-verification-follow-up>` or
 `<workflow-setup-required>`.
 
+One-off builds (`postBuildFlow.reason: "direct-one-off-build-succeeded"`) hand
+off to the `one-off-operations` skill instead — verification is optional there
+and completion is a live run with read-back. If both sets of instructions are
+in context for a one-off build, the one-off flow wins.
+
 These instructions are in English, but user-visible text you write while
 following them stays in the user's conversation language.
 
@@ -45,6 +50,9 @@ is to call `workflows(action="setup")` with the `workflowId` from the payload. D
 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:
 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
+[Credentials the user skipped](#credentials-the-user-skipped).
 After setup completes or is applied, follow
 [Mocked verification live-test follow-up](#mocked-verification-live-test-follow-up)
 if the payload or prior verification evidence says mocked credentials,
@@ -148,6 +156,35 @@ 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.
 
+### Credentials the user skipped
+
+Skipping is remembered for the whole conversation. A setup result may carry
+`skippedByUser` (nodes and credential types the user passed on), and a build
+outcome may carry `setupRequirement.status === "not_required"` with
+`reason: "skipped-by-user"`. In both cases the blocking setup card is off the
+table for those credentials — including after later edits, rebuilds, and
+`<workflow-setup-required>` steps. Asking again is the single most common
+complaint about this flow.
+
+Instead, in your normal message:
+
+- name what stays unconfigured and what happens at runtime (e.g. "the Slack post
+  will fail until a channel is selected; the email still sends"),
+- offer to set it up whenever they want.
+
+Only once the user asks for a specific credential — "connect Slack now", "let's
+do the Slack setup", or picking it out of an offer you made — call
+`workflows(action="setup", reopenSkipped: ["slackApi"])`, naming just what they
+asked for so the rest stays skipped. A generic "yes" to an unrelated question is
+not an ask.
+
+Pass the `reopenWith` value the tool reported for that card, not the user's
+wording — a credential type for a credential card, a node name for one that was
+only missing a parameter. If nothing matches, setup answers with
+`unknown_reopen_target` and the list you can choose from; pick from it or tell
+the user what they named isn't part of this workflow. Don't fall back to
+re-offering, the user already asked.
+
 ## Publishing and testing
 
 **Publishing is never required for testing.** Both `executions(action="run")` and
@@ -156,6 +193,23 @@ 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.
 
+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
+for those nodes. A successful verification that used any of these is not
+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.
+
+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
+it with `executions(action="get", executionId)`. The user's statement alone is
+not execution evidence. A user-run execution satisfies the publishing gate only
+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
 `verify-built-workflow`, never with raw `executions(action="run")`.** It reuses
 the build outcome simulation plan, mocked credentials, and temporary pin data, so
@@ -181,6 +235,19 @@ 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):
+
+- 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.
+
 ## After build-workflow succeeds
 
 1. Read `workflowId`, `workItemId`, `triggerNodes`, `verificationReadiness`,
@@ -236,19 +303,24 @@ again.
 4. When `workflows(action="setup")` 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`, respect the user's
-   decision — do not retry with `credentials(action="setup")` or any other
-   setup tool. The user chose to set things up later.
+5. When `workflows(action="setup")` returns `deferred: true`, or reports
+   `skippedByUser`, or applies only part of the card, respect the user's
+   decision — do not retry with `credentials(action="setup")`, another
+   `workflows(action="setup")` call, or any other setup tool. `partial: true`
+   with `nodesStillNeedingSetup` is not permission to re-open the card in the
+   same turn: report what remains as described in
+   [Credentials the user skipped](#credentials-the-user-skipped).
 6. After setup completes or is applied, follow
    [Mocked verification live-test follow-up](#mocked-verification-live-test-follow-up)
    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.
+   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.
 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.
+   publish. Never publish automatically or proactively offer publishing before
+   the publish-readiness requirement above is met.
 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
@@ -314,21 +386,33 @@ If the user says yes:
 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. Do not run the live test automatically.
+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 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 live test fails, treat the workflow as unresolved and do
+not offer publishing. If the user declines or defers, state what remains
+untested, do not claim live end-to-end verification, and do not offer
+publishing.
 
 ## Claiming success
 
 Do not tell the user a workflow is "fixed", "verified", "tested", "working", or
-has "no errors" unless this turn has a passing `verify-built-workflow` or
-`executions(action="run")` that exercised the path being claimed. A successful
-`build-workflow`/save, a static `workflows(action="validate")`, or your own
-narration are NOT execution evidence. For a produced artifact (a file, generated
-document, or Code-node output), read the real output before calling it complete;
-do not infer correctness from the fact that a node ran. If you could not run the
+has "no errors" unless you have a passing `verify-built-workflow`,
+`executions(action="run")`, or 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
+your own narration are NOT execution evidence. For a produced artifact (a file,
+generated document, or Code-node output), read the real output before calling it
+complete; do not infer correctness from the fact that a node ran. The same
+applies to rows or records written to an external system: never make quantitative
+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
 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/workflow-builder/SKILL.md

@@ -70,6 +70,13 @@ For repairs, prefer editing the workspace file directly with file tools
 (`workspace_str_replace_file`) and calling `build-workflow` again with the same
 `filePath`.
 
+When a repair adds a node into an existing chain (an ensure-the-target-exists
+step, a dedupe, a notification), check what the downstream node reads before
+wiring it in-line — workflow rule 7 applies: an inserted write/create node
+replaces the payload flowing into the next node with its own API response.
+Branch it in parallel, reorder it upstream of the data producer, or make the
+downstream node reference the data node explicitly.
+
 ## Escalation
 
 If the service or workflow shape is clear, never stop before the first
@@ -279,7 +286,8 @@ When this turn is responsible for verification, do not stop after a successful
 save. The job is done when one of these is true:
 
 - The workflow is verified by structured tool evidence.
-- Setup is required and `workflows(action="setup")` has been routed or deferred.
+- Setup is required and `workflows(action="setup")` has been routed or deferred,
+  or the only setup left is for credentials the user skipped earlier.
 - A remediation guard says `shouldEdit: false`.
 - You are blocked after one repair attempt per unique failure signature.
 
@@ -476,7 +484,8 @@ 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.
+- 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.
 - 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
@@ -492,6 +501,15 @@ every reported error and warning before calling `build-workflow`.
   configs and from `sticky()` options alike. Positions are auto-calculated, and
   the saved workflow's own layout is restored on save, so nothing you drop here
   is lost. Leaving some in place is worse than dropping all of them.
+- When editing a pre-loaded workflow, keep every `config.id` value **exactly** as
+  `get-as-code` produced it, on the node it came with. `id` is the node's
+  permanent identity in n8n — execution logs, poll cursors, deduplication state
+  and the version diff are all keyed on it. Rename a node freely; the `id` stays.
+  Move it, rewire it, change its parameters — the `id` stays. Never invent, edit,
+  renumber or reuse an `id`, and never copy one from a template, another workflow
+  or another node. **Omit `id` entirely for any node you are adding** — one is
+  assigned on save. Deleting a node means deleting its `id` line with it. This is
+  the opposite of `position`: drop every `position`, keep every `id`.
 - Use `placeholder('hint')` directly as the parameter value. Do not wrap
   placeholders in `expr()`, objects, or arrays unless the node definition
   explicitly expects an object and the placeholder is the direct value of one
@@ -624,6 +642,15 @@ Follow these rules strictly when generating workflows:
    match time units broadly (day/days, week/weeks…), and give every classifier
    an explicit fallback bucket — a one-phrasing regex silently misroutes every
    other phrasing.
+7. Inserting a node into an existing connection A→B changes what B receives:
+   `$json` and auto-mapped fields in B now read the inserted node's output, not
+   A's. Write/create/send nodes output their **API response** (ids, metadata,
+   `ok` flags), never the data that flowed into them — so inserting one
+   in-line (e.g. an ensure-the-target-exists step before a write) silently
+   replaces the payload with metadata. Keep the data path intact instead:
+   branch the inserted node in parallel from the data producer, reorder it
+   upstream of the data producer, or have B reference `$('Data Node')`
+   explicitly.
 
 ## Tool Naming Rules
 

package/dist/tools/nodes/node-search-engine.d.ts

@@ -1,21 +0,0 @@
-import type { NodeSearchResult, SearchableNodeType } from './node-search-engine.types';
-export declare const SCORE_WEIGHTS: {
-    readonly CONNECTION_EXACT: 100;
-    readonly CONNECTION_IN_EXPRESSION: 50;
-};
-export declare class NodeSearchEngine {
-    private readonly nodeTypes;
-    private readonly nameSearchCache;
-    private readonly connectionSearchCache;
-    constructor(nodeTypes: SearchableNodeType[]);
-    private fuzzySearchNodes;
-    searchByName(query: string, limit?: number): NodeSearchResult[];
-    searchByConnectionType(connectionType: string, limit?: number, nameFilter?: string): NodeSearchResult[];
-    formatResult(result: NodeSearchResult): string;
-    getSubnodesForConnectionType(connectionType: string): string[];
-    getRelatedSubnodeIds(nodeIds: string[], excludeNodeIds: Set<string>): Set<string>;
-    getNodeType(nodeId: string): SearchableNodeType | undefined;
-    private getConnectionScore;
-    static isAiConnectionType(connectionType: string): boolean;
-    static getAiConnectionTypes(): readonly string[];
-}