@n8n/node-cli 0.21.0 → 0.23.0

package/dist/commands/release.d.ts

@@ -2,6 +2,8 @@ import { Command } from '@oclif/core';
 export default class Release extends Command {
     static description: string;
     static examples: string[];
-    static flags: {};
+    static flags: {
+        publish: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
     run(): Promise<void>;
 }

package/dist/commands/release.js

@@ -7,10 +7,26 @@ const package_manager_1 = require("../utils/package-manager");
 const prompts_2 = require("../utils/prompts");
 class Release extends core_1.Command {
     async run() {
-        await this.parse(Release);
+        const { flags } = await this.parse(Release);
         (0, prompts_1.intro)(await (0, prompts_2.getCommandHeader)('n8n-node release'));
         const pm = (await (0, package_manager_1.detectPackageManager)()) ?? 'npm';
+        const isCI = Boolean(process.env.GITHUB_ACTIONS);
         try {
+            if (isCI) {
+                await (0, child_process_1.runCommand)(pm, ['run', 'lint'], { stdio: 'inherit' });
+                await (0, child_process_1.runCommand)(pm, ['run', 'build'], { stdio: 'inherit' });
+                await (0, child_process_1.runCommand)('npm', ['publish'], {
+                    stdio: 'inherit',
+                    env: {
+                        RELEASE_MODE: 'true',
+                        NPM_CONFIG_PROVENANCE: 'true',
+                    },
+                });
+                return;
+            }
+            if (flags.publish) {
+                prompts_1.log.warning('Publishing directly from your machine will not include npm provenance, which is required for n8n Cloud starting May 1 2026.\nConsider switching to GitHub Actions publishing. See: https://docs.n8n.io/integrations/creating-nodes/deploy/submit-community-nodes/');
+            }
             await (0, child_process_1.runCommand)('release-it', [
                 '-n',
                 '--git.requireBranch main',
@@ -24,6 +40,7 @@ class Release extends core_1.Command {
                 '--github.release',
                 `--hooks.before:init="${pm} run lint && ${pm} run build"`,
                 '--hooks.after:bump="npx auto-changelog -p"',
+                ...(flags.publish ? [] : ['--npm.publish=false']),
             ], {
                 stdio: 'inherit',
                 context: 'local',
@@ -31,6 +48,9 @@ class Release extends core_1.Command {
                     RELEASE_MODE: 'true',
                 },
             });
+            if (!flags.publish) {
+                prompts_1.log.info('The node was not published to NPM. Starting May 1 2026, n8n requires verified community nodes to be published via GitHub Actions with npm provenance. Learn more in our documentation: https://docs.n8n.io/integrations/creating-nodes/deploy/submit-community-nodes/');
+            }
         }
         catch (error) {
             if (error instanceof child_process_1.ChildProcessError) {
@@ -45,8 +65,34 @@ class Release extends core_1.Command {
         }
     }
 }
-Release.description = 'Publish your community node package to npm';
+Release.description = `Release your community node package.
+
+When running locally (default): Runs release-it to bump the version interactively, generate a changelog, commit, tag, push, and create a GitHub release. Does NOT publish to npm — use GitHub Actions for that.
+
+When running inside a GitHub Action: Detected automatically via the GITHUB_ACTIONS environment variable. Runs lint and build, then publishes with provenance enabled (NPM_CONFIG_PROVENANCE=true).
+
+Starting May 1 2026, n8n requires all community nodes to be published via GitHub Actions with npm provenance. Provenance lets anyone cryptographically verify that a package was built from a specific repository and commit.
+
+To set up GitHub Actions publishing:
+  1. Add a publish.yml workflow that triggers on version tags (e.g. v*.*.*).
+  2. Grant the publish job: permissions: { id-token: write, contents: read }
+  3. Use actions/setup-node with registry-url: 'https://registry.npmjs.org/'
+  4. Run \`npm run release\` as the publish step.
+
+For npm Trusted Publishing (no long-lived secrets):
+  On npmjs.com → package settings → Trusted Publishers → add your repo and workflow name.
+  Leave NPM_TOKEN unset; GitHub's OIDC token is used automatically.
+
+For token-based auth (fallback):
+  Add NPM_TOKEN to your repository secrets and pass it as NODE_AUTH_TOKEN.
+
+Full documentation: https://docs.n8n.io/integrations/creating-nodes/deploy/submit-community-nodes/`;
 Release.examples = ['<%= config.bin %> <%= command.id %>'];
-Release.flags = {};
+Release.flags = {
+    publish: core_1.Flags.boolean({
+        description: 'Publish to npm from your local machine (not recommended). Packages published this way will not include npm provenance and cannot become verified community nodes.',
+        default: false,
+    }),
+};
 exports.default = Release;
 //# sourceMappingURL=release.js.map

package/dist/commands/release.js.map

@@ -1 +1 @@
-{"version":3,"file":"release.js","sourceRoot":"","sources":["../../src/commands/release.ts"],"names":[],"mappings":";;AAAA,4CAAuC;AACvC,sCAAsC;AAEtC,0DAAuE;AACvE,8DAAgE;AAChE,8CAAoD;AAEpD,MAAqB,OAAQ,SAAQ,cAAO;IAK3C,KAAK,CAAC,GAAG;QACR,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAE1B,IAAA,eAAK,EAAC,MAAM,IAAA,0BAAgB,EAAC,kBAAkB,CAAC,CAAC,CAAC;QAElD,MAAM,EAAE,GAAG,CAAC,MAAM,IAAA,sCAAoB,GAAE,CAAC,IAAI,KAAK,CAAC;QAEnD,IAAI,CAAC;YACJ,MAAM,IAAA,0BAAU,EACf,YAAY,EACZ;gBACC,IAAI;gBACJ,0BAA0B;gBAC1B,8BAA8B;gBAC9B,uBAAuB;gBACvB,sBAAsB;gBACtB,cAAc;gBACd,WAAW;gBACX,YAAY;gBACZ,kGAAkG;gBAClG,kBAAkB;gBAClB,wBAAwB,EAAE,gBAAgB,EAAE,aAAa;gBACzD,4CAA4C;aAC5C,EACD;gBACC,KAAK,EAAE,SAAS;gBAChB,OAAO,EAAE,OAAO;gBAChB,GAAG,EAAE;oBACJ,YAAY,EAAE,MAAM;iBACpB;aACD,CACD,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,KAAK,YAAY,iCAAiB,EAAE,CAAC;gBACxC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;oBAClB,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;gBACzC,CAAC;qBAAM,CAAC;oBACP,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;gBAC/B,CAAC;YACF,CAAC;YACD,MAAM,KAAK,CAAC;QACb,CAAC;IACF,CAAC;;AA9Ce,mBAAW,GAAG,4CAA4C,CAAC;AAC3D,gBAAQ,GAAG,CAAC,qCAAqC,CAAC,CAAC;AACnD,aAAK,GAAG,EAAE,CAAC;kBAHP,OAAO"}
+{"version":3,"file":"release.js","sourceRoot":"","sources":["../../src/commands/release.ts"],"names":[],"mappings":";;AAAA,4CAA4C;AAC5C,sCAA6C;AAE7C,0DAAuE;AACvE,8DAAgE;AAChE,8CAAoD;AAEpD,MAAqB,OAAQ,SAAQ,cAAO;IAkC3C,KAAK,CAAC,GAAG;QACR,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAE5C,IAAA,eAAK,EAAC,MAAM,IAAA,0BAAgB,EAAC,kBAAkB,CAAC,CAAC,CAAC;QAElD,MAAM,EAAE,GAAG,CAAC,MAAM,IAAA,sCAAoB,GAAE,CAAC,IAAI,KAAK,CAAC;QACnD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QAEjD,IAAI,CAAC;YACJ,IAAI,IAAI,EAAE,CAAC;gBACV,MAAM,IAAA,0BAAU,EAAC,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;gBAC5D,MAAM,IAAA,0BAAU,EAAC,EAAE,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;gBAC7D,MAAM,IAAA,0BAAU,EAAC,KAAK,EAAE,CAAC,SAAS,CAAC,EAAE;oBACpC,KAAK,EAAE,SAAS;oBAChB,GAAG,EAAE;wBACJ,YAAY,EAAE,MAAM;wBACpB,qBAAqB,EAAE,MAAM;qBAC7B;iBACD,CAAC,CAAC;gBACH,OAAO;YACR,CAAC;YAED,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;gBACnB,aAAG,CAAC,OAAO,CACV,mQAAmQ,CACnQ,CAAC;YACH,CAAC;YAED,MAAM,IAAA,0BAAU,EACf,YAAY,EACZ;gBACC,IAAI;gBACJ,0BAA0B;gBAC1B,8BAA8B;gBAC9B,uBAAuB;gBACvB,sBAAsB;gBACtB,cAAc;gBACd,WAAW;gBACX,YAAY;gBACZ,kGAAkG;gBAClG,kBAAkB;gBAClB,wBAAwB,EAAE,gBAAgB,EAAE,aAAa;gBACzD,4CAA4C;gBAC5C,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC;aACjD,EACD;gBACC,KAAK,EAAE,SAAS;gBAChB,OAAO,EAAE,OAAO;gBAChB,GAAG,EAAE;oBACJ,YAAY,EAAE,MAAM;iBACpB;aACD,CACD,CAAC;YAEF,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;gBACpB,aAAG,CAAC,IAAI,CACP,uQAAuQ,CACvQ,CAAC;YACH,CAAC;QACF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,KAAK,YAAY,iCAAiB,EAAE,CAAC;gBACxC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;oBAClB,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;gBACzC,CAAC;qBAAM,CAAC;oBACP,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;gBAC/B,CAAC;YACF,CAAC;YACD,MAAM,KAAK,CAAC;QACb,CAAC;IACF,CAAC;;AAtGe,mBAAW,GAAG;;;;;;;;;;;;;;;;;;;;;mGAqBoE,CAAC;AAEnF,gBAAQ,GAAG,CAAC,qCAAqC,CAAC,CAAC;AAEnD,aAAK,GAAG;IACvB,OAAO,EAAE,YAAK,CAAC,OAAO,CAAC;QACtB,WAAW,EACV,mKAAmK;QACpK,OAAO,EAAE,KAAK;KACd,CAAC;CACF,CAAC;kBAhCkB,OAAO"}

package/dist/template/core.js

@@ -28,7 +28,7 @@ async function copyDefaultTemplateFilesToDestination(data) {
 }
 async function templateStaticFiles(data) {
     const files = await (0, fast_glob_1.default)('**/*.{md,json,yml}', {
-        ignore: ['tsconfig.json', 'tsconfig.build.json'],
+        ignore: ['tsconfig.json', 'tsconfig.build.json', 'AGENTS.md', 'CLAUDE.md', '.agents/*.md'],
         cwd: data.destinationPath,
         absolute: true,
         dot: true,

package/dist/template/core.js.map

@@ -1 +1 @@
-{"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/template/core.ts"],"names":[],"mappings":";;;;;AAgCA,wEASC;AAED,sFAMC;AAED,kDAkBC;AAED,wCAYC;AAnFD,0DAA6B;AAC7B,4DAAoC;AACpC,gEAAkC;AAClC,0DAA6B;AAE7B,oDAAiD;AA2B1C,KAAK,UAAU,8BAA8B,CACnD,QAA0B,EAC1B,IAAkB;IAElB,MAAM,IAAA,uBAAU,EAAC;QAChB,MAAM,EAAE,QAAQ,CAAC,IAAI;QACrB,WAAW,EAAE,IAAI,CAAC,eAAe;QACjC,MAAM,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC;KAChC,CAAC,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,qCAAqC,CAAC,IAAkB;IAC7E,MAAM,IAAA,uBAAU,EAAC;QAChB,MAAM,EAAE,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,0BAA0B,CAAC;QAC3D,WAAW,EAAE,IAAI,CAAC,eAAe;QACjC,MAAM,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC;KAChC,CAAC,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,mBAAmB,CAAC,IAAkB;IAC3D,MAAM,KAAK,GAAG,MAAM,IAAA,mBAAI,EAAC,oBAAoB,EAAE;QAC9C,MAAM,EAAE,CAAC,eAAe,EAAE,qBAAqB,CAAC;QAChD,GAAG,EAAE,IAAI,CAAC,eAAe;QACzB,QAAQ,EAAE,IAAI;QACd,GAAG,EAAE,IAAI;KACT,CAAC,CAAC;IAEH,MAAM,OAAO,CAAC,GAAG,CAChB,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACxB,MAAM,OAAO,GAAG,MAAM,kBAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACjD,MAAM,UAAU,GAAG,oBAAU,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAEzE,IAAI,UAAU,KAAK,OAAO,EAAE,CAAC;YAC5B,MAAM,kBAAE,CAAC,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACtC,CAAC;IACF,CAAC,CAAC,CACF,CAAC;AACH,CAAC;AAED,SAAgB,cAAc,CAC7B,QAA0B;IAE1B,OAAO;QACN,GAAG,QAAQ;QACX,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACnB,MAAM,qCAAqC,CAAC,IAAI,CAAC,CAAC;YAClD,MAAM,8BAA8B,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACrD,MAAM,mBAAmB,CAAC,IAAI,CAAC,CAAC;YAChC,MAAM,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;KACD,CAAC;AACH,CAAC"}
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/template/core.ts"],"names":[],"mappings":";;;;;AAgCA,wEASC;AAED,sFAMC;AAED,kDAkBC;AAED,wCAYC;AAnFD,0DAA6B;AAC7B,4DAAoC;AACpC,gEAAkC;AAClC,0DAA6B;AAE7B,oDAAiD;AA2B1C,KAAK,UAAU,8BAA8B,CACnD,QAA0B,EAC1B,IAAkB;IAElB,MAAM,IAAA,uBAAU,EAAC;QAChB,MAAM,EAAE,QAAQ,CAAC,IAAI;QACrB,WAAW,EAAE,IAAI,CAAC,eAAe;QACjC,MAAM,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC;KAChC,CAAC,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,qCAAqC,CAAC,IAAkB;IAC7E,MAAM,IAAA,uBAAU,EAAC;QAChB,MAAM,EAAE,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,0BAA0B,CAAC;QAC3D,WAAW,EAAE,IAAI,CAAC,eAAe;QACjC,MAAM,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC;KAChC,CAAC,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,mBAAmB,CAAC,IAAkB;IAC3D,MAAM,KAAK,GAAG,MAAM,IAAA,mBAAI,EAAC,oBAAoB,EAAE;QAC9C,MAAM,EAAE,CAAC,eAAe,EAAE,qBAAqB,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,CAAC;QAC1F,GAAG,EAAE,IAAI,CAAC,eAAe;QACzB,QAAQ,EAAE,IAAI;QACd,GAAG,EAAE,IAAI;KACT,CAAC,CAAC;IAEH,MAAM,OAAO,CAAC,GAAG,CAChB,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACxB,MAAM,OAAO,GAAG,MAAM,kBAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACjD,MAAM,UAAU,GAAG,oBAAU,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAEzE,IAAI,UAAU,KAAK,OAAO,EAAE,CAAC;YAC5B,MAAM,kBAAE,CAAC,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACtC,CAAC;IACF,CAAC,CAAC,CACF,CAAC;AACH,CAAC;AAED,SAAgB,cAAc,CAC7B,QAA0B;IAE1B,OAAO;QACN,GAAG,QAAQ;QACX,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACnB,MAAM,qCAAqC,CAAC,IAAI,CAAC,CAAC;YAClD,MAAM,8BAA8B,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACrD,MAAM,mBAAmB,CAAC,IAAI,CAAC,CAAC;YAChC,MAAM,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/template/templates/shared/default/.agents/credentials.md

@@ -0,0 +1,115 @@
+# Credentials
+
+Credentials are used to authenticate with external services and store
+sensitive values. They are encrypted at rest.
+
+## Credential class anatomy
+Credentials classes have:
+- `name` – machine name (used in nodes' `credentials` array)
+- `displayName` – human-readable label in the UI
+- `properties` – parameters (similar types to node properties)
+Sensitive properties should set `typeOptions.password = true`
+
+## Example
+Simplified WordPress example:
+```typescript
+export class WordpressApi implements ICredentialType {
+  name = 'wordpressApi';
+  displayName = 'Wordpress API';
+  documentationUrl = 'wordpress';
+
+  properties: INodeProperties[] = [
+    {
+      displayName: 'Username',
+      name: 'username',
+      type: 'string',
+      default: '',
+    },
+    {
+      displayName: 'Password',
+      name: 'password',
+      type: 'string',
+      typeOptions: {
+        password: true,
+      },
+      default: '',
+    },
+    {
+      displayName: 'Wordpress URL',
+      name: 'url',
+      type: 'string',
+      default: '',
+      placeholder: 'https://example.com',
+    },
+  ];
+
+  authenticate: IAuthenticateGeneric = {
+    type: 'generic',
+    properties: {
+      auth: {
+        username: '={{$credentials.username}}',
+        password: '={{$credentials.password}}',
+      },
+    },
+  };
+
+  test: ICredentialTestRequest = {
+    request: {
+      baseURL: '={{$credentials?.url}}/wp-json/wp/v2',
+      url: '/users',
+      method: 'GET',
+    },
+  };
+}
+```
+
+## Notes
+- `test` describes how to check if credentials are valid to show a
+  message to the user in the UI
+  - Not strictly required, but strongly recommended.
+- `authenticate` describes how to modify requests for declarative-style
+  nodes and the HTTP Request node.
+
+## Custom authenticate function
+You can also use a custom authenticate function:
+```typescript
+authenticate: IAuthenticate = async (credentials, requestOptions) => {
+  const values = (credentials.headers as { values: Array<{ name: string; value: string }> }).values;
+
+  const headers = values.reduce((acc, cur) => {
+    acc[cur.name] = cur.value;
+    return acc;
+  }, {} as Record<string, string>);
+
+  return {
+    ...requestOptions,
+    headers: {
+      ...requestOptions.headers,
+      ...headers,
+    },
+  };
+};
+```
+
+## OAuth2 credentials
+For services using OAuth2:
+- You usually do not need to define `test` or `authenticate` explicitly.
+- Instead, create credentials that extend `oAuth2Api`:
+```typescript
+export class MyServiceOAuth2Api implements ICredentialType {
+  name = 'myServiceOAuth2Api';
+  displayName = 'My Service OAuth2 API';
+  extends = ['oAuth2Api'];
+
+  properties: INodeProperties[] = [
+    // Add only the extra properties your service needs,
+    // e.g. scopes, custom URLs, etc.
+  ];
+}
+```
+- The base `oAuth2Api` handles the generic OAuth2 flow.
+- When allowing users to specify scopes in a custom OAuth2 credential,
+  make sure to follow n8n's internal rules (see n8n docs).
+- If you want to define scopes that the credentials will request, add a
+  property with `name: 'scope'`, `type: 'hidden'` and `default` field
+  that has your desired scopes

package/dist/template/templates/shared/default/.agents/nodes-declarative.md

@@ -0,0 +1,103 @@
+# Declarative nodes
+
+Preferred for most integrations that simply call external APIs.
+
+Also read `.agents/nodes.md` for shared node anatomy and conventions.
+
+## When to use
+- The integration is mostly simple HTTP/REST requests and responses
+- You can express the behavior by mapping parameters to
+  URL/query/body/headers
+
+If you need multiple dependent API calls, complex control flow, or heavy
+transformations, use programmatic-style instead (see
+`.agents/nodes-programmatic.md`).
+
+## What you define
+- Node `properties` (parameters)
+- `requestDefaults` (base URL, default headers)
+- `routing` on parameters and operations:
+  - Where to send the request (URL, method)
+  - How to map parameters to query/body/headers
+  - Optional pre-send and post-receive transformations
+
+## requestDefaults
+```typescript
+requestDefaults: {
+  baseURL: 'https://api.nasa.gov',
+  headers: {
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+  },
+},
+```
+
+## Parameter routing
+Example parameter with `routing`:
+```typescript
+{
+  displayName: 'Rover Name',
+  description: 'Choose which Mars Rover to get a photo from',
+  required: true,
+  name: 'roverName',
+  type: 'options',
+  options: [
+    { name: 'Curiosity', value: 'curiosity' },
+    { name: 'Opportunity', value: 'opportunity' },
+    { name: 'Perseverance', value: 'perseverance' },
+    { name: 'Spirit', value: 'spirit' },
+  ],
+  routing: {
+    request: {
+      method: 'GET',
+      url: '=/mars-photos/api/v1/rovers/{{$value}}/photos',
+    },
+  },
+  default: 'curiosity',
+  displayOptions: {
+    show: {
+      resource: ['marsRoverPhotos'],
+    },
+  },
+}
+```
+
+## Post-receive transformations
+You can modify response data with `routing.output.postReceive`:
+```typescript
+postReceive: [
+  {
+    type: 'setKeyValue',
+    properties: {
+      name: '={{$responseItem.modelName}}',
+      description: '={{$responseItem.modelArn}}',
+      value: '={{$responseItem.modelId}}',
+    },
+  },
+  {
+    type: 'sort',
+    properties: {
+      key: 'name',
+    },
+  },
+  async function (
+    this: IExecuteSingleFunctions,
+    data: INodeExecutionData[],
+    response: IN8nHttpFullResponse,
+  ): Promise<INodeExecutionData[]> {
+    // Custom transformation if needed
+    return data;
+  },
+]
+```
+
+## Pre-send transformations
+You can also use `routing.send.preSend` to change the request before
+sending (e.g. add custom headers or body transformations).
+
+## Guidelines
+- Prefer **declarative transformations** like `setKeyValue`, `sort`, etc
+  (there are other transformations that are not in the example).
+- Only add custom functions when necessary.
+- Declarative-style nodes only support **light versioning** (not full
+  versioning). See `.agents/versioning.md` for details.

package/dist/template/templates/shared/default/.agents/nodes-programmatic.md

@@ -0,0 +1,76 @@
+# Programmatic nodes
+
+Programmatic-style nodes implement an `execute` method and have full
+control over HTTP calls, loops, transformations, etc.
+
+Also read `.agents/nodes.md` for shared node anatomy and conventions.
+
+## When to use
+- You need multiple dependent API calls per node execution.
+- You need complex transformations or branching logic.
+- The API doesn't map cleanly into simple "one request per item"
+  patterns.
+
+If the integration is mostly simple HTTP/REST requests, prefer
+declarative-style instead (see `.agents/nodes-declarative.md`).
+
+If you choose programmatic-style, briefly explain **why**
+declarative-style won't work for this particular node.
+
+## Canonical execute pattern
+```typescript
+async execute(
+  this: IExecuteFunctions,
+): Promise<INodeExecutionData[][]> {
+  const items = this.getInputData();
+  const returnData: INodeExecutionData[] = [];
+
+  for (let i = 0; i < items.length; i++) {
+    try {
+      const resource = this.getNodeParameter('resource', i) as string;
+      const operation = this.getNodeParameter('operation', i) as string;
+
+      // Implement logic based on resource + operation
+      // Use this.helpers.httpRequest / httpRequestWithAuthentication, etc.
+      const responseData = {};
+
+      returnData.push({
+        json: responseData,
+        pairedItem: { item: i },
+      });
+    } catch (error) {
+      if (this.continueOnFail()) {
+        returnData.push({
+          json: {
+            error: (error as Error).message,
+          },
+          pairedItem: { item: i },
+        });
+        continue;
+      }
+
+      // Implement a check to see what error we have
+      const isApiError = true;
+      // Use NodeApiError for API-related errors
+      if (isApiError) {
+        throw new NodeApiError(this.getNode(), error as Error, { itemIndex: i });
+      }
+
+      // Use NodeOperationError for configuration/validation errors
+      throw new NodeOperationError(this.getNode(), error as Error, { itemIndex: i });
+    }
+  }
+
+  return [returnData];
+}
+```
+
+## Guidelines
+- Always get input items via `this.getInputData()`
+- Pass the correct item index as the second argument to
+  `getNodeParameter`
+- Handle errors using `NodeApiError` (for API failures) and
+  `NodeOperationError` (for operational/validation errors)
+- Support `continueOnFail()` to allow workflows to proceed when possible
+- Programmatic-style nodes support both **light and full versioning**.
+  See `.agents/versioning.md` for details.

package/dist/template/templates/shared/default/.agents/nodes.md

@@ -0,0 +1,178 @@
+# Building nodes
+
+## Overview
+Community nodes depend on `n8n-workflow` package that has different interfaces,
+classes and helper functions.
+
+Nodes can be built using one of two styles. To identify which style an
+existing node uses:
+- **Declarative-style** — no `execute` method. Instead, the node has
+  `requestDefaults` and parameters use `routing` (with `routing.request`,
+  `routing.send.preSend`, `routing.output.postReceive`, etc.) to
+  describe HTTP calls. See `.agents/nodes-declarative.md`
+- **Programmatic-style** — has an `async execute(this: IExecuteFunctions)`
+  method that manually calls APIs (via `this.helpers.httpRequest` /
+  `httpRequestWithAuthentication`), loops over items, and builds the
+  return array. See `.agents/nodes-programmatic.md`
+
+## Node description
+Nodes have `description` which defines:
+- `displayName`, `name`
+- `icon`, `group`, `version`
+- `inputs`, `outputs`
+- `properties`
+- Optional `subtitle`, `usableAsTool`, etc
+and an optional `execute` function for programmatic-style nodes.
+
+Example node description (simplified, using WordPress **only as an
+example**):
+```typescript
+description: INodeTypeDescription = {
+  displayName: 'Wordpress',
+  name: 'wordpress',
+  icon: 'file:wordpress.svg',
+  group: ['output'],
+  version: 1,
+  subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',
+  description: 'Consume Wordpress API',
+  defaults: {
+    name: 'Wordpress',
+  },
+  usableAsTool: true,
+  inputs: [NodeConnectionTypes.Main],
+  outputs: [NodeConnectionTypes.Main],
+  credentials: [
+    {
+        name: 'wordpressApi',
+        required: true,
+    },
+  ],
+  properties: [
+    {
+      displayName: 'Resource',
+      name: 'resource',
+      type: 'options',
+      noDataExpression: true,
+      options: [
+        { name: 'Post', value: 'post' },
+        { name: 'Page', value: 'page' },
+        { name: 'User', value: 'user' },
+      ],
+      default: 'post',
+    },
+    // other properties for specific resources and operations
+  ],
+};
+```
+
+## Description fields
+- `inputs` and `outputs` specify which inputs and outputs a node has.
+  - **Most nodes will need only 1 main input and 1 main output, unless
+    there is specific reason to have something else** (e.g. a node like
+    `If` that has a `true` and `false` outputs).
+- `usableAsTool`
+  - Set to `true` to allow n8n to use this node as a tool for the AI
+    agent.
+  - Set to `false` or omit this if node works heavily with **binary
+    data** which tools don't support
+- `properties` define the UI parameters
+  - Use the convention: first a **"Resource"** parameter and for each resource an **"Operation"** parameter.
+  - You can choose to not follow this convention **ONLY if it's not
+    applicable to the node you're developing** (i.e. data transformation
+    nodes, etc.)
+
+## Resource and operation pattern
+Example "operations":
+```typescript
+export const postOperations: INodeProperties[] = [
+  {
+    displayName: 'Operation',
+    name: 'operation',
+    type: 'options',
+    noDataExpression: true,
+    displayOptions: {
+      show: {
+        resource: ['post'],
+      },
+    },
+    options: [
+      { name: 'Create', value: 'create', description: 'Create a post', action: 'Create a post', },
+      { name: 'Get', value: 'get', description: 'Get a post', action: 'Get a post', },
+      { name: 'Get Many', value: 'getAll', description: 'Get many posts', action: 'Get many posts', },
+      { name: 'Update', value: 'update', description: 'Update a post', action: 'Update a post', },
+    ],
+    default: 'create',
+  },
+];
+```
+In your implementation:
+- Replace `post` and operation names with the **real resource and operations** for the target API.
+
+Example properties for "Create post" operation:
+```typescript
+export const postFields: INodeProperties[] = [
+  {
+    displayName: 'Title',
+    name: 'title',
+    type: 'string',
+    required: true,
+    default: '',
+    displayOptions: {
+      show: {
+        resource: ['post'],
+        operation: ['create'],
+      },
+    },
+    description: 'The title for the post',
+  },
+  {
+    displayName: 'Additional Fields',
+    name: 'additionalFields',
+    type: 'collection',
+    placeholder: 'Add Field',
+    default: {},
+    displayOptions: {
+      show: {
+        resource: ['post'],
+        operation: ['create'],
+      },
+    },
+    options: [
+      {
+        displayName: 'Content',
+        name: 'content',
+        type: 'string',
+        default: '',
+        description: 'The content for the post',
+      },
+      // Add more fields as needed for the real API
+    ],
+  },
+];
+```
+**Important**:
+- In a real node, replace `post`, `Title`, `Content`, etc. with the
+  **real names** from the target API.
+- Do not reuse these exact WordPress-specific field names unless the
+  node is actually for WordPress.
+- Remember that these examples are **incomplete** and n8n provides a lot
+  of options for defining properties. Refer to their docs, when in doubt
+
+## General guidelines
+- `icon` property can either be a string, which starts with `file:` and
+  contains a path to a PNG or an SVG. That path **is relative to the current
+  file**, you can reference icons in other folders: `file:../icon.svg`. If the
+  node has different icons for light and dark mode, provide an object for the
+  `icon` property: `{ light: 'file:icon.light.svg', dark: 'file:icon.dark.svg' }`
+- For operations that are supposed to return multiple items, like "Get Many
+  Posts", make sure you return those items, instead of single object that has
+  them. I.e. if you have an object like `{ data: [{ ... }, { ... }], count: 2 }`,
+  then return the items inside `data` array
+- If the API response is complex, you can add a "Simplify Output" toggle. When
+  it's `false` - return the raw response. If it's `true` - return a more
+  user-friendly response with only the essential data
+- For "Get Many" operations add "Return All" toggle that would return all of
+  the items, and a "Limit" parameter to limit the number of items, if "Return
+  All" is `false`
+- Don't forget to mark required properties as `required: true`
+- Use camelCase for property names