@uipath/skills 1.204.0 → 1.204.1

package/skills/uipath-maestro-flow/references/shared/file-format.md

@@ -0,0 +1,582 @@
+# UiPath Flow File Format
+
+The `.flow` file is a JSON document at `<ProjectName>.flow` in the project root. It is the **only file you should edit** — other generated files will be overwritten.
+
+## Table of contents
+
+- [Top-level structure](#top-level-structure)
+- [Project structure (generated scaffold)](#project-structure-generated-scaffold)
+- [Node instance](#node-instance)
+- [Layout](#layout)
+- [Edge — both ports required](#edge--both-ports-required)
+- [Definition entry](#definition-entry)
+- [Common node types](#common-node-types)
+- [Standard ports by node type](#standard-ports-by-node-type)
+- [Implicit error port on action nodes](#implicit-error-port-on-action-nodes)
+- [Minimal working example — dice roller](#minimal-working-example--dice-roller)
+- [entry-points.json — auto-generated, do not edit](#entry-pointsjson--auto-generated-do-not-edit)
+- [Bindings — Orchestrator resource bindings (top-level `bindings[]`)](#bindings--orchestrator-resource-bindings-top-level-bindings)
+- [Bindings — Data Fabric entity bindings](#bindings--data-fabric-entity-bindings)
+- [Bindings — connector connection binding](#bindings--connector-connection-binding)
+
+## Top-level structure
+
+```json
+{
+  "id": "<uuid>",
+  "version": "<scaffolded file-format version>",
+  "name": "MyFlow",
+  "nodes": [],
+  "edges": [],
+  "definitions": [],
+  "bindings": [],
+  "variables": {},
+  "layout": {
+    "nodes": {}
+  }
+}
+```
+
+> **Key order is NOT guaranteed — never anchor edits on it.** The skeleton above is illustrative; the CLI does not commit to a stable top-level key sequence or to which optional keys are present. Real flows vary: `runtime` may appear (and has been observed *before* `nodes`, not after `definitions`) or be absent entirely; `bindings`, `variables`, `solutionId`, `projectId`, and a trailing `metadata` object surface in different positions depending on CLI version and what the flow contains. When editing a `.flow`, anchor each `Edit` on the **target array's own key** (`"nodes": [`, `"edges": [`, `"definitions": [`, or `layout.nodes`) located in the text you just `Read` — never on "the key that follows X." See [greenfield.md — Anchoring parallel `.flow` Edits](../author/greenfield.md#anchoring-parallel-flow-edits--anchor-on-what-you-read-not-on-key-order).
+
+Optional top-level `runtime`: a CLI-managed object that appears on some flows (e.g. after `uip maestro flow node add` for an HTTP/connector node) and is absent on others. It is not user-authored — do not add, remove, or anchor on it. Its presence and position are not guaranteed.
+
+**Top-level `version`** = workflow file-format version. **Use the exact value `uip maestro flow init` scaffolds** — do not hand-pick, hardcode, or downgrade it. It is not a semver string; the schema gates on an exact literal for the current file-format version, so an older value (e.g. `"1.0"`, `"1.0.0"`) that worked for a legacy parser will fail for a new flow. `init` always writes the accepted value; preserve it. To see the current value, scaffold a throwaway flow with `init` and read its top-level `version`, or read it from an existing `init`-generated `.flow`.
+
+> **Don't confuse top-level `version` with `definitions[].version` / `typeVersion`.** Node-definition `version` (and matching node-instance `typeVersion`) are validated by `versionSchema`, a regex that accepts both `x.y` and `x.y.z` (`/^\d+\.\d+(\.\d+)?$/`, error `'Version must be in format "x.y" or "x.y.z"'`). Both layers are canonically `x.y`, but the node-level regex still accepts legacy 3-part strings so registry definitions (`"1.0"`) and older scaffolded nodes (`"1.0.0"`) both parse. The two layers report distinct errors, but Zod may collapse a node-level mismatch to path `(root)`. If you see a version-related error at `(root)`, audit the top-level `version` first; if it's correct, check each node's `typeVersion` against the matching `definitions[].version`.
+
+`solutionId` and `projectId` may also appear at the top level — these are auto-populated by the project scaffold and packaging. Preserve the generated values.
+
+> **`bindings[]`** holds Orchestrator resource references for `uipath.core.*` resource nodes (rpa, agent, flow, agentic-process, api-workflow, hitl) and for connector-node connections. See [Bindings — Orchestrator resource bindings](#bindings--orchestrator-resource-bindings-top-level-bindings) below and the [connector plugin](../author/plugins/connector/impl.md) for the connector-binding shape.
+
+## Project structure (generated scaffold)
+
+```
+<ProjectName>/
+├── project.uiproj          # { "Name": "...", "ProjectType": "Flow" }
+├── <ProjectName>.flow      # ← edit this
+├── bindings_v2.json        # resource bindings
+├── entry-points.json       # input/output schema declarations
+├── operate.json            # runtime options
+└── package-descriptor.json # packaging manifest
+```
+
+## Node instance
+
+```json
+{
+  "id": "rollDice",
+  "type": "core.action.script",
+  "typeVersion": "1.0",
+  "display": { "label": "Roll Dice" },
+  "inputs": {
+    "script": "return { roll: Math.floor(Math.random() * 6) + 1 };"
+  },
+  "outputs": {
+    "output": {
+      "type": "object",
+      "description": "The return value of the script",
+      "source": "=result.response",
+      "var": "output"
+    },
+    "error": {
+      "type": "object",
+      "description": "Error information if the script fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+**Required fields on every node**: `id`, `type`, `typeVersion`, **`display`** (with at least a `label`). This applies to **every** node — triggers (`core.trigger.manual`, `core.trigger.scheduled`, connector triggers), action nodes, control-flow nodes (`core.control.end`, `core.logic.terminate`), and human-task nodes. The Zod `nodeSchema` declares `display: displayConfigSchema` without `.optional()`, so no node type is exempt — even ones that "feel" trivial.
+
+`typeVersion` must match the corresponding `definitions[].version` exactly. The registry often returns versions such as `"1.0"` while older examples or scaffolded files may show `"1.0.0"`. If a node uses `typeVersion: "1.0.0"` but the copied definition is `"version": "1.0"`, validation reports "Node type `<type>:1.0.0` has no matching definition." When direct-authoring a new node from `registry get`, set `typeVersion` to the copied definition's `version`; when preserving an existing node, preserve its existing node/definition pair unless you intentionally update both together. <!-- version-check-skip --> (explains the x.y vs x.y.z mismatch mechanic; literals are illustrative, not pinned)
+
+> **Gotcha — vague schema-validation error on missing `display`.** Omitting `display` on any node produces:
+>
+> ```
+> [error] [(root)] Schema validation failed: Invalid input: expected object, received undefined
+> ```
+>
+> The error path is `(root)` and does NOT pinpoint which node or which field is missing. If you see this error after editing a `.flow` file, audit every node for a `display` block before doing anything else.
+
+> **No instance `model` block.** BPMN type, serviceType, event definition, and binding/context templates all live in the node's **definition** (the manifest copied from the registry into `definitions[]`). The runtime hydrates them from the definition at serialization time — instances carry only per-instance data (`inputs`, `outputs`, `display`). This applies to every inline-agent-related node too: `uipath.agent.autonomous` plus every attached `uipath.agent.resource.*` node (tool, escalation, context) carries source identity at `inputs.source`. Their definitions declare `model.source: true`; flow-core hoists that identity onto each instance's `inputs.source`. Do not write a `"model": { "source": ... }` block on the instance.
+>
+> **No `ui` block on nodes.** Position and size are stored in the top-level `layout` object, not on individual nodes. See [Layout](#layout) below.
+
+### Instance-specific identity fields
+
+A few per-instance identity fields live on the node instance:
+
+| Field | Used by | Purpose |
+|-------|---------|---------|
+| `inputs.entryPointId` | All trigger nodes (`core.trigger.manual`, `core.trigger.scheduled`, connector triggers) | Stable UUID identifying the entry point |
+| `inputs.isDefaultEntryPoint` | Trigger nodes in subflows | Boolean marking the default entry point when a subflow has multiple triggers |
+| `inputs.source` | `uipath.agent.autonomous` and every attached `uipath.agent.resource.*` node (tool, escalation, context) | For `uipath.agent.autonomous`: the inline agent's `projectId`. For resource nodes: the attached resource UUID. Definitions declare `model.source: true`; flow-core hoists onto the instance — no instance `model` block. |
+| `inputs.color`, `inputs.content` | Sticky-note nodes | Visual content of the sticky note |
+
+Example — manual start trigger:
+
+```json
+{
+  "id": "start",
+  "type": "core.trigger.manual",
+  "typeVersion": "1.0",
+  "display": { "label": "Manual trigger" },
+  "inputs": {
+    "entryPointId": "3d4a8c34-5682-4ebe-a6bc-d92a18830bb5"
+  },
+  "outputs": {
+    "output": { "type": "object", "description": "Data passed when manually triggering the process.", "source": "null", "var": "output" }
+  }
+}
+```
+
+### Node outputs
+
+`$vars.<sourceNodeId>.<outputId>` resolution at runtime is driven by **`variables.nodes[]`**, not by the node instance's `outputs` block. The BPMN emitter walks `variables.nodes[]` to write the process-level `<uipath:inputOutput id="<nodeId>.<outputId>">` declarations the runtime needs; the action-node instance `outputs` block is ignored at serialization (the manifest's `outputDefinition` supplies the activity-side mapping). End / terminate nodes are the exception — their instance `outputs` block IS consumed to map workflow-level `out` variables. See [end/impl.md](../author/plugins/end/impl.md).
+
+The canonical recipe for a data-producing node is therefore:
+
+- `definitions[]` entry copied verbatim from `uip maestro flow registry get` (carries the manifest `outputDefinition`).
+- `variables.nodes[]` entry per output: `{ "id": "<nodeId>.<outputId>", "type": "object", "binding": { "nodeId": "<nodeId>", "outputId": "<outputId>" } }`.
+- Optional instance `outputs` block matching the manifest — harmless and matches the canonical examples below for clarity, but **not** what controls runtime variable visibility.
+
+Skipping `variables.nodes[]` produces a flow that passes `flow validate` but resolves `$vars.<sourceNodeId>.output` to `undefined` at runtime. `uip maestro flow format` regenerates `variables.nodes[]` from `nodes[]` + `definitions[]`, so always run it after structural edits — the omission becomes self-healing.
+
+When you DO author the instance `outputs` block (for documentation / parity with manifest schema), use the shape below. Each output entry has:
+
+- `type` — data type (usually `"object"`)
+- `description` — human-readable description
+- `source` — runtime binding expression, copied from the manifest `outputDefinition`. `"=Error"` for errors, always.
+- `var` — the variable name (matches the output ID, e.g., `"output"`, `"error"`)
+
+**Orchestrator-job nodes (api-workflow, rpa-workflow, agent, agentic-process, function): declare `error` only — `output` is derived.** They are the one family whose instance block the converter reads: it copies an authored `source` verbatim, and injects `{output, jsonSchema, "=this"}` when a non-empty `outputs` omits `output`. So `"=result.response"` there — the connector/script source — leaves `$vars.<nodeId>.output` null at runtime while `flow validate` passes. Studio Web serializes `error`-only instances too (verified on api-workflow, published-flow, and inline-agent nodes). Subflow and published-flow (`uipath.core.flow.*`) instance blocks are never read — still declare `error` only.
+
+The standard `outputs` block for most action nodes (script, HTTP, transform, connector):
+
+```json
+"outputs": {
+  "output": {
+    "type": "object",
+    "description": "The return value of the <node type>",
+    "source": "=result.response",
+    "var": "output"
+  },
+  "error": {
+    "type": "object",
+    "description": "Error information if the <node type> fails",
+    "source": "=Error",
+    "var": "error"
+  }
+}
+```
+
+Trigger nodes (manual, scheduled, connector triggers) have a single output — no error port. A manual trigger carries the literal string `"null"` as its `source`, matching what Studio Web writes:
+
+```json
+"outputs": {
+  "output": {
+    "type": "object",
+    "description": "Data passed when manually triggering the process.",
+    "source": "null",
+    "var": "output"
+  }
+}
+```
+
+End/terminate nodes do **not** use this pattern — their `outputs` maps workflow-level output variables (see the [Author end plugin reference](../author/plugins/end/impl.md)).
+
+## Layout
+
+Node positioning is stored in a **top-level `layout` object**, keyed by node `id`. The same shape applies inside each subflow as `subflows[<id>].layout`. Layout data is owned by `uip maestro flow format` (see [cli-commands.md](cli-commands.md#uip-maestro-flow-format)) — you should not need to hand-write it.
+
+```json
+"layout": {
+  "nodes": {
+    "start": {
+      "position": { "x": 200, "y": 144 },
+      "size": { "width": 96, "height": 96 },
+      "collapsed": false
+    },
+    "rollDice": {
+      "position": { "x": 400, "y": 144 },
+      "size": { "width": 96, "height": 96 },
+      "collapsed": false
+    },
+    "end": {
+      "position": { "x": 600, "y": 144 },
+      "size": { "width": 96, "height": 96 },
+      "collapsed": false
+    }
+  }
+}
+```
+
+Each key in `layout.nodes` is a node `id`. `flow format` creates an entry for every node and populates `position` + `size`.
+
+**What format does:**
+- Arranges nodes horizontally (left-to-right) with `nodeSpacing: 96`, anchored to the leftmost node's original position
+- Sets each node's `size` to match its canvas shape: inline agents (`uipath.agent.autonomous` / `uipath.agent.conversational`, `shape: rectangle`) → `{ "width": 288, "height": 96 }`; containers (loops/groups) → `{ "width": 560, "height": 320 }`; everything else — including referenced `uipath.core.agent.<guid>` nodes — → `{ "width": 96, "height": 96 }`. A size that disagrees with the node's shape renders misshapen in Studio Web.
+- Skips `stickyNote` nodes from layout (they keep their custom position and size)
+- Recurses into every subflow and rewrites its `subflows[<id>].layout` map
+
+**Subflow layout is scoped.** Each subflow entry in `subflows[<id>]` has its **own** `layout.nodes` map for the nodes inside that subflow — they do NOT live in the top-level `layout.nodes`. Format handles both passes. See the [Author subflow plugin reference](../author/plugins/subflow/impl.md).
+
+## Edge — both ports required
+
+```json
+{
+  "id": "edge-start-rollDice",
+  "sourceNodeId": "start",
+  "sourcePort": "output",
+  "targetNodeId": "rollDice",
+  "targetPort": "input"
+}
+```
+
+> **Gotcha**: `targetPort` is required. Omitting it produces `[error] [edges[N].targetPort] Invalid input: expected string, received undefined` at validate time.
+>
+> **Gotcha**: the source field is `sourcePort`, not `sourceHandle`. If you write `sourceHandle`, validation fails with `[error] [edges[N].sourcePort] Invalid input: expected string, received undefined` — the path identifies the offending edge entry exactly.
+>
+> **Gotcha — edge `id` MUST start with a letter (XML NCName).** Never use a bare UUID or any id with a leading digit (`"12bd09dd-…"`, `"1edge-start"`). Edge ids become BPMN `<bpmn:incoming>/<bpmn:outgoing>` IDREFs; a leading digit makes the converter silently drop those references while still emitting the `sequenceFlow`, so `flow validate` passes and upload succeeds — but the engine cannot traverse: the run reports **Completed having executed only the start node**, every output null. Use descriptive ids (`e-<source>-<target>`, e.g. `e-start-agent`); prefixing a letter (`e12bd09dd-…`) also works. Same rule applies to node ids.
+
+## Definition entry
+
+Every node type appearing in `nodes` must have a matching entry in `definitions`. Get the correct definition from:
+
+```bash
+uip maestro flow registry get core.action.script --output json
+```
+
+Copy the returned node definition object into your `definitions` array. Depending on CLI/plugin version, that object may appear at `Data.Node` or as the top-level object containing fields such as `nodeType`, `version`, and `handleConfiguration`. Do not write definitions by hand — always pull from the registry to ensure schema compliance.
+
+## Common node types
+
+| Type | Purpose | Key inputs |
+|------|---------|------------|
+| `core.trigger.manual` | Entry point | `entryPointId` |
+| `core.trigger.scheduled` | Recurring schedule trigger | `entryPointId`, `timerType`, `timerValue` |
+| `core.action.script` | Run JavaScript | `script` |
+| `core.action.http.v2` | HTTP request | `method`, `url`, `headers`, `body` |
+| `core.action.transform` | Map/filter/group data | `collection`, `operations` |
+| `core.logic.decision` | If/else branch | `expression` |
+| `core.logic.switch` | Multi-way branch | `cases` |
+| `core.logic.loop` | Iterate collection | `collection`, `parallel` |
+| `core.logic.merge` | Sync parallel paths | — |
+| `core.control.end` | Graceful end | — |
+| `core.logic.terminate` | Abort workflow | — |
+
+> The BPMN type for each node (e.g., `bpmn:StartEvent`, `bpmn:ScriptTask`) lives in the `definitions` entry copied from `uip maestro flow registry get`. Instances do not carry the BPMN type.
+
+For full details on each node (ports, inputs, outputs, when to use), see the [Author planning architecture guide](../author/planning-arch.md). For implementation resolution (registry lookups, connection binding, reference field resolution), see the [Author planning implementation guide](../author/planning-impl.md).
+
+Discover all available types:
+```bash
+uip maestro flow registry list --output json
+uip maestro flow registry search <keyword>
+```
+
+## Standard ports by node type
+
+| Node type | Source ports (outgoing) | Target ports (incoming) |
+|-----------|------------------------|------------------------|
+| `core.trigger.manual` | `output` | — |
+| `core.action.script` | `success`, `error` | `input` |
+| `core.action.http.v2` | `default`, `error`, `branch-{id}` (dynamic) | `input` |
+| `core.action.transform` | `output`, `error` | `input` |
+| `core.logic.decision` | `true`, `false` | `input` |
+| `core.logic.switch` | `case-{id}` (dynamic), `default` | `input` |
+| `core.logic.loop` | `success`, `error` (outer), `start` (inner) | `input` (outer), `continue`, `break` (inner) |
+| `core.logic.merge` | `output` | `input` |
+| `core.control.end` | — | `input` |
+| `core.logic.terminate` | — | `input` |
+
+Connector activities, agent nodes, and RPA nodes follow the same pattern as the generic action nodes above: a primary source port plus an implicit `error` port. The `core.datafabric.*` nodes are the exception — `input` and `output` only.
+
+Verify exact ports for any node type:
+```bash
+uip maestro flow registry get <node-type> --output json
+# Look at Data.Node.handleConfiguration[].handles[].id
+# Also check Data.Node.supportsErrorHandling — see "Implicit error port" below
+```
+
+## Implicit error port on action nodes
+
+Any node with `supportsErrorHandling: true` in the registry exposes an implicit `error` source port for catching node-level failures. This applies to HTTP, Script, Transform (all variants), connector activities, agent nodes, and RPA nodes — most action nodes, but not all: the `core.datafabric.*` family does not declare it and has no `error` port ([data-fabric/impl.md](../author/plugins/data-fabric/impl.md#no-error-port)). Check the registry rather than assuming.
+
+The port is **not** listed in the registry's `handleConfiguration`. Studio Web only exposes it when the source node has `inputs.errorHandlingEnabled: true`; when the flow contains an outgoing edge with `sourcePort: "error"` from that node, the serializer emits a BPMN boundary error event attached to the node. Because of this gate, `uip maestro flow validate` reports an error when a node has an outgoing `sourcePort: "error"` edge but `inputs.errorHandlingEnabled` is not `true` — so the inconsistency is caught before publish rather than surfacing as a hidden edge in Studio Web.
+
+### Default: off — enable only for a failure the flow actually handles
+
+`inputs.errorHandlingEnabled` is **opt-in, and stays off unless the requirements name a failure fallback.** Turning it on suppresses the node's fault: the node returns instead of faulting and execution continues. Enable it only when both hold:
+
+1. The requirements state what should happen when this node fails ("if the call fails, …", "return X for invalid input", "handle timeouts") — **and**
+2. You wire the node's `error` port to a handler that produces an outcome distinguishable from success.
+
+Never set the flag on a node that has no outgoing `error` edge — it suppresses the fault with nothing to catch it, converting a real failure into a run that reports success. Let the CLI own the flag: `uip maestro flow edge add --source-port error` and `uip maestro flow format` set it from the error edges actually present. If you find the flag on a node with no error edge, remove it.
+
+### Do not swallow the failure
+
+An `error` edge must not rejoin the happy path. When it does, every failure walks the success route and the run reports `Completed` while the work never happened — the flow "always looks successful."
+
+| | Error-path target | Result |
+| --- | --- | --- |
+| ✗ | The next node on the happy path | Failure is invisible; downstream nodes run on missing data |
+| ✗ | The same End node the success path reaches | Success path's output mappings run against the failed node's empty output |
+| ✓ | A **distinct** End node mapping an error/status `out` variable | Caller can tell failure from success |
+| ✓ | `core.logic.terminate` | Aborts the flow when recovery is impossible — see [terminate/impl.md](../author/plugins/terminate/impl.md) |
+| ✓ | A recovery branch that rejoins **only after obtaining valid data** — a retry that succeeded, or a fallback source that returned data | Downstream runs on real data, not on the failed node's empty output |
+
+```text
+Trigger -> HTTP Request
+  |-- default -> Process -> End (success — status: "ok")
+  |-- error   -> Log Error -> End (failure — status: "failed", message from $vars.httpCall.error)
+```
+
+### When the error port fires
+
+- Network failures, DNS errors, TLS errors
+- Request timeouts
+- Non-2xx HTTP responses (unless caught by a configured `inputs.branches` entry)
+- Script exceptions (`throw`, undefined reference, etc.)
+- Transform operation failures (invalid collection, missing field)
+- Any unhandled runtime exception inside the node
+
+Without a wired error edge, any of these fails the whole flow with `finalStatus: "Faulted"`. **That is the correct default, not a defect to design around** — a faulted run is visible to the operator; a swallowed failure is not. Only trade the fault for an error path when the requirements say what that path should do.
+
+### Wiring the error port
+
+```bash
+# Confirm the node supports error handling
+uip maestro flow registry get <node-type> --output json --output-filter "Node.SupportsErrorHandling"
+
+# Add an outgoing edge with sourcePort: "error"
+uip maestro flow edge add <Project>.flow <actionNodeId> <errorHandlerId> \
+  --source-port error --target-port input --output json
+```
+
+`uip maestro flow edge add --source-port error` and `uip maestro flow format` set `inputs.errorHandlingEnabled: true` on the source node automatically — only for nodes that have an error edge. When editing `.flow` JSON directly, set the flag yourself **on those nodes only**:
+
+```json
+{
+  "id": "<actionNodeId>",
+  "inputs": {
+    "errorHandlingEnabled": true
+  }
+}
+```
+
+Inside the error handler, `$vars.{actionNodeId}.error` resolves to the error object. For HTTP it's `{ code, message, detail, category, status }`; other nodes have similar shapes — check the node's `outputDefinition.error.schema` in the registry.
+
+### Error port vs other branching
+
+| Mechanism | When to use |
+| --- | --- |
+| **`error` source port** (any action node) | The node failed (exception, timeout, non-2xx not caught by a branch). Generic "something went wrong" handler. |
+| **`branch-{id}` ports** (HTTP only, `inputs.branches`) | The call succeeded and you want to route on response *content* — different paths for e.g. empty vs non-empty results. |
+| **`core.logic.decision` downstream** | Simple yes/no routing on the node's successful output. Doesn't help if the node itself fails. |
+| **`core.logic.switch` downstream** | Multi-way routing on the node's successful output. Same — doesn't catch failures. |
+
+## Minimal working example — dice roller
+
+Building a flow is a two-step process: write the nodes/edges structure, then populate `definitions` from the registry.
+
+### Step 1 — Write nodes and edges
+
+Replace `<uuid>` with any generated UUID (e.g. `crypto.randomUUID()` in Node.js, or any UUID v4 generator) — this applies ONLY to the top-level flow `id` and `entryPointId` (the same UUID must appear in `entry-points.json` as `uniqueId`). **Node and edge ids are NOT UUIDs** — they must start with a letter (see the Edge gotcha above). Set top-level `version` to the value `uip maestro flow init` scaffolds — never hand-pick it (see [Top-level structure](#top-level-structure)).
+
+```json
+{
+  "id": "3d4a8c34-5682-4ebe-a6bc-d92a18830bb5",
+  "version": "<scaffolded file-format version>",
+  "name": "DiceRoller",
+  "nodes": [
+    {
+      "id": "start",
+      "type": "core.trigger.manual",
+      "typeVersion": "1.0",
+      "display": { "label": "Manual trigger" },
+      "inputs": {
+        "entryPointId": "<uuid>"
+      },
+      "outputs": {
+        "output": {
+          "type": "object",
+          "description": "Data passed when manually triggering the process.",
+          "source": "null",
+          "var": "output"
+        }
+      }
+    },
+    {
+      "id": "rollDice",
+      "type": "core.action.script",
+      "typeVersion": "1.0",
+      "display": { "label": "Roll Dice" },
+      "inputs": {
+        "script": "return { roll: Math.floor(Math.random() * 6) + 1 };"
+      },
+      "outputs": {
+        "output": {
+          "type": "object",
+          "description": "The return value of the script",
+          "source": "=result.response",
+          "var": "output"
+        },
+        "error": {
+          "type": "object",
+          "description": "Error information if the script fails",
+          "source": "=Error",
+          "var": "error"
+        }
+      }
+    },
+    {
+      "id": "end",
+      "type": "core.logic.terminate",
+      "typeVersion": "1.0",
+      "display": { "label": "End" },
+      "inputs": {}
+    }
+  ],
+  "edges": [
+    {
+      "id": "edge-start-roll",
+      "sourceNodeId": "start",
+      "sourcePort": "output",
+      "targetNodeId": "rollDice",
+      "targetPort": "input"
+    },
+    {
+      "id": "edge-roll-end",
+      "sourceNodeId": "rollDice",
+      "sourcePort": "success",
+      "targetNodeId": "end",
+      "targetPort": "input"
+    }
+  ],
+  "definitions": [],
+  "bindings": [],
+  "variables": {},
+  "layout": {
+    "nodes": {
+      "start": {
+        "position": { "x": 200, "y": 144 },
+        "size": { "width": 96, "height": 96 },
+        "collapsed": false
+      },
+      "rollDice": {
+        "position": { "x": 400, "y": 144 },
+        "size": { "width": 96, "height": 96 },
+        "collapsed": false
+      },
+      "end": {
+        "position": { "x": 600, "y": 144 },
+        "size": { "width": 96, "height": 96 },
+        "collapsed": false
+      }
+    }
+  }
+}
+```
+
+### Step 2 — Populate definitions from the registry
+
+Run one command per node type used in `nodes`. Copy the returned node definition object from each response into the `definitions` array, and set each matching node instance's `typeVersion` to the copied definition's exact `version`.
+
+```bash
+uip maestro flow registry get core.trigger.manual --output json
+uip maestro flow registry get core.action.script --output json
+uip maestro flow registry get core.logic.terminate --output json
+```
+
+The `definitions` array must contain exactly one entry per unique `type:typeVersion` used — not one per node instance. If two nodes share the same type and version, one definition covers both.
+
+> **Never write definitions by hand.** The registry is the authoritative source; hand-written definitions will fail validation or cause runtime errors.
+
+## entry-points.json — auto-generated, do not edit
+
+`entry-points.json` declares the flow's external interface (input/output schemas and trigger entry points). Preserve its lifecycle-generated contents; project scaffolding creates it, and the Flow lifecycle regenerates it before execution or publication.
+
+Flow input and output parameters are declared through **variables** in the `.flow` file:
+- **Flow inputs**: Add entries to `variables.nodes[]` whose `binding.nodeId` is the start node and whose `binding.outputId` names each input value — the start node "outputs" input values to downstream nodes
+- **Flow outputs**: Add output variables to the end/terminate node
+- Downstream nodes reference inputs via `$vars.start.output.<paramName>`
+
+The packaging/debug step derives `entry-points.json` from these variable declarations.
+
+## Bindings — Orchestrator resource bindings (top-level `bindings[]`)
+
+The top-level `bindings` array (a sibling of `nodes`, `edges`, `definitions`, `variables`, `layout`) holds resource-reference indirections for **Orchestrator resource nodes** — RPA workflows, agents, flows, agentic processes, API workflows, and HITL apps.
+
+Folder-scoped Data Fabric entities also write rows into this same array, but resolve them by a **different rule**. Everything in this section describes the Orchestrator-resource form; see [Bindings — Data Fabric entity bindings](#bindings--data-fabric-entity-bindings) below for how the `Entity` kind differs.
+
+Each resource node needs two binding entries (one for `name`, one for `folderPath`). The node instance itself has no binding or context data — just `inputs`. The definition (copied verbatim from the registry) carries `model.context[]` templates like `<bindings.name>` and `<bindings.folderPath>`. At BPMN emit time the runtime rewrites those placeholders to `=bindings.<id>` by matching the placeholder name against a workflow-level binding, scoped by the definition's `model.bindings.resourceKey`.
+
+```json
+"bindings": [
+  {
+    "id": "<UNIQUE_ID>",
+    "name": "name",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "<FolderPath>.<ResourceName>",
+    "default": "<ResourceName>",
+    "propertyAttribute": "name",
+    "resourceSubType": "Process"
+  },
+  {
+    "id": "<UNIQUE_ID_2>",
+    "name": "folderPath",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "<FolderPath>.<ResourceName>",
+    "default": "<FolderPath>",
+    "propertyAttribute": "folderPath",
+    "resourceSubType": "Process"
+  }
+]
+```
+
+**Rules:**
+
+- Add **two entries** per resource node (one for `name`, one for `folderPath`).
+- **Share** entries across node instances that reference the same resource — do not duplicate. Matching is by `(resourceKey, name)`, so any node whose definition has the same `resourceKey` resolves to the same binding pair.
+- Entry IDs are unique strings within the file. Descriptive IDs (e.g. `bDepositRpaName`) are preferred over short random IDs.
+- The node instance has no `model` block — it carries only `inputs`, `outputs`, and `display`.
+- `resourceKey` must exactly match the definition's `model.bindings.resourceKey` (verbatim from the registry). The runtime uses this key to scope placeholder resolution so that binding names like `name` / `folderPath` (shared across resource kinds) don't cross-alias.
+- `resourceSubType` mirrors the definition's `model.bindings.resourceSubType`: `Process` (rpa), `Agent` (agent), `Flow` (flow), `ProcessOrchestration` (agentic-process), `Api` (api-workflow), or the app type for HITL.
+
+**Why this is required.** The definition's `model.context[].value` fields are placeholders of the form `<bindings.{name}>` — deliberately invalid as runtime expressions, so they can't be confused with one. Before the BPMN is emitted, the runtime rewrites each placeholder to `=bindings.<id>` by finding a workflow-level binding with `(resourceKey, name)` matching the node's manifest `model.bindings.resourceKey` + the placeholder name. Without matching entries in top-level `bindings[]`, `uip maestro flow debug` fails with "Folder does not exist or the user does not have access to the folder" even though `uip maestro flow validate` passes.
+
+**Definitions stay verbatim.** Do NOT rewrite `<bindings.*>` placeholders inside the `definitions` entry — the definition is the authoring template. See "Every node type needs a `definitions` entry" in [author/CAPABILITY.md](../author/CAPABILITY.md).
+
+See each resource plugin's `impl.md` for the full JSON per node type: [rpa](../author/plugins/rpa/impl.md), [agent](../author/plugins/agent/impl.md), [flow](../author/plugins/flow/impl.md), [agentic-process](../author/plugins/agentic-process/impl.md), [api-workflow](../author/plugins/api-workflow/impl.md), [hitl](../author/plugins/hitl/impl.md).
+
+**Not to be confused with `bindings_v2.json`.** That file holds connector connection bindings for Integration Service nodes — a separate system. A flow may have both: a top-level `bindings[]` for resource references and a `bindings_v2.json` file for connector connections.
+
+## Bindings — Data Fabric entity bindings
+
+A **folder-scoped** Data Fabric entity (`core.datafabric.*` nodes) writes two rows into the same top-level `bindings[]` array, but they are not Orchestrator resource bindings and most of the rules in the section above do not carry over:
+
+| Aspect | Orchestrator resource nodes | Data Fabric `Entity` |
+| --- | --- | --- |
+| `resource` | `process`, `agent`, … | `Entity` — capitalized; a lowercase row is ignored by packaging, so deploy emits no override |
+| Matched by | `(resourceKey, name)` | `(resourceKey, propertyAttribute)`, falling back to `name` only when `propertyAttribute` is absent |
+| `name` holds | the placeholder name (`name` / `folderPath`) | a **display label** — the entity name, and `<entityName>Folder` for the folder row |
+| `propertyAttribute` | `name` / `folderPath` | `name` / **`folderKey`** — never `folderPath` |
+| `resourceSubType` | required, mirrors the definition | **absent** — Entity bindings have no definition-side `model.bindings` |
+
+The value is in `default` for both forms. There is also no `<bindings.{name}>` placeholder to rewrite: the entity has no definition-side `model.context[]`, and the serializer emits `bindings.<id>` tokens directly into the `=datafabric[...]` expression it builds.
+
+`folderKey` rather than `folderPath` is load-bearing. The platform's deploy-time override for an `Entity` resource carries `{ name, folderPath, folderKey }` and rewrites binding defaults by `propertyAttribute`; a `folderPath` row receives the Orchestrator FQN, which the Data Fabric query rejects even in the source org.
+
+Tenant-scoped entities need no bindings at all — they serialize as a dotted literal. See [data-fabric/impl.md — Folder-scoped entities and bindings](../author/plugins/data-fabric/impl.md#folder-scoped-entities-and-bindings) for the full JSON and when to hand-author it.
+
+## Bindings — connector connection binding
+
+When a flow uses connector nodes, the runtime needs to know **which authenticated connection** to use for each connector. This is configured in `content/bindings_v2.json`.
+
+See the relevant node guide in `nodes/` for the full `bindings_v2.json` schema, connection resource field reference, JSON examples, and the connection fetching workflow.