(CODUX-105) Document node-flow workflows

docs-web/architecture/data-model.md

@@ -17,7 +17,13 @@ Project
 │   │   └── ExecutionInvocation
 │   └── PreviewSession
 ├── AgentPreset
-│   └── SkillStorageBinding
+│   ├── SkillStorageBinding
+│   └── NodeFlowSkillAttachment
+├── NodeFlow
+│   ├── NodeFlowVersion
+│   ├── NodeFlowRun
+│   │   └── NodeFlowNodeRun
+│   └── NodeFlowSkillAttachment
 ├── SkillStorage
 │   ├── Skill
 │   └── SkillEmbedding
@@ -163,6 +169,20 @@ Persistent skills are stored separately from project workspaces, memories, knowl
 
 Skill markdown is imported from YAML-like frontmatter plus a body. Frontmatter maps to metadata; the body remains the authoritative agent instruction. Backend retrieval can search all project storages, one storage, or the storages attached to an agent preset. Enabled attached agents receive provider prompt guidance, retrieval-only `search_skills` MCP access where eligible, and writable persistent-skill mounts outside the project workspace.
 
+## NodeFlow
+
+Node flows are project-scoped repeatable workflow graphs managed from the Nodes dashboard and the `manage_node_flows` MCP tool.
+
+| Table | Purpose |
+| --- | --- |
+| `node_flows` | Current flow title, description, normalized graph JSON, project id, version, and timestamps. |
+| `node_flow_versions` | Immutable graph snapshots written on create and each update. |
+| `node_flow_agent_skills` | Attachments that expose a flow as a repeatable skill for an agent preset. |
+| `node_flow_runs` | Parent run rows with status, version, trigger type, redacted trigger payload, redacted input/output, error message, timestamps, and optional execution invocation link. |
+| `node_flow_node_runs` | Per-node run rows with status, node id, redacted input/output, error message, timestamps, and optional execution invocation link. |
+
+`node_flow_runs.execution_invocation_id` points at the parent `execution_invocations` row with `type = "node_flow"`. Provider and HTTP node rows may also set `node_flow_node_runs.execution_invocation_id` to invocation rows with `type = "node_flow_node"`. Deleting a node flow cascades its versions, attachments, run rows, and node-run rows.
+
 ## Memory
 
 | Field | Type | Notes |

docs-web/content/docs/architecture-data-model.mdx

@@ -17,7 +17,13 @@ Project
 │   │   └── ExecutionInvocation
 │   └── PreviewSession
 ├── AgentPreset
-│   └── SkillStorageBinding
+│   ├── SkillStorageBinding
+│   └── NodeFlowSkillAttachment
+├── NodeFlow
+│   ├── NodeFlowVersion
+│   ├── NodeFlowRun
+│   │   └── NodeFlowNodeRun
+│   └── NodeFlowSkillAttachment
 ├── SkillStorage
 │   ├── Skill
 │   └── SkillEmbedding
@@ -163,6 +169,20 @@ Persistent skills are stored separately from project workspaces, memories, knowl
 
 Skill markdown is imported from YAML-like frontmatter plus a body. Frontmatter maps to metadata; the body remains the authoritative agent instruction. Backend retrieval can search all project storages, one storage, or the storages attached to an agent preset. Enabled attached agents receive provider prompt guidance, retrieval-only `search_skills` MCP access where eligible, and writable persistent-skill mounts outside the project workspace.
 
