diff --git a/docs-web/content/docs/developer-mcp-tools.mdx b/docs-web/content/docs/developer-mcp-tools.mdx index 785ad691b6..ccd081a3a0 100644 --- a/docs-web/content/docs/developer-mcp-tools.mdx +++ b/docs-web/content/docs/developer-mcp-tools.mdx @@ -200,9 +200,12 @@ Agents should build Code UX-adapted node flows rather than cloning n8n workflows should include dynamic widget schemas for editable graph inputs and node fields; callers can provide `widgets` as a graph-level `{ fields: [...] }` schema or as node-id keys mapped to node widget schemas. -Executable node types are currently `input`, `set_fields`, `template`, `provider_prompt`, -`http_request`, and `output`. Graph validation accepts structured drafts, but runtime execution rejects -unsupported node types. +The governed built-ins currently registered with executable handlers are `input`, `set_fields`, +`template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, +`approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. A +registered custom definition can execute only when its validated versioned manifest, immutable +artifact, and custom-node runtime are available. Unknown, legacy, mockup, and non-executable +definitions remain planned or unavailable and are rejected by runtime dispatch. Minimal create payload: diff --git a/docs-web/content/docs/registry.ts b/docs-web/content/docs/registry.ts index 29351c228c..c346b5dcaf 100644 --- a/docs-web/content/docs/registry.ts +++ b/docs-web/content/docs/registry.ts @@ -260,7 +260,7 @@ export const docsRegistry: Record = { path: '/docs/user-dashboard-nodes', section: 'User Guide', title: "Nodes", - description: "The Nodes page (/nodes) opens the browser-local Nodes Canvas workspace for drafting Code UX workflow graphs. It does not require a selected project and does not call the node-flow backend APIs.", + description: "The Nodes page (/nodes) is the project-scoped backend workspace for authoring and operating governed node flows. Select a project to load its flow library, credential metadata, publications, and durable run history; w...", }, 'user-dashboard-nodes-canvas': { id: 'user-dashboard-nodes-canvas', @@ -274,7 +274,7 @@ export const docsRegistry: Record = { path: '/docs/user-dashboard-node-flows', section: 'User Guide', title: "Node Flows", - description: "The Nodes page (/nodes) is where dashboard users create and operate saved node-flow workflows for the active project. A node flow is a repeatable graph that can be validated, run manually, scheduled, inspected through...", + description: "The Nodes page (/nodes) is the project-scoped backend authoring, publication, and operations surface for canonical node flows. No selected project means no flow library, credential metadata, publications, or durable r...", }, 'user-dashboard-scheduler': { id: 'user-dashboard-scheduler', diff --git a/docs-web/content/docs/user-dashboard-node-flows.mdx b/docs-web/content/docs/user-dashboard-node-flows.mdx index 0b39ac2177..c3593cc4e5 100644 --- a/docs-web/content/docs/user-dashboard-node-flows.mdx +++ b/docs-web/content/docs/user-dashboard-node-flows.mdx @@ -1,47 +1,31 @@ # Node Flows -The **Nodes** page (`/nodes`) is where dashboard users create and operate saved node-flow workflows for the active project. A node flow is a repeatable graph that can be validated, run manually, scheduled, inspected through persisted runs, and attached to project agents as a reusable skill. +The **Nodes** page (`/nodes`) is the project-scoped backend authoring, publication, and operations surface for canonical node flows. No selected project means no flow library, credential metadata, publications, or durable run history are requested. -## Flow Library And Canvas +## Library, Drafts, And Migration -The flow library lists project-owned flows. Selecting one opens an editable graph canvas with nodes, directed edges, positions, and node JSON data. The canvas is built into Code UX and is not a generic n8n importer; runtime execution supports Code UX node types rather than arbitrary external workflow nodes. +The flow library contains backend drafts and publications owned by the active project. Saves include the loaded draft revision, so a concurrent edit produces a visible conflict and never overwrites newer work. -New editable canvas surfaces use a pure dashboard state module for typed nodes, ports, edges, config fields, selection, deterministic layout, validation issues, JSON serialization, and malformed-draft recovery. Its starter graph lays out trigger, agent, task, condition, and output nodes so workflows begin from a useful Code UX shape. +The former browser graph at `codeux:nodes-canvas:v1` is eligible for one import into the selected project. Code UX normalizes it to Graph v2, creates an **Imported Nodes Canvas** backend draft, and only then removes the legacy value and records a project-specific marker. A failed import remains retryable, while a successful marker prevents duplicates. Browser storage is never the ongoing workflow source of truth. -Agent-driven graph edits use a separate UI-free helper that accepts structured JSON commands for adding nodes, patching node fields, connecting ports, deleting graph entities, selecting entities, and replacing a graph from serialized JSON. The helper applies commands through the canvas reducer and returns deterministic summaries, diffs, and validation blockers. +## Registry-Driven Editing And Credentials -Side panels stay controlled by the page shell: the palette emits typed create-node actions, the inspector -emits field/config/metadata changes for the selected node, edge details are read-only, and validation -issues expose select/focus callbacks for the affected node or edge. +The versioned node-definition registry supplies palette entries, typed ports, configuration and widget schemas, execution availability, capabilities, side effects, policies, and credential requirements. Selecting a definition loads its manifest and renders the inspector from that contract. Graphs reference a definition version and store non-secret configuration and credential ids; they do not contain custom-node source or resolved credentials. -## Dynamic Widgets +Credential slots display metadata-only states such as bound, missing, or denied and can request a binding. Secret values remain behind the credential broker and are excluded from graphs and browser output. -The inspector renders widget schemas attached to the selected node. Supported field types are text, textarea, number, boolean, select, JSON, secret reference, and key-value entries. Graph-level input widgets describe manual or scheduled run input. +The complete governed built-in set currently registered with executable handlers is `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. -Use secret reference fields for credentials. Do not paste raw tokens, API keys, cookies, passwords, or private headers into widget defaults, node data, metadata, or run input. +Registered custom definitions can execute only when their validated versioned manifest, immutable artifact, and custom-node runtime are available. Legacy `trigger`/`agent`/`task` canvas kinds, unknown or unregistered types, mockup entries, and definitions marked non-executable are planned or unavailable definitions, not executable handlers. -## Validation +## Governance And Publication -Validation checks graph shape before saving: unique node ids, valid edge endpoints, acyclic edges, JSON-safe data, and valid widget field definitions. Validation issues are shown as field-level messages so you can repair the draft before saving. +Draft review provides structural validation, policy findings, requested permissions, side-effect review, and a non-executing dry run. Publication requires the current draft revision, a valid governed review, and all required credentials. Each publication is an immutable snapshot; comparison and rollback operate on versioned history, and only a pinned or latest-published version can execute. -A graph can be structurally valid even when it contains a future node type that the runtime cannot execute yet. Current executable node types are `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`. +## Durable Debugger And Scheduling -## Running And Inspection +The debugger reads persisted flow runs, node runs, attempt history, retry classifications and decisions, approval records, invocation links, timing, and redacted input and output. Pending approvals offer **Approve & continue** and **Reject** actions. A decision continues or terminates the same pinned run, and repeated decisions return its current durable state without duplicating a governed attempt or external send. The debugger also supports cancellation and safe retry. -The manual run panel accepts JSON object input and starts a node-flow run. Runs persist both the parent flow result and per-node rows, including status, error messages, redacted input/output, and linked execution invocation ids when a provider or HTTP node is externally observable. +Use the [Scheduler](/docs/user-dashboard-scheduler) to target a pinned or latest-published version. A flow can also be attached to a project agent preset as a reusable skill; removing the attachment does not remove the flow, publications, schedules, or run history. -Rendered run payloads redact secret-shaped keys such as `apiKey`, `authorization`, `cookie`, `password`, `secret`, and `token`. - -The run debugger lists durable approvals beside node attempts. A pending item offers **Approve & continue** and **Reject** actions. The decision applies to the same pinned run, and repeated clicks return its current state without sending an approved external effect twice. - -## Agent Attachment - -A flow can be attached to a project agent preset as a repeatable skill with a name and description. Detaching removes only that binding; the flow, its graph, schedules, and run history remain in the project. - -## Scheduling - -Use the [Scheduler](/docs/user-dashboard-scheduler) page to run a saved node flow once or on a recurrence. Scheduled node-flow entries select a project-owned flow and may include optional JSON object input. Pause, resume, failure handling, and due-run behavior match the normal scheduler model. - -## Graph v2 boundary - -The dashboard edits the shared Graph v2 contract. The executable registry is limited to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`; planned palette concepts are not runtime handlers. +Outside development builds, `/nodes` requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. Individual definitions can additionally require provider, credential-broker, egress, approval/outbox, webhook, or custom-runtime configuration. Catalog presence and feature visibility do not assert that an integration is configured or production-ready. diff --git a/docs-web/content/docs/user-dashboard-nodes.mdx b/docs-web/content/docs/user-dashboard-nodes.mdx index 923258a79e..cedf23159d 100644 --- a/docs-web/content/docs/user-dashboard-nodes.mdx +++ b/docs-web/content/docs/user-dashboard-nodes.mdx @@ -1,17 +1,27 @@ # Nodes -The **Nodes** page (`/nodes`) opens the browser-local Nodes Canvas workspace for drafting Code UX workflow graphs. It does not require a selected project and does not call the node-flow backend APIs. +The **Nodes** page (`/nodes`) is the project-scoped backend workspace for authoring and operating governed node flows. Select a project to load its flow library, credential metadata, publications, and durable run history; without an active project, the page does not request node-flow data. -Use it to: +## Backend Workspace And Legacy Import -- add trigger, agent, task, condition, and output nodes from the palette -- select and move nodes on the canvas -- edit selected node labels, descriptions, metadata intents, and config fields in the inspector -- inspect selected edge source and target wiring -- review local structural validation issues -- import and export deterministic graph JSON -- view command-friendly graph metadata for agent workflows +Creating or saving a draft persists it in the selected project's canonical node-flow repository. Saves include the loaded draft revision, so a concurrent edit produces a visible conflict instead of overwriting newer work. Changing projects clears the current workspace before loading the next project's records. -The graph is saved to browser `localStorage` under `codeux:nodes-canvas:v1`. There is no cloud sync, database persistence, or real workflow execution on this page. +The former browser graph at `codeux:nodes-canvas:v1` is only a one-time migration source. On the first eligible load for a selected project, Code UX converts that graph to Graph v2 and creates an **Imported Nodes Canvas** backend draft. It removes the legacy value and records a project-specific marker only after creation succeeds; failed imports remain available for retry, and the marker prevents duplicate imports. Browser storage is not used for ongoing workflow persistence. -For the full local canvas contract, see [Nodes Canvas](/docs/user-dashboard-nodes-canvas). For saved project-scoped node-flow runtime behavior, see [Node Flows](/docs/user-dashboard-node-flows). +## Registry-Driven Editing And Execution + +The versioned node-definition registry drives palette entries, executable state, typed ports, configuration and widget schemas, credential slots, capabilities, side-effect classifications, and default policies. The inspector renders the selected manifest, while the graph stores its type/version reference, non-secret configuration, policies, and credential ids rather than custom source or secret values. + +The complete governed built-in set currently registered with executable handlers is `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. + +Registered custom definitions can execute only when their validated versioned manifest, immutable artifact, and custom-node runtime are available. Legacy `trigger`/`agent`/`task` canvas kinds, unknown or unregistered types, mockup entries, and definitions marked non-executable are planned or unavailable definitions, not executable handlers. + +## Review, Publication, And Debugging + +Validation and dry run report structural errors, requested capabilities, credential requirements, side-effect changes, and policy findings; dry run does not invoke handlers. Publication requires the current draft revision, a valid governed review, and every required credential binding. Published snapshots are immutable, and version comparison and rollback preserve that history. Only published versions run. + +The debugger reads persisted flow runs, node runs, attempts, retry decisions, approvals, invocation links, timing, and redacted input and output. Cancellation, safe retry, and approval decisions update the same durable pinned run rather than creating an unrelated execution. Scheduling targets a pinned or latest-published version from the [Scheduler](/docs/user-dashboard-scheduler). + +Outside development builds, the workspace requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. A definition can also require a configured provider, credential broker, allowed egress, approval/outbox services, webhook ingress, or custom-node runtime. Registry presence and feature visibility do not assert that an integration is configured or production-ready. + +For the detailed editing contract, see [Nodes Canvas](/docs/user-dashboard-nodes-canvas). For API behavior, publication, execution, and scheduling, see [Node Flows](/docs/user-dashboard-node-flows). diff --git a/docs-web/developer/mcp-tools.md b/docs-web/developer/mcp-tools.md index 7633d6ac16..2198cb93d5 100644 --- a/docs-web/developer/mcp-tools.md +++ b/docs-web/developer/mcp-tools.md @@ -200,9 +200,12 @@ Agents should build Code UX-adapted node flows rather than cloning n8n workflows should include dynamic widget schemas for editable graph inputs and node fields; callers can provide `widgets` as a graph-level `{ fields: [...] }` schema or as node-id keys mapped to node widget schemas. -Executable node types are currently `input`, `set_fields`, `template`, `provider_prompt`, -`http_request`, and `output`. Graph validation accepts structured drafts, but runtime execution rejects -unsupported node types. +The governed built-ins currently registered with executable handlers are `input`, `set_fields`, +`template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, +`approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. A +registered custom definition can execute only when its validated versioned manifest, immutable +artifact, and custom-node runtime are available. Unknown, legacy, mockup, and non-executable +definitions remain planned or unavailable and are rejected by runtime dispatch. Minimal create payload: diff --git a/docs-web/user/dashboard/node-flows.md b/docs-web/user/dashboard/node-flows.md index 0acfe45d15..efe7feebf2 100644 --- a/docs-web/user/dashboard/node-flows.md +++ b/docs-web/user/dashboard/node-flows.md @@ -1,47 +1,31 @@ # Node Flows -The **Nodes** page (`/nodes`) is where dashboard users create and operate saved node-flow workflows for the active project. A node flow is a repeatable graph that can be validated, run manually, scheduled, inspected through persisted runs, and attached to project agents as a reusable skill. +The **Nodes** page (`/nodes`) is the project-scoped backend authoring, publication, and operations surface for canonical node flows. No selected project means no flow library, credential metadata, publications, or durable run history are requested. -## Flow Library And Canvas +## Library, Drafts, And Migration -The flow library lists project-owned flows. Selecting one opens an editable graph canvas with nodes, directed edges, positions, and node JSON data. The canvas is built into Code UX and is not a generic n8n importer; runtime execution supports Code UX node types rather than arbitrary external workflow nodes. +The flow library contains backend drafts and publications owned by the active project. Saves include the loaded draft revision, so a concurrent edit produces a visible conflict and never overwrites newer work. -New editable canvas surfaces use a pure dashboard state module for typed nodes, ports, edges, config fields, selection, deterministic layout, validation issues, JSON serialization, and malformed-draft recovery. Its starter graph lays out trigger, agent, task, condition, and output nodes so workflows begin from a useful Code UX shape. +The former browser graph at `codeux:nodes-canvas:v1` is eligible for one import into the selected project. Code UX normalizes it to Graph v2, creates an **Imported Nodes Canvas** backend draft, and only then removes the legacy value and records a project-specific marker. A failed import remains retryable, while a successful marker prevents duplicates. Browser storage is never the ongoing workflow source of truth. -Agent-driven graph edits use a separate UI-free helper that accepts structured JSON commands for adding nodes, patching node fields, connecting ports, deleting graph entities, selecting entities, and replacing a graph from serialized JSON. The helper applies commands through the canvas reducer and returns deterministic summaries, diffs, and validation blockers. +## Registry-Driven Editing And Credentials -Side panels stay controlled by the page shell: the palette emits typed create-node actions, the inspector -emits field/config/metadata changes for the selected node, edge details are read-only, and validation -issues expose select/focus callbacks for the affected node or edge. +The versioned node-definition registry supplies palette entries, typed ports, configuration and widget schemas, execution availability, capabilities, side effects, policies, and credential requirements. Selecting a definition loads its manifest and renders the inspector from that contract. Graphs reference a definition version and store non-secret configuration and credential ids; they do not contain custom-node source or resolved credentials. -## Dynamic Widgets +Credential slots display metadata-only states such as bound, missing, or denied and can request a binding. Secret values remain behind the credential broker and are excluded from graphs and browser output. -The inspector renders widget schemas attached to the selected node. Supported field types are text, textarea, number, boolean, select, JSON, secret reference, and key-value entries. Graph-level input widgets describe manual or scheduled run input. +The complete governed built-in set currently registered with executable handlers is `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. -Use secret reference fields for credentials. Do not paste raw tokens, API keys, cookies, passwords, or private headers into widget defaults, node data, metadata, or run input. +Registered custom definitions can execute only when their validated versioned manifest, immutable artifact, and custom-node runtime are available. Legacy `trigger`/`agent`/`task` canvas kinds, unknown or unregistered types, mockup entries, and definitions marked non-executable are planned or unavailable definitions, not executable handlers. -## Validation +## Governance And Publication -Validation checks graph shape before saving: unique node ids, valid edge endpoints, acyclic edges, JSON-safe data, and valid widget field definitions. Validation issues are shown as field-level messages so you can repair the draft before saving. +Draft review provides structural validation, policy findings, requested permissions, side-effect review, and a non-executing dry run. Publication requires the current draft revision, a valid governed review, and all required credentials. Each publication is an immutable snapshot; comparison and rollback operate on versioned history, and only a pinned or latest-published version can execute. -A graph can be structurally valid even when it contains a future node type that the runtime cannot execute yet. Current executable node types are `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`. +## Durable Debugger And Scheduling -## Running And Inspection +The debugger reads persisted flow runs, node runs, attempt history, retry classifications and decisions, approval records, invocation links, timing, and redacted input and output. Pending approvals offer **Approve & continue** and **Reject** actions. A decision continues or terminates the same pinned run, and repeated decisions return its current durable state without duplicating a governed attempt or external send. The debugger also supports cancellation and safe retry. -The manual run panel accepts JSON object input and starts a node-flow run. Runs persist both the parent flow result and per-node rows, including status, error messages, redacted input/output, and linked execution invocation ids when a provider or HTTP node is externally observable. +Use the [Scheduler](./scheduler.md) to target a pinned or latest-published version. A flow can also be attached to a project agent preset as a reusable skill; removing the attachment does not remove the flow, publications, schedules, or run history. -Rendered run payloads redact secret-shaped keys such as `apiKey`, `authorization`, `cookie`, `password`, `secret`, and `token`. - -The run debugger lists durable approvals beside node attempts. A pending item offers **Approve & continue** and **Reject** actions. The decision applies to the same pinned run, and repeated clicks return its current state without sending an approved external effect twice. - -## Agent Attachment - -A flow can be attached to a project agent preset as a repeatable skill with a name and description. Detaching removes only that binding; the flow, its graph, schedules, and run history remain in the project. - -## Scheduling - -Use the [Scheduler](./scheduler.md) page to run a saved node flow once or on a recurrence. Scheduled node-flow entries select a project-owned flow and may include optional JSON object input. Pause, resume, failure handling, and due-run behavior match the normal scheduler model. - -## Graph v2 boundary - -The dashboard edits the shared Graph v2 contract. The executable registry is limited to `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`; planned palette concepts are not runtime handlers. +Outside development builds, `/nodes` requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. Individual definitions can additionally require provider, credential-broker, egress, approval/outbox, webhook, or custom-runtime configuration. Catalog presence and feature visibility do not assert that an integration is configured or production-ready. diff --git a/docs-web/user/dashboard/nodes.md b/docs-web/user/dashboard/nodes.md index 4b2755fb6b..80c4cec3bc 100644 --- a/docs-web/user/dashboard/nodes.md +++ b/docs-web/user/dashboard/nodes.md @@ -1,17 +1,27 @@ # Nodes -The **Nodes** page (`/nodes`) opens the browser-local Nodes Canvas workspace for drafting Code UX workflow graphs. It does not require a selected project and does not call the node-flow backend APIs. +The **Nodes** page (`/nodes`) is the project-scoped backend workspace for authoring and operating governed node flows. Select a project to load its flow library, credential metadata, publications, and durable run history; without an active project, the page does not request node-flow data. -Use it to: +## Backend Workspace And Legacy Import -- add trigger, agent, task, condition, and output nodes from the palette -- select and move nodes on the canvas -- edit selected node labels, descriptions, metadata intents, and config fields in the inspector -- inspect selected edge source and target wiring -- review local structural validation issues -- import and export deterministic graph JSON -- view command-friendly graph metadata for agent workflows +Creating or saving a draft persists it in the selected project's canonical node-flow repository. Saves include the loaded draft revision, so a concurrent edit produces a visible conflict instead of overwriting newer work. Changing projects clears the current workspace before loading the next project's records. -The graph is saved to browser `localStorage` under `codeux:nodes-canvas:v1`. There is no cloud sync, database persistence, or real workflow execution on this page. +The former browser graph at `codeux:nodes-canvas:v1` is only a one-time migration source. On the first eligible load for a selected project, Code UX converts that graph to Graph v2 and creates an **Imported Nodes Canvas** backend draft. It removes the legacy value and records a project-specific marker only after creation succeeds; failed imports remain available for retry, and the marker prevents duplicate imports. Browser storage is not used for ongoing workflow persistence. -For the full local canvas contract, see [Nodes Canvas](./nodes-canvas.md). For saved project-scoped node-flow runtime behavior, see [Node Flows](./node-flows.md). +## Registry-Driven Editing And Execution + +The versioned node-definition registry drives palette entries, executable state, typed ports, configuration and widget schemas, credential slots, capabilities, side-effect classifications, and default policies. The inspector renders the selected manifest, while the graph stores its type/version reference, non-secret configuration, policies, and credential ids rather than custom source or secret values. + +The complete governed built-in set currently registered with executable handlers is `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. + +Registered custom definitions can execute only when their validated versioned manifest, immutable artifact, and custom-node runtime are available. Legacy `trigger`/`agent`/`task` canvas kinds, unknown or unregistered types, mockup entries, and definitions marked non-executable are planned or unavailable definitions, not executable handlers. + +## Review, Publication, And Debugging + +Validation and dry run report structural errors, requested capabilities, credential requirements, side-effect changes, and policy findings; dry run does not invoke handlers. Publication requires the current draft revision, a valid governed review, and every required credential binding. Published snapshots are immutable, and version comparison and rollback preserve that history. Only published versions run. + +The debugger reads persisted flow runs, node runs, attempts, retry decisions, approvals, invocation links, timing, and redacted input and output. Cancellation, safe retry, and approval decisions update the same durable pinned run rather than creating an unrelated execution. Scheduling targets a pinned or latest-published version from the [Scheduler](./scheduler.md). + +Outside development builds, the workspace requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. A definition can also require a configured provider, credential broker, allowed egress, approval/outbox services, webhook ingress, or custom-node runtime. Registry presence and feature visibility do not assert that an integration is configured or production-ready. + +For the detailed editing contract, see [Nodes Canvas](./nodes-canvas.md). For API behavior, publication, execution, and scheduling, see [Node Flows](./node-flows.md). diff --git a/docs/dashboard/node-flows.md b/docs/dashboard/node-flows.md index 80c54871a6..54517209b3 100644 --- a/docs/dashboard/node-flows.md +++ b/docs/dashboard/node-flows.md @@ -1,29 +1,31 @@ # Node Flows Dashboard -The **Nodes** page (`/nodes`) is the project-scoped authoring and operations surface for canonical node flows. No selected project means no flow library, credentials, publications, or run history are requested. +The **Nodes** page (`/nodes`) is the project-scoped backend authoring, publication, and operations surface for canonical node flows. No selected project means no flow library, credential metadata, publications, or durable run history are requested. -## Library and drafts +## Library, drafts, and migration The library loads through `GET /api/projects/:projectId/node-flows`. Drafts are created through `POST /api/projects/:projectId/node-flow-drafts` and saved through revision-checked `PATCH /api/node-flow-drafts/:flowId`. A stale revision produces a visible conflict and never overwrites newer work. -The former browser canvas is eligible for one project-specific import. After a successful backend draft creation, its graph value is removed and a migration marker prevents duplicates. Browser storage is never used for ongoing persistence. +The former browser graph at `codeux:nodes-canvas:v1` is eligible for one import into the selected project. Code UX normalizes it to Graph v2, creates an **Imported Nodes Canvas** backend draft, and only then removes the legacy value and records a project-specific marker. A failed import remains retryable, while a successful marker prevents duplicates. Browser storage is never the ongoing workflow source of truth. -## Registry and credentials +## Registry-driven editing and credentials -`GET /api/node-flow-catalog` is the registry source for palette entries, typed ports, configuration and widget schemas, execution availability, capabilities, side effects, policies, and credential requirements. Selecting a definition loads its full versioned manifest. Graphs reference a definition version and do not contain custom-node source. +`GET /api/node-flow-catalog` is the versioned registry source for palette entries, typed ports, configuration and widget schemas, execution availability, capabilities, side effects, policies, and credential requirements. Selecting a definition loads its manifest and renders the inspector from that contract. Graphs reference a definition version and store non-secret configuration and credential ids; they do not contain custom-node source or resolved credentials. -The inspector displays credential slots as bound, missing, or denied and can request a binding. It displays credential metadata only; secret values never enter the graph or dashboard output. +Credential slots display metadata-only states such as bound, missing, or denied and can request a binding. Secret values remain behind the credential broker and are excluded from graphs, browser output, logs, and documentation examples. -The registered governed built-ins are `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. Registered, validated custom definitions can execute when their immutable artifact and runtime are available. Legacy canvas kinds, unregistered names, and definitions marked non-executable remain planning or unavailable definitions and cannot run. +The complete governed built-in set currently registered with executable handlers is `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. + +Registered custom definitions can execute only when their validated versioned manifest, immutable artifact, and custom-node runtime are available. Legacy `trigger`/`agent`/`task` canvas kinds, unknown or unregistered types, mockup entries, and definitions marked non-executable are planned or unavailable definitions, not executable handlers. ## Governance and publication -T06 draft endpoints provide structural validation, policy findings, requested permissions, side-effect review, dry runs, immutable publication, version comparison, and rollback. Dry runs never execute nodes. Only a valid draft with satisfied required credentials can publish, and only published versions execute. +Draft review provides structural validation, policy findings, requested permissions, side-effect review, and a non-executing dry run. Publication requires the current draft revision, a valid governed review, and all required credentials. Each publication is an immutable snapshot; comparison and rollback operate on versioned history, and only a pinned or latest-published version can execute. -## Run debugger and scheduling +## Durable debugger and scheduling -The debugger reads persisted runs, node runs, attempt history, and approval decisions. Pending approvals expose keyboard-accessible **Approve & continue** and **Reject** actions. A decision continues or terminates the same pinned run, and repeated clicks return its current durable state without duplicating the governed attempt or external send. The debugger also overlays node state, shows retry reasons and decisions, links invocation ids, reports timing, supports cancellation and safe retry, and redacts secret-shaped values before rendering. Scheduling is entered through `/scheduler`; scheduler execution also resolves published versions. +The debugger reads persisted flow runs, node runs, attempt history, retry classifications and decisions, approval records, invocation links, timing, and redacted input and output. Pending approvals expose keyboard-accessible **Approve & continue** and **Reject** actions. A decision continues or terminates the same pinned run, and repeated decisions return its current durable state without duplicating a governed attempt or external send. The debugger also supports cancellation and safe retry. -The layout stacks on small screens, preserves keyboard-visible focus, labels loading/error/empty states, and bounds long histories and JSON output with scrolling. +Scheduling is entered through `/scheduler` and targets a pinned or latest-published version. A flow can also be attached to a project agent preset as a reusable skill; removing the attachment does not remove the flow, publications, schedules, or run history. -Outside development, `/nodes` requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. Individual definitions can require additional provider, credential-broker, egress, approval/outbox, webhook, or custom-runtime configuration; catalog presence alone does not assert production readiness for an integration. +Outside development builds, `/nodes` requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. Individual definitions can additionally require provider, credential-broker, egress, approval/outbox, webhook, or custom-runtime configuration. Catalog presence and feature visibility do not assert that an integration is configured or production-ready. diff --git a/docs/dashboard/nodes.md b/docs/dashboard/nodes.md index 78b5679e7b..675204f44f 100644 --- a/docs/dashboard/nodes.md +++ b/docs/dashboard/nodes.md @@ -1,17 +1,27 @@ # Nodes -The **Nodes** page (`/nodes`) opens the browser-local Nodes Canvas workspace for drafting Code UX workflow graphs. It does not require a selected project and does not call the node-flow backend APIs. +The **Nodes** page (`/nodes`) is the project-scoped backend workspace for authoring and operating governed node flows. Select a project to load its flow library, credential metadata, publications, and durable run history; without an active project, the page does not request node-flow data. -Use it to: +## Backend workspace and legacy import -- add trigger, agent, task, condition, and output nodes from the palette -- select and move nodes on the canvas -- edit selected node labels, descriptions, metadata intents, and config fields in the inspector -- inspect selected edge source and target wiring -- review local structural validation issues -- import and export deterministic graph JSON -- view command-friendly graph metadata for agent workflows +Creating or saving a draft persists it in the selected project's canonical node-flow repository. Saves include the loaded draft revision, so a concurrent edit produces a visible conflict instead of overwriting newer work. Changing projects clears the current workspace before loading the next project's records. -The graph is saved to browser `localStorage` under `codeux:nodes-canvas:v1`. There is no cloud sync, database persistence, or real workflow execution on this page. +The former browser graph at `codeux:nodes-canvas:v1` is only a one-time migration source. On the first eligible load for a selected project, Code UX converts that graph to Graph v2 and creates an **Imported Nodes Canvas** backend draft. It removes the legacy value and records a project-specific marker only after creation succeeds; failed imports remain available for retry, and the marker prevents duplicate imports. Browser storage is not used for ongoing workflow persistence. -For the full local canvas contract, see [Nodes Canvas](./nodes-canvas.md). For the saved project-scoped runtime, validation API, manual runs, scheduling, and agent-skill attachments, see [Node Flows Dashboard](./node-flows.md). +## Registry-driven editing and execution + +The versioned node-definition registry drives palette entries, executable state, typed ports, configuration and widget schemas, credential slots, capabilities, side-effect classifications, and default policies. The inspector renders the selected manifest, while the graph stores its type/version reference, non-secret configuration, policies, and credential ids rather than custom source or secret values. + +The complete governed built-in set currently registered with executable handlers is `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. + +Registered custom definitions can execute only when their validated versioned manifest, immutable artifact, and custom-node runtime are available. Legacy `trigger`/`agent`/`task` canvas kinds, unknown or unregistered types, mockup entries, and definitions marked non-executable are planned or unavailable definitions, not executable handlers. + +## Review, publication, and debugging + +Validation and dry run report structural errors, requested capabilities, credential requirements, side-effect changes, and policy findings; dry run does not invoke handlers. Publication requires the current draft revision, a valid governed review, and every required credential binding. Published snapshots are immutable, and version comparison and rollback preserve that history. Only published versions run. + +The debugger reads persisted flow runs, node runs, attempts, retry decisions, approvals, invocation links, timing, and redacted input and output. Cancellation, safe retry, and approval decisions update the same durable pinned run rather than creating an unrelated execution. Scheduling targets a pinned or latest-published version from the [Scheduler](./scheduler.md). + +Outside development builds, the workspace requires the Nodes feature flag plus the node-flow backend and automation-security prerequisites. A definition can also require a configured provider, credential broker, allowed egress, approval/outbox services, webhook ingress, or custom-node runtime. Registry presence and feature visibility do not assert that an integration is configured or production-ready. + +For the detailed editing contract, see [Nodes Canvas](./nodes-canvas.md). For API behavior, publication, execution, and scheduling, see [Node Flows Dashboard](./node-flows.md). diff --git a/docs/mcp/tools-and-contracts.md b/docs/mcp/tools-and-contracts.md index f802016e77..b4d5c2c74f 100644 --- a/docs/mcp/tools-and-contracts.md +++ b/docs/mcp/tools-and-contracts.md @@ -438,7 +438,7 @@ The graph payload is the shared `NodeFlowGraph` contract: - `inputSchema`: optional graph-level widget schema for run input - `metadata`: optional JSON object -Validation checks graph shape, unique node ids, edge endpoints, acyclicity, JSON-safe node data, widget schema fields, select options, finite numeric constraints, and default values that match field types. Runtime support is narrower than graph storage: executable node types are currently `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, and `output`. +Validation checks graph shape, unique node ids, edge endpoints, acyclicity, JSON-safe node data, widget schema fields, select options, finite numeric constraints, and default values that match field types. The governed built-ins currently registered with executable handlers are `input`, `set_fields`, `template`, `provider_prompt`, `http_request`, `condition`, `switch`, `foreach`, `merge`, `delay`, `approval`, `email_draft`, `email_send`, `execute_subflow`, `webhook_trigger`, and `output`. A registered custom definition can execute only when its validated versioned manifest, immutable artifact, and custom-node runtime are available; unknown, legacy, mockup, and non-executable definitions remain planned or unavailable and are rejected by runtime dispatch. Agents should build Code UX-adapted flows from structured graph specs instead of cloning n8n workflows one-to-one. A good flow exposes the values an operator or agent should edit, keeps runtime behavior repeatable, names nodes by Code UX behavior, and validates every required field before saving. MCP callers can provide `widgets` as a graph-level `{ fields: [...] }` schema or as node-id keys mapped to each node's `widgetSchema`.