@n8n-as-code/skills 2.0.2-next.7 → 2.1.0-next.45

package/README.md

@@ -6,9 +6,9 @@ This package powers the shared n8n ontology behind `n8n-as-code`: searchable nod
 
 > **⚠️ BREAKING CHANGE (v0.16.0)**: Workflows are now generated and documented in **TypeScript format** (`.workflow.ts`) instead of JSON for better AI compatibility and readability.
 
-> **BREAKING CHANGE (v2.0.0)**: Generated agent context now assumes the split runtime model: use `n8n-manager` for global instance/auth/runtime/project state and `n8nac workspace` for workspace overrides. Legacy workspace-local instance libraries are no longer treated as the runtime source of truth.
+> **BREAKING CHANGE (v2.0.0)**: Generated agent context now assumes the environment model: use `n8nac env` for workspace environments, `n8nac workspace` for readiness/migration/upgrade, and `n8n-manager` for local managed instances. Legacy workspace-local instance libraries are no longer treated as the source of truth.
 
-Runtime documentation: [n8n-manager guide](https://n8nascode.dev/docs/usage/n8n-manager/) · [CLI workspace commands](https://n8nascode.dev/docs/usage/cli/#workspace) · [Skills guide](https://n8nascode.dev/docs/usage/skills/)
+Documentation: [CLI guide](https://n8nascode.dev/docs/usage/cli/) · [n8n-manager guide](https://n8nascode.dev/docs/usage/n8n-manager/) · [Skills guide](https://n8nascode.dev/docs/usage/skills/)
 
 > **📌 Internal Library** — This package is not meant to be used directly. Public access is via [`n8nac`](https://www.npmjs.com/package/n8nac): `npx n8nac skills <command>`.
 

package/dist/agent-skills/n8n-architect/SKILL.md

@@ -5,7 +5,9 @@ description: Use when the user explicitly wants to create, edit, validate, sync,
 
 # 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.
+Use this skill for all n8n-as-code work: workspace readiness, migration, environments, managed local instances, tunnels, workflow authoring, validation, sync, push, and pull.
+
+Use `{{N8NAC_CMD}}` as the primary interface. Use `{{N8N_MANAGER_CMD}}` only for local managed runtime lifecycle, tunnels, and workflow presentation commands that are explicitly exposed by n8n-manager.
 
 ## Context Root Protocol
 
@@ -13,42 +15,171 @@ Use this skill for workflow engineering. Use the `n8n-manager` skill for instanc
 - {{N8NAC_CONTEXT_ROOT_HINT}}
 - Before any n8n work, first run `{{N8NAC_CMD}} 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 `{{N8NAC_CMD}} workspace ...`, `{{N8NAC_CMD}} list`, `pull`, `push`, `validate`, `test`, and `update-ai` command from the context root unless the user explicitly gives another context root.
+- Run every `{{N8NAC_CMD}} env ...`, `{{N8NAC_CMD}} workspace ...`, `{{N8NAC_CMD}} 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`.
+- Do not infer environment, project, sync folder, or workflow directory from `AGENTS.md`.
 - Before n8n work, resolve the effective context from the backend:
 
 ```bash
-{{N8NAC_CMD}} workspace status --json
+{{N8NAC_CMD}} env 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 `{{N8NAC_CMD}} workspace ...` commands.
+- Never write `n8nac-config.json`, `~/.n8n-manager`, or n8n-manager secret files by hand.
+
+## Workspace Readiness
+
+Use the unified migration preflight before resolving the effective environment. The dry-run is safe and reports whether any workspace migration is required:
+
+```bash
+{{N8NAC_CMD}} workspace migrate --json
+{{N8NAC_CMD}} env status --json
+```
+
+- Treat `workspace migrate --json` as the source of migration need.
+- Treat `env status --json` as the source of effective workspace readiness only after migration is not required or has been applied.
+- Do not infer readiness from raw files, generated agent docs, or directory names.
+- If migration is required, do not edit config files by hand or continue with environment/workflow work until it has been applied or explicitly deferred by the user.
+
+## Migration
+
+Migration is one user-facing command. Do not reason about internal migration phases directly; summarize the report `operations` array when explaining what will change.
+
+1. Run the dry-run first:
+
+```bash
+{{N8NAC_CMD}} workspace migrate --json
+```
+
+2. If the dry-run reports `status: "dry-run"`, `required: true`, or otherwise indicates pending changes, stop and ask once before applying it. Do not run `workspace migrate --write` unless the user already directly requested applying migration.
+3. After confirmation, apply migration and re-check readiness:
+
+```bash
+{{N8NAC_CMD}} workspace migrate --write
+{{N8NAC_CMD}} workspace migrate --json
+{{N8NAC_CMD}} env status --json
+```
+
+- Do not run `workspace migrate --write` without explicit confirmation unless the user already directly requested applying migration.
+- When reporting a dry-run, summarize the unified `operations` list and ask for exactly one confirmation for `{{N8NAC_CMD}} workspace migrate --write`.
+- Do not ask separately for different operation types. `{{N8NAC_CMD}} workspace migrate --write` applies the required migration as one operation.
+- Do not run environment, workflow, or setup commands while `workspace migrate --json` still reports migration required.
+- Managed local instances remain machine-global runtime resources.
+- Workspace environments remain workspace-scoped and are managed through `{{N8NAC_CMD}} env ...`.
 
 ## Bootstrap Order
 
 1. `cd` to the context root.
 2. Run `{{N8NAC_CMD}} update-ai`, then read `AGENTS.md`.
-3. Run `{{N8NAC_CMD}} workspace status --json`.
-4. If the context root is not ready, inspect instances with `{{N8N_MANAGER_CMD}} 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:
+3. Run `{{N8NAC_CMD}} workspace migrate --json`.
+4. If migration is required, stop and ask for confirmation before `{{N8NAC_CMD}} workspace migrate --write` unless the user already requested applying migration.
+5. Run `{{N8NAC_CMD}} env status --json` after migration is not required or has been applied.
+6. If the context root is not ready, inspect managed local instances with `{{N8N_MANAGER_CMD}} instance list`.
+7. Reuse an existing environment or managed local instance when suitable.
+8. If no suitable environment exists, stop and ask the user whether they want to connect a remote n8n URL or create/reuse a managed local n8n instance. Do not create infrastructure by default. If the user chooses a managed local instance, ask separately whether they want a public tunnel.
+9. Ask for host/API key only for an explicitly remote n8n environment.
+10. Configure the environment with:
+
+```bash
+{{N8NAC_CMD}} env add <name> --base-url <url> --sync-folder workflows/<name>
+{{N8NAC_CMD}} env auth set <name> --api-key-stdin
+{{N8NAC_CMD}} env use <name>
+```
+
+For a managed local instance:
+
+```bash
+{{N8NAC_CMD}} env add Local --managed-instance <id> --sync-folder workflows/local
+{{N8NAC_CMD}} env use Local
+```
+
+11. Run `{{N8NAC_CMD}} update-ai` after changing environments when the facade does not do it automatically.
+
+## Environments
+
+Use `{{N8NAC_CMD}} env ...` for workspace environments, remote URLs, active environment, API-key binding, projects, and sync folders.
+
+```bash
+{{N8NAC_CMD}} env status --json
+{{N8NAC_CMD}} env list
+{{N8NAC_CMD}} env add <name> --base-url <url> --sync-folder workflows/<name>
+{{N8NAC_CMD}} env auth set <name> --api-key-stdin
+{{N8NAC_CMD}} env use <name>
+```
+
+- Prefer `--api-key-stdin` for API keys.
+- Do not pass secrets inline in shell arguments.
+- Do not ask for host/API key when the user wants a managed local Docker instance.
+- Do not print API keys or credential secret values back to the user.
+- If a command or flag is unfamiliar, run `{{N8NAC_CMD}} env --help` or `{{N8NAC_CMD}} env <subcommand> --help`.
+
+Attach a managed local instance to the workspace with `{{N8NAC_CMD}} env ...`:
+
+```bash
+{{N8NAC_CMD}} env add Local --managed-instance <id> --sync-folder workflows/local
+{{N8NAC_CMD}} env use Local
+```
+
+## Managed Local Runtime
+
+Use `{{N8N_MANAGER_CMD}}` only for local managed instance lifecycle, tunnels, and workflow presentation commands that are part of the local runtime layer.
+
+Inspect existing managed instances before changing local machine state:
+
+```bash
+{{N8N_MANAGER_CMD}} instance list
+{{N8N_MANAGER_CMD}} instance --help
+{{N8N_MANAGER_CMD}} config get
+```
+
+Do not invent n8n-manager subcommands. Use `{{N8N_MANAGER_CMD}} <subcommand> --help` when unsure.
+
+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 managed local instance if one is available;
+- create a new managed local n8n instance;
+- configure a remote n8n URL as a workspace environment through `{{N8NAC_CMD}} env`.
+
+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`.
+
+Only run these commands after the user has explicitly chosen the corresponding option.
+
+Managed local instance without public tunnel:
+
+```bash
+{{N8N_MANAGER_CMD}} instance create
+{{N8N_MANAGER_CMD}} instance start <id>
+{{N8N_MANAGER_CMD}} instance list
+```
+
+Managed local instance with public tunnel:
 
 ```bash
-{{N8NAC_CMD}} workspace pin-instance --instance-id <id>
-{{N8NAC_CMD}} workspace set-sync-folder workflows
-{{N8NAC_CMD}} workspace set-project --project-id <id> --project-name <name>
+{{N8N_MANAGER_CMD}} instance create
+{{N8N_MANAGER_CMD}} instance start <id>
+{{N8N_MANAGER_CMD}} tunnel start <id>
 ```
 
-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:
+Instance and tunnel operations are per managed local instance:
 
 ```bash
-{{N8NAC_CMD}} workspace set-project --project-id personal --project-name Personal
+{{N8N_MANAGER_CMD}} instance start <id>
+{{N8N_MANAGER_CMD}} instance stop <id>
+{{N8N_MANAGER_CMD}} instance remove <id>
+{{N8N_MANAGER_CMD}} tunnel start <id>
+{{N8N_MANAGER_CMD}} tunnel stop <id>
 ```
 
-9. Run `{{N8NAC_CMD}} update-ai` after changing context-root overrides when the facade does not do it automatically.
+- Do not delete local instance 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.
 
 ## Sync Discipline
 
@@ -63,7 +194,7 @@ For self-hosted n8n instances where the projects API is unavailable or returns 4
 ```
 
 - `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 `{{N8NAC_CMD}} list --local`.
+- For a new workflow, create the file inside the `workflowDir` returned by `env status --json`, then confirm it with `{{N8NAC_CMD}} 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.
@@ -275,7 +406,7 @@ For webhook, chat, or form workflows, prefer the production test sequence:
 
 ## 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.
+`{{N8NAC_CMD}} workflow present` is the standard way to show a workflow to the user. It is v4-environment aware and part of the workflow authoring loop.
 
 Run it whenever one of these is true:
 
@@ -285,16 +416,17 @@ Run it whenever one of these is true:
 - the user asks to show, open, present, display, or give the URL/link for a workflow.
 
 ```bash
-{{N8N_MANAGER_CMD}} presentWorkflowResult --workflow-id <workflowId> --workspace-root <contextRoot>
+{{N8NAC_CMD}} workflow present <workflowId> --json
 ```
 
 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.
+- Use the `url` returned by `workflow present --json` as the user-facing URL.
 - If you do not know the workflow ID, run `{{N8NAC_CMD}} 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 not call `{{N8N_MANAGER_CMD}} presentWorkflowResult`; it is a legacy runtime command and is not workspace-environment aware.
+- If `workflow present` 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
@@ -357,7 +489,7 @@ When a workflow is blocked by missing credentials, resolve the credential gap wi
 
 For most workflow tasks:
 
-1. Resolve context with `workspace status --json`.
+1. Resolve context with `env status --json`.
 2. Read `workflowDir` from the backend response.
 3. Inspect existing workflows with `list`.
 4. Pull before editing an existing workflow.
@@ -367,13 +499,13 @@ For most workflow tasks:
 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`.
+11. Present the final workflow link with `{{N8NAC_CMD}} workflow present <workflowId> --json`.
 
 ## 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.
+- When the user asks for an URL or visual inspection of a workflow, run `{{N8NAC_CMD}} workflow present <workflowId> --json` instead of composing a URL manually.
+- If setup is missing, use `n8nac env ...` for workspace environments and `n8n-manager` only for managed local instances.
+- Do not ask for host/API key unless the user chooses a remote n8n environment.
 - 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/dist/assets/n8n-credentials-ontology.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-05-08T10:19:20.566Z",
+  "generatedAt": "2026-05-11T08:14:21.198Z",
   "n8nVersion": "unknown",
   "sourceFileCount": 428,
   "scanDirectories": [