+## NodeFlow
+
+Node flows are project-scoped repeatable workflow graphs managed from the Nodes dashboard and the `manage_node_flows` MCP tool.
+
+| Table | Purpose |
+| --- | --- |
+| `node_flows` | Current flow title, description, normalized graph JSON, project id, version, and timestamps. |
+| `node_flow_versions` | Immutable graph snapshots written on create and each update. |
+| `node_flow_agent_skills` | Attachments that expose a flow as a repeatable skill for an agent preset. |
+| `node_flow_runs` | Parent run rows with status, version, trigger type, redacted trigger payload, redacted input/output, error message, timestamps, and optional execution invocation link. |
+| `node_flow_node_runs` | Per-node run rows with status, node id, redacted input/output, error message, timestamps, and optional execution invocation link. |
+
+`node_flow_runs.execution_invocation_id` points at the parent `execution_invocations` row with `type = "node_flow"`. Provider and HTTP node rows may also set `node_flow_node_runs.execution_invocation_id` to invocation rows with `type = "node_flow_node"`. Deleting a node flow cascades its versions, attachments, run rows, and node-run rows.
+
 ## Memory
 
 | Field | Type | Notes |

docs-web/content/docs/developer-mcp-tools.mdx

@@ -114,6 +114,61 @@ 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.
+
+Minimal create payload:
+
+```jsonc
+{
+  "action": "create",
+  "projectId": "project-123",
+  "name": "Daily API Check",
+  "graph": {
+    "nodes": [
+      { "id": "input", "type": "input", "title": "Run input" },
+      {
+        "id": "request",
+        "type": "http_request",
+        "title": "Fetch status",
+        "data": {
+          "method": "GET",
+          "url": "{{ input.statusUrl }}",
+          "headers": { "authorization": "Bearer {{ input.apiTokenRef }}" }
+        }
+      },
+      { "id": "output", "type": "output", "title": "Output" }
+    ],
+    "edges": [
+      { "fromNodeId": "input", "toNodeId": "request" },
+      { "fromNodeId": "request", "toNodeId": "output" }
+    ]
+  },
+  "widgets": {
+    "fields": [
+      { "id": "statusUrl", "type": "text", "label": "Status URL", "required": true },
+      { "id": "apiTokenRef", "type": "secretRef", "label": "API token reference", "required": true }
+    ]
+  }
+}
+```
+
+Attach and run:
+
+```jsonc
+{ "action": "attach_to_agent", "flowId": "flow-123", "agentPresetId": "agent-123", "skillAlias": "Daily API Check" }
+```
+
+```jsonc
+{ "action": "run", "projectId": "project-123", "flowId": "flow-123", "input": { "statusUrl": "https://example.test/status", "apiTokenRef": "secret://status/token" } }
+```
+
+Use `validate` to inspect a draft graph without saving, `list_runs` for recent run summaries, and
+`get_run` for the parent run plus per-node rows. Keep raw secrets out of MCP payloads; use references
+and let Code UX redaction mask any secret-shaped keys in returned graph, input, trigger, and output
+payloads.
+
 ## Approval handshake (destructive actions)
 
 Destructive and mutating actions require a two-step confirmation. The first call returns an approval

docs-web/content/docs/registry.ts

@@ -22,6 +22,7 @@ export type DocsSlug =
   | 'user-dashboard-chat'
   | 'user-dashboard-agents'
   | 'user-dashboard-nodes'
+  | 'user-dashboard-node-flows'
   | 'user-dashboard-scheduler'
   | 'user-dashboard-memory'
   | 'user-dashboard-knowledge'
@@ -195,6 +196,13 @@ export const docsRegistry: Record<DocsSlug, DocsRegistryEntry> = {
     title: "Nodes",
     description: "The Nodes page (/nodes) manages project-scoped workflow graphs for editing, widget configuration, agent attachments, validation, and persisted run inspection.",
   },
