@n8n-as-code/n8nac 2.0.0-next.56

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# @n8n-as-code/n8nac
+
+## [2026.5.0](https://github.com/EtienneLescot/n8n-as-code/compare/@n8n-as-code/n8nac@v2026.4.1...@n8n-as-code/n8nac@v2026.5.0) (2026-03-31)
+
+### Features
+
+* add integration tests for CLI instance management and update AI functionality ([f3131de](https://github.com/EtienneLescot/n8n-as-code/commit/f3131de6f74c28875e8264c5ac929291046cee7b))
+* add agent-friendly instance management flows ([3d63571](https://github.com/EtienneLescot/n8n-as-code/commit/3d63571e1c5243e58a51a93b0c0b927946be86bf))
+* extend instance library to plugins docs and integration tests ([3f97f54](https://github.com/EtienneLescot/n8n-as-code/commit/3f97f54869ddf99cd8c9b3837cf7ec94d35dccb5))
+
+### Bug Fixes
+
+* address PR review feedback for instance config flows ([06f0298](https://github.com/EtienneLescot/n8n-as-code/commit/06f029828969da738b154cf65f64461c8bda5571))
+
+### Documentation
+
+* align config flows across product surfaces ([d961f78](https://github.com/EtienneLescot/n8n-as-code/commit/d961f783e1b95022acdbf3f13ca0982520026619))
+
+## [2026.4.1](https://github.com/EtienneLescot/n8n-as-code/compare/@n8n-as-code/n8nac@v2026.4.0...@n8n-as-code/n8nac@v2026.4.1) (2026-03-30)
+
+### Bug Fixes
+
+* make agent workflow testing and sync state resilient ([5850d07](https://github.com/EtienneLescot/n8n-as-code/commit/5850d07d8136ffb24c5106c7391b2d49d4dd2e5d))
+
+## [2026.4.0](https://github.com/EtienneLescot/n8n-as-code/compare/@n8n-as-code/n8nac@v2026.3.1...@n8n-as-code/n8nac@v2026.4.0) (2026-03-17)
+
+### Features
+
+* scope OpenClaw n8n context via bundled skill ([abf1501](https://github.com/EtienneLescot/n8n-as-code/commit/abf15012e2d5f5cab9bd04fc930fe27b4fd48802))
+
+### Bug Fixes
+
+* tighten getChildEnv() allowlist + add unit tests ([2846414](https://github.com/EtienneLescot/n8n-as-code/commit/28464143bfb3390d51db6303bb377783a2994cfb))
+* prevent credential forwarding to child processes via explicit env filtering ([283d005](https://github.com/EtienneLescot/n8n-as-code/commit/283d0059a1fcf33d70ec27d4485333e4441be240))
+* refresh generated OpenClaw skill output ([b1f1eac](https://github.com/EtienneLescot/n8n-as-code/commit/b1f1eacb7bf1a988e19f42bdc86bb9088691cbae))
+* generate OpenClaw skill from shared SSOT ([b6678bd](https://github.com/EtienneLescot/n8n-as-code/commit/b6678bd45c7da338b5ea4b6d5082be8b6d5105d4))
+
+## [2026.3.1](https://github.com/EtienneLescot/n8n-as-code/compare/@n8n-as-code/n8nac@v2026.3.0...@n8n-as-code/n8nac@v2026.3.1) (2026-03-13)
+
+### Documentation
+
+* align editor and integration release messaging ([e1d6198](https://github.com/EtienneLescot/n8n-as-code/commit/e1d6198c3c6c942afe024f34b4ad419005ed991c))

package/README.md

@@ -0,0 +1,170 @@
+# @n8n-as-code/n8nac
+
+**OpenClaw access to the standard `n8n-as-code` skills and workflow stack.**
+
+Use OpenClaw to build, update, validate, and manage n8n workflows with the same `n8nac` CLI and AI context model used across the wider `n8n-as-code` project.
+
+## v2 migration note
+
+Version 2 removes the facade-specific OpenClaw runtime tool path. The plugin now delegates instance, auth, project, tunnel, credential, and presentation operations to `n8n-manager`, while workspace sync context is stored through `n8nac workspace` in `~/.openclaw/n8nac/`.
+
+## Install
+
+```bash
+openclaw plugins install @n8n-as-code/n8nac
+```
+
+If you previously installed `@n8n-as-code/openclaw-plugin`, remove the old install first so OpenClaw re-registers the plugin cleanly under `n8nac`:
+
+```bash
+openclaw plugins uninstall n8nac
+openclaw plugins install @n8n-as-code/n8nac
+```
+
+Restart the gateway. Runtime access, project selection, workspace sync, and
+workflow guidance are handled by the bundled `n8n-manager` and `n8n-architect`
+skills through their documented shell commands.
+
+## Usage
+
+Once the runtime and workspace are configured through the skills, talk to OpenClaw:
+
+> "Create an n8n workflow that sends a Slack message when a GitHub issue is opened"
+
+> "Pull workflow 42 and add an error handler to it"
+
+> "What operations does the Google Sheets node support?"
+
+The plugin keeps its prompt hook lightweight. OpenClaw uses the bundled
+`n8n-manager` and `n8n-architect` skills for explicit n8n sessions. Those
+skills use the same shell commands as Claude, Codex, Cursor, VS Code, and other
+agents: `n8n-manager ...` and `n8nac ...`.
+
+## CLI commands
+
+| Command | Description |
+|---|---|
+| `openclaw n8nac:status` | Show workspace status |
+
+## Workspace
+
+All files live in `~/.openclaw/n8nac/`:
+
+```
+~/.openclaw/n8nac/
+  n8nac-config.json     ← workspace project/sync overrides only
+  AGENTS.md             ← lightweight agent bootstrap (written by n8nac update-ai)
+  .agents/skills/       ← portable n8n-manager + n8n-architect skills
+  workflows/            ← .workflow.ts files (your n8n workflows)
+```
+
+Instances and API keys are not stored in this workspace. They live in the global
+`n8n-manager` configuration under `~/.n8n-manager`.
+
+## Agent skills
+
+The plugin does not register a facade-specific agent tool. Agents should use
+the portable skills and shell commands directly:
+
+```bash
+n8n-manager instances list
+n8nac workspace status --json
+n8nac list
+n8nac pull <workflowId>
+n8nac push <path-to-workflow.workflow.ts> --verify
+n8nac skills node-info <nodeName>
+```
+
+`AGENTS.md` is not a configuration source of truth. It points agents to the
+local skills and to `n8nac workspace status --json`, which resolves the
+effective context through the backend.
+
+## Local development
+
+This section covers how to load the plugin from source during development so
+that changes take effect immediately without an npm publish cycle.
+
+### 1. Link the plugin directory
+
+OpenClaw's `--link` flag registers a local path instead of installing a copy.
+jiti is used to run TypeScript directly, so no build step is needed.
+
+```bash
+openclaw plugins install --link \
+  /home/etienne/repos/n8n-as-code/plugins/openclaw/n8n-as-code
+```
+
+What this does:
+- Adds the path to `plugins.load.paths` in `~/.openclaw/openclaw.json`
+- Registers a `source: "path"` install record bound to the plugin ID `n8nac`
+- No file copy — OpenClaw loads `index.ts` directly from the source tree
+
+### 2. Verify the plugin is registered
+
+```bash
+openclaw plugins info n8nac
+```
+
+You should see status `loaded`, the bundled skills, and the `n8nac:status` CLI
+command. The plugin intentionally does not register a
+facade-specific agent tool.
+
+### 3. Configure runtime access through skills
+
+```bash
+n8n-manager auth set --url <url> --api-key-stdin
+n8n-manager projects list
+n8n-manager projects select <project-id-or-name>
+n8nac workspace set-sync-folder workflows
+n8nac update-ai
+```
+
+The OpenClaw plugin does not own setup orchestration. It exposes lightweight
+context and lets the portable skills manage global instances, secrets, projects,
+workspace overrides, `AGENTS.md`, and `.agents/skills`.
+
+### 4. Iterate on the code
+
+- Edit any `.ts` file in `plugins/openclaw/n8n-as-code/`
+- **Restart the gateway** to reload: `openclaw stop && openclaw start` (or the
+  equivalent service restart on your setup)
+- The `before_prompt_build` hook and CLI commands reload on
+  gateway start
+
+### 5. Check gateway logs
+
+```bash
+tail -f ~/.openclaw/logs/openclaw-$(date +%Y-%m-%d).log | grep n8nac
+```
+
+The plugin prefixes all `api.logger` calls with `[n8nac]`.
+
+### 6. Inspect the n8nac workspace
+
+```
+~/.openclaw/n8nac/
+  n8nac-config.json   ← workspace project/sync overrides only
+  AGENTS.md           ← lightweight bootstrap written by update-ai
+  .agents/skills/     ← portable skills written by update-ai
+  workflows/          ← .workflow.ts files
+```
+
+To reset and redo setup from scratch:
+
+```bash
+rm -rf ~/.openclaw/n8nac
+n8nac workspace set-sync-folder workflows
+n8nac update-ai
+```
+
+### 7. Unlink when done
+
+```bash
+openclaw plugins uninstall n8nac
+```
+
+---
+
+## Source
+
+Part of the [n8n-as-code](https://github.com/EtienneLescot/n8n-as-code) monorepo.

package/index.ts

@@ -0,0 +1,137 @@
+import { accessSync, constants, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { N8N_FACADE_SETUP_MODES } from "@n8n-as-code/workflow-core";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { registerN8nAcCli } from "./src/cli.js";
+import { getWorkspaceDir, isWorkspaceInitialized, readWorkspaceBinding } from "./src/workspace.js";
+
+// ---------------------------------------------------------------------------
+// Lightweight prompt context
+// ---------------------------------------------------------------------------
+
+const SETUP_MODE_CONTEXT = N8N_FACADE_SETUP_MODES
+  .map((mode) => `- \`${mode.id}\`: ${mode.description}`)
+  .join("\n");
+
+const BOOTSTRAP_CONTEXT = `\
+## n8n-as-code — Bootstrap
+
+The n8n-as-code plugin is installed but the workspace has not been initialized yet.
+
+**Tell the user:**
+> "To start building n8n workflows, choose whether I should connect to your existing n8n access, let n8n-manager prepare runtime access, or stay in generation-only mode."
+
+Supported facade runtime modes:
+${SETUP_MODE_CONTEXT}
+
+For agent-driven flows, use the installed \`n8n-manager\` and \`n8n-architect\`
+skills and their documented shell commands. Instance/auth/project management
+belongs to \`n8n-manager\`; context-root overrides and workflow sync belong
+to \`n8nac workspace\` and the n8n-as-code skills.
+`;
+
+function buildStatusHeader(workspaceDir: string): string {
+  const cfg = readWorkspaceBinding(workspaceDir);
+  return [
+    "## n8n-as-code Context Root Status",
+    "",
+    "**The context root is initialized. Do NOT infer effective n8n config from this prompt.**",
+    "",
+    `- Context root: \`${workspaceDir}\``,
+    `- Local overrides file: \`${join(workspaceDir, "n8nac-config.json")}\``,
+    `- Bootstrap file: \`${join(workspaceDir, "AGENTS.md")}\``,
+    "",
+    "Before n8n work, run `n8nac workspace status --json` from the context root and use the backend-resolved result.",
+    cfg.activeInstanceId || cfg.projectId || cfg.projectName || cfg.syncFolder
+      ? "The local overrides file exists, but n8n-manager plus n8nac backend resolution remains the only source of effective state."
+      : "The local overrides file is present but incomplete.",
+  ].join("\n");
+}
+
+function hasAgentsContext(workspaceDir: string): boolean {
+  const agentsPath = join(workspaceDir, "AGENTS.md");
+  try {
+    accessSync(agentsPath, constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function buildPromptContext(workspaceDir: string): string {
+  if (!isWorkspaceInitialized(workspaceDir)) {
+    return BOOTSTRAP_CONTEXT;
+  }
+
+  const agentsPath = join(workspaceDir, "AGENTS.md");
+  const guidanceLines = hasAgentsContext(workspaceDir)
+    ? [
+        "",
+        "Detailed workflow-authoring guidance is intentionally scoped to the `n8n-architect` skill.",
+        "Only use that deeper n8n workflow context when the request is clearly about n8n workflow work.",
+        `When that happens, read \`${agentsPath}\` and the local \`${join(workspaceDir, ".agents", "skills")}\` skills.`,
+      ]
+    : [
+        "",
+        "Detailed workflow-authoring guidance is intentionally scoped to the `n8n-architect` skill, but the generated workspace AI context file (`AGENTS.md`) is missing.",
+        "If the user starts explicit n8n workflow work, use the n8n-manager and n8n-architect skills to configure access and regenerate `AGENTS.md` with `npx --yes n8nac update-ai` when needed.",
+      ];
+
+  return [
+    buildStatusHeader(workspaceDir),
+    ...guidanceLines,
+    "",
+    "For unrelated requests, ignore this plugin context.",
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+
+const n8nAcPlugin = {
+  id: "n8nac",
+  name: "n8n-as-code",
+  description:
+    "Create and manage n8n workflows from OpenClaw using n8n-as-code (n8nac). " +
+    "Guides through workspace initialization, workflow CRUD, and AI-powered node schema lookup.",
+
+  register(api: OpenClawPluginApi) {
+    const workspaceDir = getWorkspaceDir();
+
+    // Ensure the plugin workspace directory always exists.
+    mkdirSync(workspaceDir, { recursive: true });
+
+    // -- Context injection ---------------------------------------------------
+    // Keep default context lightweight; full workflow-authoring guidance lives
+    // in the bundled skills and the context-root AGENTS.md file.
+    api.on("before_prompt_build", () => {
+      return { prependContext: buildPromptContext(workspaceDir) };
+    });
+
+    // -- CLI status ----------------------------------------------------------
+    api.registerCli(
+      ({ program }) => registerN8nAcCli({ program, workspaceDir }),
+      { commands: ["n8nac:status"] },
+    );
+
+    // -- Service -------------------------------------------------------------
+    api.registerService({
+      id: "n8nac-context",
+      start: async () => {
+        if (isWorkspaceInitialized(workspaceDir)) {
+          if (hasAgentsContext(workspaceDir)) {
+            api.logger.info("[n8nac] Workspace ready — lightweight prompt context enabled; n8n skill available.");
+          } else {
+            api.logger.warn("[n8nac] Workspace ready, but AGENTS.md is missing or unreadable.");
+          }
+        } else {
+          api.logger.info("[n8nac] Workspace not initialized. Use the n8n-manager and n8n-architect skills to configure it.");
+        }
+      },
+      stop: async () => {},
+    });
+  },
+};
+
+export default n8nAcPlugin;

package/openclaw.plugin.json

@@ -0,0 +1,19 @@
+{
+  "id": "n8nac",
+  "name": "n8n-as-code",
+  "description": "Create and manage n8n workflows from OpenClaw. Uses n8n-manager for runtime setup and n8nac for workspace/workflow tools.",
+  "skills": [
+    "skills"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the n8n-as-code integration"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@n8n-as-code/n8nac",
+  "version": "2.0.0-next.56",
+  "description": "OpenClaw plugin for n8n-as-code — create and manage n8n workflows from OpenClaw",
+  "keywords": [
+    "n8n",
+    "workflow",
+    "automation",
+    "openclaw",
+    "openclaw-plugin",
+    "n8nac"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EtienneLescot/n8n-as-code.git",
+    "directory": "plugins/openclaw/n8n-as-code"
+  },
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "npm run typecheck",
+    "clean": "rm -rf node_modules/.vitest",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@n8n-as-code/workflow-core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "openclaw": "^2026.2.26",
+    "typescript": "^5.8.0",
+    "vitest": "^1.6.1"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "README.md",
+    "index.ts",
+    "openclaw.plugin.json",
+    "skills/",
+    "src/",
+    "tsconfig.json"
+  ],
+  "peerDependencies": {
+    "openclaw": ">=2026.2.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/skills/n8n-architect/SKILL.md

@@ -0,0 +1,379 @@
+---
+name: n8n-architect
+description: Use when the user explicitly wants to create, edit, validate, sync, or troubleshoot n8n workflows, asks about n8n nodes or automation, or wants to use n8n-as-code in the current context root.
+---
+
+# n8n Architect
+
+Use this skill for workflow engineering. Use the `n8n-manager` skill for instance, auth, runtime, tunnel, project-default, credential infrastructure, or workflow presentation work.
+
+## Context Root Protocol
+
+- Treat the current context root as the directory containing `n8nac-config.json`, `AGENTS.md`, `.agents/skills`, and the workflow sync folder.
+- Generated context root hint: not embedded. Use the shell launch directory or the workspace path explicitly given by the user.
+- Before any n8n work, first run `npx --yes n8nac update-ai` from the context root, then read `AGENTS.md`. `update-ai` is designed to create or refresh the n8n-as-code block without destroying existing user or agent instructions.
+- Use the exact `n8nac command` and `n8n-manager command` listed in `AGENTS.md`. Those context-root commands override the portable examples in this skill.
+- Run every `npx --yes n8nac workspace ...`, `npx --yes n8nac list`, `pull`, `push`, `validate`, `test`, and `update-ai` command from the context root unless the user explicitly gives another context root.
+- `AGENTS.md` is bootstrap context only, not a source of configuration truth.
+- Do not infer instance, project, sync folder, or workflow directory from `AGENTS.md`.
+- Before n8n work, resolve the effective context from the backend:
+
+```bash
+npx --yes n8nac workspace status --json
+```
+
+- Use the returned `workflowDir` for workflow files. Do not reconstruct it from `syncFolder`, `instanceIdentifier`, or `projectName`.
+- Never write `n8nac-config.json` by hand. Use `npx --yes n8nac workspace ...` commands.
+
+## Bootstrap Order
+
+1. `cd` to the context root.
+2. Run `npx --yes n8nac update-ai`, then read `AGENTS.md`.
+3. Run `npx --yes n8nac workspace status --json`.
+4. If the context root is not ready, inspect instances with `n8n-manager instances list`.
+5. Reuse an existing instance when suitable.
+6. If no suitable instance exists, stop and ask the user whether they want to reuse/configure an existing instance, create a managed local n8n instance, or connect an existing/remote n8n instance. Do not create infrastructure by default. If the user chooses a managed local instance, ask separately whether they want a public tunnel.
+7. Ask for host/API key only for an explicitly remote or existing n8n instance.
+8. Configure context-root overrides with:
+
+```bash
+npx --yes n8nac workspace pin-instance --instance-id <id>
+npx --yes n8nac workspace set-sync-folder workflows
+npx --yes n8nac workspace set-project --project-id <id> --project-name <name>
+```
+
+For self-hosted n8n instances where the projects API is unavailable or returns 401/403, do not keep retrying project discovery. Use the standard personal project override unless the user gave another project:
+
+```bash
+npx --yes n8nac workspace set-project --project-id personal --project-name Personal
+```
+
+9. Run `npx --yes n8nac update-ai` after changing context-root overrides when the facade does not do it automatically.
+
+## Sync Discipline
+
+- Pull before reading or modifying an existing workflow.
+- Push after every modification.
+- Use `list` to inspect workflow IDs, file paths, and sync status.
+
+```bash
+npx --yes n8nac list
+npx --yes n8nac pull <workflowId>
+npx --yes n8nac push <path-to-workflow.workflow.ts> --verify
+```
+
+- `push` requires the full workflow file path, either absolute or context-root-relative. Do not pass a bare filename.
+- For a new workflow, create the file inside the `workflowDir` returned by `workspace status --json`, then confirm it with `npx --yes n8nac list --local`.
+- If push/pull reports a conflict, use explicit resolution commands. Do not overwrite remote changes blindly.
+- `pull` and conflict resolution operate on a single workflow ID.
+- `list` is the lightweight command that covers all workflows at once.
+- If you skip pull, a later push can be rejected by optimistic concurrency control when the remote changed.
+
+## Conflict Handling
+
+If push or pull reports a conflict, stop and inspect the conflict. Use explicit resolution commands only after choosing the intended direction:
+
+```bash
+npx --yes n8nac resolve <workflowId> --mode keep-current
+npx --yes n8nac resolve <workflowId> --mode keep-incoming
+```
+
+- `keep-current` force-pushes the local version.
+- `keep-incoming` force-pulls the remote version.
+- Never silently force-push over a remote change.
+
+## Schema-First Research
+
+Never guess n8n node parameters.
+
+```bash
+npx --yes n8nac skills examples search "<workflow pattern>"
+npx --yes n8nac skills search "<node or capability>"
+npx --yes n8nac skills node-info <nodeName>
+npx --yes n8nac skills validate <workflow.workflow.ts>
+```
+
+- Use exact node `type` and valid `typeVersion` values from `node-info`.
+- Use exact resource, operation, option, and parameter names from schema output.
+- Do not invent parameters, operations, credential types, or CLI flags.
+- Treat schema output as the absolute source of truth even if examples or memory disagree.
+- Prefer the highest valid `typeVersion` returned by schema output.
+- For fixed collections such as Switch/If rules, Wait form fields, or nested options, read the full `node-info` output before writing values.
+
+## Knowledge Commands
+
+Use these commands instead of guessing:
+
+```bash
+npx --yes n8nac skills search "<node or capability>"
+npx --yes n8nac skills node-info <nodeName>
+npx --yes n8nac skills node-schema <nodeName>
+npx --yes n8nac skills docs "<topic>"
+npx --yes n8nac skills guides "<topic>"
+npx --yes n8nac skills examples search "<workflow pattern>"
+npx --yes n8nac skills examples info <id>
+npx --yes n8nac skills examples download <id>
+```
+
+- Start with `examples search` when the user asks for a common automation pattern.
+- Use examples to learn patterns, not as authority over current node schemas.
+- If a command or flag is unfamiliar, run `npx --yes n8nac <subcommand> --help`; do not invent flags.
+
+## Workflow Authoring Rules
+
+- Use TypeScript decorators from `@n8n-as-code/transformer`.
+- Regular nodes connect with `source.out(0).to(target.in(0))`.
+- AI sub-nodes connect with `.uses()`, never `.out().to()`.
+- `ai_tool` and `ai_document` connections are arrays: `ai_tool: [this.Tool.output]`.
+- Other AI connection types are single refs, such as `ai_languageModel: this.Model.output`.
+- Check `node-info` for connection-dependent boolean flags before declaring `.uses()` connections.
+
+Every `.workflow.ts` file starts with a `<workflow-map>` block. Read that map first, locate the property name you need, then read only the relevant class section.
+
+### Minimal Workflow Structure
+
+```typescript
+import { workflow, node, links } from '@n8n-as-code/transformer';
+
+@workflow({
+  name: 'Workflow Name',
+  active: false
+})
+export class MyWorkflow {
+  @node({
+    name: 'Descriptive Name',
+    type: '/* exact type from node-info */',
+    version: 4,
+    position: [250, 300]
+  })
+  MyNode = {
+    /* parameters from node-info */
+  };
+
+  @node({
+    name: 'Next Node',
+    type: '/* exact type from node-info */',
+    version: 3,
+    position: [520, 300]
+  })
+  NextNode = {};
+
+  @links()
+  defineRouting() {
+    this.MyNode.out(0).to(this.NextNode.in(0));
+  }
+}
+```
+
+### Expression Syntax
+
+- Prefer modern expressions: `{{ $json.fieldName }}`.
+- Use specific-node expressions when needed: `{{ $('Node Name').item.json.field }}`.
+- Avoid legacy `$node["Name"].json.field` unless you are preserving an existing workflow and have a reason.
+- In Switch/If comparisons, `value1` is the expression being evaluated and `value2` is the literal comparison value.
+
+### Node Naming
+
+- Use descriptive names such as `Get Customers`, `Send Slack Alert`, or `Normalize Payload`.
+- Avoid names like `Node1`, `HTTP Request`, or `Code` when a more specific name is available.
+- Connection references must match the exact node property names in the TypeScript class.
+
+## Reading Workflow Files Efficiently
+
+Use the `<workflow-map>` block as the index before loading large workflow files.
+
+```typescript
+// <workflow-map>
+// Workflow : My Workflow
+// Nodes   : 12  |  Connections: 14
+//
+// NODE INDEX
+// Property name                    Node type (short)         Flags
+// ScheduleTrigger                  scheduleTrigger
+// AgentGenerateApplication         agent                      [AI] [creds]
+// OpenaiChatModel                  lmChatOpenAi               [creds] [ai_languageModel]
+// Memory                           memoryBufferWindow         [ai_memory]
+// GithubCheckBranchRef             httpRequest                [onError->out(1)]
+//
+// ROUTING MAP
+// ScheduleTrigger
+//   -> Configuration
+//     -> BuildProfileSources -> LoopOverProfileSources
+//
+// AI CONNECTIONS
+// AgentGenerateApplication.uses({ ai_languageModel: OpenaiChatModel, ai_memory: Memory })
+// </workflow-map>
+```
+
+Navigation rule:
+
+1. Read `<workflow-map>` first.
+2. Locate the property name you need.
+3. Search for that property in the file.
+4. Read only the relevant node or routing section unless broader context is required.
+
+## AI And LangChain Node Rules
+
+AI sub-nodes are not regular data-flow nodes.
+
+```typescript
+@links()
+defineRouting() {
+  this.ChatTrigger.out(0).to(this.AiAgent.in(0));
+
+  this.AiAgent.uses({
+    ai_languageModel: this.OpenaiModel.output,
+    ai_memory: this.Memory.output,
+    ai_outputParser: this.OutputParser.output,
+    ai_tool: [this.SearchTool.output],
+  });
+}
+```
+
+- Use `.uses()` for language models, memory, tools, parsers, embeddings, vector stores, retrievers, and other AI sub-nodes.
+- Never connect AI sub-nodes with `.out().to()`.
+- `ai_tool` and `ai_document` must be arrays.
+- Most other AI connection types are single refs.
+- Some nodes require boolean flags to expose AI ports or gated parameters. Check `node-info` before declaring `.uses()`.
+
+## Common Mistakes To Avoid
+
+- Wrong node type: use the exact full type returned by schema output, including package prefix when provided.
+- Outdated or non-existent typeVersion: use a value from the schema output.
+- Invalid operation/resource value: use exact option values from the schema.
+- Mismatched resource and operation: each resource enables its own operations.
+- Guessing nested structures: fixed collections have exact shapes.
+- Wrong connection names: match TypeScript property names exactly.
+- Inventing nodes, credentials, operations, or parameters.
+- Connecting AI sub-nodes with `.out().to()`.
+- Using `ai_tool: this.Tool.output` instead of `ai_tool: [this.Tool.output]`.
+- Inverting Switch/If `value1` and `value2`.
+- Using old Wait form structures such as `formFieldsUi.fieldItems` when the current schema expects `formFields: { values: [...] }`.
+- Passing a bare filename to `push`.
+- Treating Class A runtime/config gaps as workflow-code bugs.
+
+## Verify, Test, And Present
+
+After pushing:
+
+```bash
+npx --yes n8nac verify <workflowId>
+npx --yes n8nac test-plan <workflowId> --json
+```
+
+For webhook, chat, or form workflows, prefer the production test sequence:
+
+```bash
+npx --yes n8nac workflow activate <workflowId>
+npx --yes n8nac test <workflowId> --prod
+```
+
+- Class A configuration gaps require user/config action, not workflow rewrites.
+- Runtime-state issues such as unarmed test webhooks are not workflow-code bugs.
+- Class B wiring errors are fixable in the workflow file.
+- Stop after two repeated failures with the same diagnostic.
+
+## Workflow Presentation Contract
+
+`presentWorkflowResult` is the standard way to show a workflow to the user. It is part of the workflow authoring loop, even though the command lives in n8n-manager.
+
+Run it whenever one of these is true:
+
+- you created a workflow;
+- you modified and pushed a workflow;
+- you ran or tested a workflow and the user needs to inspect it;
+- the user asks to show, open, present, display, or give the URL/link for a workflow.
+
+```bash
+n8n-manager presentWorkflowResult --workflow-id <workflowId> --workspace-root <contextRoot>
+```
+
+Rules:
+
+- Do not manually construct n8n workflow URLs.
+- Do not return an internal local n8n URL when a presentation URL is available.
+- Use the `url` returned by `presentWorkflowResult` as the user-facing URL.
+- If you do not know the workflow ID, run `npx --yes n8nac list` first and select the matching workflow.
+- If `presentWorkflowResult` fails, report the backend diagnostic and then provide the best direct n8n URL only as a fallback.
+- Do this before the final response when the task created, changed, pushed, ran, or explicitly asks to show a workflow.
+
+### Testability Protocol
+
+For webhook, chat, or form workflows:
+
+1. Push with verification when possible.
+2. Run `test-plan` to inspect trigger type, endpoint, and suggested payload.
+3. Activate the workflow.
+4. Test with `--prod` by default.
+
+```bash
+npx --yes n8nac push <path-to-workflow.workflow.ts> --verify
+npx --yes n8nac test-plan <workflowId> --json
+npx --yes n8nac workflow activate <workflowId>
+npx --yes n8nac test <workflowId> --prod
+```
+
+Use bare `npx --yes n8nac test <workflowId>` only when a test URL was intentionally armed in the n8n editor.
+
+For GET/HEAD webhooks that read from `$json.query`, prefer:
+
+```bash
+npx --yes n8nac test <workflowId> --query '{"key":"value"}' --prod
+```
+
+## Execution Debugging
+
+If a webhook returns success but the workflow behavior is wrong, inspect executions instead of guessing:
+
+```bash
+npx --yes n8nac execution list --workflow-id <workflowId> --limit 5 --json
+npx --yes n8nac execution get <executionId> --include-data --json
+```
+
+- A successful HTTP trigger only means n8n accepted the request.
+- The execution can still fail later inside the workflow.
+- Use execution data to identify the failing node and real payload shape.
+
+## Credential Workflow
+
+When a workflow is blocked by missing credentials, resolve the credential gap without rewriting unrelated workflow logic.
+
+```bash
+npx --yes n8nac workflow credential-required <workflowId> --json
+npx --yes n8nac credential schema <type>
+npx --yes n8nac credential list --json
+npx --yes n8nac credential create --type <type> --name <name> --file cred.json --json
+npx --yes n8nac workflow activate <workflowId>
+```
+
+- `workflow credential-required` exits non-zero when at least one credential is missing. Treat that as a signal to act, not as a workflow-code failure.
+- Use `credential schema` to discover required fields.
+- Ask the user for secret values when needed.
+- Prefer `--file` for credential creation. Do not pass secrets inline in shell arguments.
+- Do not print API keys or credential secret values back to the user.
+- If credential creation fails, read the validation message and change the payload before retrying.
+
+## Operating Loop
+
+For most workflow tasks:
+
+1. Resolve context with `workspace status --json`.
+2. Read `workflowDir` from the backend response.
+3. Inspect existing workflows with `list`.
+4. Pull before editing an existing workflow.
+5. Search examples and schemas.
+6. Edit or create the `.workflow.ts` file.
+7. Validate locally.
+8. Push with `--verify`.
+9. Test if the workflow is HTTP-triggered.
+10. Inspect executions when behavior is unclear.
+11. Present the final workflow link with `presentWorkflowResult`.
+
+## Response Discipline
+
+- Explain concrete actions and command results, not generic capability.
+- When the user asks for an URL or visual inspection of a workflow, run `presentWorkflowResult` instead of composing a URL manually.
+- If setup is missing, use `n8n-manager` for instance/auth/runtime and `n8nac workspace ...` for context-root overrides.
+- Do not ask for host/API key until existing n8n-manager instances have been inspected.
+- Do not tell the user to run setup commands when you can run non-interactive commands yourself.
+- Stop after two repeated failures with the same diagnostic and report the backend error clearly.

package/skills/n8n-manager/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: n8n-manager
+description: Use when the user needs n8n instance, runtime, tunnel, auth, project, credential, or workflow presentation management through n8n-manager.
+---
+
+# n8n Manager
+
+Use this skill for global n8n instance management. `n8n-manager` is the source of truth for instances, runtime state, tunnels, API keys, managed owner credentials, default projects, and workflow presentation links.
+
+## Responsibility Boundary
+
+- Generated context root hint: not embedded. Use the shell launch directory or the workspace path explicitly given by the user.
+- If `n8nac` is available, first run `npx --yes n8nac update-ai` from the context root, then read `AGENTS.md`. `update-ai` is designed to create or refresh the n8n-as-code block without destroying existing user or agent instructions.
+- Use the exact `n8n-manager command` and `n8nac command` listed in `AGENTS.md` when present. Those context-root commands override the portable examples in this skill.
+- Use `n8n-manager` for global instance, auth, runtime, tunnel, project-default, credential, and workflow-presentation operations.
+- Use `npx --yes n8nac workspace ...` only for context-root overrides such as pinned instance, sync folder, and project override.
+- Use `npx --yes n8nac` workflow commands only after the effective context is ready.
+- Never edit `n8nac-config.json`, `~/.n8n-manager`, or n8n-manager secret files by hand.
+
+## Core Commands
+
+Inspect existing instances before changing state:
+
+```bash
+n8n-manager instances list
+n8n-manager instances --help
+n8n-manager config get
+```
+
+Do not invent n8n-manager subcommands. In particular, `instances create` and `--type local` are not valid. Use `instances add --mode ...` exactly as documented by `instances --help`.
+
+## Unconfigured Context Root
+
+When the context root is not configured and no suitable existing instance is available, stop and ask the user to choose. Do not create infrastructure by default.
+
+Present these choices clearly:
+
+- use an existing n8n-manager instance if one is available;
+- create a new managed local Docker n8n instance;
+- connect an existing or remote n8n instance with user-provided credentials.
+
+If the user chooses a managed local Docker instance, ask the tunnel question separately:
+
+- without public tunnel: local n8n only, suitable for normal UI/API workflow work;
+- with public tunnel: exposes the instance through a public URL, useful for webhooks/forms/chat triggers and remote callbacks.
+
+Do not enable, refresh, or start a public tunnel unless the user explicitly requested public access, webhook testing, or approved the tunnel option. If public access is not needed, create/start the managed instance without `--tunnel`.
+
+## Confirmed Setup Commands
+
+Only run these commands after the user has explicitly chosen the corresponding option.
+
+Managed local Docker without public tunnel:
+
+```bash
+n8n-manager instances add --name <name> --mode managed-local-docker
+n8n-manager instances setup <id-or-name>
+n8n-manager instances start <id-or-name>
+n8n-manager instances status <id-or-name>
+```
+
+Managed local Docker with public tunnel:
+
+```bash
+n8n-manager instances add --name <name> --mode managed-local-docker --tunnel
+n8n-manager instances setup <id-or-name> --tunnel
+n8n-manager instances start <id-or-name>
+n8n-manager instances tunnel status <id-or-name>
+```
+
+Remote or existing instances require user-provided credentials. Prefer stdin for API keys:
+
+```bash
+n8n-manager auth set --url <url> --api-key-stdin --name <name>
+n8n-manager auth test --instance <id-or-name>
+```
+
+Project selection is instance-level unless the context root explicitly needs a workspace override:
+
+```bash
+n8n-manager projects list --instance <id-or-name>
+n8n-manager projects select <project-id-or-name> --instance <id-or-name>
+```
+
+Self-hosted n8n may not expose the projects API or may return 401/403. In that case, do not retry project discovery. Use the n8n-architect workspace override path with the standard personal project unless the user gave another project:
+
+```bash
+npx --yes n8nac workspace set-project --project-id personal --project-name Personal
+```
+
+Runtime and tunnel operations are per instance:
+
+```bash
+n8n-manager instances start <id-or-name>
+n8n-manager instances stop <id-or-name>
+n8n-manager instances restart <id-or-name>
+n8n-manager instances tunnel status <id-or-name>
+n8n-manager instances tunnel start <id-or-name>
+n8n-manager instances tunnel refresh <id-or-name>
+```
+
+Present workflow results after creating, modifying, pushing, or running a workflow:
+
+```bash
+n8n-manager presentWorkflowResult --workflow-id <workflowId> --workspace-root <contextRoot>
+```
+
+## Guardrails
+
+- Do not ask for host/API key before checking `instances list`.
+- Do not ask for host/API key when the user wants a managed local Docker instance.
+- Do not print API keys back to the user.
+- Do not delete runtime data unless the user explicitly asks for destructive deletion.
+- If Docker is unavailable or the daemon is stopped, report the backend diagnostic and stop. Do not loop.
+- If a command fails repeatedly, stop after two attempts and explain the backend diagnostic.
+- For workflow credentials, inspect the required credential type before asking for secret values.

package/src/cli.ts

@@ -0,0 +1,24 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { isWorkspaceInitialized } from "./workspace.js";
+
+type CliProgram = Parameters<Parameters<OpenClawPluginApi["registerCli"]>[0]>[0]["program"];
+
+type CliOpts = {
+  program: CliProgram;
+  workspaceDir: string;
+};
+
+export function registerN8nAcCli({ program, workspaceDir }: CliOpts): void {
+  program
+    .command("n8nac:status")
+    .description("Show n8n-as-code workspace status")
+    .action(() => {
+      const initialized = isWorkspaceInitialized(workspaceDir);
+      console.log(`\nn8n-as-code workspace: ${workspaceDir}`);
+      console.log(`Status: ${initialized ? "✓  Initialized" : "✗  Not initialized"}`);
+      if (!initialized) {
+        console.log("\nUse the n8n-manager and n8n-architect skills to configure runtime access and workflow guidance.");
+      }
+      console.log();
+    });
+}

package/src/workspace.ts

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type WorkspaceBinding = {
+  projectId?: string;
+  projectName?: string;
+  syncFolder?: string;
+  activeInstanceId?: string;
+};
+
+/**
+ * Fixed context-root directory for V1.
+ * All n8nac context files (n8nac-config.json, AGENTS.md, .agents/skills, workflows/) live here.
+ * n8n instances and credentials are stored globally by n8n-manager.
+ */
+export function getWorkspaceDir(): string {
+  return join(homedir(), ".openclaw", "n8nac");
+}
+
+function readString(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+export function readWorkspaceBinding(workspaceDir: string): WorkspaceBinding {
+  const configPath = join(workspaceDir, "n8nac-config.json");
+  if (!existsSync(configPath)) {
+    return {};
+  }
+
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(raw) as Record<string, unknown>;
+
+    return {
+      projectId: readString(config.projectId) || undefined,
+      projectName: readString(config.projectName) || undefined,
+      syncFolder: readString(config.syncFolder) || undefined,
+      activeInstanceId: readString(config.activeInstanceId) || undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Returns true when n8nac has been initialized in the given directory,
+ * meaning the config exists and contains a selected project + sync folder.
+ */
+export function isWorkspaceInitialized(workspaceDir: string): boolean {
+  const binding = readWorkspaceBinding(workspaceDir);
+  return Boolean(binding.projectId && binding.projectName && binding.syncFolder);
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "lib": ["DOM", "DOM.Iterable", "ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "es2023"
+  },
+  "include": ["index.ts", "src/**/*", "tests/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}