+  'user-dashboard-node-flows': {
+    id: 'user-dashboard-node-flows',
+    path: '/docs/user-dashboard-node-flows',
+    section: 'User Guide',
+    title: "Node Flows",
+    description: "Create and operate saved node-flow workflows for the active project, including dynamic widgets, validation, manual runs, scheduling, run inspection, and agent skill attachments.",
+  },
   'user-dashboard-scheduler': {
     id: 'user-dashboard-scheduler',
     path: '/docs/user-dashboard-scheduler',
@@ -427,6 +435,7 @@ export const orderedDocs: DocsRegistryEntry[] = [
   docsRegistry['user-dashboard-chat'],
   docsRegistry['user-dashboard-agents'],
   docsRegistry['user-dashboard-nodes'],
+  docsRegistry['user-dashboard-node-flows'],
   docsRegistry['user-dashboard-scheduler'],
   docsRegistry['user-dashboard-memory'],
   docsRegistry['user-dashboard-knowledge'],

docs-web/content/docs/user-dashboard-node-flows.mdx

@@ -0,0 +1,33 @@
+# 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.
+
+## Flow Library And Canvas
+
+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.
+
+## Dynamic Widgets
+
+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.
+
+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.
+
+## Validation
+
+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.
+
+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`.
+
+## Running And Inspection
+
+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.
+
+Rendered run payloads redact secret-shaped keys such as `apiKey`, `authorization`, `cookie`, `password`, `secret`, and `token`.
+
+## 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.

docs-web/content/docs/user-dashboard-overview.mdx

@@ -37,7 +37,8 @@ The background is an animated Three.js scene ("Deep Ocean") that lazy-loads afte
 | `/live` | [Live Session](/docs/user-dashboard-live-session) | Real-time view of the active sprint run |
 | `/chat` | [Chat](/docs/user-dashboard-chat) | Conversation threads with agents, plus invocation logs |
 | `/agents` | [Agents](/docs/user-dashboard-agents) | Agent presets — system instructions, avatars, memory templates |
-| `/scheduler` | [Scheduler](/docs/user-dashboard-scheduler) | Scheduled sprints, quicksprints, and messages with recurrence |
+| `/nodes` | [Node Flows](/docs/user-dashboard-node-flows) | Create, validate, run, schedule, and attach repeatable node workflows |
+| `/scheduler` | [Scheduler](/docs/user-dashboard-scheduler) | Scheduled sprints, quicksprints, node flows, messages, and memory remediation |
 | `/memory` | [Memory](/docs/user-dashboard-memory) | Short/long-term memory, embedding model management, semantic search |
 | `/knowledge` | [Knowledge](/docs/user-dashboard-knowledge) | Project knowledge base — documents, embeddings, semantic search |
 | `/files` | [File Browser](/docs/user-dashboard-file-browser) | Browse project files and review sprint Git changes |

docs-web/content/docs/user-dashboard-scheduler.mdx

@@ -24,8 +24,8 @@ Each scheduler entry has a **target** — the thing that runs when it fires:
 
 Node-flow entries store `nodeFlowTarget = { flowId, input?, flowVersion? }` inside the existing
 target JSON payload, validate that the flow belongs to the selected project, and run through the
-node-flow runtime with scheduler trigger metadata when due. Blank dashboard JSON input is omitted,
-and invalid JSON is rejected before submission.
+node-flow runtime with scheduler trigger metadata when due. Blank dashboard input is omitted, and
+supplied input must be a JSON object.
 
 The backend scheduler contract also supports agent-created wakeups and scheduled task reruns.
 Agent wakeups and task reruns are stored in the same target JSON payload with `origin` and `source` set to
@@ -44,6 +44,12 @@ agent wakeups and task reruns can still be paused, resumed, or deleted from the
 An entry can run once at a specific time or repeat on a **recurrence rule** (for example daily or
 weekly). The page previews the next occurrences so you can confirm the cadence before saving.
 
+For node-flow schedules, recurrence uses the same model as other targets. Due runs call the node-flow
+runtime with `triggerType = "scheduler"` and trigger metadata containing the scheduler entry id,
+scheduled occurrence time, target type, and stored flow version when present. Node-flow schedules
+advance only after runtime startup succeeds; failures move the entry to `failed` with the last error
+visible in the list.
+
 ## Managing entries
 
 From the page you can:

docs-web/developer/mcp-tools.md

@@ -114,6 +114,61 @@ 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.
+
+Minimal create payload:
+
+```jsonc
+{
+  "action": "create",
+  "projectId": "project-123",
+  "name": "Daily API Check",
+  "graph": {
+    "nodes": [
+      { "id": "input", "type": "input", "title": "Run input" },
+      {
+        "id": "request",
+        "type": "http_request",
+        "title": "Fetch status",
+        "data": {
+          "method": "GET",
+          "url": "{{ input.statusUrl }}",
+          "headers": { "authorization": "Bearer {{ input.apiTokenRef }}" }
+        }
+      },
+      { "id": "output", "type": "output", "title": "Output" }
+    ],
+    "edges": [
+      { "fromNodeId": "input", "toNodeId": "request" },
+      { "fromNodeId": "request", "toNodeId": "output" }
+    ]
+  },
+  "widgets": {
+    "fields": [
+      { "id": "statusUrl", "type": "text", "label": "Status URL", "required": true },
+      { "id": "apiTokenRef", "type": "secretRef", "label": "API token reference", "required": true }
+    ]
+  }
+}
+```
+
+Attach and run:
+
+```jsonc
+{ "action": "attach_to_agent", "flowId": "flow-123", "agentPresetId": "agent-123", "skillAlias": "Daily API Check" }
+```
+
+```jsonc
+{ "action": "run", "projectId": "project-123", "flowId": "flow-123", "input": { "statusUrl": "https://example.test/status", "apiTokenRef": "secret://status/token" } }
+```
+
+Use `validate` to inspect a draft graph without saving, `list_runs` for recent run summaries, and
+`get_run` for the parent run plus per-node rows. Keep raw secrets out of MCP payloads; use references
+and let Code UX redaction mask any secret-shaped keys in returned graph, input, trigger, and output
+payloads.
+
 ## Approval handshake (destructive actions)
 
 Destructive and mutating actions require a two-step confirmation. The first call returns an approval

docs-web/routes/docs.user-dashboard-node-flows.lazy.tsx

@@ -0,0 +1,11 @@
+import { createLazyFileRoute } from '@tanstack/react-router'
+import UserDashboardNodeFlowsContent from '../content/docs/user-dashboard-node-flows.mdx'
+import { DocsPage } from '../components/docs/DocsPage'
+
+export const Route = createLazyFileRoute('/docs/user-dashboard-node-flows')({
+  component: () => (
+    <DocsPage id="user-dashboard-node-flows">
+      <UserDashboardNodeFlowsContent />
+    </DocsPage>
+  )
+})

docs-web/user/dashboard/node-flows.md

@@ -0,0 +1,33 @@
+# 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.
+
+## Flow Library And Canvas
+
+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.
+
+## Dynamic Widgets
+
+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.
+
+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.
+
+## Validation
+
+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.
+
+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`.
+
+## Running And Inspection
+
+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.
+
+Rendered run payloads redact secret-shaped keys such as `apiKey`, `authorization`, `cookie`, `password`, `secret`, and `token`.
+
+## 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.

docs-web/user/dashboard/overview.md

@@ -37,7 +37,8 @@ The background is an animated Three.js scene ("Deep Ocean") that lazy-loads afte
 | `/live` | [Live Session](./live-session.md) | Real-time view of the active sprint run |
 | `/chat` | [Chat](./chat.md) | Conversation threads with agents, plus invocation logs |
 | `/agents` | [Agents](./agents.md) | Agent presets — system instructions, avatars, memory templates |
-| `/scheduler` | [Scheduler](./scheduler.md) | Scheduled sprints, quicksprints, and messages with recurrence |
+| `/nodes` | [Node Flows](./node-flows.md) | Create, validate, run, schedule, and attach repeatable node workflows |
+| `/scheduler` | [Scheduler](./scheduler.md) | Scheduled sprints, quicksprints, node flows, messages, and memory remediation |
 | `/memory` | [Memory](./memory.md) | Short/long-term memory, embedding model management, semantic search |
 | `/knowledge` | [Knowledge](./knowledge.md) | Project knowledge base — documents, embeddings, semantic search |
 | `/files` | [File Browser](./file-browser.md) | Browse project files and review sprint Git changes |